Repository Public
1---2title: Create Session3url: https://platform.claude.com/docs/en/api/beta/sessions/create4---56# Create Session78**POST** `/v1/sessions`910Create Session1112## 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- `agent: string or BetaManagedAgentsAgentParams or BetaManagedAgentsAgentWithOverridesParams`119120 Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified.121122 - `string`123124 - `BetaManagedAgentsAgentParams object`125126 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version127128 - `type: "agent"`129130 - `id: string`131132 The `agent` ID.133134 minLength: 1, maxLength: 128135136 - `version: optional number`137138 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.139140 format: int32141142 - `BetaManagedAgentsAgentWithOverridesParams object`143144 Reference to an `agent` plus optional configuration overrides. Each provided field replaces the agent's value for the caller's use; the agent resource is unchanged.145146 - `type: "agent_with_overrides"`147148 - `id: string`149150 The `agent` ID.151152 minLength: 1, maxLength: 128153154 - `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams`155156 Replacement MCP server list. Full replacement: the provided array becomes the MCP servers. Send an empty array to clear; omit to preserve the agent's servers.157158 - `type: "url"`159160 - `name: string`161162 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.163164 minLength: 1, maxLength: 255165166 - `url: string`167168 Endpoint URL for the MCP server.169170 maxLength: 2048171172 - `model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams`173174 Replacement model. Accepts the model string, e.g. `claude-opus-5`, or a `model_config` object. Omit to use the agent's model.175176 - `BetaManagedAgentsModel = "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more or string`177178 The model that will power your agent.179180 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.181182 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`183184 The model that will power your agent.185186 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.187188 - `"claude-fable-5-1"`189190 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows191192 - `"claude-sonnet-5"`193194 High-performance model for coding and agents195196 - `"claude-fable-5"`197198 Next generation of intelligence for the hardest knowledge work and coding problems199200 - `"claude-opus-5"`201202 Powerful intelligence for long-running agents and coding203204 - `"claude-opus-4-8"`205206 Powerful intelligence for long-running agents and coding207208 - `"claude-opus-4-7"`209210 Powerful intelligence for long-running agents and coding211212 - `"claude-opus-4-6"`213214 Powerful intelligence for long-running agents and coding215216 - `"claude-sonnet-4-6"`217218 Best combination of speed and intelligence219220 - `"claude-haiku-4-5"`221222 Fastest model with near-frontier intelligence223224 - `"claude-haiku-4-5-20251001"`225226 Fastest model with near-frontier intelligence227228 - `"claude-opus-4-5"`229230 Powerful intelligence for long-running agents and coding231232 - `"claude-opus-4-5-20251101"`233234 Powerful intelligence for long-running agents and coding235236 - `"claude-sonnet-4-5"`237238 High-performance model for agents and coding239240 - `"claude-sonnet-4-5-20250929"`241242 High-performance model for agents and coding243244 - `string`245246 - `BetaManagedAgentsModelConfigParams object`247248 An object that defines additional configuration control over model use249250 - `id: BetaManagedAgentsModel`251252 The model that will power your agent.253254 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.255256 - `effort: optional "low" or "medium" or "high" or 2 more or BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or 3 more or null`257258 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.259260 - `BetaManagedAgentsEffortLevel = "low" or "medium" or "high" or 2 more`261262 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.263264 - `"low"`265266 - `"medium"`267268 - `"high"`269270 - `"xhigh"`271272 - `"max"`273274 - `BetaManagedAgentsEffortLow object`275276 Low effort. Favors latency over reasoning depth.277278 - `type: "low"`279280 - `BetaManagedAgentsEffortMedium object`281282 Medium effort. Balances latency and reasoning depth.283284 - `type: "medium"`285286 - `BetaManagedAgentsEffortHigh object`287288 High effort. Favors reasoning depth.289290 - `type: "high"`291292 - `BetaManagedAgentsEffortXhigh object`293294 Extra-high effort. Not all models accept this level.295296 - `type: "xhigh"`297298 - `BetaManagedAgentsEffortMax object`299300 Maximum effort. Favors reasoning depth over latency.301302 - `type: "max"`303304 - `inference_geo: optional string or null`305306 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.307308 - `speed: optional "standard" or "fast" or null`309310 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.311312 - `"standard"`313314 - `"fast"`315316 - `skills: optional array of BetaManagedAgentsSkillParams`317318 Replacement skill list. Full replacement: the provided array becomes the skills. Send an empty array to clear; omit to preserve the agent's skills.319320 - `BetaManagedAgentsAnthropicSkillParams object`321322 An Anthropic-managed skill.323324 - `type: "anthropic"`325326 - `skill_id: string`327328 Identifier of the Anthropic skill (e.g., "xlsx").329330 minLength: 1, maxLength: 64331332 - `version: optional string or null`333334 Version to pin. Defaults to latest if omitted.335336 minLength: 1, maxLength: 64337338 - `BetaManagedAgentsCustomSkillParams object`339340 A user-created custom skill.341342 - `type: "custom"`343344 - `skill_id: string`345346 Tagged ID of the custom skill (e.g., "skill_01XJ5...").347348 minLength: 1, maxLength: 64349350 - `version: optional string or null`351352 Version to pin. Defaults to latest if omitted.353354 minLength: 1, maxLength: 64355356 - `system: optional string or null`357358 Replacement system prompt. Up to 100,000 characters. Set to null to clear the agent's system prompt; omit to preserve it.359360 maxLength: 100000361362 - `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams`363364 Replacement tool list. Full replacement: the provided array becomes the tool configuration. Send an empty array to clear; omit to preserve the agent's tools.365366 - `BetaManagedAgentsAgentToolset20260401Params object`367368 Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.369370 - `type: "agent_toolset_20260401"`371372 - `configs: optional array of BetaManagedAgentsAgentToolConfigParams`373374 Per-tool configuration overrides.375376 - `BetaManagedAgentsBashToolConfigParams object`377378 Configuration override for the bash tool.379380 - `type: optional "bash"`381382 - `name: "bash"`383384 Must be "bash".385386 - `enabled: optional boolean or null`387388 Whether this tool is enabled and available to Claude. Overrides the default_config setting.389390 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`391392 Permission policy for tool execution.393394 - `BetaManagedAgentsAlwaysAllowPolicy object`395396 Tool calls are automatically approved without user confirmation.397398 - `type: "always_allow"`399400 - `BetaManagedAgentsAlwaysAskPolicy object`401402 Tool calls require user confirmation before execution.403404 - `type: "always_ask"`405406 - `BetaManagedAgentsAutoPolicy object`407408 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.409410 - `type: "auto"`411412 - `BetaManagedAgentsEditToolConfigParams object`413414 Configuration override for the edit tool.415416 - `type: optional "edit"`417418 - `name: "edit"`419420 Must be "edit".421422 - `enabled: optional boolean or null`423424 Whether this tool is enabled and available to Claude. Overrides the default_config setting.425426 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`427428 Permission policy for tool execution.429430 - `BetaManagedAgentsAlwaysAllowPolicy object`431432 Tool calls are automatically approved without user confirmation.433434 - `BetaManagedAgentsAlwaysAskPolicy object`435436 Tool calls require user confirmation before execution.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 - `BetaManagedAgentsReadToolConfigParams object`443444 Configuration override for the read tool.445446 - `type: optional "read"`447448 - `name: "read"`449450 Must be "read".451452 - `enabled: optional boolean or null`453454 Whether this tool is enabled and available to Claude. Overrides the default_config setting.455456 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`457458 Permission policy for tool execution.459460 - `BetaManagedAgentsAlwaysAllowPolicy object`461462 Tool calls are automatically approved without user confirmation.463464 - `BetaManagedAgentsAlwaysAskPolicy object`465466 Tool calls require user confirmation before execution.467468 - `BetaManagedAgentsAutoPolicy object`469470 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.471472 - `BetaManagedAgentsWriteToolConfigParams object`473474 Configuration override for the write tool.475476 - `type: optional "write"`477478 - `name: "write"`479480 Must be "write".481482 - `enabled: optional boolean or null`483484 Whether this tool is enabled and available to Claude. Overrides the default_config setting.485486 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`487488 Permission policy for tool execution.489490 - `BetaManagedAgentsAlwaysAllowPolicy object`491492 Tool calls are automatically approved without user confirmation.493494 - `BetaManagedAgentsAlwaysAskPolicy object`495496 Tool calls require user confirmation before execution.497498 - `BetaManagedAgentsAutoPolicy object`499500 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.501502 - `BetaManagedAgentsGlobToolConfigParams object`503504 Configuration override for the glob tool.505506 - `type: optional "glob"`507508 - `name: "glob"`509510 Must be "glob".511512 - `enabled: optional boolean or null`513514 Whether this tool is enabled and available to Claude. Overrides the default_config setting.515516 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`517518 Permission policy for tool execution.519520 - `BetaManagedAgentsAlwaysAllowPolicy object`521522 Tool calls are automatically approved without user confirmation.523524 - `BetaManagedAgentsAlwaysAskPolicy object`525526 Tool calls require user confirmation before execution.527528 - `BetaManagedAgentsAutoPolicy object`529530 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.531532 - `BetaManagedAgentsGrepToolConfigParams object`533534 Configuration override for the grep tool.535536 - `type: optional "grep"`537538 - `name: "grep"`539540 Must be "grep".541542 - `enabled: optional boolean or null`543544 Whether this tool is enabled and available to Claude. Overrides the default_config setting.545546 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`547548 Permission policy for tool execution.549550 - `BetaManagedAgentsAlwaysAllowPolicy object`551552 Tool calls are automatically approved without user confirmation.553554 - `BetaManagedAgentsAlwaysAskPolicy object`555556 Tool calls require user confirmation before execution.557558 - `BetaManagedAgentsAutoPolicy object`559560 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.561562 - `BetaManagedAgentsWebFetchToolConfigParams object`563564 Configuration override for the web_fetch tool.565566 - `type: optional "web_fetch"`567568 - `name: "web_fetch"`569570 Must be "web_fetch".571572 - `allowed_domains: optional array of string`573574 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.575576 - `blocked_domains: optional array of string`577578 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.579580 - `enabled: optional boolean or null`581582 Whether this tool is enabled and available to Claude. Overrides the default_config setting.583584 - `max_content_tokens: optional number or null`585586 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.587588 format: int32589590 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`591592 Permission policy for tool execution.593594 - `BetaManagedAgentsAlwaysAllowPolicy object`595596 Tool calls are automatically approved without user confirmation.597598 - `BetaManagedAgentsAlwaysAskPolicy object`599600 Tool calls require user confirmation before execution.601602 - `BetaManagedAgentsAutoPolicy object`603604 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.605606 - `BetaManagedAgentsWebSearchToolConfigParams object`607608 Configuration override for the web_search tool.609610 - `type: optional "web_search"`611612 - `name: "web_search"`613614 Must be "web_search".615616 - `allowed_domains: optional array of string`617618 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.619620 - `blocked_domains: optional array of string`621622 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.623624 - `enabled: optional boolean or null`625626 Whether this tool is enabled and available to Claude. Overrides the default_config setting.627628 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`629630 Permission policy for tool execution.631632 - `BetaManagedAgentsAlwaysAllowPolicy object`633634 Tool calls are automatically approved without user confirmation.635636 - `BetaManagedAgentsAlwaysAskPolicy object`637638 Tool calls require user confirmation before execution.639640 - `BetaManagedAgentsAutoPolicy object`641642 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.643644 - `user_location: optional BetaManagedAgentsUserLocation or null`645646 Approximate user location for search result localization.647648 - `type: "approximate"`649650 Location precision. Only "approximate" is supported.651652 - `city: optional string or null`653654 City name.655656 minLength: 1, maxLength: 255657658 - `country: optional string or null`659660 Two-letter ISO 3166-1 country code, uppercase.661662 - `region: optional string or null`663664 Region or state name.665666 minLength: 1, maxLength: 255667668 - `timezone: optional string or null`669670 IANA timezone identifier, e.g. "America/Los_Angeles".671672 minLength: 1, maxLength: 255673674 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null`675676 Default configuration for all tools in a toolset.677678 - `enabled: optional boolean or null`679680 Whether tools are enabled and available to Claude by default. Defaults to true if not specified.681682 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`683684 Permission policy for tool execution.685686 - `BetaManagedAgentsAlwaysAllowPolicy object`687688 Tool calls are automatically approved without user confirmation.689690 - `BetaManagedAgentsAlwaysAskPolicy object`691692 Tool calls require user confirmation before execution.693694 - `BetaManagedAgentsAutoPolicy object`695696 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.697698 - `BetaManagedAgentsMCPToolsetParams object`699700 Configuration for tools from an MCP server defined in `mcp_servers`.701702 - `type: "mcp_toolset"`703704 - `mcp_server_name: string`705706 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.707708 minLength: 1, maxLength: 255709710 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`711712 Per-tool configuration overrides.713714 - `name: string`715716 Name of the MCP tool to configure. 1-128 characters.717718 minLength: 1, maxLength: 128719720 - `enabled: optional boolean or null`721722 Whether this tool is enabled. Overrides the `default_config` setting.723724 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`725726 Permission policy for tool execution.727728 - `BetaManagedAgentsAlwaysAllowPolicy object`729730 Tool calls are automatically approved without user confirmation.731732 - `BetaManagedAgentsAlwaysAskPolicy object`733734 Tool calls require user confirmation before execution.735736 - `BetaManagedAgentsAutoPolicy object`737738 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.739740 - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null`741742 Default configuration for all tools from an MCP server.743744 - `enabled: optional boolean or null`745746 Whether tools are enabled by default. Defaults to true if not specified.747748 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`749750 Permission policy for tool execution.751752 - `BetaManagedAgentsAlwaysAllowPolicy object`753754 Tool calls are automatically approved without user confirmation.755756 - `BetaManagedAgentsAlwaysAskPolicy object`757758 Tool calls require user confirmation before execution.759760 - `BetaManagedAgentsAutoPolicy object`761762 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.763764 - `BetaManagedAgentsCustomToolParams object`765766 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.767768 - `type: "custom"`769770 - `description: string`771772 Description of what the tool does, shown to the agent to help it decide when to use the tool.773774 minLength: 1775776 - `input_schema: BetaManagedAgentsCustomToolInputSchema`777778 JSON Schema for custom tool input parameters.779780 - `type: "object"`781782 - `properties: optional map[unknown] or null`783784 - `required: optional array of string or null`785786 - `name: string`787788 Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.789790 minLength: 1, maxLength: 128791792 - `version: optional number`793794 The specific `agent` version to use. Omit to use the latest version.795796 format: int32797798- `environment_id: string`799800 ID of the `environment` defining the container configuration for this session.801802 minLength: 1, maxLength: 128803804- `budget: optional BetaManagedAgentsBudgetLimit`805806 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.807808 - `type: "limit"`809810 - `max_list_cost: BetaMonetaryAmount`811812 A monetary amount in a specific currency.813814 - `amount: string`815816 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.817818 - `currency: BetaCurrency`819820 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.821822- `initial_events: optional array of BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserDefineOutcomeEventParams`823824 Initial events to send to the `session` at creation, processed in order. Supports `user.message` and `user.define_outcome` events. Maximum 50 events.825826 - `BetaManagedAgentsUserMessageEventParams object`827828 Parameters for sending a user message to the session.829830 - `type: "user.message"`831832 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`833834 Array of content blocks for the user message.835836 - `BetaManagedAgentsTextBlock object`837838 Regular text content.839840 - `type: "text"`841842 - `text: string`843844 The text content.845846 minLength: 1847848 - `BetaManagedAgentsImageBlock object`849850 Image content specified directly as base64 data or as a reference via a URL.851852 - `type: "image"`853854 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`855856 Union type for image source variants.857858 - `BetaManagedAgentsBase64ImageSource object`859860 Base64-encoded image data.861862 - `type: "base64"`863864 - `data: string`865866 Base64-encoded image data.867868 minLength: 1869870 - `media_type: string`871872 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").873874 minLength: 1875876 - `BetaManagedAgentsURLImageSource object`877878 Image referenced by URL.879880 - `type: "url"`881882 - `url: string`883884 URL of the image to fetch.885886 minLength: 1887888 - `BetaManagedAgentsFileImageSource object`889890 Image referenced by file ID.891892 - `type: "file"`893894 - `file_id: string`895896 ID of a previously uploaded file.897898 minLength: 1899900 - `BetaManagedAgentsDocumentBlock object`901902 Document content, either specified directly as base64 data, as text, or as a reference via a URL.903904 - `type: "document"`905906 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`907908 Union type for document source variants.909910 - `BetaManagedAgentsBase64DocumentSource object`911912 Base64-encoded document data.913914 - `type: "base64"`915916 - `data: string`917918 Base64-encoded document data.919920 minLength: 1921922 - `media_type: string`923924 MIME type of the document (e.g., "application/pdf").925926 minLength: 1927928 - `BetaManagedAgentsPlainTextDocumentSource object`929930 Plain text document content.931932 - `type: "text"`933934 - `data: string`935936 The plain text content.937938 minLength: 1939940 - `media_type: "text/plain"`941942 MIME type of the text content. Must be "text/plain".943944 - `BetaManagedAgentsURLDocumentSource object`945946 Document referenced by URL.947948 - `type: "url"`949950 - `url: string`951952 URL of the document to fetch.953954 minLength: 1955956 - `BetaManagedAgentsFileDocumentSource object`957958 Document referenced by file ID.959960 - `type: "file"`961962 - `file_id: string`963964 ID of a previously uploaded file.965966 minLength: 1967968 - `context: optional string or null`969970 Additional context about the document for the model.971972 - `title: optional string or null`973974 The title of the document.975976 - `BetaManagedAgentsRedactedBlock object`977978 Placeholder for content withheld by Anthropic model policy.979980 - `type: "redacted"`981982 - `BetaManagedAgentsUserDefineOutcomeEventParams object`983984 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.985986 - `type: "user.define_outcome"`987988 - `description: string`989990 What the agent should produce. This is the task specification.991992 - `rubric: BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams`993994 Rubric for grading the quality of an outcome.995996 - `BetaManagedAgentsFileRubricParams object`997998 Rubric referenced by a file uploaded via the Files API.9991000 - `type: "file"`10011002 - `file_id: string`10031004 ID of the rubric file.10051006 - `BetaManagedAgentsTextRubricParams object`10071008 Rubric content provided inline as text.10091010 - `type: "text"`10111012 - `content: string`10131014 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.10151016 maxLength: 26214410171018 - `max_iterations: optional number or null`10191020 Eval→revision cycles before giving up. Default 3, max 20.10211022 format: int3210231024- `metadata: optional map[string]`10251026 Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.10271028- `resources: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam`10291030 Resources (e.g. repositories, files) to mount into the session's container.10311032 - `BetaManagedAgentsGitHubRepositoryResourceParams object`10331034 Mount a GitHub repository into the session's container.10351036 - `type: "github_repository"`10371038 - `url: string`10391040 Github URL of the repository10411042 minLength: 1, maxLength: 204810431044 - `authorization_token: optional string`10451046 GitHub authorization token used to clone the repository. Required for private repositories; optional for public ones.10471048 minLength: 1, maxLength: 409610491050 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`10511052 Branch or commit to check out. Defaults to the repository's default branch.10531054 - `BetaManagedAgentsBranchCheckout object`10551056 - `type: "branch"`10571058 - `name: string`10591060 Branch name to check out.10611062 minLength: 1, maxLength: 25510631064 - `BetaManagedAgentsCommitCheckout object`10651066 - `type: "commit"`10671068 - `sha: string`10691070 Full commit SHA to check out.10711072 minLength: 7, maxLength: 6410731074 - `mount_path: optional string or null`10751076 Mount path in the container. Defaults to `/workspace/<repo-name>`.10771078 minLength: 1, maxLength: 409610791080 - `BetaManagedAgentsFileResourceParams object`10811082 Mount a file uploaded via the Files API into the session.10831084 - `type: "file"`10851086 - `file_id: string`10871088 ID of a previously uploaded file.10891090 minLength: 1, maxLength: 12810911092 - `mount_path: optional string or null`10931094 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.10951096 minLength: 1, maxLength: 409610971098 - `BetaManagedAgentsMemoryStoreResourceParam object`10991100 Parameters for attaching a memory store to an agent session.11011102 - `type: "memory_store"`11031104 - `memory_store_id: string`11051106 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.11071108 - `access: optional "read_write" or "read_only" or null`11091110 Access mode for an attached memory store.11111112 - `"read_write"`11131114 - `"read_only"`11151116 - `instructions: optional string or null`11171118 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.11191120 maxLength: 409611211122- `title: optional string or null`11231124 Human-readable session title.11251126 maxLength: 50011271128- `vault_ids: optional array of string`11291130 Vault IDs for stored credentials the agent can use during the session.11311132## Returns11331134- `BetaManagedAgentsSession object`11351136 A Managed Agents `session`.11371138 - `type: "session"`11391140 - `id: string`11411142 - `agent: BetaManagedAgentsSessionAgent`11431144 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.11451146 - `type: "agent"`11471148 - `id: string`11491150 - `description: string or null`11511152 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`11531154 - `type: "url"`11551156 - `name: string`11571158 - `url: string`11591160 - `model: BetaManagedAgentsModelConfig`11611162 Model identifier and configuration.11631164 - `id: BetaManagedAgentsModel`11651166 The model that will power your agent.11671168 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.11691170 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`11711172 The model that will power your agent.11731174 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.11751176 - `"claude-fable-5-1"`11771178 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows11791180 - `"claude-sonnet-5"`11811182 High-performance model for coding and agents11831184 - `"claude-fable-5"`11851186 Next generation of intelligence for the hardest knowledge work and coding problems11871188 - `"claude-opus-5"`11891190 Powerful intelligence for long-running agents and coding11911192 - `"claude-opus-4-8"`11931194 Powerful intelligence for long-running agents and coding11951196 - `"claude-opus-4-7"`11971198 Powerful intelligence for long-running agents and coding11991200 - `"claude-opus-4-6"`12011202 Powerful intelligence for long-running agents and coding12031204 - `"claude-sonnet-4-6"`12051206 Best combination of speed and intelligence12071208 - `"claude-haiku-4-5"`12091210 Fastest model with near-frontier intelligence12111212 - `"claude-haiku-4-5-20251001"`12131214 Fastest model with near-frontier intelligence12151216 - `"claude-opus-4-5"`12171218 Powerful intelligence for long-running agents and coding12191220 - `"claude-opus-4-5-20251101"`12211222 Powerful intelligence for long-running agents and coding12231224 - `"claude-sonnet-4-5"`12251226 High-performance model for agents and coding12271228 - `"claude-sonnet-4-5-20250929"`12291230 High-performance model for agents and coding12311232 - `string`12331234 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`12351236 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.12371238 - `BetaManagedAgentsEffortLow object`12391240 Low effort. Favors latency over reasoning depth.12411242 - `type: "low"`12431244 - `BetaManagedAgentsEffortMedium object`12451246 Medium effort. Balances latency and reasoning depth.12471248 - `type: "medium"`12491250 - `BetaManagedAgentsEffortHigh object`12511252 High effort. Favors reasoning depth.12531254 - `type: "high"`12551256 - `BetaManagedAgentsEffortXhigh object`12571258 Extra-high effort. Not all models accept this level.12591260 - `type: "xhigh"`12611262 - `BetaManagedAgentsEffortMax object`12631264 Maximum effort. Favors reasoning depth over latency.12651266 - `type: "max"`12671268 - `inference_geo: optional string`12691270 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.12711272 - `speed: optional "standard" or "fast"`12731274 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.12751276 - `"standard"`12771278 - `"fast"`12791280 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`12811282 Resolved coordinator topology with full agent definitions for each roster member.12831284 - `type: "coordinator"`12851286 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`12871288 Full `agent` definitions the coordinator may spawn as session threads.12891290 - `BetaManagedAgentsSessionThreadAgent object`12911292 Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.12931294 - `type: "agent"`12951296 - `id: string`12971298 - `description: string or null`12991300 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`13011302 - `type: "url"`13031304 - `name: string`13051306 - `url: string`13071308 - `model: BetaManagedAgentsModelConfig`13091310 Model identifier and configuration.13111312 - `name: string`13131314 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`13151316 - `BetaManagedAgentsAnthropicSkill object`13171318 A resolved Anthropic-managed skill.13191320 - `type: "anthropic"`13211322 - `skill_id: string`13231324 - `version: string`13251326 - `BetaManagedAgentsCustomSkill object`13271328 A resolved user-created custom skill.13291330 - `type: "custom"`13311332 - `skill_id: string`13331334 - `version: string`13351336 - `system: string or null`13371338 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`13391340 - `BetaManagedAgentsAgentToolset20260401 object`13411342 - `type: "agent_toolset_20260401"`13431344 - `configs: array of BetaManagedAgentsAgentToolConfig`13451346 - `BetaManagedAgentsBashToolConfig object`13471348 Configuration for the bash tool.13491350 - `type: "bash"`13511352 - `enabled: boolean`13531354 - `name: "bash"`13551356 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`13571358 Permission policy for tool execution.13591360 - `BetaManagedAgentsAlwaysAllowPolicy object`13611362 Tool calls are automatically approved without user confirmation.13631364 - `type: "always_allow"`13651366 - `BetaManagedAgentsAlwaysAskPolicy object`13671368 Tool calls require user confirmation before execution.13691370 - `type: "always_ask"`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 - `type: "auto"`13771378 - `BetaManagedAgentsEditToolConfig object`13791380 Configuration for the edit tool.13811382 - `type: "edit"`13831384 - `enabled: boolean`13851386 - `name: "edit"`13871388 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`13891390 Permission policy for tool execution.13911392 - `BetaManagedAgentsAlwaysAllowPolicy object`13931394 Tool calls are automatically approved without user confirmation.13951396 - `BetaManagedAgentsAlwaysAskPolicy object`13971398 Tool calls require user confirmation before execution.13991400 - `BetaManagedAgentsAutoPolicy object`14011402 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.14031404 - `BetaManagedAgentsReadToolConfig object`14051406 Configuration for the read tool.14071408 - `type: "read"`14091410 - `enabled: boolean`14111412 - `name: "read"`14131414 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`14151416 Permission policy for tool execution.14171418 - `BetaManagedAgentsAlwaysAllowPolicy object`14191420 Tool calls are automatically approved without user confirmation.14211422 - `BetaManagedAgentsAlwaysAskPolicy object`14231424 Tool calls require user confirmation before execution.14251426 - `BetaManagedAgentsAutoPolicy object`14271428 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.14291430 - `BetaManagedAgentsWriteToolConfig object`14311432 Configuration for the write tool.14331434 - `type: "write"`14351436 - `enabled: boolean`14371438 - `name: "write"`14391440 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`14411442 Permission policy for tool execution.14431444 - `BetaManagedAgentsAlwaysAllowPolicy object`14451446 Tool calls are automatically approved without user confirmation.14471448 - `BetaManagedAgentsAlwaysAskPolicy object`14491450 Tool calls require user confirmation before execution.14511452 - `BetaManagedAgentsAutoPolicy object`14531454 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.14551456 - `BetaManagedAgentsGlobToolConfig object`14571458 Configuration for the glob tool.14591460 - `type: "glob"`14611462 - `enabled: boolean`14631464 - `name: "glob"`14651466 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`14671468 Permission policy for tool execution.14691470 - `BetaManagedAgentsAlwaysAllowPolicy object`14711472 Tool calls are automatically approved without user confirmation.14731474 - `BetaManagedAgentsAlwaysAskPolicy object`14751476 Tool calls require user confirmation before execution.14771478 - `BetaManagedAgentsAutoPolicy object`14791480 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.14811482 - `BetaManagedAgentsGrepToolConfig object`14831484 Configuration for the grep tool.14851486 - `type: "grep"`14871488 - `enabled: boolean`14891490 - `name: "grep"`14911492 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`14931494 Permission policy for tool execution.14951496 - `BetaManagedAgentsAlwaysAllowPolicy object`14971498 Tool calls are automatically approved without user confirmation.14991500 - `BetaManagedAgentsAlwaysAskPolicy object`15011502 Tool calls require user confirmation before execution.15031504 - `BetaManagedAgentsAutoPolicy object`15051506 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.15071508 - `BetaManagedAgentsWebFetchToolConfig object`15091510 Configuration for the web_fetch tool.15111512 - `type: "web_fetch"`15131514 - `enabled: boolean`15151516 - `name: "web_fetch"`15171518 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`15191520 Permission policy for tool execution.15211522 - `BetaManagedAgentsAlwaysAllowPolicy object`15231524 Tool calls are automatically approved without user confirmation.15251526 - `BetaManagedAgentsAlwaysAskPolicy object`15271528 Tool calls require user confirmation before execution.15291530 - `BetaManagedAgentsAutoPolicy object`15311532 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.15331534 - `allowed_domains: optional array of string`15351536 - `blocked_domains: optional array of string`15371538 - `max_content_tokens: optional number or null`15391540 format: int3215411542 - `BetaManagedAgentsWebSearchToolConfig object`15431544 Configuration for the web_search tool.15451546 - `type: "web_search"`15471548 - `enabled: boolean`15491550 - `name: "web_search"`15511552 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`15531554 Permission policy for tool execution.15551556 - `BetaManagedAgentsAlwaysAllowPolicy object`15571558 Tool calls are automatically approved without user confirmation.15591560 - `BetaManagedAgentsAlwaysAskPolicy object`15611562 Tool calls require user confirmation before execution.15631564 - `BetaManagedAgentsAutoPolicy object`15651566 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.15671568 - `allowed_domains: optional array of string`15691570 - `blocked_domains: optional array of string`15711572 - `user_location: optional BetaManagedAgentsUserLocation or null`15731574 Approximate user location for search result localization.15751576 - `type: "approximate"`15771578 Location precision. Only "approximate" is supported.15791580 - `city: optional string or null`15811582 City name.15831584 minLength: 1, maxLength: 25515851586 - `country: optional string or null`15871588 Two-letter ISO 3166-1 country code, uppercase.15891590 - `region: optional string or null`15911592 Region or state name.15931594 minLength: 1, maxLength: 25515951596 - `timezone: optional string or null`15971598 IANA timezone identifier, e.g. "America/Los_Angeles".15991600 minLength: 1, maxLength: 25516011602 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`16031604 Resolved default configuration for agent tools.16051606 - `enabled: boolean`16071608 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`16091610 Permission policy for tool execution.16111612 - `BetaManagedAgentsAlwaysAllowPolicy object`16131614 Tool calls are automatically approved without user confirmation.16151616 - `BetaManagedAgentsAlwaysAskPolicy object`16171618 Tool calls require user confirmation before execution.16191620 - `BetaManagedAgentsAutoPolicy object`16211622 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.16231624 - `BetaManagedAgentsMCPToolset object`16251626 - `type: "mcp_toolset"`16271628 - `configs: array of BetaManagedAgentsMCPToolConfig`16291630 - `enabled: boolean`16311632 - `name: string`16331634 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`16351636 Permission policy for tool execution.16371638 - `BetaManagedAgentsAlwaysAllowPolicy object`16391640 Tool calls are automatically approved without user confirmation.16411642 - `BetaManagedAgentsAlwaysAskPolicy object`16431644 Tool calls require user confirmation before execution.16451646 - `BetaManagedAgentsAutoPolicy object`16471648 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.16491650 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`16511652 Resolved default configuration for all tools from an MCP server.16531654 - `enabled: boolean`16551656 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`16571658 Permission policy for tool execution.16591660 - `BetaManagedAgentsAlwaysAllowPolicy object`16611662 Tool calls are automatically approved without user confirmation.16631664 - `BetaManagedAgentsAlwaysAskPolicy object`16651666 Tool calls require user confirmation before execution.16671668 - `BetaManagedAgentsAutoPolicy object`16691670 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.16711672 - `mcp_server_name: string`16731674 - `BetaManagedAgentsCustomTool object`16751676 A custom tool as returned in API responses.16771678 - `type: "custom"`16791680 - `description: string`16811682 - `input_schema: BetaManagedAgentsCustomToolInputSchema`16831684 JSON Schema for custom tool input parameters.16851686 - `type: "object"`16871688 - `properties: optional map[unknown] or null`16891690 - `required: optional array of string or null`16911692 - `name: string`16931694 - `version: number`16951696 format: int3216971698 - `BetaManagedAgentsAdvisor object`16991700 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.17011702 - `type: "advisor"`17031704 - `model: string`17051706 The advisor model id.17071708 - `name: string`17091710 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`17111712 - `BetaManagedAgentsAnthropicSkill object`17131714 A resolved Anthropic-managed skill.17151716 - `BetaManagedAgentsCustomSkill object`17171718 A resolved user-created custom skill.17191720 - `system: string or null`17211722 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`17231724 - `BetaManagedAgentsAgentToolset20260401 object`17251726 - `BetaManagedAgentsMCPToolset object`17271728 - `BetaManagedAgentsCustomTool object`17291730 A custom tool as returned in API responses.17311732 - `version: number`17331734 format: int3217351736 - `archived_at: string or null`17371738 A timestamp in RFC 3339 format17391740 format: date-time17411742 - `budget: BetaManagedAgentsBudgetLimit or null`17431744 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.17451746 - `type: "limit"`17471748 - `max_list_cost: BetaMonetaryAmount`17491750 A monetary amount in a specific currency.17511752 - `amount: string`17531754 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.17551756 - `currency: BetaCurrency`17571758 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.17591760 - `created_at: string`17611762 A timestamp in RFC 3339 format17631764 format: date-time17651766 - `environment_id: string`17671768 - `metadata: map[string]`17691770 - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource`17711772 Per-outcome evaluation state. One entry per `define_outcome` event sent to the session.17731774 - `type: "outcome_evaluation"`17751776 - `completed_at: string or null`17771778 A timestamp in RFC 3339 format17791780 format: date-time17811782 - `description: string`17831784 What the agent should produce.17851786 - `explanation: string or null`17871788 Grader's verdict text from the most recent evaluation. For `satisfied`, explains why criteria are met; for `needs_revision` (intermediate), what's missing; for `failed`, why unrecoverable.17891790 - `iteration: number`17911792 0-indexed revision cycle the outcome is currently on.17931794 format: int3217951796 - `outcome_id: string`17971798 Server-generated outc_ ID for this outcome.17991800 - `result: string`18011802 Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.18031804 - `resources: array of BetaManagedAgentsSessionResource`18051806 - `BetaManagedAgentsGitHubRepositoryResource object`18071808 - `type: "github_repository"`18091810 - `id: string`18111812 - `created_at: string`18131814 A timestamp in RFC 3339 format18151816 format: date-time18171818 - `mount_path: string`18191820 - `updated_at: string`18211822 A timestamp in RFC 3339 format18231824 format: date-time18251826 - `url: string`18271828 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`18291830 - `BetaManagedAgentsBranchCheckout object`18311832 - `type: "branch"`18331834 - `name: string`18351836 Branch name to check out.18371838 minLength: 1, maxLength: 25518391840 - `BetaManagedAgentsCommitCheckout object`18411842 - `type: "commit"`18431844 - `sha: string`18451846 Full commit SHA to check out.18471848 minLength: 7, maxLength: 6418491850 - `BetaManagedAgentsFileResource object`18511852 - `type: "file"`18531854 - `id: string`18551856 - `created_at: string`18571858 A timestamp in RFC 3339 format18591860 format: date-time18611862 - `file_id: string`18631864 - `mount_path: string`18651866 - `updated_at: string`18671868 A timestamp in RFC 3339 format18691870 format: date-time18711872 - `BetaManagedAgentsMemoryStoreResource object`18731874 A memory store attached to an agent session.18751876 - `type: "memory_store"`18771878 - `memory_store_id: string`18791880 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.18811882 - `access: optional "read_write" or "read_only" or null`18831884 Access mode for an attached memory store.18851886 - `"read_write"`18871888 - `"read_only"`18891890 - `description: optional string`18911892 Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.18931894 - `instructions: optional string or null`18951896 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.18971898 maxLength: 409618991900 - `mount_path: optional string or null`19011902 Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.19031904 - `name: optional string or null`19051906 Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.19071908 - `stats: BetaManagedAgentsSessionStats`19091910 Timing statistics for a session.19111912 - `active_seconds: optional number`19131914 Cumulative time in seconds the session spent in `running` status. Excludes idle time.19151916 format: double19171918 - `duration_seconds: optional number`19191920 Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.19211922 format: double19231924 - `status: "rescheduling" or "running" or "idle" or "terminated"`19251926 SessionStatus enum19271928 - `"rescheduling"`19291930 - `"running"`19311932 - `"idle"`19331934 - `"terminated"`19351936 - `title: string or null`19371938 - `updated_at: string`19391940 A timestamp in RFC 3339 format19411942 format: date-time19431944 - `usage: BetaManagedAgentsSessionUsage`19451946 Cumulative token usage for a session across all turns.19471948 - `active_seconds: optional number`19491950 Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on.19511952 format: double19531954 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`19551956 Prompt-cache creation token usage broken down by cache lifetime.19571958 - `ephemeral_1h_input_tokens: optional number`19591960 Tokens used to create 1-hour ephemeral cache entries.19611962 format: int3219631964 - `ephemeral_5m_input_tokens: optional number`19651966 Tokens used to create 5-minute ephemeral cache entries.19671968 format: int3219691970 - `cache_read_input_tokens: optional number`19711972 Total tokens read from prompt cache.19731974 format: int3219751976 - `input_tokens: optional number`19771978 Total input tokens consumed across all turns.19791980 format: int3219811982 - `list_cost: optional BetaMonetaryAmount or null`19831984 A monetary amount in a specific currency.19851986 - `output_tokens: optional number`19871988 Total output tokens generated across all turns.19891990 format: int3219911992 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null`19931994 Cumulative count of server-executed tool invocations, broken down by tool.19951996 - `web_fetch_requests: optional number`19971998 Number of server-executed web fetch requests.19992000 format: int3220012002 - `web_search_requests: optional number`20032004 Number of server-executed web search requests.20052006 format: int3220072008 - `vault_ids: array of string`20092010 Vault IDs attached to the session at creation. Empty when no vaults were supplied.20112012 - `deployment_id: optional string or null`20132014 Deployment ID when the session was created from a deployment reference. Null otherwise.20152016## Example20172018```bash2019curl https://api.anthropic.com/v1/sessions \2020 -H 'Content-Type: application/json' \2021 -H 'anthropic-version: 2023-06-01' \2022 -H 'anthropic-beta: managed-agents-2026-04-01' \2023 -H "X-Api-Key: $ANTHROPIC_API_KEY" \2024 -d '{2025 "agent": "agent_011CZkYpogX7uDKUyvBTophP",2026 "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",2027 "title": "Order #1234 inquiry"2028 }'2029```20302031### Response (200)20322033```json2034{2035 "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",2036 "agent": {2037 "id": "agent_011CZkYpogX7uDKUyvBTophP",2038 "description": "A general-purpose starter agent.",2039 "mcp_servers": [2040 {2041 "name": "example-mcp",2042 "type": "url",2043 "url": "https://example-server.modelcontextprotocol.io/sse"2044 }2045 ],2046 "model": {2047 "id": "claude-opus-5",2048 "effort": {2049 "type": "low"2050 },2051 "inference_geo": "inference_geo",2052 "speed": "standard"2053 },2054 "multiagent": {2055 "agents": [2056 {2057 "id": "agent_011CZkYqphY8vELVzwCUpqiQ",2058 "description": "A focused research subagent.",2059 "mcp_servers": [2060 {2061 "name": "example-mcp",2062 "type": "url",2063 "url": "https://example-server.modelcontextprotocol.io/sse"2064 }2065 ],2066 "model": {2067 "id": "claude-opus-5",2068 "effort": {2069 "type": "low"2070 },2071 "inference_geo": "inference_geo",2072 "speed": "standard"2073 },2074 "name": "Researcher",2075 "skills": [2076 {2077 "skill_id": "xlsx",2078 "type": "anthropic",2079 "version": "1"2080 }2081 ],2082 "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",2083 "tools": [2084 {2085 "configs": [2086 {2087 "enabled": true,2088 "name": "bash",2089 "permission_policy": {2090 "type": "always_allow"2091 },2092 "type": "bash"2093 }2094 ],2095 "default_config": {2096 "enabled": true,2097 "permission_policy": {2098 "type": "always_ask"2099 }2100 },2101 "type": "agent_toolset_20260401"2102 }2103 ],2104 "type": "agent",2105 "version": 12106 }2107 ],2108 "type": "coordinator"2109 },2110 "name": "My First Agent",2111 "skills": [2112 {2113 "skill_id": "xlsx",2114 "type": "anthropic",2115 "version": "1"2116 },2117 {2118 "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",2119 "type": "custom",2120 "version": "2"2121 }2122 ],2123 "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.",2124 "tools": [2125 {2126 "configs": [2127 {2128 "enabled": true,2129 "name": "bash",2130 "permission_policy": {2131 "type": "always_allow"2132 },2133 "type": "bash"2134 }2135 ],2136 "default_config": {2137 "enabled": true,2138 "permission_policy": {2139 "type": "always_ask"2140 }2141 },2142 "type": "agent_toolset_20260401"2143 }2144 ],2145 "type": "agent",2146 "version": 12147 },2148 "archived_at": null,2149 "budget": {2150 "max_list_cost": {2151 "amount": "2500",2152 "currency": "USD"2153 },2154 "type": "limit"2155 },2156 "created_at": "2026-03-15T10:00:00Z",2157 "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",2158 "metadata": {},2159 "outcome_evaluations": [2160 {2161 "completed_at": "2026-03-15T10:02:31Z",2162 "description": "Produce a 2-page summary as summary.md",2163 "explanation": "All five sections present with inline citations.",2164 "iteration": 0,2165 "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",2166 "result": "satisfied",2167 "type": "outcome_evaluation"2168 }2169 ],2170 "resources": [2171 {2172 "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",2173 "created_at": "2026-03-15T10:00:00Z",2174 "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",2175 "mount_path": "/uploads/receipt.pdf",2176 "type": "file",2177 "updated_at": "2026-03-15T10:00:00Z"2178 },2179 {2180 "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",2181 "created_at": "2026-03-15T10:00:00Z",2182 "mount_path": "/workspace/example-repo",2183 "type": "github_repository",2184 "updated_at": "2026-03-15T10:00:00Z",2185 "url": "https://github.com/example-org/example-repo",2186 "checkout": {2187 "name": "main",2188 "type": "branch"2189 }2190 }2191 ],2192 "stats": {2193 "active_seconds": 0,2194 "duration_seconds": 02195 },2196 "status": "idle",2197 "title": "Order #1234 inquiry",2198 "type": "session",2199 "updated_at": "2026-03-15T10:00:00Z",2200 "usage": {2201 "active_seconds": 0,2202 "cache_creation": {2203 "ephemeral_1h_input_tokens": 0,2204 "ephemeral_5m_input_tokens": 02205 },2206 "cache_read_input_tokens": 0,2207 "input_tokens": 0,2208 "list_cost": {2209 "amount": "2500",2210 "currency": "USD"2211 },2212 "output_tokens": 0,2213 "server_tool_use": {2214 "web_fetch_requests": 0,2215 "web_search_requests": 32216 }2217 },2218 "vault_ids": [2219 "vlt_011CZkZDLs7fYzm1hXNPeRjv"2220 ],2221 "deployment_id": "deployment_id"2222}2223```2224