Agents

An agent is the configured worker that a session runs. You can create and edit agents in the Context app or with this API, which follows Anthropic’s Managed Agents API with the differences listed at the end of this page. An agent you create with the API appears in the Context app, and the owner of the API key owns it.

To create or update an agent, you must use a personal key with the agents:write capability.

Endpoints

Endpoint	What it does
`GET /v1/agents`	Lists the agents an API key can run, one page at a time.
`GET /v1/agents/{agent_id}`	Returns an agent that the calling API key can run.
`POST /v1/agents`	Creates an agent that the key’s owner owns.
`POST /v1/agents/{agent_id}`	Updates an agent. Fields you leave out keep their values.

The agent object

Field	Type	Description
`id`	`string`	The agent’s ID. Pass it as `agent` when you create a session.
`type`	`string`	Always `agent`.
`name`	`string`	The agent’s name, as shown in the app.
`description`	`string \| null`	The agent’s purpose. `null` when the agent has no description.
`model`	`object`	The agent’s model, as an object with one field, `id`. The ID is `default` when the agent uses your deployment’s default model.
`system`	`string \| null`	The agent’s instructions. They are returned only to a personal key with `agents:write` whose owner created the agent and still owns it. Any other key gets `null`. If the agent has no instructions, that key gets `""`.
`tools`	`array`	The agent’s built-in tools, as one `agent_toolset_20260401` entry that lists all eight tools with their `enabled` and `permission_policy`. The list is empty when every built-in tool is off.
`skills`	`array`	The agent’s skills, each `{type, skill_id, version}`. A built-in skill has `type` `anthropic` and its slug as `skill_id`. A custom skill has `type` `custom` and its skill ID. `version` is always `latest`.
`created_at`	`string`	When the agent was created, as an RFC 3339 timestamp.
`updated_at`	`string`	When the agent was last changed, as an RFC 3339 timestamp.

Each built-in tool maps to its approval setting in the app. always_allow is Allow, always_ask is Ask (each call waits for a person to approve it), and enabled: false is Deny. edit and write share one setting in the app, so they always read the same. web_search is always off, because agents search the web with your deployment’s own search tool. A tool that is off reads always_ask.

Some fields always hold the same value: version is 1, mcp_servers is empty, metadata is {} (the workspace_id sent on create is not stored), multiagent and archived_at are null, and execution_identity is {type: "service_account"}.

{
  "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60",
  "archived_at": null,
  "created_at": "2026-10-21T01:35:05.337Z",
  "description": "Answers questions about the sales pipeline",
  "execution_identity": {
    "type": "service_account"
  },
  "mcp_servers": [],
  "metadata": {},
  "model": {
    "id": "default"
  },
  "multiagent": null,
  "name": "Research Assistant",
  "skills": [
    {
      "type": "anthropic",
      "skill_id": "xlsx",
      "version": "latest"
    }
  ],
  "system": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_ask"
        }
      },
      "configs": [
        {
          "type": "bash",
          "name": "bash",
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        {
          "type": "edit",
          "name": "edit",
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        {
          "type": "read",
          "name": "read",
          "enabled": true,
          "permission_policy": {
            "type": "always_allow"
          }
        },
        {
          "type": "write",
          "name": "write",
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        {
          "type": "glob",
          "name": "glob",
          "enabled": true,
          "permission_policy": {
            "type": "always_allow"
          }
        },
        {
          "type": "grep",
          "name": "grep",
          "enabled": true,
          "permission_policy": {
            "type": "always_allow"
          }
        },
        {
          "type": "web_fetch",
          "name": "web_fetch",
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          },
          "url_sources": null
        },
        {
          "type": "web_search",
          "name": "web_search",
          "enabled": false,
          "permission_policy": {
            "type": "always_ask"
          }
        }
      ]
    }
  ],
  "type": "agent",
  "updated_at": "2026-10-21T01:35:05.337Z",
  "version": 1
}

Differences from Anthropic’s API

This API follows Anthropic’s Managed Agents API, with these differences:

The agent version and archive endpoints return 404. Every agent has one version, 1, and an update changes it in place, so a later update overwrites an earlier one without an error. In an update, version must be 1.
The model object has only an id field. effort, inference_geo and speed return 400.
system is null unless the key is a personal key with agents:write whose owner created the agent and still owns it.
tools takes only the built-in toolset. Custom tools, MCP servers, the auto permission policy and the domain and location options of the web tools return 400. web_search is always off. To give an agent MCP servers or connected accounts, set them up in the Context app.
Skills take latest as their only version.
multiagent and any execution_identity other than {type: "service_account"} return 400.
To create an agent in a workspace, send metadata.workspace_id. The anthropic-workspace-id header returns 400.

For every difference in one place, see Coming from Anthropic’s API.