Repository Public
1---2title: Create Agent3url: https://platform.claude.com/docs/en/api/beta/agents/create4---56# Create Agent78**POST** `/v1/agents`910Create Agent1112## Headers1314- `"anthropic-beta": optional array of AnthropicBeta`1516 Optional header to specify the beta version(s) you want to use.1718 - `string`1920 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`2122 - `"message-batches-2024-09-24"`2324 - `"prompt-caching-2024-07-31"`2526 - `"computer-use-2024-10-22"`2728 - `"computer-use-2025-01-24"`2930 - `"pdfs-2024-09-25"`3132 - `"token-counting-2024-11-01"`3334 - `"token-efficient-tools-2025-02-19"`3536 - `"output-128k-2025-02-19"`3738 - `"files-api-2025-04-14"`3940 - `"mcp-client-2025-04-04"`4142 - `"mcp-client-2025-11-20"`4344 - `"dev-full-thinking-2025-05-14"`4546 - `"interleaved-thinking-2025-05-14"`4748 - `"code-execution-2025-05-22"`4950 - `"extended-cache-ttl-2025-04-11"`5152 - `"context-1m-2025-08-07"`5354 - `"context-management-2025-06-27"`5556 - `"model-context-window-exceeded-2025-08-26"`5758 - `"skills-2025-10-02"`5960 - `"fast-mode-2026-02-01"`6162 - `"output-300k-2026-03-24"`6364 - `"user-profiles-2026-03-24"`6566 - `"user-profiles-2026-08-18"`6768 - `"user-profiles-2026-09-04"`6970 - `"advisor-tool-2026-03-01"`7172 - `"managed-agents-2026-04-01"`7374 - `"cache-diagnosis-2026-04-07"`7576 - `"dreaming-2026-04-21"`7778 - `"thinking-token-count-2026-05-13"`7980 - `"server-side-fallback-2026-06-01"`8182 - `"server-side-fallback-2026-07-01"`8384 - `"fallback-credit-2026-06-01"`8586 - `"fallback-credit-2026-07-01"`8788 - `"agent-memory-2026-07-22"`8990 - `"mid-conversation-tool-changes-2026-07-01"`9192 - `"compact-2026-01-12"`9394 - `"computer-use-2025-11-24"`9596 - `"mcp-tunnels-2026-06-22"`9798 - `"structured-outputs-2025-11-13"`99100 - `"task-budgets-2026-03-13"`101102 - `"thinking-display-updates-2026-08-18"`103104 - `"ce-user-management-2026-07-13"`105106 - `"mid-conversation-output-config-2026-07-01"`107108 - `"thinking-binding-controls-2026-08-01"`109110 - `"mid-conversation-system-clear-at-2026-08-21"`111112 - `"compact-2026-09-04"`113114- `"anthropic-workspace-id": optional string`115116## Body parameters117118- `model: BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams`119120 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 control121122 - `BetaManagedAgentsModel = "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more or string`123124 The model that will power your agent.125126 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.127128 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`129130 The model that will power your agent.131132 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.133134 - `"claude-fable-5-1"`135136 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows137138 - `"claude-sonnet-5"`139140 High-performance model for coding and agents141142 - `"claude-fable-5"`143144 Next generation of intelligence for the hardest knowledge work and coding problems145146 - `"claude-opus-5"`147148 Powerful intelligence for long-running agents and coding149150 - `"claude-opus-4-8"`151152 Powerful intelligence for long-running agents and coding153154 - `"claude-opus-4-7"`155156 Powerful intelligence for long-running agents and coding157158 - `"claude-opus-4-6"`159160 Powerful intelligence for long-running agents and coding161162 - `"claude-sonnet-4-6"`163164 Best combination of speed and intelligence165166 - `"claude-haiku-4-5"`167168 Fastest model with near-frontier intelligence169170 - `"claude-haiku-4-5-20251001"`171172 Fastest model with near-frontier intelligence173174 - `"claude-opus-4-5"`175176 Powerful intelligence for long-running agents and coding177178 - `"claude-opus-4-5-20251101"`179180 Powerful intelligence for long-running agents and coding181182 - `"claude-sonnet-4-5"`183184 High-performance model for agents and coding185186 - `"claude-sonnet-4-5-20250929"`187188 High-performance model for agents and coding189190 - `string`191192 - `BetaManagedAgentsModelConfigParams object`193194 An object that defines additional configuration control over model use195196 - `id: BetaManagedAgentsModel`197198 The model that will power your agent.199200 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.201202 - `effort: optional "low" or "medium" or "high" or 2 more or BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or 3 more or null`203204 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.205206 - `BetaManagedAgentsEffortLevel = "low" or "medium" or "high" or 2 more`207208 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.209210 - `"low"`211212 - `"medium"`213214 - `"high"`215216 - `"xhigh"`217218 - `"max"`219220 - `BetaManagedAgentsEffortLow object`221222 Low effort. Favors latency over reasoning depth.223224 - `type: "low"`225226 - `BetaManagedAgentsEffortMedium object`227228 Medium effort. Balances latency and reasoning depth.229230 - `type: "medium"`231232 - `BetaManagedAgentsEffortHigh object`233234 High effort. Favors reasoning depth.235236 - `type: "high"`237238 - `BetaManagedAgentsEffortXhigh object`239240 Extra-high effort. Not all models accept this level.241242 - `type: "xhigh"`243244 - `BetaManagedAgentsEffortMax object`245246 Maximum effort. Favors reasoning depth over latency.247248 - `type: "max"`249250 - `inference_geo: optional string or null`251252 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.253254 - `speed: optional "standard" or "fast" or null`255256 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.257258 - `"standard"`259260 - `"fast"`261262- `name: string`263264 Human-readable name for the agent.265266 minLength: 1, maxLength: 256267268- `description: optional string or null`269270 Description of what the agent does.271272 maxLength: 2048273274- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams`275276 MCP servers this agent connects to. Maximum 20. Names must be unique within the array. Every server must be referenced by an `mcp_toolset` in `tools`; unreferenced servers are rejected. See the [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector).277278 - `type: "url"`279280 - `name: string`281282 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.283284 minLength: 1, maxLength: 255285286 - `url: string`287288 Endpoint URL for the MCP server.289290 maxLength: 2048291292- `metadata: optional map[string]`293294 Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.295296- `multiagent: optional BetaManagedAgentsMultiagentParams or null`297298 A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster.299300 - `type: "coordinator"`301302 - `agents: array of BetaManagedAgentsMultiagentRosterEntryParams`303304 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).305306 - `string`307308 - `BetaManagedAgentsAgentParams object`309310 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version311312 - `type: "agent"`313314 - `id: string`315316 The `agent` ID.317318 minLength: 1, maxLength: 128319320 - `version: optional number`321322 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.323324 format: int32325326 - `BetaManagedAgentsMultiagentSelfParams object`327328 Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.329330 - `type: "self"`331332 - `BetaManagedAgentsAdvisorParams object`333334 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`.335336 - `type: "advisor"`337338 - `model: string`339340 A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.341342 minLength: 1, maxLength: 256343344- `skills: optional array of BetaManagedAgentsSkillParams`345346 Skills available to the agent.347348 - `BetaManagedAgentsAnthropicSkillParams object`349350 An Anthropic-managed skill.351352 - `type: "anthropic"`353354 - `skill_id: string`355356 Identifier of the Anthropic skill (e.g., "xlsx").357358 minLength: 1, maxLength: 64359360 - `version: optional string or null`361362 Version to pin. Defaults to latest if omitted.363364 minLength: 1, maxLength: 64365366 - `BetaManagedAgentsCustomSkillParams object`367368 A user-created custom skill.369370 - `type: "custom"`371372 - `skill_id: string`373374 Tagged ID of the custom skill (e.g., "skill_01XJ5...").375376 minLength: 1, maxLength: 64377378 - `version: optional string or null`379380 Version to pin. Defaults to latest if omitted.381382 minLength: 1, maxLength: 64383384- `system: optional string or null`385386 System prompt for the agent.387388 maxLength: 100000389390- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams`391392 Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed.393394 - `BetaManagedAgentsAgentToolset20260401Params object`395396 Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.397398 - `type: "agent_toolset_20260401"`399400 - `configs: optional array of BetaManagedAgentsAgentToolConfigParams`401402 Per-tool configuration overrides.403404 - `BetaManagedAgentsBashToolConfigParams object`405406 Configuration override for the bash tool.407408 - `type: optional "bash"`409410 - `name: "bash"`411412 Must be "bash".413414 - `enabled: optional boolean or null`415416 Whether this tool is enabled and available to Claude. Overrides the default_config setting.417418 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`419420 Permission policy for tool execution.421422 - `BetaManagedAgentsAlwaysAllowPolicy object`423424 Tool calls are automatically approved without user confirmation.425426 - `type: "always_allow"`427428 - `BetaManagedAgentsAlwaysAskPolicy object`429430 Tool calls require user confirmation before execution.431432 - `type: "always_ask"`433434 - `BetaManagedAgentsAutoPolicy object`435436 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.437438 - `type: "auto"`439440 - `BetaManagedAgentsEditToolConfigParams object`441442 Configuration override for the edit tool.443444 - `type: optional "edit"`445446 - `name: "edit"`447448 Must be "edit".449450 - `enabled: optional boolean or null`451452 Whether this tool is enabled and available to Claude. Overrides the default_config setting.453454 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`455456 Permission policy for tool execution.457458 - `BetaManagedAgentsAlwaysAllowPolicy object`459460 Tool calls are automatically approved without user confirmation.461462 - `BetaManagedAgentsAlwaysAskPolicy object`463464 Tool calls require user confirmation before execution.465466 - `BetaManagedAgentsAutoPolicy object`467468 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.469470 - `BetaManagedAgentsReadToolConfigParams object`471472 Configuration override for the read tool.473474 - `type: optional "read"`475476 - `name: "read"`477478 Must be "read".479480 - `enabled: optional boolean or null`481482 Whether this tool is enabled and available to Claude. Overrides the default_config setting.483484 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`485486 Permission policy for tool execution.487488 - `BetaManagedAgentsAlwaysAllowPolicy object`489490 Tool calls are automatically approved without user confirmation.491492 - `BetaManagedAgentsAlwaysAskPolicy object`493494 Tool calls require user confirmation before execution.495496 - `BetaManagedAgentsAutoPolicy object`497498 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.499500 - `BetaManagedAgentsWriteToolConfigParams object`501502 Configuration override for the write tool.503504 - `type: optional "write"`505506 - `name: "write"`507508 Must be "write".509510 - `enabled: optional boolean or null`511512 Whether this tool is enabled and available to Claude. Overrides the default_config setting.513514 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`515516 Permission policy for tool execution.517518 - `BetaManagedAgentsAlwaysAllowPolicy object`519520 Tool calls are automatically approved without user confirmation.521522 - `BetaManagedAgentsAlwaysAskPolicy object`523524 Tool calls require user confirmation before execution.525526 - `BetaManagedAgentsAutoPolicy object`527528 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.529530 - `BetaManagedAgentsGlobToolConfigParams object`531532 Configuration override for the glob tool.533534 - `type: optional "glob"`535536 - `name: "glob"`537538 Must be "glob".539540 - `enabled: optional boolean or null`541542 Whether this tool is enabled and available to Claude. Overrides the default_config setting.543544 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`545546 Permission policy for tool execution.547548 - `BetaManagedAgentsAlwaysAllowPolicy object`549550 Tool calls are automatically approved without user confirmation.551552 - `BetaManagedAgentsAlwaysAskPolicy object`553554 Tool calls require user confirmation before execution.555556 - `BetaManagedAgentsAutoPolicy object`557558 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.559560 - `BetaManagedAgentsGrepToolConfigParams object`561562 Configuration override for the grep tool.563564 - `type: optional "grep"`565566 - `name: "grep"`567568 Must be "grep".569570 - `enabled: optional boolean or null`571572 Whether this tool is enabled and available to Claude. Overrides the default_config setting.573574 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`575576 Permission policy for tool execution.577578 - `BetaManagedAgentsAlwaysAllowPolicy object`579580 Tool calls are automatically approved without user confirmation.581582 - `BetaManagedAgentsAlwaysAskPolicy object`583584 Tool calls require user confirmation before execution.585586 - `BetaManagedAgentsAutoPolicy object`587588 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.589590 - `BetaManagedAgentsWebFetchToolConfigParams object`591592 Configuration override for the web_fetch tool.593594 - `type: optional "web_fetch"`595596 - `name: "web_fetch"`597598 Must be "web_fetch".599600 - `allowed_domains: optional array of string`601602 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.603604 - `blocked_domains: optional array of string`605606 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.607608 - `enabled: optional boolean or null`609610 Whether this tool is enabled and available to Claude. Overrides the default_config setting.611612 - `max_content_tokens: optional number or null`613614 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.615616 format: int32617618 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`619620 Permission policy for tool execution.621622 - `BetaManagedAgentsAlwaysAllowPolicy object`623624 Tool calls are automatically approved without user confirmation.625626 - `BetaManagedAgentsAlwaysAskPolicy object`627628 Tool calls require user confirmation before execution.629630 - `BetaManagedAgentsAutoPolicy object`631632 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.633634 - `BetaManagedAgentsWebSearchToolConfigParams object`635636 Configuration override for the web_search tool.637638 - `type: optional "web_search"`639640 - `name: "web_search"`641642 Must be "web_search".643644 - `allowed_domains: optional array of string`645646 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.647648 - `blocked_domains: optional array of string`649650 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.651652 - `enabled: optional boolean or null`653654 Whether this tool is enabled and available to Claude. Overrides the default_config setting.655656 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`657658 Permission policy for tool execution.659660 - `BetaManagedAgentsAlwaysAllowPolicy object`661662 Tool calls are automatically approved without user confirmation.663664 - `BetaManagedAgentsAlwaysAskPolicy object`665666 Tool calls require user confirmation before execution.667668 - `BetaManagedAgentsAutoPolicy object`669670 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.671672 - `user_location: optional BetaManagedAgentsUserLocation or null`673674 Approximate user location for search result localization.675676 - `type: "approximate"`677678 Location precision. Only "approximate" is supported.679680 - `city: optional string or null`681682 City name.683684 minLength: 1, maxLength: 255685686 - `country: optional string or null`687688 Two-letter ISO 3166-1 country code, uppercase.689690 - `region: optional string or null`691692 Region or state name.693694 minLength: 1, maxLength: 255695696 - `timezone: optional string or null`697698 IANA timezone identifier, e.g. "America/Los_Angeles".699700 minLength: 1, maxLength: 255701702 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null`703704 Default configuration for all tools in a toolset.705706 - `enabled: optional boolean or null`707708 Whether tools are enabled and available to Claude by default. Defaults to true if not specified.709710 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`711712 Permission policy for tool execution.713714 - `BetaManagedAgentsAlwaysAllowPolicy object`715716 Tool calls are automatically approved without user confirmation.717718 - `BetaManagedAgentsAlwaysAskPolicy object`719720 Tool calls require user confirmation before execution.721722 - `BetaManagedAgentsAutoPolicy object`723724 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.725726 - `BetaManagedAgentsMCPToolsetParams object`727728 Configuration for tools from an MCP server defined in `mcp_servers`.729730 - `type: "mcp_toolset"`731732 - `mcp_server_name: string`733734 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.735736 minLength: 1, maxLength: 255737738 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`739740 Per-tool configuration overrides.741742 - `name: string`743744 Name of the MCP tool to configure. 1-128 characters.745746 minLength: 1, maxLength: 128747748 - `enabled: optional boolean or null`749750 Whether this tool is enabled. Overrides the `default_config` setting.751752 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`753754 Permission policy for tool execution.755756 - `BetaManagedAgentsAlwaysAllowPolicy object`757758 Tool calls are automatically approved without user confirmation.759760 - `BetaManagedAgentsAlwaysAskPolicy object`761762 Tool calls require user confirmation before execution.763764 - `BetaManagedAgentsAutoPolicy object`765766 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.767768 - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null`769770 Default configuration for all tools from an MCP server.771772 - `enabled: optional boolean or null`773774 Whether tools are enabled by default. Defaults to true if not specified.775776 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`777778 Permission policy for tool execution.779780 - `BetaManagedAgentsAlwaysAllowPolicy object`781782 Tool calls are automatically approved without user confirmation.783784 - `BetaManagedAgentsAlwaysAskPolicy object`785786 Tool calls require user confirmation before execution.787788 - `BetaManagedAgentsAutoPolicy object`789790 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.791792 - `BetaManagedAgentsCustomToolParams object`793794 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.795796 - `type: "custom"`797798 - `description: string`799800 Description of what the tool does, shown to the agent to help it decide when to use the tool.801802 minLength: 1803804 - `input_schema: BetaManagedAgentsCustomToolInputSchema`805806 JSON Schema for custom tool input parameters.807808 - `type: "object"`809810 - `properties: optional map[unknown] or null`811812 - `required: optional array of string or null`813814 - `name: string`815816 Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.817818 minLength: 1, maxLength: 128819820## Returns821822- `BetaManagedAgentsAgent object`823824 A Managed Agents `agent`.825826 - `type: "agent"`827828 - `id: string`829830 - `archived_at: string or null`831832 A timestamp in RFC 3339 format833834 format: date-time835836 - `created_at: string`837838 A timestamp in RFC 3339 format839840 format: date-time841842 - `description: string or null`843844 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`845846 - `type: "url"`847848 - `name: string`849850 - `url: string`851852 - `metadata: map[string]`853854 - `model: BetaManagedAgentsModelConfig`855856 Model identifier and configuration.857858 - `id: BetaManagedAgentsModel`859860 The model that will power your agent.861862 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.863864 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`865866 The model that will power your agent.867868 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.869870 - `"claude-fable-5-1"`871872 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows873874 - `"claude-sonnet-5"`875876 High-performance model for coding and agents877878 - `"claude-fable-5"`879880 Next generation of intelligence for the hardest knowledge work and coding problems881882 - `"claude-opus-5"`883884 Powerful intelligence for long-running agents and coding885886 - `"claude-opus-4-8"`887888 Powerful intelligence for long-running agents and coding889890 - `"claude-opus-4-7"`891892 Powerful intelligence for long-running agents and coding893894 - `"claude-opus-4-6"`895896 Powerful intelligence for long-running agents and coding897898 - `"claude-sonnet-4-6"`899900 Best combination of speed and intelligence901902 - `"claude-haiku-4-5"`903904 Fastest model with near-frontier intelligence905906 - `"claude-haiku-4-5-20251001"`907908 Fastest model with near-frontier intelligence909910 - `"claude-opus-4-5"`911912 Powerful intelligence for long-running agents and coding913914 - `"claude-opus-4-5-20251101"`915916 Powerful intelligence for long-running agents and coding917918 - `"claude-sonnet-4-5"`919920 High-performance model for agents and coding921922 - `"claude-sonnet-4-5-20250929"`923924 High-performance model for agents and coding925926 - `string`927928 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`929930 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.931932 - `BetaManagedAgentsEffortLow object`933934 Low effort. Favors latency over reasoning depth.935936 - `type: "low"`937938 - `BetaManagedAgentsEffortMedium object`939940 Medium effort. Balances latency and reasoning depth.941942 - `type: "medium"`943944 - `BetaManagedAgentsEffortHigh object`945946 High effort. Favors reasoning depth.947948 - `type: "high"`949950 - `BetaManagedAgentsEffortXhigh object`951952 Extra-high effort. Not all models accept this level.953954 - `type: "xhigh"`955956 - `BetaManagedAgentsEffortMax object`957958 Maximum effort. Favors reasoning depth over latency.959960 - `type: "max"`961962 - `inference_geo: optional string`963964 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.965966 - `speed: optional "standard" or "fast"`967968 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.969970 - `"standard"`971972 - `"fast"`973974 - `multiagent: BetaManagedAgentsMultiagent or null`975976 Resolved coordinator topology with a concrete agent roster.977978 - `type: "coordinator"`979980 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`981982 Agents the coordinator may spawn as session threads, each resolved to a specific version.983984 - `BetaManagedAgentsAgentReference object`985986 A resolved agent reference with a concrete version.987988 - `type: "agent"`989990 - `id: string`991992 - `version: number`993994 format: int32995996 - `BetaManagedAgentsAdvisor object`997998 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.9991000 - `type: "advisor"`10011002 - `model: string`10031004 The advisor model id.10051006 - `name: string`10071008 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`10091010 - `BetaManagedAgentsAnthropicSkill object`10111012 A resolved Anthropic-managed skill.10131014 - `type: "anthropic"`10151016 - `skill_id: string`10171018 - `version: string`10191020 - `BetaManagedAgentsCustomSkill object`10211022 A resolved user-created custom skill.10231024 - `type: "custom"`10251026 - `skill_id: string`10271028 - `version: string`10291030 - `system: string or null`10311032 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`10331034 - `BetaManagedAgentsAgentToolset20260401 object`10351036 - `type: "agent_toolset_20260401"`10371038 - `configs: array of BetaManagedAgentsAgentToolConfig`10391040 - `BetaManagedAgentsBashToolConfig object`10411042 Configuration for the bash tool.10431044 - `type: "bash"`10451046 - `enabled: boolean`10471048 - `name: "bash"`10491050 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`10511052 Permission policy for tool execution.10531054 - `BetaManagedAgentsAlwaysAllowPolicy object`10551056 Tool calls are automatically approved without user confirmation.10571058 - `type: "always_allow"`10591060 - `BetaManagedAgentsAlwaysAskPolicy object`10611062 Tool calls require user confirmation before execution.10631064 - `type: "always_ask"`10651066 - `BetaManagedAgentsAutoPolicy object`10671068 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.10691070 - `type: "auto"`10711072 - `BetaManagedAgentsEditToolConfig object`10731074 Configuration for the edit tool.10751076 - `type: "edit"`10771078 - `enabled: boolean`10791080 - `name: "edit"`10811082 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`10831084 Permission policy for tool execution.10851086 - `BetaManagedAgentsAlwaysAllowPolicy object`10871088 Tool calls are automatically approved without user confirmation.10891090 - `BetaManagedAgentsAlwaysAskPolicy object`10911092 Tool calls require user confirmation before execution.10931094 - `BetaManagedAgentsAutoPolicy object`10951096 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.10971098 - `BetaManagedAgentsReadToolConfig object`10991100 Configuration for the read tool.11011102 - `type: "read"`11031104 - `enabled: boolean`11051106 - `name: "read"`11071108 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`11091110 Permission policy for tool execution.11111112 - `BetaManagedAgentsAlwaysAllowPolicy object`11131114 Tool calls are automatically approved without user confirmation.11151116 - `BetaManagedAgentsAlwaysAskPolicy object`11171118 Tool calls require user confirmation before execution.11191120 - `BetaManagedAgentsAutoPolicy object`11211122 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.11231124 - `BetaManagedAgentsWriteToolConfig object`11251126 Configuration for the write tool.11271128 - `type: "write"`11291130 - `enabled: boolean`11311132 - `name: "write"`11331134 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`11351136 Permission policy for tool execution.11371138 - `BetaManagedAgentsAlwaysAllowPolicy object`11391140 Tool calls are automatically approved without user confirmation.11411142 - `BetaManagedAgentsAlwaysAskPolicy object`11431144 Tool calls require user confirmation before execution.11451146 - `BetaManagedAgentsAutoPolicy object`11471148 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.11491150 - `BetaManagedAgentsGlobToolConfig object`11511152 Configuration for the glob tool.11531154 - `type: "glob"`11551156 - `enabled: boolean`11571158 - `name: "glob"`11591160 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`11611162 Permission policy for tool execution.11631164 - `BetaManagedAgentsAlwaysAllowPolicy object`11651166 Tool calls are automatically approved without user confirmation.11671168 - `BetaManagedAgentsAlwaysAskPolicy object`11691170 Tool calls require user confirmation before execution.11711172 - `BetaManagedAgentsAutoPolicy object`11731174 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.11751176 - `BetaManagedAgentsGrepToolConfig object`11771178 Configuration for the grep tool.11791180 - `type: "grep"`11811182 - `enabled: boolean`11831184 - `name: "grep"`11851186 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`11871188 Permission policy for tool execution.11891190 - `BetaManagedAgentsAlwaysAllowPolicy object`11911192 Tool calls are automatically approved without user confirmation.11931194 - `BetaManagedAgentsAlwaysAskPolicy object`11951196 Tool calls require user confirmation before execution.11971198 - `BetaManagedAgentsAutoPolicy object`11991200 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.12011202 - `BetaManagedAgentsWebFetchToolConfig object`12031204 Configuration for the web_fetch tool.12051206 - `type: "web_fetch"`12071208 - `enabled: boolean`12091210 - `name: "web_fetch"`12111212 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`12131214 Permission policy for tool execution.12151216 - `BetaManagedAgentsAlwaysAllowPolicy object`12171218 Tool calls are automatically approved without user confirmation.12191220 - `BetaManagedAgentsAlwaysAskPolicy object`12211222 Tool calls require user confirmation before execution.12231224 - `BetaManagedAgentsAutoPolicy object`12251226 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.12271228 - `allowed_domains: optional array of string`12291230 - `blocked_domains: optional array of string`12311232 - `max_content_tokens: optional number or null`12331234 format: int3212351236 - `BetaManagedAgentsWebSearchToolConfig object`12371238 Configuration for the web_search tool.12391240 - `type: "web_search"`12411242 - `enabled: boolean`12431244 - `name: "web_search"`12451246 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`12471248 Permission policy for tool execution.12491250 - `BetaManagedAgentsAlwaysAllowPolicy object`12511252 Tool calls are automatically approved without user confirmation.12531254 - `BetaManagedAgentsAlwaysAskPolicy object`12551256 Tool calls require user confirmation before execution.12571258 - `BetaManagedAgentsAutoPolicy object`12591260 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.12611262 - `allowed_domains: optional array of string`12631264 - `blocked_domains: optional array of string`12651266 - `user_location: optional BetaManagedAgentsUserLocation or null`12671268 Approximate user location for search result localization.12691270 - `type: "approximate"`12711272 Location precision. Only "approximate" is supported.12731274 - `city: optional string or null`12751276 City name.12771278 minLength: 1, maxLength: 25512791280 - `country: optional string or null`12811282 Two-letter ISO 3166-1 country code, uppercase.12831284 - `region: optional string or null`12851286 Region or state name.12871288 minLength: 1, maxLength: 25512891290 - `timezone: optional string or null`12911292 IANA timezone identifier, e.g. "America/Los_Angeles".12931294 minLength: 1, maxLength: 25512951296 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`12971298 Resolved default configuration for agent tools.12991300 - `enabled: boolean`13011302 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`13031304 Permission policy for tool execution.13051306 - `BetaManagedAgentsAlwaysAllowPolicy object`13071308 Tool calls are automatically approved without user confirmation.13091310 - `BetaManagedAgentsAlwaysAskPolicy object`13111312 Tool calls require user confirmation before execution.13131314 - `BetaManagedAgentsAutoPolicy object`13151316 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.13171318 - `BetaManagedAgentsMCPToolset object`13191320 - `type: "mcp_toolset"`13211322 - `configs: array of BetaManagedAgentsMCPToolConfig`13231324 - `enabled: boolean`13251326 - `name: string`13271328 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`13291330 Permission policy for tool execution.13311332 - `BetaManagedAgentsAlwaysAllowPolicy object`13331334 Tool calls are automatically approved without user confirmation.13351336 - `BetaManagedAgentsAlwaysAskPolicy object`13371338 Tool calls require user confirmation before execution.13391340 - `BetaManagedAgentsAutoPolicy object`13411342 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.13431344 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`13451346 Resolved default configuration for all tools from an MCP server.13471348 - `enabled: boolean`13491350 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`13511352 Permission policy for tool execution.13531354 - `BetaManagedAgentsAlwaysAllowPolicy object`13551356 Tool calls are automatically approved without user confirmation.13571358 - `BetaManagedAgentsAlwaysAskPolicy object`13591360 Tool calls require user confirmation before execution.13611362 - `BetaManagedAgentsAutoPolicy object`13631364 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.13651366 - `mcp_server_name: string`13671368 - `BetaManagedAgentsCustomTool object`13691370 A custom tool as returned in API responses.13711372 - `type: "custom"`13731374 - `description: string`13751376 - `input_schema: BetaManagedAgentsCustomToolInputSchema`13771378 JSON Schema for custom tool input parameters.13791380 - `type: "object"`13811382 - `properties: optional map[unknown] or null`13831384 - `required: optional array of string or null`13851386 - `name: string`13871388 - `updated_at: string`13891390 A timestamp in RFC 3339 format13911392 format: date-time13931394 - `version: number`13951396 The agent's current version. Starts at 1 and increments when the agent is modified.13971398 format: int3213991400## Example14011402```bash1403curl https://api.anthropic.com/v1/agents \1404 -H 'Content-Type: application/json' \1405 -H 'anthropic-version: 2023-06-01' \1406 -H 'anthropic-beta: managed-agents-2026-04-01' \1407 -H "X-Api-Key: $ANTHROPIC_API_KEY" \1408 -d '{1409 "model": "claude-opus-5",1410 "name": "My First Agent",1411 "description": "A general-purpose starter agent.",1412 "metadata": {1413 "foo": "bar"1414 },1415 "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.",1416 "tools": [1417 {1418 "type": "agent_toolset_20260401"1419 }1420 ]1421 }'1422```14231424### Response (200)14251426```json1427{1428 "id": "agent_011CZkYpogX7uDKUyvBTophP",1429 "archived_at": null,1430 "created_at": "2026-03-15T10:00:00Z",1431 "description": "A general-purpose starter agent.",1432 "mcp_servers": [1433 {1434 "name": "example-mcp",1435 "type": "url",1436 "url": "https://example-server.modelcontextprotocol.io/sse"1437 }1438 ],1439 "metadata": {1440 "foo": "bar"1441 },1442 "model": {1443 "id": "claude-opus-5",1444 "effort": {1445 "type": "low"1446 },1447 "inference_geo": "inference_geo",1448 "speed": "standard"1449 },1450 "multiagent": {1451 "agents": [1452 {1453 "id": "agent_011CZkYqphY8vELVzwCUpqiQ",1454 "type": "agent",1455 "version": 11456 }1457 ],1458 "type": "coordinator"1459 },1460 "name": "My First Agent",1461 "skills": [1462 {1463 "skill_id": "xlsx",1464 "type": "anthropic",1465 "version": "1"1466 },1467 {1468 "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",1469 "type": "custom",1470 "version": "2"1471 }1472 ],1473 "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.",1474 "tools": [1475 {1476 "configs": [1477 {1478 "enabled": true,1479 "name": "bash",1480 "permission_policy": {1481 "type": "always_allow"1482 },1483 "type": "bash"1484 }1485 ],1486 "default_config": {1487 "enabled": true,1488 "permission_policy": {1489 "type": "always_ask"1490 }1491 },1492 "type": "agent_toolset_20260401"1493 }1494 ],1495 "type": "agent",1496 "updated_at": "2026-03-15T10:00:00Z",1497 "version": 11498}1499```1500