Update an agent

POST /v1/agents/{agent_id}

Updates an agent. Fields you leave out keep their values.

The API applies the same checks as an edit in the Context app. You must be allowed to edit the agent, and the key’s Agent scope, if it has one, must include the agent. tools and skills replace the whole list when you send them. Every agent has one version, 1: an update changes the agent in place and does not check for edits made since you read it, so the last update wins.

If part of an update is saved and a later part is refused, the error message names the saved fields. Get the agent before you retry.

The key must be a personal key with the agents:write capability. For what each capability allows, see Keys.

Path parameters

Name	Type	Required	Default	Description
`agent_id`	`string`	Yes		The ID of the agent to update.

Body

Name	Type	Required	Description
`name`	`string`	No	The agent’s name. Must be between 1 and 100 characters after leading and trailing spaces are trimmed.
`description`	`string \| null`	No	The agent’s purpose. `null` clears it.
`system`	`string \| null`	No	The agent’s instructions. `null` clears them.
`model`	`string \| object`	No	A model ID your deployment runs, or the object form `{id}`. `default` removes the agent’s own model, so it uses your deployment’s default.
`tools`	`array<object> \| null`	No	The agent’s built-in tool settings, in the same shape as on Create an agent. Replaces the whole list. `null` or `[]` turns every built-in tool off.
`skills`	`array<object> \| null`	No	The agent’s skills, in the same shape as on Create an agent. Replaces the whole list. `null` or `[]` removes them.
`version`	`integer`	No	The agent’s version. Must be `1`. Any other value returns `400`.

Response

Returns 200 with the agent object. For every field, see Agents.

{
  "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": "Answer in one paragraph.",
  "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-21T02:10:44.918Z",
  "version": 1
}

Errors

This endpoint can return these errors as well as the common errors.

Status	`error.type`	Cause and fix
400	`invalid_request_error`	`version` is not `1`. Omit it or send `1`.
400	`invalid_request_error`	`metadata` is not empty. Omit it or send `{}`. To change an agent’s workspace, use the Context app.
400	`invalid_request_error`	A field breaks a rule of Create an agent, such as an unknown model or a custom tool. Fix the field as the matching row there describes.
400	`invalid_request_error`	The agent’s permission mode is read-only, or its permissions are a hand-written permission block, so its tools can’t be changed here. Choose another permission mode for the agent in the app first.
400	`invalid_request_error`	The tool settings you sent conflict with the agent’s permission mode or with permission rules set in the app. Change those settings in the app, or send tool settings that match them.
403	`permission_error`	This key lacks `agents:write`, is not a personal key, or its Agent scope doesn’t include this agent. Use a personal key with `agents:write` whose Agent scope, if any, includes this agent.
403	`permission_error`	You are not allowed to edit this agent. Ask its owner for access.
403	`permission_error`	A custom skill isn’t shared with the agent, and the API can’t share it for you. Name skills you own, or move the agent to the skill’s workspace in the app.
404	`not_found_error`	No agent in this key’s organization has this ID, or a custom skill you sent doesn’t exist or isn’t visible to the key’s owner. Check the IDs.

Example

curl -sS "$CONTEXT_BASE_URL/v1/agents/6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60" -H "x-api-key: $CONTEXT_API_KEY" \
  -H "content-type: application/json" -d '{"system": "Answer in one paragraph."}'

agent = client.beta.agents.update("6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", system="Answer in one paragraph.")

const agent = await client.beta.agents.update("6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", { system: "Answer in one paragraph." })