Repository Public
1---2title: Update Agent3url: https://platform.claude.com/docs/en/api/beta/agents/update4---56# Update Agent78**POST** `/v1/agents/{agent_id}`910Update Agent1112## Path parameters1314- `agent_id: string`1516## Headers1718- `"anthropic-beta": optional array of AnthropicBeta`1920 Optional header to specify the beta version(s) you want to use.2122 - `string`2324 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`2526 - `"message-batches-2024-09-24"`2728 - `"prompt-caching-2024-07-31"`2930 - `"computer-use-2024-10-22"`3132 - `"computer-use-2025-01-24"`3334 - `"pdfs-2024-09-25"`3536 - `"token-counting-2024-11-01"`3738 - `"token-efficient-tools-2025-02-19"`3940 - `"output-128k-2025-02-19"`4142 - `"files-api-2025-04-14"`4344 - `"mcp-client-2025-04-04"`4546 - `"mcp-client-2025-11-20"`4748 - `"dev-full-thinking-2025-05-14"`4950 - `"interleaved-thinking-2025-05-14"`5152 - `"code-execution-2025-05-22"`5354 - `"extended-cache-ttl-2025-04-11"`5556 - `"context-1m-2025-08-07"`5758 - `"context-management-2025-06-27"`5960 - `"model-context-window-exceeded-2025-08-26"`6162 - `"skills-2025-10-02"`6364 - `"fast-mode-2026-02-01"`6566 - `"output-300k-2026-03-24"`6768 - `"user-profiles-2026-03-24"`6970 - `"user-profiles-2026-08-18"`7172 - `"user-profiles-2026-09-04"`7374 - `"advisor-tool-2026-03-01"`7576 - `"managed-agents-2026-04-01"`7778 - `"cache-diagnosis-2026-04-07"`7980 - `"dreaming-2026-04-21"`8182 - `"thinking-token-count-2026-05-13"`8384 - `"server-side-fallback-2026-06-01"`8586 - `"server-side-fallback-2026-07-01"`8788 - `"fallback-credit-2026-06-01"`8990 - `"fallback-credit-2026-07-01"`9192 - `"agent-memory-2026-07-22"`9394 - `"mid-conversation-tool-changes-2026-07-01"`9596 - `"compact-2026-01-12"`9798 - `"computer-use-2025-11-24"`99100 - `"mcp-tunnels-2026-06-22"`101102 - `"structured-outputs-2025-11-13"`103104 - `"task-budgets-2026-03-13"`105106 - `"thinking-display-updates-2026-08-18"`107108 - `"ce-user-management-2026-07-13"`109110 - `"mid-conversation-output-config-2026-07-01"`111112 - `"thinking-binding-controls-2026-08-01"`113114 - `"mid-conversation-system-clear-at-2026-08-21"`115116 - `"compact-2026-09-04"`117118- `"anthropic-workspace-id": optional string`119120## Body parameters121122- `description: optional string or null`123124 Description. Omit to preserve; send empty string or null to clear.125126 maxLength: 2048127128- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams or null`129130 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](https://platform.claude.com/docs/en/managed-agents/mcp-connector).131132 - `type: "url"`133134 - `name: string`135136 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.137138 minLength: 1, maxLength: 255139140 - `url: string`141142 Endpoint URL for the MCP server.143144 maxLength: 2048145146- `metadata: optional map[string] or null`147148 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.149150- `model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams`151152 Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-5`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared.153154 - `BetaManagedAgentsModel = "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more or string`155156 The model that will power your agent.157158 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.159160 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`161162 The model that will power your agent.163164 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.165166 - `"claude-fable-5-1"`167168 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows169170 - `"claude-sonnet-5"`171172 High-performance model for coding and agents173174 - `"claude-fable-5"`175176 Next generation of intelligence for the hardest knowledge work and coding problems177178 - `"claude-opus-5"`179180 Powerful intelligence for long-running agents and coding181182 - `"claude-opus-4-8"`183184 Powerful intelligence for long-running agents and coding185186 - `"claude-opus-4-7"`187188 Powerful intelligence for long-running agents and coding189190 - `"claude-opus-4-6"`191192 Powerful intelligence for long-running agents and coding193194 - `"claude-sonnet-4-6"`195196 Best combination of speed and intelligence197198 - `"claude-haiku-4-5"`199200 Fastest model with near-frontier intelligence201202 - `"claude-haiku-4-5-20251001"`203204 Fastest model with near-frontier intelligence205206 - `"claude-opus-4-5"`207208 Powerful intelligence for long-running agents and coding209210 - `"claude-opus-4-5-20251101"`211212 Powerful intelligence for long-running agents and coding213214 - `"claude-sonnet-4-5"`215216 High-performance model for agents and coding217218 - `"claude-sonnet-4-5-20250929"`219220 High-performance model for agents and coding221222 - `string`223224 - `BetaManagedAgentsModelConfigParams object`225226 An object that defines additional configuration control over model use227228 - `id: BetaManagedAgentsModel`229230 The model that will power your agent.231232 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.233234 - `effort: optional "low" or "medium" or "high" or 2 more or BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or 3 more or null`235236 How hard Claude works on each inference call. Accepts a bare level string (`"high"`) or `{"type": "high"}`. On create, omitting it resolves the per-model default; on update, omitting it leaves the stored value unchanged.237238 - `BetaManagedAgentsEffortLevel = "low" or "medium" or "high" or 2 more`239240 How hard Claude works on each turn. Higher levels favor reasoning depth over latency. Not all models accept every level; invalid combinations are rejected at create time.241242 - `"low"`243244 - `"medium"`245246 - `"high"`247248 - `"xhigh"`249250 - `"max"`251252 - `BetaManagedAgentsEffortLow object`253254 Low effort. Favors latency over reasoning depth.255256 - `type: "low"`257258 - `BetaManagedAgentsEffortMedium object`259260 Medium effort. Balances latency and reasoning depth.261262 - `type: "medium"`263264 - `BetaManagedAgentsEffortHigh object`265266 High effort. Favors reasoning depth.267268 - `type: "high"`269270 - `BetaManagedAgentsEffortXhigh object`271272 Extra-high effort. Not all models accept this level.273274 - `type: "xhigh"`275276 - `BetaManagedAgentsEffortMax object`277278 Maximum effort. Favors reasoning depth over latency.279280 - `type: "max"`281282 - `inference_geo: optional string or null`283284 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it.285286 - `speed: optional "standard" or "fast" or null`287288 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.289290 - `"standard"`291292 - `"fast"`293294- `multiagent: optional BetaManagedAgentsMultiagentParams or null`295296 A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster.297298 - `type: "coordinator"`299300 - `agents: array of BetaManagedAgentsMultiagentRosterEntryParams`301302 Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1).303304 - `string`305306 - `BetaManagedAgentsAgentParams object`307308 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version309310 - `type: "agent"`311312 - `id: string`313314 The `agent` ID.315316 minLength: 1, maxLength: 128317318 - `version: optional number`319320 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.321322 format: int32323324 - `BetaManagedAgentsMultiagentSelfParams object`325326 Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.327328 - `type: "self"`329330 - `BetaManagedAgentsAdvisorParams object`331332 Platform advisor roster entry: a model the session's primary thread may consult mid-turn. At most one per roster; the entry occupies the roster name `anthropic.advisor`.333334 - `type: "advisor"`335336 - `model: string`337338 A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.339340 minLength: 1, maxLength: 256341342- `name: optional string`343344 Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.345346 maxLength: 256347348- `skills: optional array of BetaManagedAgentsSkillParams or null`349350 Skills. Full replacement. Omit to preserve; send empty array or null to clear.351352 - `BetaManagedAgentsAnthropicSkillParams object`353354 An Anthropic-managed skill.355356 - `type: "anthropic"`357358 - `skill_id: string`359360 Identifier of the Anthropic skill (e.g., "xlsx").361362 minLength: 1, maxLength: 64363364 - `version: optional string or null`365366 Version to pin. Defaults to latest if omitted.367368 minLength: 1, maxLength: 64369370 - `BetaManagedAgentsCustomSkillParams object`371372 A user-created custom skill.373374 - `type: "custom"`375376 - `skill_id: string`377378 Tagged ID of the custom skill (e.g., "skill_01XJ5...").379380 minLength: 1, maxLength: 64381382 - `version: optional string or null`383384 Version to pin. Defaults to latest if omitted.385386 minLength: 1, maxLength: 64387388- `system: optional string or null`389390 System prompt. Omit to preserve; send empty string or null to clear.391392 maxLength: 100000393394- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams or null`395396 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.397398 - `BetaManagedAgentsAgentToolset20260401Params object`399400 Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.401402 - `type: "agent_toolset_20260401"`403404 - `configs: optional array of BetaManagedAgentsAgentToolConfigParams`405406 Per-tool configuration overrides.407408 - `BetaManagedAgentsBashToolConfigParams object`409410 Configuration override for the bash tool.411412 - `type: optional "bash"`413414 - `name: "bash"`415416 Must be "bash".417418 - `enabled: optional boolean or null`419420 Whether this tool is enabled and available to Claude. Overrides the default_config setting.421422 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`423424 Permission policy for tool execution.425426 - `BetaManagedAgentsAlwaysAllowPolicy object`427428 Tool calls are automatically approved without user confirmation.429430 - `type: "always_allow"`431432 - `BetaManagedAgentsAlwaysAskPolicy object`433434 Tool calls require user confirmation before execution.435436 - `type: "always_ask"`437438 - `BetaManagedAgentsAutoPolicy object`439440 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.441442 - `type: "auto"`443444 - `BetaManagedAgentsEditToolConfigParams object`445446 Configuration override for the edit tool.447448 - `type: optional "edit"`449450 - `name: "edit"`451452 Must be "edit".453454 - `enabled: optional boolean or null`455456 Whether this tool is enabled and available to Claude. Overrides the default_config setting.457458 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`459460 Permission policy for tool execution.461462 - `BetaManagedAgentsAlwaysAllowPolicy object`463464 Tool calls are automatically approved without user confirmation.465466 - `BetaManagedAgentsAlwaysAskPolicy object`467468 Tool calls require user confirmation before execution.469470 - `BetaManagedAgentsAutoPolicy object`471472 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.473474 - `BetaManagedAgentsReadToolConfigParams object`475476 Configuration override for the read tool.477478 - `type: optional "read"`479480 - `name: "read"`481482 Must be "read".483484 - `enabled: optional boolean or null`485486 Whether this tool is enabled and available to Claude. Overrides the default_config setting.487488 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`489490 Permission policy for tool execution.491492 - `BetaManagedAgentsAlwaysAllowPolicy object`493494 Tool calls are automatically approved without user confirmation.495496 - `BetaManagedAgentsAlwaysAskPolicy object`497498 Tool calls require user confirmation before execution.499500 - `BetaManagedAgentsAutoPolicy object`501502 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.503504 - `BetaManagedAgentsWriteToolConfigParams object`505506 Configuration override for the write tool.507508 - `type: optional "write"`509510 - `name: "write"`511512 Must be "write".513514 - `enabled: optional boolean or null`515516 Whether this tool is enabled and available to Claude. Overrides the default_config setting.517518 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`519520 Permission policy for tool execution.521522 - `BetaManagedAgentsAlwaysAllowPolicy object`523524 Tool calls are automatically approved without user confirmation.525526 - `BetaManagedAgentsAlwaysAskPolicy object`527528 Tool calls require user confirmation before execution.529530 - `BetaManagedAgentsAutoPolicy object`531532 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.533534 - `BetaManagedAgentsGlobToolConfigParams object`535536 Configuration override for the glob tool.537538 - `type: optional "glob"`539540 - `name: "glob"`541542 Must be "glob".543544 - `enabled: optional boolean or null`545546 Whether this tool is enabled and available to Claude. Overrides the default_config setting.547548 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`549550 Permission policy for tool execution.551552 - `BetaManagedAgentsAlwaysAllowPolicy object`553554 Tool calls are automatically approved without user confirmation.555556 - `BetaManagedAgentsAlwaysAskPolicy object`557558 Tool calls require user confirmation before execution.559560 - `BetaManagedAgentsAutoPolicy object`561562 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.563564 - `BetaManagedAgentsGrepToolConfigParams object`565566 Configuration override for the grep tool.567568 - `type: optional "grep"`569570 - `name: "grep"`571572 Must be "grep".573574 - `enabled: optional boolean or null`575576 Whether this tool is enabled and available to Claude. Overrides the default_config setting.577578 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`579580 Permission policy for tool execution.581582 - `BetaManagedAgentsAlwaysAllowPolicy object`583584 Tool calls are automatically approved without user confirmation.585586 - `BetaManagedAgentsAlwaysAskPolicy object`587588 Tool calls require user confirmation before execution.589590 - `BetaManagedAgentsAutoPolicy object`591592 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.593594 - `BetaManagedAgentsWebFetchToolConfigParams object`595596 Configuration override for the web_fetch tool.597598 - `type: optional "web_fetch"`599600 - `name: "web_fetch"`601602 Must be "web_fetch".603604 - `allowed_domains: optional array of string`605606 Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.607608 - `blocked_domains: optional array of string`609610 Never fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.611612 - `enabled: optional boolean or null`613614 Whether this tool is enabled and available to Claude. Overrides the default_config setting.615616 - `max_content_tokens: optional number or null`617618 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.619620 format: int32621622 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`623624 Permission policy for tool execution.625626 - `BetaManagedAgentsAlwaysAllowPolicy object`627628 Tool calls are automatically approved without user confirmation.629630 - `BetaManagedAgentsAlwaysAskPolicy object`631632 Tool calls require user confirmation before execution.633634 - `BetaManagedAgentsAutoPolicy object`635636 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.637638 - `BetaManagedAgentsWebSearchToolConfigParams object`639640 Configuration override for the web_search tool.641642 - `type: optional "web_search"`643644 - `name: "web_search"`645646 Must be "web_search".647648 - `allowed_domains: optional array of string`649650 Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.651652 - `blocked_domains: optional array of string`653654 Never return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.655656 - `enabled: optional boolean or null`657658 Whether this tool is enabled and available to Claude. Overrides the default_config setting.659660 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`661662 Permission policy for tool execution.663664 - `BetaManagedAgentsAlwaysAllowPolicy object`665666 Tool calls are automatically approved without user confirmation.667668 - `BetaManagedAgentsAlwaysAskPolicy object`669670 Tool calls require user confirmation before execution.671672 - `BetaManagedAgentsAutoPolicy object`673674 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.675676 - `user_location: optional BetaManagedAgentsUserLocation or null`677678 Approximate user location for search result localization.679680 - `type: "approximate"`681682 Location precision. Only "approximate" is supported.683684 - `city: optional string or null`685686 City name.687688 minLength: 1, maxLength: 255689690 - `country: optional string or null`691692 Two-letter ISO 3166-1 country code, uppercase.693694 - `region: optional string or null`695696 Region or state name.697698 minLength: 1, maxLength: 255699700 - `timezone: optional string or null`701702 IANA timezone identifier, e.g. "America/Los_Angeles".703704 minLength: 1, maxLength: 255705706 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null`707708 Default configuration for all tools in a toolset.709710 - `enabled: optional boolean or null`711712 Whether tools are enabled and available to Claude by default. Defaults to true if not specified.713714 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`715716 Permission policy for tool execution.717718 - `BetaManagedAgentsAlwaysAllowPolicy object`719720 Tool calls are automatically approved without user confirmation.721722 - `BetaManagedAgentsAlwaysAskPolicy object`723724 Tool calls require user confirmation before execution.725726 - `BetaManagedAgentsAutoPolicy object`727728 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.729730 - `BetaManagedAgentsMCPToolsetParams object`731732 Configuration for tools from an MCP server defined in `mcp_servers`.733734 - `type: "mcp_toolset"`735736 - `mcp_server_name: string`737738 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.739740 minLength: 1, maxLength: 255741742 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`743744 Per-tool configuration overrides.745746 - `name: string`747748 Name of the MCP tool to configure. 1-128 characters.749750 minLength: 1, maxLength: 128751752 - `enabled: optional boolean or null`753754 Whether this tool is enabled. Overrides the `default_config` setting.755756 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`757758 Permission policy for tool execution.759760 - `BetaManagedAgentsAlwaysAllowPolicy object`761762 Tool calls are automatically approved without user confirmation.763764 - `BetaManagedAgentsAlwaysAskPolicy object`765766 Tool calls require user confirmation before execution.767768 - `BetaManagedAgentsAutoPolicy object`769770 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.771772 - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null`773774 Default configuration for all tools from an MCP server.775776 - `enabled: optional boolean or null`777778 Whether tools are enabled by default. Defaults to true if not specified.779780 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`781782 Permission policy for tool execution.783784 - `BetaManagedAgentsAlwaysAllowPolicy object`785786 Tool calls are automatically approved without user confirmation.787788 - `BetaManagedAgentsAlwaysAskPolicy object`789790 Tool calls require user confirmation before execution.791792 - `BetaManagedAgentsAutoPolicy object`793794 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.795796 - `BetaManagedAgentsCustomToolParams object`797798 A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event.799800 - `type: "custom"`801802 - `description: string`803804 Description of what the tool does, shown to the agent to help it decide when to use the tool.805806 minLength: 1807808 - `input_schema: BetaManagedAgentsCustomToolInputSchema`809810 JSON Schema for custom tool input parameters.811812 - `type: "object"`813814 - `properties: optional map[unknown] or null`815816 - `required: optional array of string or null`817818 - `name: string`819820 Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.821822 minLength: 1, maxLength: 128823824- `version: optional number`825826 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.827828 format: int32829830## Returns831832- `BetaManagedAgentsAgent object`833834 A Managed Agents `agent`.835836 - `type: "agent"`837838 - `id: string`839840 - `archived_at: string or null`841842 A timestamp in RFC 3339 format843844 format: date-time845846 - `created_at: string`847848 A timestamp in RFC 3339 format849850 format: date-time851852 - `description: string or null`853854 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`855856 - `type: "url"`857858 - `name: string`859860 - `url: string`861862 - `metadata: map[string]`863864 - `model: BetaManagedAgentsModelConfig`865866 Model identifier and configuration.867868 - `id: BetaManagedAgentsModel`869870 The model that will power your agent.871872 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.873874 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`875876 The model that will power your agent.877878 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.879880 - `"claude-fable-5-1"`881882 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows883884 - `"claude-sonnet-5"`885886 High-performance model for coding and agents887888 - `"claude-fable-5"`889890 Next generation of intelligence for the hardest knowledge work and coding problems891892 - `"claude-opus-5"`893894 Powerful intelligence for long-running agents and coding895896 - `"claude-opus-4-8"`897898 Powerful intelligence for long-running agents and coding899900 - `"claude-opus-4-7"`901902 Powerful intelligence for long-running agents and coding903904 - `"claude-opus-4-6"`905906 Powerful intelligence for long-running agents and coding907908 - `"claude-sonnet-4-6"`909910 Best combination of speed and intelligence911912 - `"claude-haiku-4-5"`913914 Fastest model with near-frontier intelligence915916 - `"claude-haiku-4-5-20251001"`917918 Fastest model with near-frontier intelligence919920 - `"claude-opus-4-5"`921922 Powerful intelligence for long-running agents and coding923924 - `"claude-opus-4-5-20251101"`925926 Powerful intelligence for long-running agents and coding927928 - `"claude-sonnet-4-5"`929930 High-performance model for agents and coding931932 - `"claude-sonnet-4-5-20250929"`933934 High-performance model for agents and coding935936 - `string`937938 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`939940 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.941942 - `BetaManagedAgentsEffortLow object`943944 Low effort. Favors latency over reasoning depth.945946 - `type: "low"`947948 - `BetaManagedAgentsEffortMedium object`949950 Medium effort. Balances latency and reasoning depth.951952 - `type: "medium"`953954 - `BetaManagedAgentsEffortHigh object`955956 High effort. Favors reasoning depth.957958 - `type: "high"`959960 - `BetaManagedAgentsEffortXhigh object`961962 Extra-high effort. Not all models accept this level.963964 - `type: "xhigh"`965966 - `BetaManagedAgentsEffortMax object`967968 Maximum effort. Favors reasoning depth over latency.969970 - `type: "max"`971972 - `inference_geo: optional string`973974 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.975976 - `speed: optional "standard" or "fast"`977978 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.979980 - `"standard"`981982 - `"fast"`983984 - `multiagent: BetaManagedAgentsMultiagent or null`985986 Resolved coordinator topology with a concrete agent roster.987988 - `type: "coordinator"`989990 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`991992 Agents the coordinator may spawn as session threads, each resolved to a specific version.993994 - `BetaManagedAgentsAgentReference object`995996 A resolved agent reference with a concrete version.997998 - `type: "agent"`9991000 - `id: string`10011002 - `version: number`10031004 format: int3210051006 - `BetaManagedAgentsAdvisor object`10071008 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.10091010 - `type: "advisor"`10111012 - `model: string`10131014 The advisor model id.10151016 - `name: string`10171018 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`10191020 - `BetaManagedAgentsAnthropicSkill object`10211022 A resolved Anthropic-managed skill.10231024 - `type: "anthropic"`10251026 - `skill_id: string`10271028 - `version: string`10291030 - `BetaManagedAgentsCustomSkill object`10311032 A resolved user-created custom skill.10331034 - `type: "custom"`10351036 - `skill_id: string`10371038 - `version: string`10391040 - `system: string or null`10411042 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`10431044 - `BetaManagedAgentsAgentToolset20260401 object`10451046 - `type: "agent_toolset_20260401"`10471048 - `configs: array of BetaManagedAgentsAgentToolConfig`10491050 - `BetaManagedAgentsBashToolConfig object`10511052 Configuration for the bash tool.10531054 - `type: "bash"`10551056 - `enabled: boolean`10571058 - `name: "bash"`10591060 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`10611062 Permission policy for tool execution.10631064 - `BetaManagedAgentsAlwaysAllowPolicy object`10651066 Tool calls are automatically approved without user confirmation.10671068 - `type: "always_allow"`10691070 - `BetaManagedAgentsAlwaysAskPolicy object`10711072 Tool calls require user confirmation before execution.10731074 - `type: "always_ask"`10751076 - `BetaManagedAgentsAutoPolicy object`10771078 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.10791080 - `type: "auto"`10811082 - `BetaManagedAgentsEditToolConfig object`10831084 Configuration for the edit tool.10851086 - `type: "edit"`10871088 - `enabled: boolean`10891090 - `name: "edit"`10911092 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`10931094 Permission policy for tool execution.10951096 - `BetaManagedAgentsAlwaysAllowPolicy object`10971098 Tool calls are automatically approved without user confirmation.10991100 - `BetaManagedAgentsAlwaysAskPolicy object`11011102 Tool calls require user confirmation before execution.11031104 - `BetaManagedAgentsAutoPolicy object`11051106 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.11071108 - `BetaManagedAgentsReadToolConfig object`11091110 Configuration for the read tool.11111112 - `type: "read"`11131114 - `enabled: boolean`11151116 - `name: "read"`11171118 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`11191120 Permission policy for tool execution.11211122 - `BetaManagedAgentsAlwaysAllowPolicy object`11231124 Tool calls are automatically approved without user confirmation.11251126 - `BetaManagedAgentsAlwaysAskPolicy object`11271128 Tool calls require user confirmation before execution.11291130 - `BetaManagedAgentsAutoPolicy object`11311132 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.11331134 - `BetaManagedAgentsWriteToolConfig object`11351136 Configuration for the write tool.11371138 - `type: "write"`11391140 - `enabled: boolean`11411142 - `name: "write"`11431144 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`11451146 Permission policy for tool execution.11471148 - `BetaManagedAgentsAlwaysAllowPolicy object`11491150 Tool calls are automatically approved without user confirmation.11511152 - `BetaManagedAgentsAlwaysAskPolicy object`11531154 Tool calls require user confirmation before execution.11551156 - `BetaManagedAgentsAutoPolicy object`11571158 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.11591160 - `BetaManagedAgentsGlobToolConfig object`11611162 Configuration for the glob tool.11631164 - `type: "glob"`11651166 - `enabled: boolean`11671168 - `name: "glob"`11691170 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`11711172 Permission policy for tool execution.11731174 - `BetaManagedAgentsAlwaysAllowPolicy object`11751176 Tool calls are automatically approved without user confirmation.11771178 - `BetaManagedAgentsAlwaysAskPolicy object`11791180 Tool calls require user confirmation before execution.11811182 - `BetaManagedAgentsAutoPolicy object`11831184 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.11851186 - `BetaManagedAgentsGrepToolConfig object`11871188 Configuration for the grep tool.11891190 - `type: "grep"`11911192 - `enabled: boolean`11931194 - `name: "grep"`11951196 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`11971198 Permission policy for tool execution.11991200 - `BetaManagedAgentsAlwaysAllowPolicy object`12011202 Tool calls are automatically approved without user confirmation.12031204 - `BetaManagedAgentsAlwaysAskPolicy object`12051206 Tool calls require user confirmation before execution.12071208 - `BetaManagedAgentsAutoPolicy object`12091210 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.12111212 - `BetaManagedAgentsWebFetchToolConfig object`12131214 Configuration for the web_fetch tool.12151216 - `type: "web_fetch"`12171218 - `enabled: boolean`12191220 - `name: "web_fetch"`12211222 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`12231224 Permission policy for tool execution.12251226 - `BetaManagedAgentsAlwaysAllowPolicy object`12271228 Tool calls are automatically approved without user confirmation.12291230 - `BetaManagedAgentsAlwaysAskPolicy object`12311232 Tool calls require user confirmation before execution.12331234 - `BetaManagedAgentsAutoPolicy object`12351236 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.12371238 - `allowed_domains: optional array of string`12391240 - `blocked_domains: optional array of string`12411242 - `max_content_tokens: optional number or null`12431244 format: int3212451246 - `BetaManagedAgentsWebSearchToolConfig object`12471248 Configuration for the web_search tool.12491250 - `type: "web_search"`12511252 - `enabled: boolean`12531254 - `name: "web_search"`12551256 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`12571258 Permission policy for tool execution.12591260 - `BetaManagedAgentsAlwaysAllowPolicy object`12611262 Tool calls are automatically approved without user confirmation.12631264 - `BetaManagedAgentsAlwaysAskPolicy object`12651266 Tool calls require user confirmation before execution.12671268 - `BetaManagedAgentsAutoPolicy object`12691270 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.12711272 - `allowed_domains: optional array of string`12731274 - `blocked_domains: optional array of string`12751276 - `user_location: optional BetaManagedAgentsUserLocation or null`12771278 Approximate user location for search result localization.12791280 - `type: "approximate"`12811282 Location precision. Only "approximate" is supported.12831284 - `city: optional string or null`12851286 City name.12871288 minLength: 1, maxLength: 25512891290 - `country: optional string or null`12911292 Two-letter ISO 3166-1 country code, uppercase.12931294 - `region: optional string or null`12951296 Region or state name.12971298 minLength: 1, maxLength: 25512991300 - `timezone: optional string or null`13011302 IANA timezone identifier, e.g. "America/Los_Angeles".13031304 minLength: 1, maxLength: 25513051306 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`13071308 Resolved default configuration for agent tools.13091310 - `enabled: boolean`13111312 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`13131314 Permission policy for tool execution.13151316 - `BetaManagedAgentsAlwaysAllowPolicy object`13171318 Tool calls are automatically approved without user confirmation.13191320 - `BetaManagedAgentsAlwaysAskPolicy object`13211322 Tool calls require user confirmation before execution.13231324 - `BetaManagedAgentsAutoPolicy object`13251326 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.13271328 - `BetaManagedAgentsMCPToolset object`13291330 - `type: "mcp_toolset"`13311332 - `configs: array of BetaManagedAgentsMCPToolConfig`13331334 - `enabled: boolean`13351336 - `name: string`13371338 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`13391340 Permission policy for tool execution.13411342 - `BetaManagedAgentsAlwaysAllowPolicy object`13431344 Tool calls are automatically approved without user confirmation.13451346 - `BetaManagedAgentsAlwaysAskPolicy object`13471348 Tool calls require user confirmation before execution.13491350 - `BetaManagedAgentsAutoPolicy object`13511352 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.13531354 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`13551356 Resolved default configuration for all tools from an MCP server.13571358 - `enabled: boolean`13591360 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`13611362 Permission policy for tool execution.13631364 - `BetaManagedAgentsAlwaysAllowPolicy object`13651366 Tool calls are automatically approved without user confirmation.13671368 - `BetaManagedAgentsAlwaysAskPolicy object`13691370 Tool calls require user confirmation before execution.13711372 - `BetaManagedAgentsAutoPolicy object`13731374 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.13751376 - `mcp_server_name: string`13771378 - `BetaManagedAgentsCustomTool object`13791380 A custom tool as returned in API responses.13811382 - `type: "custom"`13831384 - `description: string`13851386 - `input_schema: BetaManagedAgentsCustomToolInputSchema`13871388 JSON Schema for custom tool input parameters.13891390 - `type: "object"`13911392 - `properties: optional map[unknown] or null`13931394 - `required: optional array of string or null`13951396 - `name: string`13971398 - `updated_at: string`13991400 A timestamp in RFC 3339 format14011402 format: date-time14031404 - `version: number`14051406 The agent's current version. Starts at 1 and increments when the agent is modified.14071408 format: int3214091410## Example14111412```bash1413curl https://api.anthropic.com/v1/agents/$AGENT_ID \1414 -H 'Content-Type: application/json' \1415 -H 'anthropic-version: 2023-06-01' \1416 -H 'anthropic-beta: managed-agents-2026-04-01' \1417 -H "X-Api-Key: $ANTHROPIC_API_KEY" \1418 -d '{1419 "description": "updated",1420 "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.",1421 "version": 11422 }'1423```14241425### Response (200)14261427```json1428{1429 "id": "agent_011CZkYpogX7uDKUyvBTophP",1430 "archived_at": null,1431 "created_at": "2026-03-15T10:00:00Z",1432 "description": "A general-purpose starter agent.",1433 "mcp_servers": [1434 {1435 "name": "example-mcp",1436 "type": "url",1437 "url": "https://example-server.modelcontextprotocol.io/sse"1438 }1439 ],1440 "metadata": {1441 "foo": "bar"1442 },1443 "model": {1444 "id": "claude-opus-5",1445 "effort": {1446 "type": "low"1447 },1448 "inference_geo": "inference_geo",1449 "speed": "standard"1450 },1451 "multiagent": {1452 "agents": [1453 {1454 "id": "agent_011CZkYqphY8vELVzwCUpqiQ",1455 "type": "agent",1456 "version": 11457 }1458 ],1459 "type": "coordinator"1460 },1461 "name": "My First Agent",1462 "skills": [1463 {1464 "skill_id": "xlsx",1465 "type": "anthropic",1466 "version": "1"1467 },1468 {1469 "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",1470 "type": "custom",1471 "version": "2"1472 }1473 ],1474 "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.",1475 "tools": [1476 {1477 "configs": [1478 {1479 "enabled": true,1480 "name": "bash",1481 "permission_policy": {1482 "type": "always_allow"1483 },1484 "type": "bash"1485 }1486 ],1487 "default_config": {1488 "enabled": true,1489 "permission_policy": {1490 "type": "always_ask"1491 }1492 },1493 "type": "agent_toolset_20260401"1494 }1495 ],1496 "type": "agent",1497 "updated_at": "2026-03-15T10:00:00Z",1498 "version": 11499}1500```1501