--- title: Sessions url: https://platform.claude.com/docs/en/api/beta/sessions --- # Sessions ## Create Session **POST** `/v1/sessions` Create Session ### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. ### Body parameters - `agent: string or BetaManagedAgentsAgentParams or BetaManagedAgentsAgentWithOverridesParams` 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. - `string` - `BetaManagedAgentsAgentParams object` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `type: "agent"` - `id: string` The `agent` ID. minLength: 1, maxLength: 128 - `version: optional number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. format: int32 - `BetaManagedAgentsAgentWithOverridesParams object` 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. - `type: "agent_with_overrides"` - `id: string` The `agent` ID. minLength: 1, maxLength: 128 - `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams` 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. - `type: "url"` - `name: string` Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. minLength: 1, maxLength: 255 - `url: string` Endpoint URL for the MCP server. maxLength: 2048 - `model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams` Replacement model. Accepts the model string, e.g. `claude-opus-5-5`, or a `model_config` object. Omit to use the agent's model. - `BetaManagedAgentsModel = "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `BetaManagedAgentsModelConfigParams object` An object that defines additional configuration control over model use - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional "low" or "medium" or "high" or 2 more or BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or 3 more or null` 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. - `"low"` Low effort. Favors latency over reasoning depth. - `"medium"` Medium effort. Balances latency and reasoning depth. - `"high"` High effort. Favors reasoning depth. - `"xhigh"` Extra-high effort. Not all models accept this level. - `"max"` Maximum effort. Favors reasoning depth over latency. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string or null` 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. - `speed: optional "standard" or "fast" or null` Inference speed mode. Defaults to `standard`. - `"standard"` - `"fast"` - `skills: optional array of BetaManagedAgentsSkillParams` Replacement skill list. Full replacement: the provided array becomes the skills. Send an empty array to clear; omit to preserve the agent's skills. - `BetaManagedAgentsAnthropicSkillParams object` An Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` Identifier of the Anthropic skill (e.g., "xlsx"). minLength: 1, maxLength: 64 - `version: optional string or null` Version to pin. Defaults to latest if omitted. minLength: 1, maxLength: 64 - `BetaManagedAgentsCustomSkillParams object` A user-created custom skill. - `type: "custom"` - `skill_id: string` Tagged ID of the custom skill (e.g., "skill_01XJ5..."). minLength: 1, maxLength: 64 - `version: optional string or null` Version to pin. Defaults to latest if omitted. minLength: 1, maxLength: 64 - `system: optional string or null` Replacement system prompt. Up to 100,000 characters. Set to null to clear the agent's system prompt; omit to preserve it. maxLength: 100000 - `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` 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. - `BetaManagedAgentsAgentToolset20260401Params object` Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - `type: "agent_toolset_20260401"` - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` Per-tool configuration overrides. - `BetaManagedAgentsBashToolConfigParams object` Configuration override for the bash tool. - `type: optional "bash"` - `name: "bash"` Must be "bash". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfigParams object` Configuration override for the edit tool. - `type: optional "edit"` - `name: "edit"` Must be "edit". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfigParams object` Configuration override for the read tool. - `type: optional "read"` - `name: "read"` Must be "read". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfigParams object` Configuration override for the write tool. - `type: optional "write"` - `name: "write"` Must be "write". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfigParams object` Configuration override for the glob tool. - `type: optional "glob"` - `name: "glob"` Must be "glob". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfigParams object` Configuration override for the grep tool. - `type: optional "grep"` - `name: "grep"` Must be "grep". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfigParams object` Configuration override for the web_fetch tool. - `type: optional "web_fetch"` - `name: "web_fetch"` Must be "web_fetch". - `allowed_domains: optional array of string` 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. - `blocked_domains: optional array of string` 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. - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `max_content_tokens: optional number or null` Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs. format: int32 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: optional BetaManagedAgentsWebFetchURLSourcesParams or null` Which sources contribute URLs the tool may fetch. Omit to allow every source. - `client_tool_results: optional BetaManagedAgentsWebFetchURLSourceToolFilterParams or null` Which custom tools' results contribute URLs that may be fetched: "all" (the default), "none", or an only or except list. Each name in a list must be a custom tool in the same tools array. - `BetaManagedAgentsWebFetchURLSourceShorthand = "all" or "none"` String form of a url_sources value that has no field other than its type: "all" means {"type": "all"} and "none" means {"type": "none"}. - `"all"` - `"none"` - `BetaManagedAgentsWebFetchURLSourceToolFilter = BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which tools' results contribute URLs that may be fetched. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: optional BetaManagedAgentsWebFetchURLSourceToolFilterParams or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched: "all" (the default), "none", or an only or except list. Each name in a list must be "web_search" or "web_fetch". - `user_input: optional BetaManagedAgentsWebFetchURLSourceUserInputParams or null` Whether URLs in the text of user messages may be fetched: "all" (the default) or "none". - `BetaManagedAgentsWebFetchURLSourceShorthand = "all" or "none"` String form of a url_sources value that has no field other than its type: "all" means {"type": "all"} and "none" means {"type": "none"}. - `BetaManagedAgentsWebFetchURLSourceUserInput = BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `BetaManagedAgentsWebSearchToolConfigParams object` Configuration override for the web_search tool. - `type: optional "web_search"` - `name: "web_search"` Must be "web_search". - `allowed_domains: optional array of string` 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. - `blocked_domains: optional array of string` 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. - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null` Default configuration applied to all tools in this set. - `enabled: optional boolean or null` Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Default permission policy for tools. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolsetParams object` Configuration for tools from an MCP server defined in `mcp_servers`. - `type: "mcp_toolset"` - `mcp_server_name: string` Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. minLength: 1, maxLength: 255 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` Per-tool configuration overrides. - `name: string` Name of the MCP tool to configure. 1-128 characters. minLength: 1, maxLength: 128 - `enabled: optional boolean or null` Whether this tool is enabled. Overrides the `default_config` setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Overrides the `default_config` setting. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null` Default configuration for all tools from this server. - `enabled: optional boolean or null` Whether tools are enabled by default. Defaults to true if not specified. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Default permission policy for tools from this server. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsCustomToolParams object` 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. - `type: "custom"` - `description: string` Description of what the tool does, shown to the agent to help it decide when to use the tool. minLength: 1 - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema defining the expected input parameters for the tool. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. minLength: 1, maxLength: 128 - `version: optional number` The specific `agent` version to use. Omit to use the latest version. format: int32 - `environment_id: string` ID of the `environment` defining the container configuration for this session. minLength: 1, maxLength: 128 - `budget: optional BetaManagedAgentsBudgetLimit` Enforced spend ceiling for the session. Omit to create an uncapped session. Every model the session can run — the agent's model and each callable agent's model — must have a public list price, or the request is rejected with reason `model_not_budgetable`. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `initial_events: optional array of BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserDefineOutcomeEventParams` Initial events to send to the `session` at creation, processed in order. Supports `user.message` and `user.define_outcome` events. Maximum 50 events. - `BetaManagedAgentsUserMessageEventParams object` Parameters for sending a user message to the session. - `type: "user.message"` - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks for the user message. - `BetaManagedAgentsTextBlock object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `BetaManagedAgentsBase64ImageSource object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `BetaManagedAgentsURLImageSource object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `BetaManagedAgentsFileImageSource object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `BetaManagedAgentsBase64DocumentSource object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `BetaManagedAgentsPlainTextDocumentSource object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `BetaManagedAgentsURLDocumentSource object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `BetaManagedAgentsFileDocumentSource object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string or null` Additional context about the document for the model. - `title: optional string or null` The title of the document. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `BetaManagedAgentsUserDefineOutcomeEventParams object` Parameters for defining an outcome the agent should work toward. The agent begins work on receipt. - `type: "user.define_outcome"` - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams` How to grade the outcome. Text or file reference. - `BetaManagedAgentsFileRubricParams object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `BetaManagedAgentsTextRubricParams object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters. maxLength: 262144 - `max_iterations: optional number or null` Eval→revision cycles before giving up. Default 3, max 20. format: int32 - `metadata: optional map[string]` Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `resources: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam` Resources (e.g. repositories, files) to mount into the session's container. - `BetaManagedAgentsGitHubRepositoryResourceParams object` Mount a GitHub repository into the session's container. - `type: "github_repository"` - `url: string` Github URL of the repository minLength: 1, maxLength: 2048 - `authorization_token: optional string` GitHub authorization token used to clone the repository. Required for private repositories; optional for public ones. minLength: 1, maxLength: 4096 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` Branch or commit to check out. Defaults to the repository's default branch. - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `mount_path: optional string or null` Mount path in the container. Defaults to `/workspace/`. minLength: 1, maxLength: 4096 - `BetaManagedAgentsFileResourceParams object` Mount a file uploaded via the Files API into the session. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1, maxLength: 128 - `mount_path: optional string or null` Mount path in the container. Defaults to `/mnt/session/uploads/`. minLength: 1, maxLength: 4096 - `BetaManagedAgentsMemoryStoreResourceParam object` Parameters for attaching a memory store to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only" or null` Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `instructions: optional string or null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `title: optional string or null` Human-readable session title. maxLength: 500 - `vault_ids: optional array of string` Vault IDs for stored credentials the agent can use during the session. ### Returns - `BetaManagedAgentsSession object` A Managed Agents `session`. - `type: "session"` - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 - `archived_at: string or null` When the session was archived. Null if not archived. format: date-time - `budget: BetaManagedAgentsBudgetLimit or null` The session's enforced spend ceiling, or null when no budget is set. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `environment_id: string` - `metadata: map[string]` - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `type: "outcome_evaluation"` - `completed_at: string or null` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string or null` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. - `resources: array of BetaManagedAgentsSessionResource` - `BetaManagedAgentsGitHubRepositoryResource object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `BetaManagedAgentsFileResource object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `BetaManagedAgentsMemoryStoreResource object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only" or null` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string or null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string or null` 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. - `name: optional string or null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for the session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double - `status: "rescheduling" or "running" or "idle" or "terminated"` - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. - `title: string or null` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for the session. - `active_seconds: optional number` 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. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount or null` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `deployment_id: optional string or null` Deployment ID when the session was created from a deployment reference. Null otherwise. ### Example ```bash curl https://api.anthropic.com/v1/sessions \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" \ -d '{ "agent": "agent_011CZkYpogX7uDKUyvBTophP", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "initial_events": [ { "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message" } ], "title": "Order #1234 inquiry" }' ``` #### Response (200) ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" }, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVmjxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXym1gWMPdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ## List Sessions **GET** `/v1/sessions` List Sessions ### Query parameters - `agent_id: optional string` Filter sessions created with this agent ID. - `agent_version: optional number` Filter by agent version. Only applies when `agent_id` is also set. format: int32 - `"created_at[gt]": optional string` Return sessions created after this time (exclusive). format: date-time - `"created_at[gte]": optional string` Return sessions created at or after this time (inclusive). format: date-time - `"created_at[lt]": optional string` Return sessions created before this time (exclusive). format: date-time - `"created_at[lte]": optional string` Return sessions created at or before this time (inclusive). format: date-time - `deployment_id: optional string` Filter sessions created by this deployment ID. - `include_archived: optional boolean` When true, includes archived sessions. Default: false (exclude archived). - `limit: optional number` Maximum number of results to return. format: int32 - `memory_store_id: optional string` Filter sessions whose resources contain a `memory_store` with this memory store ID. - `order: optional "asc" or "desc"` Sort direction for results, ordered by `created_at`. Defaults to `desc` (newest first). - `"asc"` - `"desc"` - `page: optional string` Opaque pagination cursor from a previous response. - `statuses: optional array of "rescheduling" or "running" or "idle" or "terminated"` Filter by session status. Repeat the parameter to match any of multiple statuses. - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. ### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. ### Returns - `data: optional array of BetaManagedAgentsSession` List of sessions. - `type: "session"` - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 - `archived_at: string or null` When the session was archived. Null if not archived. format: date-time - `budget: BetaManagedAgentsBudgetLimit or null` The session's enforced spend ceiling, or null when no budget is set. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `environment_id: string` - `metadata: map[string]` - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `type: "outcome_evaluation"` - `completed_at: string or null` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string or null` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. - `resources: array of BetaManagedAgentsSessionResource` - `BetaManagedAgentsGitHubRepositoryResource object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `BetaManagedAgentsFileResource object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `BetaManagedAgentsMemoryStoreResource object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only" or null` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string or null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string or null` 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. - `name: optional string or null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for the session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double - `status: "rescheduling" or "running" or "idle" or "terminated"` - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. - `title: string or null` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for the session. - `active_seconds: optional number` 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. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount or null` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `deployment_id: optional string or null` Deployment ID when the session was created from a deployment reference. Null otherwise. - `next_page: optional string or null` Opaque cursor for the next page. Null when no more results. - `prev_page: optional string or null` Opaque cursor for the previous page. Null when on the first page. Pass as the `page` parameter to navigate backward. ### Example ```bash curl https://api.anthropic.com/v1/sessions \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` #### Response (200) ```json { "data": [ { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" }, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVmjxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXym1gWMPdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=", "prev_page": "page_MjAyNS0wNS0xM1QwMDowMDowMFo=" } ``` ## Get Session **GET** `/v1/sessions/{session_id}` Get Session ### Path parameters - `session_id: string` ### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. ### Returns - `BetaManagedAgentsSession object` A Managed Agents `session`. - `type: "session"` - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 - `archived_at: string or null` When the session was archived. Null if not archived. format: date-time - `budget: BetaManagedAgentsBudgetLimit or null` The session's enforced spend ceiling, or null when no budget is set. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `environment_id: string` - `metadata: map[string]` - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `type: "outcome_evaluation"` - `completed_at: string or null` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string or null` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. - `resources: array of BetaManagedAgentsSessionResource` - `BetaManagedAgentsGitHubRepositoryResource object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `BetaManagedAgentsFileResource object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `BetaManagedAgentsMemoryStoreResource object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only" or null` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string or null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string or null` 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. - `name: optional string or null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for the session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double - `status: "rescheduling" or "running" or "idle" or "terminated"` - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. - `title: string or null` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for the session. - `active_seconds: optional number` 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. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount or null` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `deployment_id: optional string or null` Deployment ID when the session was created from a deployment reference. Null otherwise. ### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` #### Response (200) ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" }, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVmjxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXym1gWMPdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ## Update Session **POST** `/v1/sessions/{session_id}` Update Session ### Path parameters - `session_id: string` ### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. ### Body parameters - `agent: optional BetaManagedAgentsSessionAgentUpdate` Agent configuration update. Only `tools` and `mcp_servers` are updatable mid-session. Only valid for sessions created from an agent or deployment reference. The session must not be running. - `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams` Replacement MCP server list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve. - `type: "url"` - `name: string` Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. minLength: 1, maxLength: 255 - `url: string` Endpoint URL for the MCP server. maxLength: 2048 - `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve. - `BetaManagedAgentsAgentToolset20260401Params object` Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - `type: "agent_toolset_20260401"` - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` Per-tool configuration overrides. - `BetaManagedAgentsBashToolConfigParams object` Configuration override for the bash tool. - `type: optional "bash"` - `name: "bash"` Must be "bash". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfigParams object` Configuration override for the edit tool. - `type: optional "edit"` - `name: "edit"` Must be "edit". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfigParams object` Configuration override for the read tool. - `type: optional "read"` - `name: "read"` Must be "read". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfigParams object` Configuration override for the write tool. - `type: optional "write"` - `name: "write"` Must be "write". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfigParams object` Configuration override for the glob tool. - `type: optional "glob"` - `name: "glob"` Must be "glob". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfigParams object` Configuration override for the grep tool. - `type: optional "grep"` - `name: "grep"` Must be "grep". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfigParams object` Configuration override for the web_fetch tool. - `type: optional "web_fetch"` - `name: "web_fetch"` Must be "web_fetch". - `allowed_domains: optional array of string` 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. - `blocked_domains: optional array of string` 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. - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `max_content_tokens: optional number or null` Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs. format: int32 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: optional BetaManagedAgentsWebFetchURLSourcesParams or null` Which sources contribute URLs the tool may fetch. Omit to allow every source. - `client_tool_results: optional BetaManagedAgentsWebFetchURLSourceToolFilterParams or null` Which custom tools' results contribute URLs that may be fetched: "all" (the default), "none", or an only or except list. Each name in a list must be a custom tool in the same tools array. - `BetaManagedAgentsWebFetchURLSourceShorthand = "all" or "none"` String form of a url_sources value that has no field other than its type: "all" means {"type": "all"} and "none" means {"type": "none"}. - `"all"` - `"none"` - `BetaManagedAgentsWebFetchURLSourceToolFilter = BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which tools' results contribute URLs that may be fetched. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: optional BetaManagedAgentsWebFetchURLSourceToolFilterParams or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched: "all" (the default), "none", or an only or except list. Each name in a list must be "web_search" or "web_fetch". - `user_input: optional BetaManagedAgentsWebFetchURLSourceUserInputParams or null` Whether URLs in the text of user messages may be fetched: "all" (the default) or "none". - `BetaManagedAgentsWebFetchURLSourceShorthand = "all" or "none"` String form of a url_sources value that has no field other than its type: "all" means {"type": "all"} and "none" means {"type": "none"}. - `BetaManagedAgentsWebFetchURLSourceUserInput = BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `BetaManagedAgentsWebSearchToolConfigParams object` Configuration override for the web_search tool. - `type: optional "web_search"` - `name: "web_search"` Must be "web_search". - `allowed_domains: optional array of string` 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. - `blocked_domains: optional array of string` 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. - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null` Default configuration applied to all tools in this set. - `enabled: optional boolean or null` Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Default permission policy for tools. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolsetParams object` Configuration for tools from an MCP server defined in `mcp_servers`. - `type: "mcp_toolset"` - `mcp_server_name: string` Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. minLength: 1, maxLength: 255 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` Per-tool configuration overrides. - `name: string` Name of the MCP tool to configure. 1-128 characters. minLength: 1, maxLength: 128 - `enabled: optional boolean or null` Whether this tool is enabled. Overrides the `default_config` setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Overrides the `default_config` setting. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null` Default configuration for all tools from this server. - `enabled: optional boolean or null` Whether tools are enabled by default. Defaults to true if not specified. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Default permission policy for tools from this server. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsCustomToolParams object` 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. - `type: "custom"` - `description: string` Description of what the tool does, shown to the agent to help it decide when to use the tool. minLength: 1 - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema defining the expected input parameters for the tool. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. minLength: 1, maxLength: 128 - `budget: optional BetaManagedAgentsBudgetLimit or null` Enforced spend ceiling for the session. Set an object to replace the budget of a session that was created with one, or `null` to remove it; omit to preserve. A budget cannot be added to a session created without one (rejected with reason `budget_create_only`), and a removed budget cannot be re-added. Allowed in any non-terminated status. Lowering `max_list_cost` to at or below the session's consumed list cost is rejected with reason `budget_not_raised`, and every model the session can run must have a public list price or the request is rejected with reason `model_not_budgetable`. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `metadata: optional map[string] or null` Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. - `title: optional string or null` Human-readable session title. minLength: 1, maxLength: 500 - `vault_ids: optional array of string` Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. ### Returns - `BetaManagedAgentsSession object` A Managed Agents `session`. - `type: "session"` - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 - `archived_at: string or null` When the session was archived. Null if not archived. format: date-time - `budget: BetaManagedAgentsBudgetLimit or null` The session's enforced spend ceiling, or null when no budget is set. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `environment_id: string` - `metadata: map[string]` - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `type: "outcome_evaluation"` - `completed_at: string or null` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string or null` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. - `resources: array of BetaManagedAgentsSessionResource` - `BetaManagedAgentsGitHubRepositoryResource object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `BetaManagedAgentsFileResource object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `BetaManagedAgentsMemoryStoreResource object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only" or null` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string or null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string or null` 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. - `name: optional string or null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for the session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double - `status: "rescheduling" or "running" or "idle" or "terminated"` - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. - `title: string or null` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for the session. - `active_seconds: optional number` 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. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount or null` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `deployment_id: optional string or null` Deployment ID when the session was created from a deployment reference. Null otherwise. ### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" \ -d '{ "title": "Order #1234 inquiry" }' ``` #### Response (200) ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" }, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVmjxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXym1gWMPdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ## Delete Session **DELETE** `/v1/sessions/{session_id}` Delete Session ### Path parameters - `session_id: string` ### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. ### Returns - `BetaManagedAgentsDeletedSession object` Confirmation that a `session` has been permanently deleted. - `type: "session_deleted"` - `id: string` ### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ -X DELETE \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` #### Response (200) ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "type": "session_deleted" } ``` ## Archive Session **POST** `/v1/sessions/{session_id}/archive` Archive Session ### Path parameters - `session_id: string` ### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. ### Returns - `BetaManagedAgentsSession object` A Managed Agents `session`. - `type: "session"` - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 - `archived_at: string or null` When the session was archived. Null if not archived. format: date-time - `budget: BetaManagedAgentsBudgetLimit or null` The session's enforced spend ceiling, or null when no budget is set. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `environment_id: string` - `metadata: map[string]` - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `type: "outcome_evaluation"` - `completed_at: string or null` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string or null` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. - `resources: array of BetaManagedAgentsSessionResource` - `BetaManagedAgentsGitHubRepositoryResource object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `BetaManagedAgentsFileResource object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `BetaManagedAgentsMemoryStoreResource object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only" or null` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string or null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string or null` 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. - `name: optional string or null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for the session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double - `status: "rescheduling" or "running" or "idle" or "terminated"` - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. - `title: string or null` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for the session. - `active_seconds: optional number` 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. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount or null` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `deployment_id: optional string or null` Deployment ID when the session was created from a deployment reference. Null otherwise. ### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/archive \ -X POST \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` #### Response (200) ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" }, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVmjxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXym1gWMPdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ## Domain types ### Beta Managed Agents Advisor Params - `BetaManagedAgentsAdvisorParams object` 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`. - `type: "advisor"` - `model: string` A Claude model id. The model must be permitted as an advisor for this agent's model. minLength: 1, maxLength: 256 ### Beta Managed Agents Agent Message Preview - `BetaManagedAgentsAgentMessagePreview object` - `type: "agent.message"` - `id: string` The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events. ### Beta Managed Agents Agent Params - `BetaManagedAgentsAgentParams object` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `type: "agent"` - `id: string` The `agent` ID. minLength: 1, maxLength: 128 - `version: optional number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. format: int32 ### Beta Managed Agents Agent Thinking Preview - `BetaManagedAgentsAgentThinkingPreview object` - `type: "agent.thinking"` - `id: string` The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow. ### Beta Managed Agents Agent With Overrides Params - `BetaManagedAgentsAgentWithOverridesParams object` 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. - `type: "agent_with_overrides"` - `id: string` The `agent` ID. minLength: 1, maxLength: 128 - `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams` 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. - `type: "url"` - `name: string` Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. minLength: 1, maxLength: 255 - `url: string` Endpoint URL for the MCP server. maxLength: 2048 - `model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams` Replacement model. Accepts the model string, e.g. `claude-opus-5-5`, or a `model_config` object. Omit to use the agent's model. - `BetaManagedAgentsModel = "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `BetaManagedAgentsModelConfigParams object` An object that defines additional configuration control over model use - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional "low" or "medium" or "high" or 2 more or BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or 3 more or null` 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. - `"low"` Low effort. Favors latency over reasoning depth. - `"medium"` Medium effort. Balances latency and reasoning depth. - `"high"` High effort. Favors reasoning depth. - `"xhigh"` Extra-high effort. Not all models accept this level. - `"max"` Maximum effort. Favors reasoning depth over latency. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string or null` 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. - `speed: optional "standard" or "fast" or null` Inference speed mode. Defaults to `standard`. - `"standard"` - `"fast"` - `skills: optional array of BetaManagedAgentsSkillParams` Replacement skill list. Full replacement: the provided array becomes the skills. Send an empty array to clear; omit to preserve the agent's skills. - `BetaManagedAgentsAnthropicSkillParams object` An Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` Identifier of the Anthropic skill (e.g., "xlsx"). minLength: 1, maxLength: 64 - `version: optional string or null` Version to pin. Defaults to latest if omitted. minLength: 1, maxLength: 64 - `BetaManagedAgentsCustomSkillParams object` A user-created custom skill. - `type: "custom"` - `skill_id: string` Tagged ID of the custom skill (e.g., "skill_01XJ5..."). minLength: 1, maxLength: 64 - `version: optional string or null` Version to pin. Defaults to latest if omitted. minLength: 1, maxLength: 64 - `system: optional string or null` Replacement system prompt. Up to 100,000 characters. Set to null to clear the agent's system prompt; omit to preserve it. maxLength: 100000 - `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` 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. - `BetaManagedAgentsAgentToolset20260401Params object` Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - `type: "agent_toolset_20260401"` - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` Per-tool configuration overrides. - `BetaManagedAgentsBashToolConfigParams object` Configuration override for the bash tool. - `type: optional "bash"` - `name: "bash"` Must be "bash". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfigParams object` Configuration override for the edit tool. - `type: optional "edit"` - `name: "edit"` Must be "edit". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfigParams object` Configuration override for the read tool. - `type: optional "read"` - `name: "read"` Must be "read". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfigParams object` Configuration override for the write tool. - `type: optional "write"` - `name: "write"` Must be "write". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfigParams object` Configuration override for the glob tool. - `type: optional "glob"` - `name: "glob"` Must be "glob". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfigParams object` Configuration override for the grep tool. - `type: optional "grep"` - `name: "grep"` Must be "grep". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfigParams object` Configuration override for the web_fetch tool. - `type: optional "web_fetch"` - `name: "web_fetch"` Must be "web_fetch". - `allowed_domains: optional array of string` 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. - `blocked_domains: optional array of string` 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. - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `max_content_tokens: optional number or null` Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs. format: int32 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: optional BetaManagedAgentsWebFetchURLSourcesParams or null` Which sources contribute URLs the tool may fetch. Omit to allow every source. - `client_tool_results: optional BetaManagedAgentsWebFetchURLSourceToolFilterParams or null` Which custom tools' results contribute URLs that may be fetched: "all" (the default), "none", or an only or except list. Each name in a list must be a custom tool in the same tools array. - `BetaManagedAgentsWebFetchURLSourceShorthand = "all" or "none"` String form of a url_sources value that has no field other than its type: "all" means {"type": "all"} and "none" means {"type": "none"}. - `"all"` - `"none"` - `BetaManagedAgentsWebFetchURLSourceToolFilter = BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which tools' results contribute URLs that may be fetched. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: optional BetaManagedAgentsWebFetchURLSourceToolFilterParams or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched: "all" (the default), "none", or an only or except list. Each name in a list must be "web_search" or "web_fetch". - `user_input: optional BetaManagedAgentsWebFetchURLSourceUserInputParams or null` Whether URLs in the text of user messages may be fetched: "all" (the default) or "none". - `BetaManagedAgentsWebFetchURLSourceShorthand = "all" or "none"` String form of a url_sources value that has no field other than its type: "all" means {"type": "all"} and "none" means {"type": "none"}. - `BetaManagedAgentsWebFetchURLSourceUserInput = BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `BetaManagedAgentsWebSearchToolConfigParams object` Configuration override for the web_search tool. - `type: optional "web_search"` - `name: "web_search"` Must be "web_search". - `allowed_domains: optional array of string` 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. - `blocked_domains: optional array of string` 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. - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null` Default configuration applied to all tools in this set. - `enabled: optional boolean or null` Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Default permission policy for tools. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolsetParams object` Configuration for tools from an MCP server defined in `mcp_servers`. - `type: "mcp_toolset"` - `mcp_server_name: string` Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. minLength: 1, maxLength: 255 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` Per-tool configuration overrides. - `name: string` Name of the MCP tool to configure. 1-128 characters. minLength: 1, maxLength: 128 - `enabled: optional boolean or null` Whether this tool is enabled. Overrides the `default_config` setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Overrides the `default_config` setting. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null` Default configuration for all tools from this server. - `enabled: optional boolean or null` Whether tools are enabled by default. Defaults to true if not specified. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Default permission policy for tools from this server. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsCustomToolParams object` 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. - `type: "custom"` - `description: string` Description of what the tool does, shown to the agent to help it decide when to use the tool. minLength: 1 - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema defining the expected input parameters for the tool. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. minLength: 1, maxLength: 128 - `version: optional number` The specific `agent` version to use. Omit to use the latest version. format: int32 ### Beta Managed Agents Branch Checkout - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 ### Beta Managed Agents Budget Limit - `BetaManagedAgentsBudgetLimit object` A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. ### Beta Managed Agents Cache Creation Usage - `BetaManagedAgentsCacheCreationUsage object` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 ### Beta Managed Agents Commit Checkout - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 ### Beta Managed Agents Deleted Session - `BetaManagedAgentsDeletedSession object` Confirmation that a `session` has been permanently deleted. - `type: "session_deleted"` - `id: string` ### Beta Managed Agents Delta Content - `BetaManagedAgentsDeltaContent object` - `type: "content_delta"` - `content: BetaManagedAgentsTextBlock` A partial element of the content array at index, typed like the element itself — the same shape the buffered agent.message carries in content. - `type: "text"` - `text: string` The text content. minLength: 1 - `index: optional number` Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise. ### Beta Managed Agents Delta Event - `BetaManagedAgentsDeltaEvent object` An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history. - `type: "event_delta"` - `delta: BetaManagedAgentsDeltaContent` One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array. - `type: "content_delta"` - `content: BetaManagedAgentsTextBlock` A partial element of the content array at index, typed like the element itself — the same shape the buffered agent.message carries in content. - `type: "text"` - `text: string` The text content. minLength: 1 - `index: optional number` Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise. - `event_id: string` The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview. ### Beta Managed Agents Delta Type - `BetaManagedAgentsDeltaType = "agent.message" or "agent.thinking"` - `"agent.message"` - `"agent.thinking"` ### Beta Managed Agents File Resource Params - `BetaManagedAgentsFileResourceParams object` Mount a file uploaded via the Files API into the session. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1, maxLength: 128 - `mount_path: optional string or null` Mount path in the container. Defaults to `/mnt/session/uploads/`. minLength: 1, maxLength: 4096 ### Beta Managed Agents GitHub Repository Resource Params - `BetaManagedAgentsGitHubRepositoryResourceParams object` Mount a GitHub repository into the session's container. - `type: "github_repository"` - `url: string` Github URL of the repository minLength: 1, maxLength: 2048 - `authorization_token: optional string` GitHub authorization token used to clone the repository. Required for private repositories; optional for public ones. minLength: 1, maxLength: 4096 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` Branch or commit to check out. Defaults to the repository's default branch. - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `mount_path: optional string or null` Mount path in the container. Defaults to `/workspace/`. minLength: 1, maxLength: 4096 ### Beta Managed Agents Memory Store Resource Param - `BetaManagedAgentsMemoryStoreResourceParam object` Parameters for attaching a memory store to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only" or null` Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `instructions: optional string or null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 ### Beta Managed Agents Multiagent - `BetaManagedAgentsMultiagent = BetaManagedAgentsMultiagentCoordinator or BetaManagedAgentsMultiagent20261001` Resolved multiagent orchestration configuration as returned in API responses. - `BetaManagedAgentsMultiagentCoordinator object` Resolved coordinator topology with a concrete agent roster. - `type: "coordinator"` - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `BetaManagedAgentsAgentReference object` A resolved agent reference with a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagent20261001 object` Resolved multiagent configuration with three members, each enabled or disabled on its own. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that this agent can spawn as session threads, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that a run's plan can use, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` ### Beta Managed Agents Multiagent Params - `BetaManagedAgentsMultiagentParams = BetaManagedAgentsMultiagentCoordinatorParams or BetaManagedAgentsMultiagent20261001Params` Multiagent orchestration configuration. - `BetaManagedAgentsMultiagentCoordinatorParams object` A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster. - `type: "coordinator"` - `agents: array of BetaManagedAgentsMultiagentRosterEntryParams` 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). - `string` - `BetaManagedAgentsAgentParams object` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `type: "agent"` - `id: string` The `agent` ID. minLength: 1, maxLength: 128 - `version: optional number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. format: int32 - `BetaManagedAgentsMultiagentSelfParams object` Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference. - `type: "self"` - `BetaManagedAgentsAdvisorParams object` 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`. - `type: "advisor"` - `model: string` A Claude model id. The model must be permitted as an advisor for this agent's model. minLength: 1, maxLength: 256 - `BetaManagedAgentsMultiagent20261001Params object` Multiagent configuration with three members, each enabled or disabled on its own. On an update, if the agent's stored `multiagent` also has type `multiagent_20261001`, this configuration is merged into the stored one, level by level, instead of replacing it. A key that the update omits keeps its stored value. A key sent as null takes its default, on create as well, so `"workflows": null` enables workflows. An object sent with a `type` other than the stored one replaces the stored object, and the keys that it omits take their defaults. A `predefined_agents` list that is sent replaces the stored list. Every object that is sent needs its `type`, and an enabled `advisor` needs its `model`. Other validation applies to the merged result. - `type: "multiagent_20261001"` - `advisor: optional BetaManagedAgentsMultiagentAdvisorParams or null` Whether the session's primary thread can consult an advisor model. Defaults to disabled. - `BetaManagedAgentsMultiagentAdvisorEnabledParams object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` A Claude model id. The model must be permitted as an advisor for this agent's model. minLength: 1, maxLength: 256 - `BetaManagedAgentsMultiagentAdvisorDisabledParams object` The agent has no advisor. - `type: "disabled"` - `subagents: optional BetaManagedAgentsMultiagentSubagentsParams or null` Whether the agent can spawn session threads. Defaults to enabled. - `BetaManagedAgentsMultiagentSubagentsEnabledParams object` The agent can spawn session threads. Each thread runs a predefined agent, which is a saved agent in `predefined_agents`, or an inline agent, which the agent defines when it spawns the thread and which is not saved. If `inline_agents` is disabled, `predefined_agents` must name at least one agent. - `type: "enabled"` - `inline_agents: optional BetaManagedAgentsMultiagentInlineAgentsParams or null` Whether the agent can define inline agents when it spawns session threads. Defaults to enabled. - `BetaManagedAgentsMultiagentInlineAgentsEnabledParams object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabledParams object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: optional array of BetaManagedAgentsMultiagentPredefinedAgentParams or null` Predefined agents that this agent can spawn as session threads. At most 20. Defaults to null. Null and an empty list both mean no predefined agents. This list is separate from `workflows.predefined_agents`, and an agent in one list is not added to the other. - `string` - `BetaManagedAgentsAgentParams object` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `BetaManagedAgentsMultiagentSelfParams object` Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference. - `BetaManagedAgentsMultiagentSubagentsDisabledParams object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: optional BetaManagedAgentsMultiagentWorkflowsParams or null` Whether the agent can start workflow runs. Defaults to enabled. - `BetaManagedAgentsMultiagentWorkflowsEnabledParams object` The agent can start workflow runs. Each run follows a plan, a program that the agent writes. A plan can use predefined agents, which are the saved agents in `predefined_agents`, and inline agents, which it defines itself and which are not saved. If `inline_agents` is disabled, `predefined_agents` must name at least one agent. - `type: "enabled"` - `inline_agents: optional BetaManagedAgentsMultiagentInlineAgentsParams or null` Whether a run's plan can define inline agents. Defaults to enabled. - `predefined_agents: optional array of BetaManagedAgentsMultiagentPredefinedAgentParams or null` Predefined agents that a run's plan can use. At most 20. Defaults to null. Null and an empty list both mean no predefined agents. This list is separate from `subagents.predefined_agents`, and an agent in one list is not added to the other. - `string` - `BetaManagedAgentsAgentParams object` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `BetaManagedAgentsMultiagentSelfParams object` Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference. - `BetaManagedAgentsMultiagentWorkflowsDisabledParams object` The agent cannot start workflow runs. - `type: "disabled"` ### Beta Managed Agents Multiagent Roster Entry Params - `BetaManagedAgentsMultiagentRosterEntryParams = string or BetaManagedAgentsAgentParams or BetaManagedAgentsMultiagentSelfParams or BetaManagedAgentsAdvisorParams` An entry in a multiagent roster: an agent ID string, a versioned agent reference, or `self`. - `string` - `BetaManagedAgentsAgentParams object` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `type: "agent"` - `id: string` The `agent` ID. minLength: 1, maxLength: 128 - `version: optional number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. format: int32 - `BetaManagedAgentsMultiagentSelfParams object` Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference. - `type: "self"` - `BetaManagedAgentsAdvisorParams object` 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`. - `type: "advisor"` - `model: string` A Claude model id. The model must be permitted as an advisor for this agent's model. minLength: 1, maxLength: 256 ### Beta Managed Agents Outcome Evaluation Resource - `BetaManagedAgentsOutcomeEvaluationResource object` Evaluation state for a single outcome defined via a `define_outcome` event. - `type: "outcome_evaluation"` - `completed_at: string or null` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string or null` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. ### Beta Managed Agents Server Tool Usage - `BetaManagedAgentsServerToolUsage object` Cumulative count of server-executed tool invocations, broken down by tool. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 ### Beta Managed Agents Session - `BetaManagedAgentsSession object` A Managed Agents `session`. - `type: "session"` - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 - `archived_at: string or null` When the session was archived. Null if not archived. format: date-time - `budget: BetaManagedAgentsBudgetLimit or null` The session's enforced spend ceiling, or null when no budget is set. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `environment_id: string` - `metadata: map[string]` - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `type: "outcome_evaluation"` - `completed_at: string or null` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string or null` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. - `resources: array of BetaManagedAgentsSessionResource` - `BetaManagedAgentsGitHubRepositoryResource object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `BetaManagedAgentsFileResource object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `BetaManagedAgentsMemoryStoreResource object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only" or null` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string or null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string or null` 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. - `name: optional string or null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for the session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double - `status: "rescheduling" or "running" or "idle" or "terminated"` - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. - `title: string or null` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for the session. - `active_seconds: optional number` 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. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount or null` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `deployment_id: optional string or null` Deployment ID when the session was created from a deployment reference. Null otherwise. ### Beta Managed Agents Session Agent - `BetaManagedAgentsSessionAgent object` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 ### Beta Managed Agents Session Agent Update - `BetaManagedAgentsSessionAgentUpdate object` Mid-session agent configuration update. Only `tools` and `mcp_servers` are updatable. Full replacement: the provided array becomes the new value. To preserve existing entries, GET the session, modify the array, and POST it back. - `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams` Replacement MCP server list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve. - `type: "url"` - `name: string` Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. minLength: 1, maxLength: 255 - `url: string` Endpoint URL for the MCP server. maxLength: 2048 - `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve. - `BetaManagedAgentsAgentToolset20260401Params object` Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - `type: "agent_toolset_20260401"` - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` Per-tool configuration overrides. - `BetaManagedAgentsBashToolConfigParams object` Configuration override for the bash tool. - `type: optional "bash"` - `name: "bash"` Must be "bash". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfigParams object` Configuration override for the edit tool. - `type: optional "edit"` - `name: "edit"` Must be "edit". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfigParams object` Configuration override for the read tool. - `type: optional "read"` - `name: "read"` Must be "read". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfigParams object` Configuration override for the write tool. - `type: optional "write"` - `name: "write"` Must be "write". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfigParams object` Configuration override for the glob tool. - `type: optional "glob"` - `name: "glob"` Must be "glob". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfigParams object` Configuration override for the grep tool. - `type: optional "grep"` - `name: "grep"` Must be "grep". - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfigParams object` Configuration override for the web_fetch tool. - `type: optional "web_fetch"` - `name: "web_fetch"` Must be "web_fetch". - `allowed_domains: optional array of string` 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. - `blocked_domains: optional array of string` 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. - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `max_content_tokens: optional number or null` Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs. format: int32 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: optional BetaManagedAgentsWebFetchURLSourcesParams or null` Which sources contribute URLs the tool may fetch. Omit to allow every source. - `client_tool_results: optional BetaManagedAgentsWebFetchURLSourceToolFilterParams or null` Which custom tools' results contribute URLs that may be fetched: "all" (the default), "none", or an only or except list. Each name in a list must be a custom tool in the same tools array. - `BetaManagedAgentsWebFetchURLSourceShorthand = "all" or "none"` String form of a url_sources value that has no field other than its type: "all" means {"type": "all"} and "none" means {"type": "none"}. - `"all"` - `"none"` - `BetaManagedAgentsWebFetchURLSourceToolFilter = BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which tools' results contribute URLs that may be fetched. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: optional BetaManagedAgentsWebFetchURLSourceToolFilterParams or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched: "all" (the default), "none", or an only or except list. Each name in a list must be "web_search" or "web_fetch". - `user_input: optional BetaManagedAgentsWebFetchURLSourceUserInputParams or null` Whether URLs in the text of user messages may be fetched: "all" (the default) or "none". - `BetaManagedAgentsWebFetchURLSourceShorthand = "all" or "none"` String form of a url_sources value that has no field other than its type: "all" means {"type": "all"} and "none" means {"type": "none"}. - `BetaManagedAgentsWebFetchURLSourceUserInput = BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `BetaManagedAgentsWebSearchToolConfigParams object` Configuration override for the web_search tool. - `type: optional "web_search"` - `name: "web_search"` Must be "web_search". - `allowed_domains: optional array of string` 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. - `blocked_domains: optional array of string` 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. - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null` Default configuration applied to all tools in this set. - `enabled: optional boolean or null` Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Default permission policy for tools. Controls whether tool calls are auto-approved or require confirmation. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolsetParams object` Configuration for tools from an MCP server defined in `mcp_servers`. - `type: "mcp_toolset"` - `mcp_server_name: string` Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. minLength: 1, maxLength: 255 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` Per-tool configuration overrides. - `name: string` Name of the MCP tool to configure. 1-128 characters. minLength: 1, maxLength: 128 - `enabled: optional boolean or null` Whether this tool is enabled. Overrides the `default_config` setting. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Permission policy for this tool. Overrides the `default_config` setting. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null` Default configuration for all tools from this server. - `enabled: optional boolean or null` Whether tools are enabled by default. Defaults to true if not specified. - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null` Default permission policy for tools from this server. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsCustomToolParams object` 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. - `type: "custom"` - `description: string` Description of what the tool does, shown to the agent to help it decide when to use the tool. minLength: 1 - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema defining the expected input parameters for the tool. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. minLength: 1, maxLength: 128 ### Beta Managed Agents Session Multiagent - `BetaManagedAgentsSessionMultiagent = BetaManagedAgentsSessionMultiagentCoordinator or BetaManagedAgentsSessionMultiagent20261001` Resolved multiagent orchestration configuration as returned on a `session`. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` ### Beta Managed Agents Session Multiagent Coordinator - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. ### Beta Managed Agents Session Multiagent Subagents - `BetaManagedAgentsSessionMultiagentSubagents = BetaManagedAgentsSessionMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` ### Beta Managed Agents Session Multiagent Subagents Enabled - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 ### Beta Managed Agents Session Multiagent Workflows - `BetaManagedAgentsSessionMultiagentWorkflows = BetaManagedAgentsSessionMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` ### Beta Managed Agents Session Multiagent Workflows Enabled - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 ### Beta Managed Agents Session Multiagent20261001 - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` ### Beta Managed Agents Session Stats - `BetaManagedAgentsSessionStats object` Timing statistics for a session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double ### Beta Managed Agents Session Updated Event - `BetaManagedAgentsSessionUpdatedEvent object` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `type: "session.updated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the update was applied. format: date-time - `agent: optional BetaManagedAgentsSessionAgent or null` The session's effective agent configuration after the update. Present only when the update changed `agent` (tools or mcp_servers); when present it is the full materialised snapshot, not a diff. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 - `budget: optional BetaManagedAgentsBudgetLimit or null` The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `metadata: optional map[string]` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title: optional string or null` The session's new title. Present only when the update changed it. ### Beta Managed Agents Session Usage - `BetaManagedAgentsSessionUsage object` Cumulative token usage for a session across all turns. - `active_seconds: optional number` 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. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount or null` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `amount: string` 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. - `currency: BetaCurrency` 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. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 ### Beta Managed Agents Session Usage Event - `BetaManagedAgentsSessionUsageEvent object` Periodic snapshot of the session's cumulative usage and tracked list cost. - `type: "session.usage"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the snapshot was taken. format: date-time - `usage: BetaManagedAgentsSessionUsageSnapshot` The session's cumulative usage at the snapshot time. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount` Cumulative list cost of the session across all turns, priced at public list rates. - `amount: string` 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. - `currency: BetaCurrency` 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. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage` Cumulative server-executed tool usage across all turns. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `budget: optional BetaManagedAgentsBudgetLimit or null` The session's configured budget at the snapshot time, or null when the session has no budget. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. ### Beta Managed Agents Start Event - `BetaManagedAgentsStartEvent object` Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history. - `type: "event_start"` - `event: BetaManagedAgentsStartEventPreview` The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them. - `BetaManagedAgentsAgentMessagePreview object` - `type: "agent.message"` - `id: string` The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events. - `BetaManagedAgentsAgentThinkingPreview object` - `type: "agent.thinking"` - `id: string` The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow. ### Beta Managed Agents Start Event Preview - `BetaManagedAgentsStartEventPreview = BetaManagedAgentsAgentMessagePreview or BetaManagedAgentsAgentThinkingPreview` - `BetaManagedAgentsAgentMessagePreview object` - `type: "agent.message"` - `id: string` The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events. - `BetaManagedAgentsAgentThinkingPreview object` - `type: "agent.thinking"` - `id: string` The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow. ### Beta Managed Agents System Content Block - `BetaManagedAgentsSystemContentBlock object` Content block in a mid-conversation system message. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 ### Beta Managed Agents System Message Event - `BetaManagedAgentsSystemMessageEvent object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. - `type: "system.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `processed_at: optional string or null` Timestamp when this system message was processed. format: date-time ### Beta Managed Agents User Tool Result Event - `BetaManagedAgentsUserToolResultEvent object` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `type: "user.tool_result"` - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `BetaManagedAgentsBase64ImageSource object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `BetaManagedAgentsURLImageSource object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `BetaManagedAgentsFileImageSource object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `BetaManagedAgentsBase64DocumentSource object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `BetaManagedAgentsPlainTextDocumentSource object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `BetaManagedAgentsURLDocumentSource object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `BetaManagedAgentsFileDocumentSource object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string or null` Additional context about the document for the model. - `title: optional string or null` The title of the document. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `type: "search_result"` - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `processed_at: optional string or null` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. ## Sessions › Events ### List Events **GET** `/v1/sessions/{session_id}/events` List Events #### Path parameters - `session_id: string` #### Query parameters - `"created_at[gt]": optional string` Return events created after this time (exclusive). Compared against the event's `processed_at` value. format: date-time - `"created_at[gte]": optional string` Return events created at or after this time (inclusive). Compared against the event's `processed_at` value. format: date-time - `"created_at[lt]": optional string` Return events created before this time (exclusive). Compared against the event's `processed_at` value. format: date-time - `"created_at[lte]": optional string` Return events created at or before this time (inclusive). Compared against the event's `processed_at` value. format: date-time - `limit: optional number` format: int32 - `order: optional "asc" or "desc"` Sort direction for results, ordered by the event's `processed_at`. Defaults to `asc` (chronological). - `"asc"` - `"desc"` - `page: optional string` Opaque pagination cursor from a previous response's `next_page`. - `types: optional array of BetaManagedAgentsSessionEventType` Filter by event type. Values match the `type` field on returned events (for example, `user.message` or `agent.tool_use`). Omit to return all event types. - `"user.message"` - `"user.interrupt"` - `"user.tool_confirmation"` - `"user.custom_tool_result"` - `"agent.custom_tool_use"` - `"agent.message"` - `"agent.thinking"` - `"agent.mcp_tool_use"` - `"agent.mcp_tool_result"` - `"agent.tool_use"` - `"agent.tool_result"` - `"agent.thread_message_received"` - `"agent.thread_message_sent"` - `"agent.thread_context_compacted"` - `"session.error"` - `"session.status_rescheduled"` - `"session.status_running"` - `"session.status_idle"` - `"session.status_terminated"` - `"session.thread_created"` - `"span.outcome_evaluation_start"` - `"span.outcome_evaluation_end"` - `"span.model_request_start"` - `"span.model_request_end"` - `"span.outcome_evaluation_ongoing"` - `"user.define_outcome"` - `"session.thread_status_running"` - `"session.thread_status_idle"` - `"session.thread_status_terminated"` - `"user.tool_result"` - `"session.thread_status_rescheduled"` - `"session.updated"` - `"system.message"` - `"session.usage"` - `"workflow_run.created"` - `"workflow_run.status_running"` - `"workflow_run.status_idle"` - `"workflow_run.status_ended"` - `"workflow_run.error"` - `"workflow_run.phase_started"` - `"workflow_run.phase_ended"` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `data: optional array of BetaManagedAgentsSessionEvent` Events for the session, ordered by `processed_at`. - `BetaManagedAgentsUserMessageEvent object` A user message event in the session conversation. - `type: "user.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `BetaManagedAgentsBase64ImageSource object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `BetaManagedAgentsURLImageSource object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `BetaManagedAgentsFileImageSource object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `BetaManagedAgentsBase64DocumentSource object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `BetaManagedAgentsPlainTextDocumentSource object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `BetaManagedAgentsURLDocumentSource object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `BetaManagedAgentsFileDocumentSource object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string or null` Additional context about the document for the model. - `title: optional string or null` The title of the document. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `processed_at: optional string or null` Timestamp when the agent finished processing this message. format: date-time - `BetaManagedAgentsUserInterruptEvent object` An interrupt event that pauses agent execution and returns control to the user. - `type: "user.interrupt"` - `id: string` Unique identifier for this event. - `processed_at: optional string or null` Timestamp when the interrupt was processed. format: date-time - `session_thread_id: optional string or null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent object` A tool confirmation event that approves or denies a pending tool execution. - `type: "user.tool_confirmation"` - `id: string` Unique identifier for this event. - `result: "allow" or "deny"` The confirmation result: 'allow' or 'deny'. - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `deny_message: optional string or null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. maxLength: 10000 - `processed_at: optional string or null` Timestamp when the confirmation was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsUserCustomToolResultEvent object` Event sent by the client providing the result of a custom tool execution. - `type: "user.custom_tool_result"` - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `type: "search_result"` - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `processed_at: optional string or null` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsAgentCustomToolUseEvent object` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. The client can send it as soon as this event arrives, without waiting for `session.status_idle`. - `type: "agent.custom_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` Timestamp when this tool use was processed. format: date-time - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentMessageEvent object` An agent response event in the session conversation. - `type: "agent.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock` Array of text blocks comprising the agent response. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when this response was generated. format: date-time - `BetaManagedAgentsAgentThinkingEvent object` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `type: "agent.thinking"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this thinking was produced. format: date-time - `BetaManagedAgentsAgentMCPToolUseEvent object` Event emitted when the agent invokes a tool provided by an MCP server. - `type: "agent.mcp_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluation` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `type: "always_allow"` - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `type: "always_ask"` - `BetaManagedAgentsAgentToolEvaluationAuto object` The resolved permission_policy was auto: the server judged this invocation individually. - `type: "auto"` - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission` The server's judgement for this invocation. - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object` The server judged the invocation safe to execute without client approval. - `type: "allow"` - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object` The server reached no judgement; the invocation is held for client approval. - `type: "ask"` - `reason_code: string` The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set. maxLength: 64 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object` The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended. - `type: "deny"` - `reason_code: string` The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set. maxLength: 64 - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentMCPToolResultEvent object` Event representing the result of an MCP tool execution. - `type: "agent.mcp_tool_result"` - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` Timestamp when this event was processed. format: date-time - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentToolUseEvent object` Event emitted when the agent invokes a built-in agent tool. - `type: "agent.tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission` The evaluated permission policy for this tool invocation. - `evaluation: optional BetaManagedAgentsAgentToolEvaluation` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentToolResultEvent object` Event representing the result of an agent tool execution. - `type: "agent.tool_result"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentThreadMessageReceivedEvent object` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `type: "agent.thread_message_received"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` Timestamp when the message was received. format: date-time - `from_agent_name: optional string or null` Name of the callable agent this message came from. Absent when received from the primary agent. - `BetaManagedAgentsAgentThreadMessageSentEvent object` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `type: "agent.thread_message_sent"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when the message was sent. format: date-time - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `to_agent_name: optional string or null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `BetaManagedAgentsAgentThreadContextCompactedEvent object` Indicates that context compaction (summarization) occurred during the session. - `type: "agent.thread_context_compacted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when compaction was processed. format: date-time - `BetaManagedAgentsSessionErrorEvent object` An error event indicating a problem occurred during session execution. - `type: "session.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 10 more` - `BetaManagedAgentsUnknownError object` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `type: "unknown_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `BetaManagedAgentsModelOverloadedError object` The model is currently overloaded. Emitted after automatic retries are exhausted. - `type: "model_overloaded_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsModelRateLimitedError object` The model request was rate-limited. - `type: "model_rate_limited_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsModelRequestFailedError object` A model request failed for a reason other than overload or rate-limiting. - `type: "model_request_failed_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsMCPConnectionFailedError object` Failed to connect to an MCP server. - `type: "mcp_connection_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsMCPAuthenticationFailedError object` Authentication to an MCP server failed. - `type: "mcp_authentication_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsBillingError object` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `type: "billing_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsCredentialHostUnreachableError object` An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit. - `type: "credential_host_unreachable_error"` - `credential_id: string` ID of the affected credential. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `vault_id: string` ID of the vault containing the affected credential. - `BetaManagedAgentsRepositoryAuthenticationError object` The repository host rejected the credentials, or required credentials and received none. - `type: "repository_authentication_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryForbiddenError object` The repository host refused access to the repository. - `type: "repository_forbidden_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryNotFoundError object` The repository host reported the repository as not found. - `type: "repository_not_found_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryCheckoutError object` The requested branch or commit does not exist in the repository. - `type: "repository_checkout_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryCloneError object` The repository could not be cloned. - `type: "repository_clone_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `processed_at: string` Timestamp when the error occurred. format: date-time - `BetaManagedAgentsSessionStatusRescheduledEvent object` Indicates the session is recovering from an error state and is rescheduled for execution. - `type: "session.status_rescheduled"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionStatusRunningEvent object` Indicates the session is actively running and the agent is working. - `type: "session.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionStatusIdleEvent object` Indicates the agent has paused and is awaiting user input. - `type: "session.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `stop_details: BetaManagedAgentsSessionRefusalStopDetails or null` Structured information about why the session stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more or null` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `"cyber"` - `"bio"` - `"frontier_llm"` - `"reasoning_extraction"` - `"general_harms"` - `explanation: string or null` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `BetaManagedAgentsSessionEndTurn object` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `BetaManagedAgentsSessionRequiresAction object` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `type: "requires_action"` - `event_ids: array of string` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `BetaManagedAgentsSessionRetriesExhausted object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `type: "retries_exhausted"` - `BetaManagedAgentsSessionBudgetReached object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `type: "budget_reached"` - `BetaManagedAgentsSessionRefusal object` The turn ended because the model's response was refused, for example by a safety classifier. - `type: "refusal"` - `BetaManagedAgentsSessionStatusTerminatedEvent object` Indicates the session has terminated, either due to an error or completion. - `type: "session.status_terminated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionThreadCreatedEvent object` Emitted when a child thread is created. Written to the parent thread's output stream so clients observing the session see child creation. - `type: "session.thread_created"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` Timestamp when the thread was created. format: date-time - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `workflow_run_id: string or null` Identifier of the workflow run that created the thread, or `null` for any other thread. - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object` Emitted when an outcome evaluation cycle begins. - `type: "span.outcome_evaluation_start"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation started. format: date-time - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `type: "span.outcome_evaluation_end"` - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation ended. format: date-time - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `usage: BetaManagedAgentsSpanModelUsage` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast" or null` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `"standard"` - `"fast"` - `BetaManagedAgentsSpanModelRequestStartEvent object` Emitted when a model request is initiated by the agent. - `type: "span.model_request_start"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the model request started. format: date-time - `BetaManagedAgentsSpanModelRequestEndEvent object` Emitted when a model request completes. - `type: "span.model_request_end"` - `id: string` Unique identifier for this event. - `is_error: boolean or null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for this model request. - `processed_at: string` Timestamp when the model request completed. format: date-time - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `type: "span.outcome_evaluation_ongoing"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when this heartbeat was emitted. format: date-time - `BetaManagedAgentsUserDefineOutcomeEvent object` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `type: "user.define_outcome"` - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number or null` Evaluate-then-revise cycles before giving up. Default 3, max 20. format: int32 - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` Timestamp when the outcome was accepted. format: date-time - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `BetaManagedAgentsFileRubric object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `BetaManagedAgentsTextRubric object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `BetaManagedAgentsSessionDeletedEvent object` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `type: "session.deleted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the session was deleted. format: date-time - `BetaManagedAgentsSessionThreadStatusRunningEvent object` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_running"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `BetaManagedAgentsSessionThreadStatusIdleEvent object` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_idle"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_details: BetaManagedAgentsSessionRefusalStopDetails or null` Structured information about why the thread stopped. `null` when there is nothing more to report. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `BetaManagedAgentsSessionEndTurn object` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionRequiresAction object` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `BetaManagedAgentsSessionRetriesExhausted object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `BetaManagedAgentsSessionBudgetReached object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `BetaManagedAgentsSessionRefusal object` The turn ended because the model's response was refused, for example by a safety classifier. - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_terminated"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `BetaManagedAgentsUserToolResultEvent object` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `type: "user.tool_result"` - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `processed_at: optional string or null` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_rescheduled"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `BetaManagedAgentsSessionUpdatedEvent object` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `type: "session.updated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the update was applied. format: date-time - `agent: optional BetaManagedAgentsSessionAgent or null` The session's effective agent configuration after the update. Present only when the update changed `agent` (tools or mcp_servers); when present it is the full materialised snapshot, not a diff. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 - `budget: optional BetaManagedAgentsBudgetLimit or null` The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `metadata: optional map[string]` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title: optional string or null` The session's new title. Present only when the update changed it. - `BetaManagedAgentsSystemMessageEvent object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. - `type: "system.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `processed_at: optional string or null` Timestamp when this system message was processed. format: date-time - `BetaManagedAgentsSessionUsageEvent object` Periodic snapshot of the session's cumulative usage and tracked list cost. - `type: "session.usage"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the snapshot was taken. format: date-time - `usage: BetaManagedAgentsSessionUsageSnapshot` The session's cumulative usage at the snapshot time. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount` Cumulative list cost of the session across all turns, priced at public list rates. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage` Cumulative server-executed tool usage across all turns. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `budget: optional BetaManagedAgentsBudgetLimit or null` The session's configured budget at the snapshot time, or null when the session has no budget. - `BetaManagedAgentsWorkflowRunCreatedEvent object` A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events. - `type: "workflow_run.created"` - `id: string` Unique identifier for this event. - `description: string or null` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `phases: array of BetaManagedAgentsWorkflowRunPhase` The phases that the run's plan declares, in the plan's order. Can be empty. - `id: string` Unique identifier for the phase. - `description: string or null` Description that the agent gave the phase, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the phase, passed on as written. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunStatusEndedEvent object` A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events. - `type: "workflow_run.status_ended"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `result: BetaManagedAgentsWorkflowRunResult` How the run ended. - `BetaManagedAgentsWorkflowRunResultCompleted object` The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded. - `type: "completed"` - `BetaManagedAgentsWorkflowRunResultError object` The run failed or reached its time limit. - `type: "error"` - `error: BetaManagedAgentsWorkflowRunError` Why the run did not finish. - `BetaManagedAgentsTimeoutWorkflowRunError object` The run reached its time limit. - `type: "timeout_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsProgramWorkflowRunError object` The plan, a program that the agent wrote, failed, or the server refused it. - `type: "program_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsUnknownWorkflowRunError object` A failure that has no type of its own. - `type: "unknown_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsThreadLimitWorkflowRunError object` The run exceeded the limit on the number of threads that a run can create. - `type: "thread_limit_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsMaxWorkflowRunsWorkflowRunError object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `type: "max_workflow_runs_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsWorkflowRunResultStopped object` The agent stopped the run. - `type: "stopped"` - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunPhaseStartedEvent object` A workflow run's plan entered a phase. - `type: "workflow_run.phase_started"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `BetaManagedAgentsWorkflowRunPhaseEndedEvent object` A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left. - `type: "workflow_run.phase_ended"` - `id: string` Unique identifier for this event. - `phase_started_id: string` Identifier of the `workflow_run.phase_started` event that opened the phase. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `BetaManagedAgentsWorkflowRunStatusRunningEvent object` A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first. - `type: "workflow_run.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunStatusIdleEvent object` A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`. - `type: "workflow_run.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunErrorEvent object` A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`. - `type: "workflow_run.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsWorkflowRunError` Why the run did not finish, or was not created. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string or null` Identifier of the run that met the error, or `null` when the error kept a run from being created. - `next_page: optional string or null` Opaque cursor for the next page. Null when no more results. #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` ##### Response (200) ```json { "data": [ { "id": "sevt_011CZkZGPp1iBcp4kaQSihUm", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" }, { "id": "sevt_011CZkZHPq1jCdq5mbRTjiVn", "content": [ { "text": "Let me look up order #1234 for you.", "type": "text" } ], "processed_at": "2026-03-15T10:00:00Z", "type": "agent.message" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ### Send Events **POST** `/v1/sessions/{session_id}/events` Send Events #### Path parameters - `session_id: string` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Body parameters - `events: array of BetaManagedAgentsEventParams` Events to send to the `session`. - `BetaManagedAgentsUserMessageEventParams object` Parameters for sending a user message to the session. - `type: "user.message"` - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks for the user message. - `BetaManagedAgentsTextBlock object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `BetaManagedAgentsBase64ImageSource object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `BetaManagedAgentsURLImageSource object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `BetaManagedAgentsFileImageSource object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `BetaManagedAgentsBase64DocumentSource object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `BetaManagedAgentsPlainTextDocumentSource object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `BetaManagedAgentsURLDocumentSource object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `BetaManagedAgentsFileDocumentSource object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string or null` Additional context about the document for the model. - `title: optional string or null` The title of the document. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `BetaManagedAgentsUserInterruptEventParams object` Parameters for sending an interrupt to pause the agent. - `type: "user.interrupt"` - `session_thread_id: optional string or null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEventParams object` Parameters for confirming or denying a tool execution request. - `type: "user.tool_confirmation"` - `result: "allow" or "deny"` The confirmation result: 'allow' or 'deny'. - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. minLength: 1, maxLength: 128 - `deny_message: optional string or null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. maxLength: 10000 - `BetaManagedAgentsUserCustomToolResultEventParams object` Parameters for providing the result of a custom tool execution. - `type: "user.custom_tool_result"` - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. minLength: 1, maxLength: 128 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `type: "search_result"` - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `BetaManagedAgentsUserDefineOutcomeEventParams object` Parameters for defining an outcome the agent should work toward. The agent begins work on receipt. - `type: "user.define_outcome"` - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams` How to grade the outcome. Text or file reference. - `BetaManagedAgentsFileRubricParams object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `BetaManagedAgentsTextRubricParams object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters. maxLength: 262144 - `max_iterations: optional number or null` Eval→revision cycles before giving up. Default 3, max 20. format: int32 - `BetaManagedAgentsUserToolResultEventParams object` Parameters for providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `type: "user.tool_result"` - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. minLength: 1, maxLength: 128 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `BetaManagedAgentsSystemMessageEventParams object` Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages. - `type: "system.message"` - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks to append. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 #### Returns - `BetaManagedAgentsSendSessionEvents object` Events that were successfully sent to the session. - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 4 more` Sent events - `BetaManagedAgentsUserMessageEvent object` A user message event in the session conversation. - `type: "user.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `BetaManagedAgentsBase64ImageSource object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `BetaManagedAgentsURLImageSource object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `BetaManagedAgentsFileImageSource object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `BetaManagedAgentsBase64DocumentSource object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `BetaManagedAgentsPlainTextDocumentSource object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `BetaManagedAgentsURLDocumentSource object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `BetaManagedAgentsFileDocumentSource object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string or null` Additional context about the document for the model. - `title: optional string or null` The title of the document. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `processed_at: optional string or null` Timestamp when the agent finished processing this message. format: date-time - `BetaManagedAgentsUserInterruptEvent object` An interrupt event that pauses agent execution and returns control to the user. - `type: "user.interrupt"` - `id: string` Unique identifier for this event. - `processed_at: optional string or null` Timestamp when the interrupt was processed. format: date-time - `session_thread_id: optional string or null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent object` A tool confirmation event that approves or denies a pending tool execution. - `type: "user.tool_confirmation"` - `id: string` Unique identifier for this event. - `result: "allow" or "deny"` The confirmation result: 'allow' or 'deny'. - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `deny_message: optional string or null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. maxLength: 10000 - `processed_at: optional string or null` Timestamp when the confirmation was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsUserCustomToolResultEvent object` Event sent by the client providing the result of a custom tool execution. - `type: "user.custom_tool_result"` - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `type: "search_result"` - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `processed_at: optional string or null` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsUserDefineOutcomeEvent object` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `type: "user.define_outcome"` - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number or null` Evaluate-then-revise cycles before giving up. Default 3, max 20. format: int32 - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` Timestamp when the outcome was accepted. format: date-time - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `BetaManagedAgentsFileRubric object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `BetaManagedAgentsTextRubric object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `BetaManagedAgentsUserToolResultEvent object` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `type: "user.tool_result"` - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `processed_at: optional string or null` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsSystemMessageEvent object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. - `type: "system.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `processed_at: optional string or null` Timestamp when this system message was processed. format: date-time #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" \ -d '{ "events": [ { "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message" } ] }' ``` ##### Response (200) ```json { "data": [ { "id": "sevt_011CZkZGPp1iBcp4kaQSihUm", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ] } ``` ### Stream Events **GET** `/v1/sessions/{session_id}/events/stream` Stream Events #### Path parameters - `session_id: string` #### Query parameters - `event_deltas: optional array of BetaManagedAgentsDeltaType` When set, this connection also receives streaming deltas (`event_start`, `event_delta`) while an event is being produced, before the event itself arrives. Deltas are best-effort; when the final event is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no final event — its terminal `span.model_request_end` closes the preview. Accepts one or more event types to preview and may be repeated: `agent.message` streams `content_delta` fragments; `agent.thinking` is start-only — a signal that the agent has begun extended thinking, concluded by the `agent.thinking` event itself. Only previews of the requested event types are sent. - `"agent.message"` - `"agent.thinking"` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 41 more` Server-sent event in the session stream. - `BetaManagedAgentsUserMessageEvent object` A user message event in the session conversation. - `type: "user.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `BetaManagedAgentsBase64ImageSource object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `BetaManagedAgentsURLImageSource object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `BetaManagedAgentsFileImageSource object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `BetaManagedAgentsBase64DocumentSource object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `BetaManagedAgentsPlainTextDocumentSource object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `BetaManagedAgentsURLDocumentSource object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `BetaManagedAgentsFileDocumentSource object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string or null` Additional context about the document for the model. - `title: optional string or null` The title of the document. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `processed_at: optional string or null` Timestamp when the agent finished processing this message. format: date-time - `BetaManagedAgentsUserInterruptEvent object` An interrupt event that pauses agent execution and returns control to the user. - `type: "user.interrupt"` - `id: string` Unique identifier for this event. - `processed_at: optional string or null` Timestamp when the interrupt was processed. format: date-time - `session_thread_id: optional string or null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent object` A tool confirmation event that approves or denies a pending tool execution. - `type: "user.tool_confirmation"` - `id: string` Unique identifier for this event. - `result: "allow" or "deny"` The confirmation result: 'allow' or 'deny'. - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `deny_message: optional string or null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. maxLength: 10000 - `processed_at: optional string or null` Timestamp when the confirmation was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsUserCustomToolResultEvent object` Event sent by the client providing the result of a custom tool execution. - `type: "user.custom_tool_result"` - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `type: "search_result"` - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `processed_at: optional string or null` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsAgentCustomToolUseEvent object` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. The client can send it as soon as this event arrives, without waiting for `session.status_idle`. - `type: "agent.custom_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` Timestamp when this tool use was processed. format: date-time - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentMessageEvent object` An agent response event in the session conversation. - `type: "agent.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock` Array of text blocks comprising the agent response. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when this response was generated. format: date-time - `BetaManagedAgentsAgentThinkingEvent object` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `type: "agent.thinking"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this thinking was produced. format: date-time - `BetaManagedAgentsAgentMCPToolUseEvent object` Event emitted when the agent invokes a tool provided by an MCP server. - `type: "agent.mcp_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluation` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `type: "always_allow"` - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `type: "always_ask"` - `BetaManagedAgentsAgentToolEvaluationAuto object` The resolved permission_policy was auto: the server judged this invocation individually. - `type: "auto"` - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission` The server's judgement for this invocation. - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object` The server judged the invocation safe to execute without client approval. - `type: "allow"` - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object` The server reached no judgement; the invocation is held for client approval. - `type: "ask"` - `reason_code: string` The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set. maxLength: 64 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object` The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended. - `type: "deny"` - `reason_code: string` The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set. maxLength: 64 - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentMCPToolResultEvent object` Event representing the result of an MCP tool execution. - `type: "agent.mcp_tool_result"` - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` Timestamp when this event was processed. format: date-time - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentToolUseEvent object` Event emitted when the agent invokes a built-in agent tool. - `type: "agent.tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission` The evaluated permission policy for this tool invocation. - `evaluation: optional BetaManagedAgentsAgentToolEvaluation` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentToolResultEvent object` Event representing the result of an agent tool execution. - `type: "agent.tool_result"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentThreadMessageReceivedEvent object` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `type: "agent.thread_message_received"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` Timestamp when the message was received. format: date-time - `from_agent_name: optional string or null` Name of the callable agent this message came from. Absent when received from the primary agent. - `BetaManagedAgentsAgentThreadMessageSentEvent object` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `type: "agent.thread_message_sent"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when the message was sent. format: date-time - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `to_agent_name: optional string or null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `BetaManagedAgentsAgentThreadContextCompactedEvent object` Indicates that context compaction (summarization) occurred during the session. - `type: "agent.thread_context_compacted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when compaction was processed. format: date-time - `BetaManagedAgentsSessionErrorEvent object` An error event indicating a problem occurred during session execution. - `type: "session.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 10 more` - `BetaManagedAgentsUnknownError object` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `type: "unknown_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `BetaManagedAgentsModelOverloadedError object` The model is currently overloaded. Emitted after automatic retries are exhausted. - `type: "model_overloaded_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsModelRateLimitedError object` The model request was rate-limited. - `type: "model_rate_limited_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsModelRequestFailedError object` A model request failed for a reason other than overload or rate-limiting. - `type: "model_request_failed_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsMCPConnectionFailedError object` Failed to connect to an MCP server. - `type: "mcp_connection_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsMCPAuthenticationFailedError object` Authentication to an MCP server failed. - `type: "mcp_authentication_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsBillingError object` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `type: "billing_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsCredentialHostUnreachableError object` An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit. - `type: "credential_host_unreachable_error"` - `credential_id: string` ID of the affected credential. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `vault_id: string` ID of the vault containing the affected credential. - `BetaManagedAgentsRepositoryAuthenticationError object` The repository host rejected the credentials, or required credentials and received none. - `type: "repository_authentication_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryForbiddenError object` The repository host refused access to the repository. - `type: "repository_forbidden_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryNotFoundError object` The repository host reported the repository as not found. - `type: "repository_not_found_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryCheckoutError object` The requested branch or commit does not exist in the repository. - `type: "repository_checkout_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryCloneError object` The repository could not be cloned. - `type: "repository_clone_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `processed_at: string` Timestamp when the error occurred. format: date-time - `BetaManagedAgentsSessionStatusRescheduledEvent object` Indicates the session is recovering from an error state and is rescheduled for execution. - `type: "session.status_rescheduled"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionStatusRunningEvent object` Indicates the session is actively running and the agent is working. - `type: "session.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionStatusIdleEvent object` Indicates the agent has paused and is awaiting user input. - `type: "session.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `stop_details: BetaManagedAgentsSessionRefusalStopDetails or null` Structured information about why the session stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more or null` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `"cyber"` - `"bio"` - `"frontier_llm"` - `"reasoning_extraction"` - `"general_harms"` - `explanation: string or null` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `BetaManagedAgentsSessionEndTurn object` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `BetaManagedAgentsSessionRequiresAction object` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `type: "requires_action"` - `event_ids: array of string` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `BetaManagedAgentsSessionRetriesExhausted object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `type: "retries_exhausted"` - `BetaManagedAgentsSessionBudgetReached object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `type: "budget_reached"` - `BetaManagedAgentsSessionRefusal object` The turn ended because the model's response was refused, for example by a safety classifier. - `type: "refusal"` - `BetaManagedAgentsSessionStatusTerminatedEvent object` Indicates the session has terminated, either due to an error or completion. - `type: "session.status_terminated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionThreadCreatedEvent object` Emitted when a child thread is created. Written to the parent thread's output stream so clients observing the session see child creation. - `type: "session.thread_created"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` Timestamp when the thread was created. format: date-time - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `workflow_run_id: string or null` Identifier of the workflow run that created the thread, or `null` for any other thread. - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object` Emitted when an outcome evaluation cycle begins. - `type: "span.outcome_evaluation_start"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation started. format: date-time - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `type: "span.outcome_evaluation_end"` - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation ended. format: date-time - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `usage: BetaManagedAgentsSpanModelUsage` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast" or null` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `"standard"` - `"fast"` - `BetaManagedAgentsSpanModelRequestStartEvent object` Emitted when a model request is initiated by the agent. - `type: "span.model_request_start"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the model request started. format: date-time - `BetaManagedAgentsSpanModelRequestEndEvent object` Emitted when a model request completes. - `type: "span.model_request_end"` - `id: string` Unique identifier for this event. - `is_error: boolean or null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for this model request. - `processed_at: string` Timestamp when the model request completed. format: date-time - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `type: "span.outcome_evaluation_ongoing"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when this heartbeat was emitted. format: date-time - `BetaManagedAgentsUserDefineOutcomeEvent object` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `type: "user.define_outcome"` - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number or null` Evaluate-then-revise cycles before giving up. Default 3, max 20. format: int32 - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` Timestamp when the outcome was accepted. format: date-time - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `BetaManagedAgentsFileRubric object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `BetaManagedAgentsTextRubric object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `BetaManagedAgentsSessionDeletedEvent object` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `type: "session.deleted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the session was deleted. format: date-time - `BetaManagedAgentsSessionThreadStatusRunningEvent object` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_running"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `BetaManagedAgentsSessionThreadStatusIdleEvent object` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_idle"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_details: BetaManagedAgentsSessionRefusalStopDetails or null` Structured information about why the thread stopped. `null` when there is nothing more to report. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `BetaManagedAgentsSessionEndTurn object` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionRequiresAction object` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `BetaManagedAgentsSessionRetriesExhausted object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `BetaManagedAgentsSessionBudgetReached object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `BetaManagedAgentsSessionRefusal object` The turn ended because the model's response was refused, for example by a safety classifier. - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_terminated"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `BetaManagedAgentsUserToolResultEvent object` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `type: "user.tool_result"` - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `processed_at: optional string or null` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_rescheduled"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `BetaManagedAgentsSessionUpdatedEvent object` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `type: "session.updated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the update was applied. format: date-time - `agent: optional BetaManagedAgentsSessionAgent or null` The session's effective agent configuration after the update. Present only when the update changed `agent` (tools or mcp_servers); when present it is the full materialised snapshot, not a diff. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 - `budget: optional BetaManagedAgentsBudgetLimit or null` The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `metadata: optional map[string]` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title: optional string or null` The session's new title. Present only when the update changed it. - `BetaManagedAgentsStartEvent object` Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history. - `type: "event_start"` - `event: BetaManagedAgentsStartEventPreview` The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them. - `BetaManagedAgentsAgentMessagePreview object` - `type: "agent.message"` - `id: string` The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events. - `BetaManagedAgentsAgentThinkingPreview object` - `type: "agent.thinking"` - `id: string` The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow. - `BetaManagedAgentsDeltaEvent object` An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history. - `type: "event_delta"` - `delta: BetaManagedAgentsDeltaContent` One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array. - `type: "content_delta"` - `content: BetaManagedAgentsTextBlock` A partial element of the content array at index, typed like the element itself — the same shape the buffered agent.message carries in content. - `index: optional number` Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise. - `event_id: string` The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview. - `BetaManagedAgentsSystemMessageEvent object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. - `type: "system.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `processed_at: optional string or null` Timestamp when this system message was processed. format: date-time - `BetaManagedAgentsSessionUsageEvent object` Periodic snapshot of the session's cumulative usage and tracked list cost. - `type: "session.usage"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the snapshot was taken. format: date-time - `usage: BetaManagedAgentsSessionUsageSnapshot` The session's cumulative usage at the snapshot time. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount` Cumulative list cost of the session across all turns, priced at public list rates. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage` Cumulative server-executed tool usage across all turns. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `budget: optional BetaManagedAgentsBudgetLimit or null` The session's configured budget at the snapshot time, or null when the session has no budget. - `BetaManagedAgentsWorkflowRunCreatedEvent object` A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events. - `type: "workflow_run.created"` - `id: string` Unique identifier for this event. - `description: string or null` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `phases: array of BetaManagedAgentsWorkflowRunPhase` The phases that the run's plan declares, in the plan's order. Can be empty. - `id: string` Unique identifier for the phase. - `description: string or null` Description that the agent gave the phase, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the phase, passed on as written. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunStatusEndedEvent object` A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events. - `type: "workflow_run.status_ended"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `result: BetaManagedAgentsWorkflowRunResult` How the run ended. - `BetaManagedAgentsWorkflowRunResultCompleted object` The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded. - `type: "completed"` - `BetaManagedAgentsWorkflowRunResultError object` The run failed or reached its time limit. - `type: "error"` - `error: BetaManagedAgentsWorkflowRunError` Why the run did not finish. - `BetaManagedAgentsTimeoutWorkflowRunError object` The run reached its time limit. - `type: "timeout_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsProgramWorkflowRunError object` The plan, a program that the agent wrote, failed, or the server refused it. - `type: "program_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsUnknownWorkflowRunError object` A failure that has no type of its own. - `type: "unknown_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsThreadLimitWorkflowRunError object` The run exceeded the limit on the number of threads that a run can create. - `type: "thread_limit_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsMaxWorkflowRunsWorkflowRunError object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `type: "max_workflow_runs_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsWorkflowRunResultStopped object` The agent stopped the run. - `type: "stopped"` - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunPhaseStartedEvent object` A workflow run's plan entered a phase. - `type: "workflow_run.phase_started"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `BetaManagedAgentsWorkflowRunPhaseEndedEvent object` A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left. - `type: "workflow_run.phase_ended"` - `id: string` Unique identifier for this event. - `phase_started_id: string` Identifier of the `workflow_run.phase_started` event that opened the phase. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `BetaManagedAgentsWorkflowRunStatusRunningEvent object` A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first. - `type: "workflow_run.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunStatusIdleEvent object` A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`. - `type: "workflow_run.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunErrorEvent object` A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`. - `type: "workflow_run.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsWorkflowRunError` Why the run did not finish, or was not created. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string or null` Identifier of the run that met the error, or `null` when the error kept a run from being created. #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` ##### Response (200) ```json { "id": "sevt_011CZkZGPp1iBcp4kaQSihUm", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ``` ## Sessions › Resources ### Add Session Resource **POST** `/v1/sessions/{session_id}/resources` Add Session Resource #### Path parameters - `session_id: string` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Body parameters - `file_id: string` ID of a previously uploaded file. minLength: 1, maxLength: 128 - `type: "file"` - `mount_path: optional string or null` Mount path in the container. Defaults to `/mnt/session/uploads/`. minLength: 1, maxLength: 4096 #### Returns - `BetaManagedAgentsFileResource object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" \ -d '{ "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "type": "file", "mount_path": "/uploads/receipt.pdf" }' ``` ##### Response (200) ```json { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" } ``` ### List Session Resources **GET** `/v1/sessions/{session_id}/resources` List Session Resources #### Path parameters - `session_id: string` #### Query parameters - `limit: optional number` Maximum number of resources to return per page (max 1000). If omitted, returns all resources. format: int32 - `page: optional string` Opaque cursor from a previous response's `next_page` field. #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `data: array of BetaManagedAgentsSessionResource` Resources for the session, ordered by `created_at`. - `BetaManagedAgentsGitHubRepositoryResource object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `BetaManagedAgentsFileResource object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `BetaManagedAgentsMemoryStoreResource object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only" or null` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string or null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string or null` 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. - `name: optional string or null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `next_page: optional string or null` Opaque cursor for the next page. Null when no more results. #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` ##### Response (200) ```json { "data": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXym1gWMPdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ### Get Session Resource **GET** `/v1/sessions/{session_id}/resources/{resource_id}` Get Session Resource #### Path parameters - `session_id: string` - `resource_id: string` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsGitHubRepositoryResource object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `BetaManagedAgentsFileResource object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `BetaManagedAgentsMemoryStoreResource object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only" or null` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string or null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string or null` 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. - `name: optional string or null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` ##### Response (200) ```json { "id": "sesrsc_011CZkZCKr6eXym1gWMPdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ``` ### Update Session Resource **POST** `/v1/sessions/{session_id}/resources/{resource_id}` Update Session Resource #### Path parameters - `session_id: string` - `resource_id: string` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Body parameters - `authorization_token: string` New authorization token for the resource. Currently only `github_repository` resources support token rotation. minLength: 1, maxLength: 4096 #### Returns - `BetaManagedAgentsGitHubRepositoryResource object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` - `BetaManagedAgentsBranchCheckout object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `BetaManagedAgentsCommitCheckout object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `BetaManagedAgentsFileResource object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `BetaManagedAgentsMemoryStoreResource object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only" or null` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string or null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string or null` 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. - `name: optional string or null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" \ -d '{ "authorization_token": "ghp_exampletoken" }' ``` ##### Response (200) ```json { "id": "sesrsc_011CZkZCKr6eXym1gWMPdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ``` ### Delete Session Resource **DELETE** `/v1/sessions/{session_id}/resources/{resource_id}` Delete Session Resource #### Path parameters - `session_id: string` - `resource_id: string` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsDeleteSessionResource object` Confirmation of resource deletion. - `type: "session_resource_deleted"` - `id: string` #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \ -X DELETE \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` ##### Response (200) ```json { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "type": "session_resource_deleted" } ``` ## Sessions › Threads ### List Session Threads **GET** `/v1/sessions/{session_id}/threads` List Session Threads #### Path parameters - `session_id: string` #### Query parameters - `limit: optional number` Maximum results per page. Defaults to 1000. format: int32 - `page: optional string` Opaque pagination cursor from a previous response's `next_page`. Forward-only. - `statuses: optional array of BetaManagedAgentsSessionThreadStatus` Return only threads that have one of these statuses. Repeat the parameter to give more than one status. Leave it out to return threads of every status. - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `data: optional array of BetaManagedAgentsSessionThread` Threads in the session, primary first then children in spawn order. - `type: "session_thread"` - `id: string` Unique identifier for this thread. - `agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor or BetaManagedAgentsInlineAgent` Resolved agent definition for this thread. Snapshot of the agent at thread creation time. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsInlineAgent object` An agent that has no Agent resource, and so no `id` or `version`. It is defined inline, in a workflow run's plan or when a session thread is spawned, and is not saved. - `type: "inline"` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` The session's execution principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` The name that the agent's definition gave, or one that the server assigned. - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `archived_at: string or null` When the thread was archived. Null if not archived. format: date-time - `created_at: string` When the thread was created. format: date-time - `parent_thread_id: string or null` Parent thread that spawned this thread. Null for the primary thread. - `session_id: string` The session this thread belongs to. - `stats: BetaManagedAgentsSessionThreadStats or null` Timing statistics for this thread. Null until the thread's first status transition. - `active_seconds: optional number` Cumulative time in seconds the thread spent actively running. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. format: double - `startup_seconds: optional number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. format: double - `status: BetaManagedAgentsSessionThreadStatus` Current execution status of the thread. - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` - `updated_at: string` When the thread was last updated. format: date-time - `usage: BetaManagedAgentsSessionThreadUsage or null` Cumulative token usage for this thread. Null until the thread's first idle transition. - `active_seconds: optional number` Cumulative time in seconds this thread spent in running status. Equal to `stats.active_seconds`; surfaced here so a thread's usage carries every quantity its cost is priced on. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount or null` Cumulative list cost of this thread across all turns, priced at public list rates. Absent until cost tracking is available for the thread. Each figure is rounded to the nearest cent independently and the session's aggregate `usage.list_cost` additionally includes session runtime, so per-thread costs do not sum exactly to the session figure; the session figure is authoritative and is what a budget is enforced against. - `amount: string` 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. - `currency: BetaCurrency` 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. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative server-executed tool usage across all turns of this thread. Absent until server-tool tracking is available for the thread. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `workflow_run_id: string or null` Identifier of the workflow run that created the thread, or `null` for any other thread. - `next_page: optional string or null` Opaque cursor for the next page. Null when no more results. #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` ##### Response (200) ```json { "data": [ { "id": "sthr_011CZkZVWa6oJjw1rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "parent_thread_id": null, "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "stats": { "active_seconds": 0, "duration_seconds": 0, "startup_seconds": 0 }, "status": "idle", "type": "session_thread", "updated_at": "2026-03-15T10:00:00Z", "usage": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "workflow_run_id": null } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ### Get Session Thread **GET** `/v1/sessions/{session_id}/threads/{thread_id}` Get Session Thread #### Path parameters - `session_id: string` - `thread_id: string` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsSessionThread object` An execution thread within a `session`. Each session has one primary thread plus zero or more child threads. - `type: "session_thread"` - `id: string` Unique identifier for this thread. - `agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor or BetaManagedAgentsInlineAgent` Resolved agent definition for this thread. Snapshot of the agent at thread creation time. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsInlineAgent object` An agent that has no Agent resource, and so no `id` or `version`. It is defined inline, in a workflow run's plan or when a session thread is spawned, and is not saved. - `type: "inline"` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` The session's execution principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` The name that the agent's definition gave, or one that the server assigned. - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `archived_at: string or null` When the thread was archived. Null if not archived. format: date-time - `created_at: string` When the thread was created. format: date-time - `parent_thread_id: string or null` Parent thread that spawned this thread. Null for the primary thread. - `session_id: string` The session this thread belongs to. - `stats: BetaManagedAgentsSessionThreadStats or null` Timing statistics for this thread. Null until the thread's first status transition. - `active_seconds: optional number` Cumulative time in seconds the thread spent actively running. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. format: double - `startup_seconds: optional number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. format: double - `status: BetaManagedAgentsSessionThreadStatus` Current execution status of the thread. - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` - `updated_at: string` When the thread was last updated. format: date-time - `usage: BetaManagedAgentsSessionThreadUsage or null` Cumulative token usage for this thread. Null until the thread's first idle transition. - `active_seconds: optional number` Cumulative time in seconds this thread spent in running status. Equal to `stats.active_seconds`; surfaced here so a thread's usage carries every quantity its cost is priced on. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount or null` Cumulative list cost of this thread across all turns, priced at public list rates. Absent until cost tracking is available for the thread. Each figure is rounded to the nearest cent independently and the session's aggregate `usage.list_cost` additionally includes session runtime, so per-thread costs do not sum exactly to the session figure; the session figure is authoritative and is what a budget is enforced against. - `amount: string` 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. - `currency: BetaCurrency` 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. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative server-executed tool usage across all turns of this thread. Absent until server-tool tracking is available for the thread. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `workflow_run_id: string or null` Identifier of the workflow run that created the thread, or `null` for any other thread. #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` ##### Response (200) ```json { "id": "sthr_011CZkZVWa6oJjw1rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "parent_thread_id": null, "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "stats": { "active_seconds": 0, "duration_seconds": 0, "startup_seconds": 0 }, "status": "idle", "type": "session_thread", "updated_at": "2026-03-15T10:00:00Z", "usage": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "workflow_run_id": null } ``` ### Archive Session Thread **POST** `/v1/sessions/{session_id}/threads/{thread_id}/archive` Archive Session Thread #### Path parameters - `session_id: string` - `thread_id: string` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsSessionThread object` An execution thread within a `session`. Each session has one primary thread plus zero or more child threads. - `type: "session_thread"` - `id: string` Unique identifier for this thread. - `agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor or BetaManagedAgentsInlineAgent` Resolved agent definition for this thread. Snapshot of the agent at thread creation time. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsInlineAgent object` An agent that has no Agent resource, and so no `id` or `version`. It is defined inline, in a workflow run's plan or when a session thread is spawned, and is not saved. - `type: "inline"` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` The session's execution principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` The name that the agent's definition gave, or one that the server assigned. - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `archived_at: string or null` When the thread was archived. Null if not archived. format: date-time - `created_at: string` When the thread was created. format: date-time - `parent_thread_id: string or null` Parent thread that spawned this thread. Null for the primary thread. - `session_id: string` The session this thread belongs to. - `stats: BetaManagedAgentsSessionThreadStats or null` Timing statistics for this thread. Null until the thread's first status transition. - `active_seconds: optional number` Cumulative time in seconds the thread spent actively running. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. format: double - `startup_seconds: optional number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. format: double - `status: BetaManagedAgentsSessionThreadStatus` Current execution status of the thread. - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` - `updated_at: string` When the thread was last updated. format: date-time - `usage: BetaManagedAgentsSessionThreadUsage or null` Cumulative token usage for this thread. Null until the thread's first idle transition. - `active_seconds: optional number` Cumulative time in seconds this thread spent in running status. Equal to `stats.active_seconds`; surfaced here so a thread's usage carries every quantity its cost is priced on. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount or null` Cumulative list cost of this thread across all turns, priced at public list rates. Absent until cost tracking is available for the thread. Each figure is rounded to the nearest cent independently and the session's aggregate `usage.list_cost` additionally includes session runtime, so per-thread costs do not sum exactly to the session figure; the session figure is authoritative and is what a budget is enforced against. - `amount: string` 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. - `currency: BetaCurrency` 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. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative server-executed tool usage across all turns of this thread. Absent until server-tool tracking is available for the thread. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `workflow_run_id: string or null` Identifier of the workflow run that created the thread, or `null` for any other thread. #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/archive \ -X POST \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` ##### Response (200) ```json { "id": "sthr_011CZkZVWa6oJjw1rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "parent_thread_id": null, "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "stats": { "active_seconds": 0, "duration_seconds": 0, "startup_seconds": 0 }, "status": "idle", "type": "session_thread", "updated_at": "2026-03-15T10:00:00Z", "usage": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "workflow_run_id": null } ``` ## Sessions › Threads › Events ### List Session Thread Events **GET** `/v1/sessions/{session_id}/threads/{thread_id}/events` List Session Thread Events #### Path parameters - `session_id: string` - `thread_id: string` #### Query parameters - `limit: optional number` format: int32 - `page: optional string` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `data: optional array of BetaManagedAgentsSessionEvent` Events for the thread, ordered by `processed_at`. - `BetaManagedAgentsUserMessageEvent object` A user message event in the session conversation. - `type: "user.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `BetaManagedAgentsBase64ImageSource object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `BetaManagedAgentsURLImageSource object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `BetaManagedAgentsFileImageSource object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `BetaManagedAgentsBase64DocumentSource object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `BetaManagedAgentsPlainTextDocumentSource object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `BetaManagedAgentsURLDocumentSource object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `BetaManagedAgentsFileDocumentSource object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string or null` Additional context about the document for the model. - `title: optional string or null` The title of the document. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `processed_at: optional string or null` Timestamp when the agent finished processing this message. format: date-time - `BetaManagedAgentsUserInterruptEvent object` An interrupt event that pauses agent execution and returns control to the user. - `type: "user.interrupt"` - `id: string` Unique identifier for this event. - `processed_at: optional string or null` Timestamp when the interrupt was processed. format: date-time - `session_thread_id: optional string or null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent object` A tool confirmation event that approves or denies a pending tool execution. - `type: "user.tool_confirmation"` - `id: string` Unique identifier for this event. - `result: "allow" or "deny"` The confirmation result: 'allow' or 'deny'. - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `deny_message: optional string or null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. maxLength: 10000 - `processed_at: optional string or null` Timestamp when the confirmation was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsUserCustomToolResultEvent object` Event sent by the client providing the result of a custom tool execution. - `type: "user.custom_tool_result"` - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `type: "search_result"` - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `processed_at: optional string or null` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsAgentCustomToolUseEvent object` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. The client can send it as soon as this event arrives, without waiting for `session.status_idle`. - `type: "agent.custom_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` Timestamp when this tool use was processed. format: date-time - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentMessageEvent object` An agent response event in the session conversation. - `type: "agent.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock` Array of text blocks comprising the agent response. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when this response was generated. format: date-time - `BetaManagedAgentsAgentThinkingEvent object` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `type: "agent.thinking"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this thinking was produced. format: date-time - `BetaManagedAgentsAgentMCPToolUseEvent object` Event emitted when the agent invokes a tool provided by an MCP server. - `type: "agent.mcp_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluation` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `type: "always_allow"` - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `type: "always_ask"` - `BetaManagedAgentsAgentToolEvaluationAuto object` The resolved permission_policy was auto: the server judged this invocation individually. - `type: "auto"` - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission` The server's judgement for this invocation. - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object` The server judged the invocation safe to execute without client approval. - `type: "allow"` - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object` The server reached no judgement; the invocation is held for client approval. - `type: "ask"` - `reason_code: string` The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set. maxLength: 64 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object` The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended. - `type: "deny"` - `reason_code: string` The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set. maxLength: 64 - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentMCPToolResultEvent object` Event representing the result of an MCP tool execution. - `type: "agent.mcp_tool_result"` - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` Timestamp when this event was processed. format: date-time - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentToolUseEvent object` Event emitted when the agent invokes a built-in agent tool. - `type: "agent.tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission` The evaluated permission policy for this tool invocation. - `evaluation: optional BetaManagedAgentsAgentToolEvaluation` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentToolResultEvent object` Event representing the result of an agent tool execution. - `type: "agent.tool_result"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentThreadMessageReceivedEvent object` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `type: "agent.thread_message_received"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` Timestamp when the message was received. format: date-time - `from_agent_name: optional string or null` Name of the callable agent this message came from. Absent when received from the primary agent. - `BetaManagedAgentsAgentThreadMessageSentEvent object` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `type: "agent.thread_message_sent"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when the message was sent. format: date-time - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `to_agent_name: optional string or null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `BetaManagedAgentsAgentThreadContextCompactedEvent object` Indicates that context compaction (summarization) occurred during the session. - `type: "agent.thread_context_compacted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when compaction was processed. format: date-time - `BetaManagedAgentsSessionErrorEvent object` An error event indicating a problem occurred during session execution. - `type: "session.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 10 more` - `BetaManagedAgentsUnknownError object` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `type: "unknown_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `BetaManagedAgentsModelOverloadedError object` The model is currently overloaded. Emitted after automatic retries are exhausted. - `type: "model_overloaded_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsModelRateLimitedError object` The model request was rate-limited. - `type: "model_rate_limited_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsModelRequestFailedError object` A model request failed for a reason other than overload or rate-limiting. - `type: "model_request_failed_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsMCPConnectionFailedError object` Failed to connect to an MCP server. - `type: "mcp_connection_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsMCPAuthenticationFailedError object` Authentication to an MCP server failed. - `type: "mcp_authentication_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsBillingError object` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `type: "billing_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsCredentialHostUnreachableError object` An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit. - `type: "credential_host_unreachable_error"` - `credential_id: string` ID of the affected credential. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `vault_id: string` ID of the vault containing the affected credential. - `BetaManagedAgentsRepositoryAuthenticationError object` The repository host rejected the credentials, or required credentials and received none. - `type: "repository_authentication_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryForbiddenError object` The repository host refused access to the repository. - `type: "repository_forbidden_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryNotFoundError object` The repository host reported the repository as not found. - `type: "repository_not_found_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryCheckoutError object` The requested branch or commit does not exist in the repository. - `type: "repository_checkout_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryCloneError object` The repository could not be cloned. - `type: "repository_clone_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `processed_at: string` Timestamp when the error occurred. format: date-time - `BetaManagedAgentsSessionStatusRescheduledEvent object` Indicates the session is recovering from an error state and is rescheduled for execution. - `type: "session.status_rescheduled"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionStatusRunningEvent object` Indicates the session is actively running and the agent is working. - `type: "session.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionStatusIdleEvent object` Indicates the agent has paused and is awaiting user input. - `type: "session.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `stop_details: BetaManagedAgentsSessionRefusalStopDetails or null` Structured information about why the session stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more or null` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `"cyber"` - `"bio"` - `"frontier_llm"` - `"reasoning_extraction"` - `"general_harms"` - `explanation: string or null` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `BetaManagedAgentsSessionEndTurn object` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `BetaManagedAgentsSessionRequiresAction object` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `type: "requires_action"` - `event_ids: array of string` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `BetaManagedAgentsSessionRetriesExhausted object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `type: "retries_exhausted"` - `BetaManagedAgentsSessionBudgetReached object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `type: "budget_reached"` - `BetaManagedAgentsSessionRefusal object` The turn ended because the model's response was refused, for example by a safety classifier. - `type: "refusal"` - `BetaManagedAgentsSessionStatusTerminatedEvent object` Indicates the session has terminated, either due to an error or completion. - `type: "session.status_terminated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionThreadCreatedEvent object` Emitted when a child thread is created. Written to the parent thread's output stream so clients observing the session see child creation. - `type: "session.thread_created"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` Timestamp when the thread was created. format: date-time - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `workflow_run_id: string or null` Identifier of the workflow run that created the thread, or `null` for any other thread. - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object` Emitted when an outcome evaluation cycle begins. - `type: "span.outcome_evaluation_start"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation started. format: date-time - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `type: "span.outcome_evaluation_end"` - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation ended. format: date-time - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `usage: BetaManagedAgentsSpanModelUsage` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast" or null` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `"standard"` - `"fast"` - `BetaManagedAgentsSpanModelRequestStartEvent object` Emitted when a model request is initiated by the agent. - `type: "span.model_request_start"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the model request started. format: date-time - `BetaManagedAgentsSpanModelRequestEndEvent object` Emitted when a model request completes. - `type: "span.model_request_end"` - `id: string` Unique identifier for this event. - `is_error: boolean or null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for this model request. - `processed_at: string` Timestamp when the model request completed. format: date-time - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `type: "span.outcome_evaluation_ongoing"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when this heartbeat was emitted. format: date-time - `BetaManagedAgentsUserDefineOutcomeEvent object` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `type: "user.define_outcome"` - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number or null` Evaluate-then-revise cycles before giving up. Default 3, max 20. format: int32 - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` Timestamp when the outcome was accepted. format: date-time - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `BetaManagedAgentsFileRubric object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `BetaManagedAgentsTextRubric object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `BetaManagedAgentsSessionDeletedEvent object` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `type: "session.deleted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the session was deleted. format: date-time - `BetaManagedAgentsSessionThreadStatusRunningEvent object` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_running"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `BetaManagedAgentsSessionThreadStatusIdleEvent object` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_idle"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_details: BetaManagedAgentsSessionRefusalStopDetails or null` Structured information about why the thread stopped. `null` when there is nothing more to report. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `BetaManagedAgentsSessionEndTurn object` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionRequiresAction object` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `BetaManagedAgentsSessionRetriesExhausted object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `BetaManagedAgentsSessionBudgetReached object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `BetaManagedAgentsSessionRefusal object` The turn ended because the model's response was refused, for example by a safety classifier. - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_terminated"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `BetaManagedAgentsUserToolResultEvent object` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `type: "user.tool_result"` - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `processed_at: optional string or null` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_rescheduled"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `BetaManagedAgentsSessionUpdatedEvent object` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `type: "session.updated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the update was applied. format: date-time - `agent: optional BetaManagedAgentsSessionAgent or null` The session's effective agent configuration after the update. Present only when the update changed `agent` (tools or mcp_servers); when present it is the full materialised snapshot, not a diff. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 - `budget: optional BetaManagedAgentsBudgetLimit or null` The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `metadata: optional map[string]` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title: optional string or null` The session's new title. Present only when the update changed it. - `BetaManagedAgentsSystemMessageEvent object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. - `type: "system.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `processed_at: optional string or null` Timestamp when this system message was processed. format: date-time - `BetaManagedAgentsSessionUsageEvent object` Periodic snapshot of the session's cumulative usage and tracked list cost. - `type: "session.usage"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the snapshot was taken. format: date-time - `usage: BetaManagedAgentsSessionUsageSnapshot` The session's cumulative usage at the snapshot time. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount` Cumulative list cost of the session across all turns, priced at public list rates. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage` Cumulative server-executed tool usage across all turns. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `budget: optional BetaManagedAgentsBudgetLimit or null` The session's configured budget at the snapshot time, or null when the session has no budget. - `BetaManagedAgentsWorkflowRunCreatedEvent object` A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events. - `type: "workflow_run.created"` - `id: string` Unique identifier for this event. - `description: string or null` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `phases: array of BetaManagedAgentsWorkflowRunPhase` The phases that the run's plan declares, in the plan's order. Can be empty. - `id: string` Unique identifier for the phase. - `description: string or null` Description that the agent gave the phase, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the phase, passed on as written. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunStatusEndedEvent object` A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events. - `type: "workflow_run.status_ended"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `result: BetaManagedAgentsWorkflowRunResult` How the run ended. - `BetaManagedAgentsWorkflowRunResultCompleted object` The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded. - `type: "completed"` - `BetaManagedAgentsWorkflowRunResultError object` The run failed or reached its time limit. - `type: "error"` - `error: BetaManagedAgentsWorkflowRunError` Why the run did not finish. - `BetaManagedAgentsTimeoutWorkflowRunError object` The run reached its time limit. - `type: "timeout_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsProgramWorkflowRunError object` The plan, a program that the agent wrote, failed, or the server refused it. - `type: "program_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsUnknownWorkflowRunError object` A failure that has no type of its own. - `type: "unknown_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsThreadLimitWorkflowRunError object` The run exceeded the limit on the number of threads that a run can create. - `type: "thread_limit_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsMaxWorkflowRunsWorkflowRunError object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `type: "max_workflow_runs_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsWorkflowRunResultStopped object` The agent stopped the run. - `type: "stopped"` - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunPhaseStartedEvent object` A workflow run's plan entered a phase. - `type: "workflow_run.phase_started"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `BetaManagedAgentsWorkflowRunPhaseEndedEvent object` A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left. - `type: "workflow_run.phase_ended"` - `id: string` Unique identifier for this event. - `phase_started_id: string` Identifier of the `workflow_run.phase_started` event that opened the phase. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `BetaManagedAgentsWorkflowRunStatusRunningEvent object` A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first. - `type: "workflow_run.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunStatusIdleEvent object` A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`. - `type: "workflow_run.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunErrorEvent object` A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`. - `type: "workflow_run.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsWorkflowRunError` Why the run did not finish, or was not created. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string or null` Identifier of the run that met the error, or `null` when the error kept a run from being created. - `next_page: optional string or null` Opaque cursor for the next page. Null when no more results. #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` ##### Response (200) ```json { "data": [ { "id": "sevt_011CZkZGPp1iBcp4kaQSihUm", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" }, { "id": "sevt_011CZkZHPq1jCdq5mbRTjiVn", "content": [ { "text": "Let me look up order #1234 for you.", "type": "text" } ], "processed_at": "2026-03-15T10:00:00Z", "type": "agent.message" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ### Stream Session Thread Events **GET** `/v1/sessions/{session_id}/threads/{thread_id}/stream` Stream Session Thread Events #### Path parameters - `session_id: string` - `thread_id: string` #### Query parameters - `event_deltas: optional array of BetaManagedAgentsDeltaType` When set, this connection also receives streaming deltas (`event_start`, `event_delta`) while an event is being produced, before the event itself arrives. Deltas are best-effort; when the final event is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no final event — its terminal `span.model_request_end` closes the preview. Accepts one or more event types to preview and may be repeated: `agent.message` streams `content_delta` fragments; `agent.thinking` is start-only — a signal that the agent has begun extended thinking, concluded by the `agent.thinking` event itself. Only previews of the requested event types are sent. - `"agent.message"` - `"agent.thinking"` #### Headers - `"anthropic-version": optional string` The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http). - `"anthropic-beta": optional array of AnthropicBeta` This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"anthropic-workspace-id": optional string` Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 41 more` Server-sent event in a single thread's stream. - `BetaManagedAgentsUserMessageEvent object` A user message event in the session conversation. - `type: "user.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `BetaManagedAgentsBase64ImageSource object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `BetaManagedAgentsURLImageSource object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `BetaManagedAgentsFileImageSource object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `BetaManagedAgentsBase64DocumentSource object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `BetaManagedAgentsPlainTextDocumentSource object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `BetaManagedAgentsURLDocumentSource object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `BetaManagedAgentsFileDocumentSource object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string or null` Additional context about the document for the model. - `title: optional string or null` The title of the document. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `processed_at: optional string or null` Timestamp when the agent finished processing this message. format: date-time - `BetaManagedAgentsUserInterruptEvent object` An interrupt event that pauses agent execution and returns control to the user. - `type: "user.interrupt"` - `id: string` Unique identifier for this event. - `processed_at: optional string or null` Timestamp when the interrupt was processed. format: date-time - `session_thread_id: optional string or null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent object` A tool confirmation event that approves or denies a pending tool execution. - `type: "user.tool_confirmation"` - `id: string` Unique identifier for this event. - `result: "allow" or "deny"` The confirmation result: 'allow' or 'deny'. - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `deny_message: optional string or null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. maxLength: 10000 - `processed_at: optional string or null` Timestamp when the confirmation was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsUserCustomToolResultEvent object` Event sent by the client providing the result of a custom tool execution. - `type: "user.custom_tool_result"` - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `type: "search_result"` - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `processed_at: optional string or null` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsAgentCustomToolUseEvent object` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. The client can send it as soon as this event arrives, without waiting for `session.status_idle`. - `type: "agent.custom_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` Timestamp when this tool use was processed. format: date-time - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentMessageEvent object` An agent response event in the session conversation. - `type: "agent.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock` Array of text blocks comprising the agent response. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when this response was generated. format: date-time - `BetaManagedAgentsAgentThinkingEvent object` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `type: "agent.thinking"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this thinking was produced. format: date-time - `BetaManagedAgentsAgentMCPToolUseEvent object` Event emitted when the agent invokes a tool provided by an MCP server. - `type: "agent.mcp_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluation` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `type: "always_allow"` - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `type: "always_ask"` - `BetaManagedAgentsAgentToolEvaluationAuto object` The resolved permission_policy was auto: the server judged this invocation individually. - `type: "auto"` - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission` The server's judgement for this invocation. - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object` The server judged the invocation safe to execute without client approval. - `type: "allow"` - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object` The server reached no judgement; the invocation is held for client approval. - `type: "ask"` - `reason_code: string` The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set. maxLength: 64 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object` The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended. - `type: "deny"` - `reason_code: string` The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set. maxLength: 64 - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentMCPToolResultEvent object` Event representing the result of an MCP tool execution. - `type: "agent.mcp_tool_result"` - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` Timestamp when this event was processed. format: date-time - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentToolUseEvent object` Event emitted when the agent invokes a built-in agent tool. - `type: "agent.tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission` The evaluated permission policy for this tool invocation. - `evaluation: optional BetaManagedAgentsAgentToolEvaluation` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back. - `BetaManagedAgentsAgentToolResultEvent object` Event representing the result of an agent tool execution. - `type: "agent.tool_result"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentThreadMessageReceivedEvent object` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `type: "agent.thread_message_received"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` Timestamp when the message was received. format: date-time - `from_agent_name: optional string or null` Name of the callable agent this message came from. Absent when received from the primary agent. - `BetaManagedAgentsAgentThreadMessageSentEvent object` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `type: "agent.thread_message_sent"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when the message was sent. format: date-time - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `to_agent_name: optional string or null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `BetaManagedAgentsAgentThreadContextCompactedEvent object` Indicates that context compaction (summarization) occurred during the session. - `type: "agent.thread_context_compacted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when compaction was processed. format: date-time - `BetaManagedAgentsSessionErrorEvent object` An error event indicating a problem occurred during session execution. - `type: "session.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 10 more` - `BetaManagedAgentsUnknownError object` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `type: "unknown_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `BetaManagedAgentsModelOverloadedError object` The model is currently overloaded. Emitted after automatic retries are exhausted. - `type: "model_overloaded_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsModelRateLimitedError object` The model request was rate-limited. - `type: "model_rate_limited_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsModelRequestFailedError object` A model request failed for a reason other than overload or rate-limiting. - `type: "model_request_failed_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsMCPConnectionFailedError object` Failed to connect to an MCP server. - `type: "mcp_connection_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsMCPAuthenticationFailedError object` Authentication to an MCP server failed. - `type: "mcp_authentication_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsBillingError object` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `type: "billing_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsCredentialHostUnreachableError object` An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit. - `type: "credential_host_unreachable_error"` - `credential_id: string` ID of the affected credential. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `vault_id: string` ID of the vault containing the affected credential. - `BetaManagedAgentsRepositoryAuthenticationError object` The repository host rejected the credentials, or required credentials and received none. - `type: "repository_authentication_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryForbiddenError object` The repository host refused access to the repository. - `type: "repository_forbidden_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryNotFoundError object` The repository host reported the repository as not found. - `type: "repository_not_found_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryCheckoutError object` The requested branch or commit does not exist in the repository. - `type: "repository_checkout_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `BetaManagedAgentsRepositoryCloneError object` The repository could not be cloned. - `type: "repository_clone_error"` - `message: string` Human-readable error description. - `repository_url: string or null` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `BetaManagedAgentsRetryStatusRetrying object` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `processed_at: string` Timestamp when the error occurred. format: date-time - `BetaManagedAgentsSessionStatusRescheduledEvent object` Indicates the session is recovering from an error state and is rescheduled for execution. - `type: "session.status_rescheduled"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionStatusRunningEvent object` Indicates the session is actively running and the agent is working. - `type: "session.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionStatusIdleEvent object` Indicates the agent has paused and is awaiting user input. - `type: "session.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `stop_details: BetaManagedAgentsSessionRefusalStopDetails or null` Structured information about why the session stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more or null` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `"cyber"` - `"bio"` - `"frontier_llm"` - `"reasoning_extraction"` - `"general_harms"` - `explanation: string or null` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `BetaManagedAgentsSessionEndTurn object` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `BetaManagedAgentsSessionRequiresAction object` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `type: "requires_action"` - `event_ids: array of string` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `BetaManagedAgentsSessionRetriesExhausted object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `type: "retries_exhausted"` - `BetaManagedAgentsSessionBudgetReached object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `type: "budget_reached"` - `BetaManagedAgentsSessionRefusal object` The turn ended because the model's response was refused, for example by a safety classifier. - `type: "refusal"` - `BetaManagedAgentsSessionStatusTerminatedEvent object` Indicates the session has terminated, either due to an error or completion. - `type: "session.status_terminated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `BetaManagedAgentsSessionThreadCreatedEvent object` Emitted when a child thread is created. Written to the parent thread's output stream so clients observing the session see child creation. - `type: "session.thread_created"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` Timestamp when the thread was created. format: date-time - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `workflow_run_id: string or null` Identifier of the workflow run that created the thread, or `null` for any other thread. - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object` Emitted when an outcome evaluation cycle begins. - `type: "span.outcome_evaluation_start"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation started. format: date-time - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `type: "span.outcome_evaluation_end"` - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation ended. format: date-time - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `usage: BetaManagedAgentsSpanModelUsage` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast" or null` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `"standard"` - `"fast"` - `BetaManagedAgentsSpanModelRequestStartEvent object` Emitted when a model request is initiated by the agent. - `type: "span.model_request_start"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the model request started. format: date-time - `BetaManagedAgentsSpanModelRequestEndEvent object` Emitted when a model request completes. - `type: "span.model_request_end"` - `id: string` Unique identifier for this event. - `is_error: boolean or null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for this model request. - `processed_at: string` Timestamp when the model request completed. format: date-time - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `type: "span.outcome_evaluation_ongoing"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when this heartbeat was emitted. format: date-time - `BetaManagedAgentsUserDefineOutcomeEvent object` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `type: "user.define_outcome"` - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number or null` Evaluate-then-revise cycles before giving up. Default 3, max 20. format: int32 - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` Timestamp when the outcome was accepted. format: date-time - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `BetaManagedAgentsFileRubric object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `BetaManagedAgentsTextRubric object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `BetaManagedAgentsSessionDeletedEvent object` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `type: "session.deleted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the session was deleted. format: date-time - `BetaManagedAgentsSessionThreadStatusRunningEvent object` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_running"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `BetaManagedAgentsSessionThreadStatusIdleEvent object` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_idle"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_details: BetaManagedAgentsSessionRefusalStopDetails or null` Structured information about why the thread stopped. `null` when there is nothing more to report. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `BetaManagedAgentsSessionEndTurn object` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionRequiresAction object` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `BetaManagedAgentsSessionRetriesExhausted object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `BetaManagedAgentsSessionBudgetReached object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `BetaManagedAgentsSessionRefusal object` The turn ended because the model's response was refused, for example by a safety classifier. - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_terminated"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `BetaManagedAgentsUserToolResultEvent object` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `type: "user.tool_result"` - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=http#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `BetaManagedAgentsTextBlock object` Regular text content. - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result. - `is_error: optional boolean or null` Whether the tool execution resulted in an error. - `processed_at: optional string or null` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string or null` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_rescheduled"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `BetaManagedAgentsSessionUpdatedEvent object` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `type: "session.updated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the update was applied. format: date-time - `agent: optional BetaManagedAgentsSessionAgent or null` The session's effective agent configuration after the update. Present only when the update changed `agent` (tools or mcp_servers); when present it is the full materialised snapshot, not a diff. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `BetaManagedAgentsAWSRoleExecutionIdentity object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `BetaManagedAgentsServiceAccountExecutionIdentity object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `string` - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagent or null` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `BetaManagedAgentsSessionMultiagentCoordinator object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `BetaManagedAgentsSessionThreadAgent object` 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`. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `BetaManagedAgentsAutoPolicy object` 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. - `type: "auto"` - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `url_sources: BetaManagedAgentsWebFetchURLSources or null` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `type: "none"` - `BetaManagedAgentsWebFetchURLSourceOnly object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `BetaManagedAgentsWebFetchURLSourceExcept object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `BetaManagedAgentsWebFetchURLSourceAll object` Every URL from this source may be fetched. This is the default. - `BetaManagedAgentsWebFetchURLSourceNone object` This source contributes no URLs that may be fetched. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` format: int32 - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string or null` City name. minLength: 1, maxLength: 255 - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string or null` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `BetaManagedAgentsMCPToolset object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `BetaManagedAgentsAutoPolicy object` 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. - `mcp_server_name: string` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown] or null` - `required: optional array of string or null` - `name: string` - `version: number` format: int32 - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `BetaManagedAgentsSessionMultiagent20261001 object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentAdvisorEnabled object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `BetaManagedAgentsMultiagentAdvisorDisabled object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagents` Whether the agent can spawn session threads. - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `BetaManagedAgentsMultiagentInlineAgentsEnabled object` The agent can define inline agents. - `type: "enabled"` - `BetaManagedAgentsMultiagentInlineAgentsDisabled object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentSubagentsDisabled object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflows` Whether the agent can start workflow runs. - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string or null` - `execution_identity: BetaManagedAgentsExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `BetaManagedAgentsMultiagentWorkflowsDisabled object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill. - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `BetaManagedAgentsAgentToolset20260401 object` - `BetaManagedAgentsMCPToolset object` - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `version: number` format: int32 - `budget: optional BetaManagedAgentsBudgetLimit or null` The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget. - `type: "limit"` - `max_list_cost: BetaMonetaryAmount` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` 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. - `currency: BetaCurrency` 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. - `metadata: optional map[string]` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title: optional string or null` The session's new title. Present only when the update changed it. - `BetaManagedAgentsStartEvent object` Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history. - `type: "event_start"` - `event: BetaManagedAgentsStartEventPreview` The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them. - `BetaManagedAgentsAgentMessagePreview object` - `type: "agent.message"` - `id: string` The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events. - `BetaManagedAgentsAgentThinkingPreview object` - `type: "agent.thinking"` - `id: string` The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow. - `BetaManagedAgentsDeltaEvent object` An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history. - `type: "event_delta"` - `delta: BetaManagedAgentsDeltaContent` One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array. - `type: "content_delta"` - `content: BetaManagedAgentsTextBlock` A partial element of the content array at index, typed like the element itself — the same shape the buffered agent.message carries in content. - `index: optional number` Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise. - `event_id: string` The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview. - `BetaManagedAgentsSystemMessageEvent object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. - `type: "system.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `processed_at: optional string or null` Timestamp when this system message was processed. format: date-time - `BetaManagedAgentsSessionUsageEvent object` Periodic snapshot of the session's cumulative usage and tracked list cost. - `type: "session.usage"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the snapshot was taken. format: date-time - `usage: BetaManagedAgentsSessionUsageSnapshot` The session's cumulative usage at the snapshot time. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional BetaMonetaryAmount` Cumulative list cost of the session across all turns, priced at public list rates. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional BetaManagedAgentsServerToolUsage` Cumulative server-executed tool usage across all turns. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `budget: optional BetaManagedAgentsBudgetLimit or null` The session's configured budget at the snapshot time, or null when the session has no budget. - `BetaManagedAgentsWorkflowRunCreatedEvent object` A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events. - `type: "workflow_run.created"` - `id: string` Unique identifier for this event. - `description: string or null` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `phases: array of BetaManagedAgentsWorkflowRunPhase` The phases that the run's plan declares, in the plan's order. Can be empty. - `id: string` Unique identifier for the phase. - `description: string or null` Description that the agent gave the phase, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the phase, passed on as written. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunStatusEndedEvent object` A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events. - `type: "workflow_run.status_ended"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `result: BetaManagedAgentsWorkflowRunResult` How the run ended. - `BetaManagedAgentsWorkflowRunResultCompleted object` The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded. - `type: "completed"` - `BetaManagedAgentsWorkflowRunResultError object` The run failed or reached its time limit. - `type: "error"` - `error: BetaManagedAgentsWorkflowRunError` Why the run did not finish. - `BetaManagedAgentsTimeoutWorkflowRunError object` The run reached its time limit. - `type: "timeout_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsProgramWorkflowRunError object` The plan, a program that the agent wrote, failed, or the server refused it. - `type: "program_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsUnknownWorkflowRunError object` A failure that has no type of its own. - `type: "unknown_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsThreadLimitWorkflowRunError object` The run exceeded the limit on the number of threads that a run can create. - `type: "thread_limit_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsMaxWorkflowRunsWorkflowRunError object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `type: "max_workflow_runs_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `BetaManagedAgentsWorkflowRunResultStopped object` The agent stopped the run. - `type: "stopped"` - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunPhaseStartedEvent object` A workflow run's plan entered a phase. - `type: "workflow_run.phase_started"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `BetaManagedAgentsWorkflowRunPhaseEndedEvent object` A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left. - `type: "workflow_run.phase_ended"` - `id: string` Unique identifier for this event. - `phase_started_id: string` Identifier of the `workflow_run.phase_started` event that opened the phase. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `BetaManagedAgentsWorkflowRunStatusRunningEvent object` A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first. - `type: "workflow_run.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunStatusIdleEvent object` A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`. - `type: "workflow_run.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `BetaManagedAgentsWorkflowRunErrorEvent object` A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`. - `type: "workflow_run.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsWorkflowRunError` Why the run did not finish, or was not created. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string or null` Identifier of the run that met the error, or `null` when the error kept a run from being created. #### Example ```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` ##### Response (200) ```json { "id": "sevt_011CZkZGPp1iBcp4kaQSihUm", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ```