@pantheon.ai/agents

This package provides the pantheon-agents CLI for managing agent configs and tasks backed by a TiDB/MySQL task list.

It includes:

• A runner loop (pantheon-agents run <agent>) that executes queued tasks via Pantheon and persists status/output to TiDB.
• A client-facing server (pantheon-agents server) that exposes the same task operations over HTTP REST and MCP (HTTP+SSE).

Build

npm run -w @pantheon.ai/agents build

Environment variables

• DATABASE_URL (required): MySQL/TiDB connection string for the task list database.
• PANTHEON_API_KEY (required for some commands): Used to query/execute Pantheon branches.
• PANTHEON_AGENTS_API_TOKEN (optional): Bearer token for API auth when running pantheon-agents server (defaults for --token).

Command requirements:

• pantheon-agents add-task|delete-task|show-config|show-tasks: requires DATABASE_URL
• pantheon-agents run: requires DATABASE_URL + PANTHEON_API_KEY
• pantheon-agents config: requires DATABASE_URL, and requires PANTHEON_API_KEY when --bootstrap is enabled (default) or when --root-branch-id is not provided
• pantheon-agents reconfig: requires DATABASE_URL + PANTHEON_API_KEY
• pantheon-agents server: requires DATABASE_URL; auth uses --token or env PANTHEON_AGENTS_API_TOKEN (unless --no-auth)

Notes:

• PANTHEON_API_KEY is also required for config-related server endpoints/tools that read Pantheon branch output or re-bootstrap configs.

Show tasks output modes

• Default: concise one-line entries.
• Table output: use --no-concise.
• JSON output: use --json.
• Time filter: use --since <time> (alias: --from <time>) with an ISO-8601 timestamp (e.g. 2026-02-12T00:00:00Z) to only include tasks with queued_at >= since.

DB schema / migrations

The schema lives in packages/agents/src/db/schema/tidb.sql.

If you have an existing DB, apply:

ALTER TABLE task ADD COLUMN cancelled_at DATETIME NULL;
ALTER TABLE task ADD COLUMN parent_task_id BIGINT NULL;
CREATE INDEX idx_task_agent_parent ON task(agent, parent_task_id);

Start the server (HTTP + MCP)

Auth is enabled by default. Provide a token via env or flag:

export PANTHEON_AGENTS_API_TOKEN="your-token"
pantheon-agents server --host 127.0.0.1 --port 8000 --base-path /

To disable auth for local-only use (not recommended):

pantheon-agents server --no-auth

REST API

Base path: /api/v1

Examples:

TOKEN="$PANTHEON_AGENTS_API_TOKEN"

curl -sS -H "Authorization: Bearer $TOKEN" \\
  http://127.0.0.1:8000/api/v1/agents

curl -sS -H "Authorization: Bearer $TOKEN" \\
  "http://127.0.0.1:8000/api/v1/agents/<agent>/tasks?status=pending,running&order_by=queued_at&order_direction=desc&limit=50"

curl -sS -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \\
  -X POST http://127.0.0.1:8000/api/v1/agents/<agent>/tasks \\
  -d '{ "project_id": "<project_id>", "task": "Do the thing", "parent_task_id": "<task_id_optional>" }'

curl -sS -H "Authorization: Bearer $TOKEN" \\
  -X POST http://127.0.0.1:8000/api/v1/agents/<agent>/tasks/<task_id>/cancel

curl -sS -H "Authorization: Bearer $TOKEN" \\
  -X DELETE http://127.0.0.1:8000/api/v1/agents/<agent>/tasks/<task_id>

# Get agent config (includes bootstrap branch output)
curl -sS -H "Authorization: Bearer $TOKEN" \\
  http://127.0.0.1:8000/api/v1/agents/<agent>/configs/<project_id>

# Re-bootstrap agent config (like `pantheon-agents reconfig`)
curl -sS -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \\
  -X POST http://127.0.0.1:8000/api/v1/agents/<agent>/configs/<project_id>/reconfig \\
  -d '{ "role": "reviewer", "skills": ["style-reviewer"] }'

MCP (HTTP+SSE)

The MCP endpoint is exposed at /mcp (and /mcp/messages for client POSTs).

Tools:

• agents.list
• tasks.list
• tasks.get
• tasks.create
• tasks.cancel
• tasks.delete
• configs.get
• configs.reconfig