Skip to main content

Agents

Agents are named configurations that combine a backend, system prompt, allowed tools, and capability settings. They are the primary dispatch target for queries and MCP calls.

All read endpoints (GET /v1/agents, GET /v1/agents/{name}) require a human access token. Write operations require admin role (/admin/agents/*).

Agent object​

{
  "id": "01HXZ...",
  "name": "researcher",
  "description": "Web research agent",
  "backend": "gpt4o",
  "system_prompt": "You are a helpful research assistant.",
  "allowed_tools": ["web_search", "calculator"],
  "approval_required_tools": [],
  "model": null,
  "history_limit": null,
  "group_id": null,
  "capability_role": "worker",
  "permissions_version": 3,
  "revoked": false,
  "on_permission_change": "notify",
  "created_at": "2026-01-10T09:00:00Z",
  "updated_at": "2026-01-15T14:32:00Z"
}

GET /v1/agents​

List all agents.

curl http://localhost:8080/v1/agents \
  -H "Authorization: Bearer $ACCESS"

GET /v1/agents/{name}​

Get an agent by name.

curl http://localhost:8080/v1/agents/researcher \
  -H "Authorization: Bearer $ACCESS"

POST /admin/agents​

Create an agent. Requires admin.

Request

{
  "name": "researcher",
  "description": "Web research agent",
  "backend": "gpt4o",
  "system_prompt": "You are a helpful research assistant.",
  "allowed_tools": ["web_search"],
  "model": null
}

Response 201 — agent object.

PATCH /admin/agents/{name}​

Update agent metadata. All fields are optional (null-pointer semantics — omit to leave unchanged).

{
  "description": "Updated description",
  "system_prompt": "New prompt",
  "model": "llama3",
  "history_limit": 20,
  "group_id": "security-group"
}

Pass "backend": null explicitly to clear the backend field.

DELETE /admin/agents/{name}​

Delete an agent. Returns {"deleted": "researcher"}.

Tool management​

POST /admin/agents/{name}/tools​

Grant tools to an agent. Use ["*"] to grant all tools the requesting admin can access (bounded by user and server ceilings). Bumps permissions_version.

{ "tools": ["web_search", "calculator"] }

DELETE /admin/agents/{name}/tools​

Revoke specific tools. Body format is identical to the grant endpoint.

Revocation​

POST /admin/agents/{name}/revoke​

Revokes the agent — new token mints are blocked. The cache entry is evicted immediately.

POST /admin/agents/{name}/unrevoke​

Restores normal operation.

Approval-required tools​

PUT /admin/agents/{name}/approval-required-tools​

Requires super_admin role. Sets which tools require human approval before each invocation. An empty list restores fully-autonomous operation. Bumps permissions_version so existing agent tokens are invalidated.

{ "tools": ["send_email", "execute_code"] }

Roles​

Capability roles define named sets of tools that can be assigned to agents.

GET /v1/agents/{name}/roles​

List capability roles assigned to an agent.

POST /admin/agents/{name}/roles​

Assign a role to an agent.

{ "role": "code-executor" }

DELETE /admin/agents/{name}/roles/{role}​

Remove a role assignment. Returns 204.

Workflows​

Workflows define directed graphs of agent nodes. Read access is available at /v1/workflows; full CRUD is under /admin/workflows.

GET /v1/workflows / GET /admin/workflows​

List workflows.

POST /admin/workflows​

{ "name": "approval-pipeline", "definition": "..." }

GET /admin/workflows/{name}​

DELETE /admin/workflows/{name}​

GET /admin/workflows/{name}/graph​

Returns nodes and edges.

{
  "nodes": [{ "id": "n1", "node_type": "agent", "agent_id": "researcher", ... }],
  "edges": [{ "id": "e1", "source_node_id": "n1", "target_node_id": "n2", ... }]
}

POST /admin/workflows/{name}/graph/nodes​

Add a node.

{
  "node_type": "agent",
  "agent_id": "researcher",
  "label": "Research step",
  "position_x": 100,
  "position_y": 200
}

PATCH /admin/workflows/{name}/graph/nodes/{node_id}​

Update position, label, config, or agent.

DELETE /admin/workflows/{name}/graph/nodes/{node_id}​

POST /admin/workflows/{name}/graph/edges​

{
  "source_node_id": "n1",
  "target_node_id": "n2",
  "edge_type": "conditional",
  "condition": "output contains 'approved'"
}

DELETE /admin/workflows/{name}/graph/edges/{edge_id}​

curl examples​

# Create agent
curl -s -X POST http://localhost:8080/admin/agents \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"researcher","backend":"gpt4o","allowed_tools":["web_search"]}' | jq .

# Grant tools
curl -s -X POST http://localhost:8080/admin/agents/researcher/tools \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"tools":["calculator","file_reader"]}' | jq .

# Revoke agent
curl -s -X POST http://localhost:8080/admin/agents/researcher/revoke \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq .