Claude Platform Docs

Update Agent

$ ant beta:agents update
POST/v1/agents/{agent_id}

Update Agent

Parameters
--agent-id: string⁠Path parameter

Unique identifier of the agent to update.

--description: optional string

Description. Omit to preserve; send empty string or null to clear.

maxLength2048
--mcp-server: optional array of BetaManagedAgentsURLMCPServerParams { type: "url", name, url }

MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. Every server must be referenced by an mcp_toolset in the agent's resulting tools; unreferenced servers are rejected. See the MCP connector guide.

--metadata: optional map[string]

Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars.

--model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams

Model identifier. Accepts the model string, e.g. claude-opus-5-5, or a model_config object for additional configuration control. Omit to preserve. Cannot be cleared.

--multiagent: optional BetaManagedAgentsMultiagentCoordinatorParams or BetaManagedAgentsMultiagent20261001Params

Multiagent orchestration configuration. Full replacement. Omit to preserve; send null to clear.

--name: optional string

Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.

maxLength256
--skill: optional array of BetaManagedAgentsSkillParams

Skills. Full replacement. Omit to preserve; send empty array or null to clear.

--system: optional string

System prompt. Omit to preserve; send empty string or null to clear.

maxLength100000
--tool: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams

Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 256 tools across all toolsets allowed.

--version: optional number

The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. Must be at least 1 if specified. When supplied, the request fails if it does not match the server's current version; omit to apply the update unconditionally.

formatint32
--beta: optional array of AnthropicBeta⁠Header parameter

Optional header to specify the beta version(s) you want to use.

--workspace-id: optional string⁠Header parameter

Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).

Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

Returns
beta_managed_agents_agent: object{ type: "agent", id, archived_at, 12 more }

A Managed Agents agent.

type: "agent"
id: string
archived_at: string

When the agent was archived. Null if not archived.

formatdate-time
created_at: string

A timestamp in RFC 3339 format

formatdate-time
description: string
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition { type: "url", name, url }
type: "url"
name: string
url: string
metadata: map[string]
model: object{ id, effort, inference_geo, speed }

Model identifier and configuration.

id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string

The model that will power your agent.

See models for additional details and options.

One of the following:
"claude-haiku-5-5"

Fastest model for high-volume, real-time tasks

"claude-sonnet-5-5"

Efficient model for coding and agents

"claude-opus-5-5"

Powerful intelligence for coding, knowledge work, and long-running agents

"claude-fable-5-1"

Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows

"claude-sonnet-5"

Efficient model for coding and agents

"claude-fable-5"

Next generation of intelligence for the hardest knowledge work and coding problems

"claude-opus-5"

Powerful intelligence for long-running agents and coding

"claude-opus-4-8"

Powerful intelligence for long-running agents and coding

"claude-opus-4-7"

Powerful intelligence for long-running agents and coding

"claude-opus-4-6"

Powerful intelligence for long-running agents and coding

"claude-sonnet-4-6"

Best combination of speed and intelligence

"claude-haiku-4-5"
"claude-haiku-4-5-20251001"
"claude-opus-4-5"

Powerful intelligence for long-running agents and coding

"claude-opus-4-5-20251101"

Powerful intelligence for long-running agents and coding

"claude-sonnet-4-5"⁠Deprecated

High-performance model for agents and coding

Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.
"claude-sonnet-4-5-20250929"⁠Deprecated

High-performance model for agents and coding

Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more

How hard Claude works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.

One of the following:
beta_managed_agents_effort_low: object{ type: "low" }

Low effort. Favors latency over reasoning depth.

type: "low"
beta_managed_agents_effort_medium: object{ type: "medium" }

Medium effort. Balances latency and reasoning depth.

type: "medium"
beta_managed_agents_effort_high: object{ type: "high" }

High effort. Favors reasoning depth.

type: "high"
beta_managed_agents_effort_xhigh: object{ type: "xhigh" }

Extra-high effort. Not all models accept this level.

type: "xhigh"
beta_managed_agents_effort_max: object{ type: "max" }

Maximum effort. Favors reasoning depth over latency.

type: "max"
inference_geo: optional string

Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.

speed: optional "standard" or "fast"

Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.

One of the following:
"standard"
"fast"
multiagent: BetaManagedAgentsMultiagentCoordinator or BetaManagedAgentsMultiagent20261001

Multiagent orchestration configuration. Null when the agent is single-threaded.

One of the following:
beta_managed_agents_multiagent_coordinator: object{ type: "coordinator", agents }

Resolved coordinator topology with a concrete agent roster.

type: "coordinator"
agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor

Agents the coordinator may spawn as session threads, each resolved to a specific version.

One of the following:
beta_managed_agents_agent_reference: object{ type: "agent", id, version }

A resolved agent reference with a concrete version.

type: "agent"
id: string
version: number
formatint32
beta_managed_agents_advisor: object{ type: "advisor", model }

Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

type: "advisor"
model: string

The advisor model id.

beta_managed_agents_multiagent20261001: object{ type: "multiagent_20261001", advisor, subagents, workflows }

Resolved multiagent configuration with three members, each enabled or disabled on its own.

type: "multiagent_20261001"
advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled

Whether the session's primary thread can consult an advisor model.

One of the following:
beta_managed_agents_multiagent_advisor_enabled: object{ type: "enabled", model }

The session's primary thread can consult model mid-turn.

type: "enabled"
model: string

The advisor model id.

beta_managed_agents_multiagent_advisor_disabled: object{ type: "disabled" }

The agent has no advisor.

type: "disabled"
subagents: BetaManagedAgentsMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled

Whether the agent can spawn session threads.

One of the following:
beta_managed_agents_multiagent_subagents_enabled: object{ type: "enabled", inline_agents, predefined_agents }

The agent can spawn session threads.

type: "enabled"
inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled

Whether the agent can define inline agents, which are not saved, when it spawns session threads.

One of the following:
beta_managed_agents_multiagent_inline_agents_enabled: object{ type: "enabled" }

The agent can define inline agents.

type: "enabled"
beta_managed_agents_multiagent_inline_agents_disabled: object{ type: "disabled" }

The agent cannot define inline agents.

type: "disabled"
predefined_agents: array of BetaManagedAgentsAgentReference { type: "agent", id, version }

Predefined agents, which are saved agents that this agent can spawn as session threads, each resolved to a specific version.

type: "agent"
id: string
version: number
formatint32
beta_managed_agents_multiagent_subagents_disabled: object{ type: "disabled" }

The agent cannot spawn session threads.

type: "disabled"
workflows: BetaManagedAgentsMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled

Whether the agent can start workflow runs.

One of the following:
beta_managed_agents_multiagent_workflows_enabled: object{ type: "enabled", inline_agents, predefined_agents }

The agent can start workflow runs.

type: "enabled"
inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled

Whether a run's plan can define inline agents, which are not saved.

One of the following:
beta_managed_agents_multiagent_inline_agents_enabled: object{ type: "enabled" }

The agent can define inline agents.

type: "enabled"
beta_managed_agents_multiagent_inline_agents_disabled: object{ type: "disabled" }

The agent cannot define inline agents.

type: "disabled"
predefined_agents: array of BetaManagedAgentsAgentReference { type: "agent", id, version }

Predefined agents, which are saved agents that a run's plan can use, each resolved to a specific version.

type: "agent"
id: string
version: number
formatint32
beta_managed_agents_multiagent_workflows_disabled: object{ type: "disabled" }

The agent cannot start workflow runs.

type: "disabled"
name: string
skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill
One of the following:
beta_managed_agents_anthropic_skill: object{ type: "anthropic", skill_id, version }

A resolved Anthropic-managed skill.

type: "anthropic"
skill_id: string
version: string
beta_managed_agents_custom_skill: object{ type: "custom", skill_id, version }

A resolved user-created custom skill.

type: "custom"
skill_id: string
version: string
system: string
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
One of the following:
beta_managed_agents_agent_toolset20260401: object{ type: "agent_toolset_20260401", configs, default_config }
beta_managed_agents_mcp_toolset: object{ type: "mcp_toolset", configs, default_config, mcp_server_name }
beta_managed_agents_custom_tool: object{ type: "custom", description, input_schema, name }

A custom tool as returned in API responses.

type: "custom"
description: string
input_schema: object{ type: "object", properties, required }

JSON Schema for custom tool input parameters.

type: "object"
properties: optional map[unknown]
required: optional array of string
name: string
updated_at: string

A timestamp in RFC 3339 format

formatdate-time
version: number

The agent's current version. Starts at 1 and increments when the agent is modified.

formatint32
Update Agent
ant beta:agents update \
  --api-key my-anthropic-api-key \
  --agent-id agent_011CZkYpogX7uDKUyvBTophP
Returns Examples
Response 200
{
  "id": "agent_011CZkYpogX7uDKUyvBTophP",
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "description": "A general-purpose starter agent.",
  "mcp_servers": [
    {
      "name": "example-mcp",
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse"
    }
  ],
  "metadata": {
    "foo": "bar"
  },
  "model": {
    "id": "claude-opus-5-5",
    "effort": {
      "type": "low"
    },
    "inference_geo": "inference_geo",
    "speed": "standard"
  },
  "multiagent": {
    "advisor": {
      "type": "disabled"
    },
    "subagents": {
      "inline_agents": {
        "type": "enabled"
      },
      "predefined_agents": [
        {
          "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
          "type": "agent",
          "version": 1
        }
      ],
      "type": "enabled"
    },
    "type": "multiagent_20261001",
    "workflows": {
      "inline_agents": {
        "type": "enabled"
      },
      "predefined_agents": [
        {
          "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
          "type": "agent",
          "version": 1
        }
      ],
      "type": "enabled"
    }
  },
  "name": "My First Agent",
  "skills": [
    {
      "skill_id": "xlsx",
      "type": "anthropic",
      "version": "1"
    },
    {
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx",
      "type": "custom",
      "version": "2"
    }
  ],
  "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
  "tools": [
    {
      "configs": [
        {
          "enabled": true,
          "name": "bash",
          "permission_policy": {
            "type": "always_allow"
          },
          "type": "bash"
        }
      ],
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_ask"
        }
      },
      "type": "agent_toolset_20260401"
    }
  ],
  "type": "agent",
  "updated_at": "2026-03-15T10:00:00Z",
  "version": 1
}