Agents

The Agents resource provides programmatic access to the same capabilities as Agent Studio. Create agents, update their configuration, assign tools, and manage their lifecycle.

Agent Configuration

An agent's configuration includes:

  • System prompt — the agent's base instructions and persona
  • Capability level — what the agent can do (read-only, standard, elevated, autonomous)
  • Tool assignments — which tools the agent has access to
  • Knowledge scope — which knowledge layers the agent can read from
  • Budget — per-interaction token budget

Lifecycle States

| State | Description | |-------|-------------| | active | Agent can receive messages and jobs | | paused | Agent exists but will not accept new work | | archived | Agent is read-only and cannot be activated |

Programmatic vs Studio

Agent configurations created via the Platform API are fully manageable through Agent Studio and vice versa. There is no distinction between agents created through either interface.

Endpoints

GET/v1/agentsComing Soon

List agents

List all agents accessible to the API key. Filter by status or team.

Parameters

NameTypeInRequiredDescription
statusstringqueryNoFilter by lifecycle state: active, paused, or archived.
team_idstringqueryNoFilter agents belonging to a specific team.

Response

{
  "agents": [
    {
      "id": "agt_01hxyz",
      "name": "Support Agent",
      "status": "active",
      "team_id": "tm_01hxyz",
      "created_at": "2026-03-01T09:00:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
POST/v1/agentsComing Soon

Create an agent

Create a new agent with the specified configuration. The agent is created in the active state by default.

Request Body

{
  "name": "string (required)",
  "system_prompt": "string (required)",
  "team_id": "string (required)",
  "capability_level": "read_only | standard | elevated | autonomous",
  "tool_ids": [
    "string"
  ],
  "budget": {
    "tokens_per_interaction": "integer"
  }
}

Response

{
  "id": "agt_01hnew",
  "name": "Research Agent",
  "status": "active",
  "team_id": "tm_01hxyz",
  "capability_level": "standard",
  "tool_ids": [
    "tool_01hxyz"
  ],
  "created_at": "2026-03-19T12:00:00Z"
}
GET/v1/agents/{agent_id}Coming Soon

Get an agent

Retrieve a single agent by ID, including its full configuration.

Parameters

NameTypeInRequiredDescription
agent_idstringpathYesThe unique identifier of the agent.

Response

{
  "id": "agt_01hxyz",
  "name": "Research Agent",
  "status": "active",
  "team_id": "tm_01hxyz",
  "system_prompt": "string",
  "capability_level": "standard",
  "tool_ids": [
    "tool_01hxyz"
  ],
  "budget": {
    "tokens_per_interaction": 8000
  },
  "created_at": "2026-03-01T09:00:00Z",
  "updated_at": "2026-03-19T10:00:00Z"
}
PATCH/v1/agents/{agent_id}Coming Soon

Update an agent

Update an agent's configuration. Only fields included in the request body are modified.

Parameters

NameTypeInRequiredDescription
agent_idstringpathYesThe unique identifier of the agent.

Request Body

{
  "name": "string (optional)",
  "system_prompt": "string (optional)",
  "status": "active | paused | archived (optional)",
  "capability_level": "read_only | standard | elevated | autonomous (optional)",
  "tool_ids": [
    "string (optional)"
  ],
  "budget": {
    "tokens_per_interaction": "integer (optional)"
  }
}

Response

{
  "id": "agt_01hxyz",
  "name": "Updated Agent Name",
  "status": "paused",
  "updated_at": "2026-03-19T13:00:00Z"
}