Update Agent

$ ant beta:agents update

POST/v1/agents/{agent_id}

Update Agent

Parameters

--agent-id: string

Path param: Path parameter agent_id

--description: optional string

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

maxLength2048

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

Body param: 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]

Body param: 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 BetaManagedAgentsModelConfigParams { id, effort, inference_geo, speed }

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

--multiagent: optional object{ agents, type }

Body param: A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the agents roster.

--name: optional string

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

maxLength256

--skill: optional array of BetaManagedAgentsSkillParams

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

--system: optional string

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

maxLength100000

--tool: optional array of BetaManagedAgentsAgentToolset20260401Params { type, configs, default_config } or BetaManagedAgentsMCPToolsetParams { mcp_server_name, type, configs, default_config } or BetaManagedAgentsCustomToolParams { description, input_schema, name, type }

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

--version: optional number

Body param: 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 param: Optional header to specify the beta version(s) you want to use.

Returns

beta_managed_agents_agent: object{ id, archived_at, created_at, 12 more }

A Managed Agents agent.

id: string

archived_at: string

A timestamp in RFC 3339 format

formatdate-time

created_at: string

A timestamp in RFC 3339 format

formatdate-time

description: string

mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition { name, type, url }

type: "url"

url: string

metadata: map[string]

model: object{ id, effort, inference_geo, speed }

Model identifier and configuration.

id: "claude-sonnet-5" or "claude-fable-5" or "claude-opus-5" or 10 more or string

The model that will power your agent.

See models for additional details and options.

One of the following:

"claude-sonnet-5"

High-performance 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"

Fastest model with near-frontier intelligence

"claude-haiku-4-5-20251001"

Fastest model with near-frontier intelligence

"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"

High-performance model for agents and coding

"claude-sonnet-4-5-20250929"

High-performance model for agents and coding

effort: optional BetaManagedAgentsEffortLow { type } or BetaManagedAgentsEffortMedium { type } or BetaManagedAgentsEffortHigh { type } or 2 more

How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.

One of the following:

beta_managed_agents_effort_low: object{ type }

Low effort. Favors latency over reasoning depth.

type: "low"

beta_managed_agents_effort_medium: object{ type }

Medium effort. Balances latency and reasoning depth.

type: "medium"

beta_managed_agents_effort_high: object{ type }

High effort. Favors reasoning depth.

type: "high"

beta_managed_agents_effort_xhigh: object{ type }

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

type: "xhigh"

beta_managed_agents_effort_max: object{ type }

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. Not all models support fast; invalid combinations are rejected at create time.

One of the following:

"standard"

"fast"

multiagent: object{ agents, type }

Resolved coordinator topology with a concrete agent roster.

agents: array of BetaManagedAgentsAgentReference { id, type, version } or BetaManagedAgentsAdvisor { model, type }

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

One of the following:

beta_managed_agents_agent_reference: object{ id, type, version }

A resolved agent reference with a concrete version.

id: string

type: "agent"

version: number

formatint32

beta_managed_agents_advisor: object{ model, type }

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

model: string

The advisor model id.

type: "advisor"

type: "coordinator"

skills: array of BetaManagedAgentsAnthropicSkill { skill_id, type, version } or BetaManagedAgentsCustomSkill { skill_id, type, version }

One of the following:

beta_managed_agents_anthropic_skill: object{ skill_id, type, version }

A resolved Anthropic-managed skill.

skill_id: string

type: "anthropic"

version: string

beta_managed_agents_custom_skill: object{ skill_id, type, version }

A resolved user-created custom skill.

skill_id: string

type: "custom"

version: string

system: string

tools: array of BetaManagedAgentsAgentToolset20260401 { configs, default_config, type } or BetaManagedAgentsMCPToolset { configs, default_config, mcp_server_name, type } or BetaManagedAgentsCustomTool { description, input_schema, name, type }

One of the following:

beta_managed_agents_agent_toolset20260401: object{ configs, default_config, type }

beta_managed_agents_mcp_toolset: object{ configs, default_config, mcp_server_name, type }

beta_managed_agents_custom_tool: object{ description, input_schema, name, type }

A custom tool as returned in API responses.

description: string

input_schema: object{ type, properties, required }

JSON Schema for custom tool input parameters.

type: "object"

properties: optional map[unknown]

required: optional array of string

type: "custom"

type: "agent"

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

{
  "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",
    "effort": {
      "type": "low"
    },
    "inference_geo": "inference_geo",
    "speed": "standard"
  },
  "multiagent": {
    "agents": [
      {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "type": "agent",
        "version": 1
      }
    ],
    "type": "coordinator"
  },
  "name": "My First Agent",
  "skills": [
    {
      "skill_id": "xlsx",
      "type": "anthropic",
      "version": "1"
    },
    {
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "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
}

Returns Examples

{
  "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",
    "effort": {
      "type": "low"
    },
    "inference_geo": "inference_geo",
    "speed": "standard"
  },
  "multiagent": {
    "agents": [
      {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "type": "agent",
        "version": 1
      }
    ],
    "type": "coordinator"
  },
  "name": "My First Agent",
  "skills": [
    {
      "skill_id": "xlsx",
      "type": "anthropic",
      "version": "1"
    },
    {
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "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
}