# title: Sessions url: https://platform.claude.com/docs/en/api/beta/sessions

# Sessions

# Create Session

POST /v1/sessions

Create Session

# Headers

"anthropic-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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, or a model_config object. Omit to use the agent's model.
    - BetaManagedAgentsModel = "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more or string
      
      The model that will power your agent.
      
      See models for additional details and options.
      - "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
      - string
    - BetaManagedAgentsModelConfigParams object
      
      An object that defines additional configuration control over model use
      - id: BetaManagedAgentsModel
        
        The model that will power your agent.
        
        See models 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.
        
        BetaManagedAgentsEffortLevel = "low" or "medium" or "high" or 2 more
        
        How hard Claude works on each turn. Higher levels favor reasoning depth over latency. Not all models accept every level; invalid combinations are rejected at create time.
        
        "low"
        
        "medium"
        
        "high"
        
        "xhigh"
        
        "max"
        
        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. fast provides significantly faster output token generation at premium pricing. Not all models support fast; invalid combinations are rejected at create time.
        
        "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 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"
        
        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 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.
        
        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 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.
        
        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 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.
        
        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 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.
        
        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 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.
        
        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 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.
        
        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 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.
        
        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 for all tools in a toolset.
        
        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
        
        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.
    - 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 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: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null
        
        Default configuration for all tools from an MCP 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
        
        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.
    - 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 for custom tool input parameters.
        
        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

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
  
  A monetary amount in a specific currency.
  - 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
        
        Union type for image source variants.
        
        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
        
        Union type for document source variants.
        
        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
    
    Rubric for grading the quality of an outcome.
    - 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/<repo-name>.
    
    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/<file_id>.
    
    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 an attached memory store.
    - "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
  - 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 for additional details and options.
      - "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
      - string
    - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
      
      How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
      - 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. Not all models support fast; invalid combinations are rejected at create time.
      - "standard"
      - "fast"
  - multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
    
    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
        
        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.
        
        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.
  - 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
  
  A timestamp in RFC 3339 format
  
  format: date-time
- budget: BetaManagedAgentsBudgetLimit or null
  
  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
    
    A monetary amount in a specific currency.
    - 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
    
    A timestamp in RFC 3339 format
    
    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 an attached memory store.
      - "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 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
- status: "rescheduling" or "running" or "idle" or "terminated"
  
  SessionStatus enum
  - "rescheduling"
  - "running"
  - "idle"
  - "terminated"
- title: string or null
- updated_at: string
  
  A timestamp in RFC 3339 format
  
  format: date-time
- usage: BetaManagedAgentsSessionUsage
  
  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
    
    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
  - 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
    
    A monetary amount in a specific currency.
  - output_tokens: optional number
    
    Total output tokens generated across all turns.
    
    format: int32
  - server_tool_use: optional BetaManagedAgentsServerToolUsage or null
    
    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
- 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",
          "title": "Order #1234 inquiry"
        }'

# Response (200)

json

{
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "agent": {
    "id": "agent_011CZkYpogX7uDKUyvBTophP",
    "description": "A general-purpose starter agent.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-opus-5",
      "effort": {
        "type": "low"
      },
      "inference_geo": "inference_geo",
      "speed": "standard"
    },
    "multiagent": {
      "agents": [
        {
          "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
          "description": "A focused research subagent.",
          "mcp_servers": [
            {
              "name": "example-mcp",
              "type": "url",
              "url": "https://example-server.modelcontextprotocol.io/sse"
            }
          ],
          "model": {
            "id": "claude-opus-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_011CZkZFNu9hAbo3jZPRgTlx",
        "type": "custom",
        "version": "2"
      }
    ],
    "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
    "tools": [
      {
        "configs": [
          {
            "enabled": true,
            "name": "bash",
            "permission_policy": {
              "type": "always_allow"
            },
            "type": "bash"
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "type": "agent_toolset_20260401"
      }
    ],
    "type": "agent",
    "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_011CZkZRSw2kEfs6ncTVljxP",
      "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_011CZkZCKr6eXyl0gWMOdQiu",
      "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"
- "running"
- "idle"
- "terminated"

# Headers

"anthropic-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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
  - 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 for additional details and options.
      - "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
      - string
    - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
      
      How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
      - 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. Not all models support fast; invalid combinations are rejected at create time.
      - "standard"
      - "fast"
  - multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
    
    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
        
        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.
        
        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.
  - 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
  
  A timestamp in RFC 3339 format
  
  format: date-time
- budget: BetaManagedAgentsBudgetLimit or null
  
  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
    
    A monetary amount in a specific currency.
    - 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
    
    A timestamp in RFC 3339 format
    
    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 an attached memory store.
      - "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 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
- status: "rescheduling" or "running" or "idle" or "terminated"
  
  SessionStatus enum
  - "rescheduling"
  - "running"
  - "idle"
  - "terminated"
- title: string or null
- updated_at: string
  
  A timestamp in RFC 3339 format
  
  format: date-time
- usage: BetaManagedAgentsSessionUsage
  
  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
    
    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
  - 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
    
    A monetary amount in a specific currency.
  - output_tokens: optional number
    
    Total output tokens generated across all turns.
    
    format: int32
  - server_tool_use: optional BetaManagedAgentsServerToolUsage or null
    
    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
- 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.",
        "mcp_servers": [
          {
            "name": "example-mcp",
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse"
          }
        ],
        "model": {
          "id": "claude-opus-5",
          "effort": {
            "type": "low"
          },
          "inference_geo": "inference_geo",
          "speed": "standard"
        },
        "multiagent": {
          "agents": [
            {
              "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
              "description": "A focused research subagent.",
              "mcp_servers": [
                {
                  "name": "example-mcp",
                  "type": "url",
                  "url": "https://example-server.modelcontextprotocol.io/sse"
                }
              ],
              "model": {
                "id": "claude-opus-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_011CZkZFNu9hAbo3jZPRgTlx",
            "type": "custom",
            "version": "2"
          }
        ],
        "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
        "tools": [
          {
            "configs": [
              {
                "enabled": true,
                "name": "bash",
                "permission_policy": {
                  "type": "always_allow"
                },
                "type": "bash"
              }
            ],
            "default_config": {
              "enabled": true,
              "permission_policy": {
                "type": "always_ask"
              }
            },
            "type": "agent_toolset_20260401"
          }
        ],
        "type": "agent",
        "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_011CZkZRSw2kEfs6ncTVljxP",
          "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_011CZkZCKr6eXyl0gWMOdQiu",
          "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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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
  - 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 for additional details and options.
      - "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
      - string
    - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
      
      How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
      - 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. Not all models support fast; invalid combinations are rejected at create time.
      - "standard"
      - "fast"
  - multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
    
    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
        
        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.
        
        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.
  - 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
  
  A timestamp in RFC 3339 format
  
  format: date-time
- budget: BetaManagedAgentsBudgetLimit or null
  
  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
    
    A monetary amount in a specific currency.
    - 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
    
    A timestamp in RFC 3339 format
    
    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 an attached memory store.
      - "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 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
- status: "rescheduling" or "running" or "idle" or "terminated"
  
  SessionStatus enum
  - "rescheduling"
  - "running"
  - "idle"
  - "terminated"
- title: string or null
- updated_at: string
  
  A timestamp in RFC 3339 format
  
  format: date-time
- usage: BetaManagedAgentsSessionUsage
  
  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
    
    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
  - 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
    
    A monetary amount in a specific currency.
  - output_tokens: optional number
    
    Total output tokens generated across all turns.
    
    format: int32
  - server_tool_use: optional BetaManagedAgentsServerToolUsage or null
    
    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
- 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.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-opus-5",
      "effort": {
        "type": "low"
      },
      "inference_geo": "inference_geo",
      "speed": "standard"
    },
    "multiagent": {
      "agents": [
        {
          "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
          "description": "A focused research subagent.",
          "mcp_servers": [
            {
              "name": "example-mcp",
              "type": "url",
              "url": "https://example-server.modelcontextprotocol.io/sse"
            }
          ],
          "model": {
            "id": "claude-opus-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_011CZkZFNu9hAbo3jZPRgTlx",
        "type": "custom",
        "version": "2"
      }
    ],
    "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
    "tools": [
      {
        "configs": [
          {
            "enabled": true,
            "name": "bash",
            "permission_policy": {
              "type": "always_allow"
            },
            "type": "bash"
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "type": "agent_toolset_20260401"
      }
    ],
    "type": "agent",
    "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_011CZkZRSw2kEfs6ncTVljxP",
      "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_011CZkZCKr6eXyl0gWMOdQiu",
      "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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# Body parameters

agent: optional BetaManagedAgentsSessionAgentUpdate

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 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"
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
        
        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 for all tools in a toolset.
      - 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
        
        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.
  - 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 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: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null
      
      Default configuration for all tools from an MCP 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
        
        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.
  - 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 for custom tool input parameters.
      - 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

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
  
  A monetary amount in a specific currency.
  - 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
  - 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 for additional details and options.
      - "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
      - string
    - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
      
      How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
      - 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. Not all models support fast; invalid combinations are rejected at create time.
      - "standard"
      - "fast"
  - multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
    
    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
        
        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.
        
        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.
  - 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
  
  A timestamp in RFC 3339 format
  
  format: date-time
- budget: BetaManagedAgentsBudgetLimit or null
  
  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
    
    A monetary amount in a specific currency.
    - 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
    
    A timestamp in RFC 3339 format
    
    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 an attached memory store.
      - "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 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
- status: "rescheduling" or "running" or "idle" or "terminated"
  
  SessionStatus enum
  - "rescheduling"
  - "running"
  - "idle"
  - "terminated"
- title: string or null
- updated_at: string
  
  A timestamp in RFC 3339 format
  
  format: date-time
- usage: BetaManagedAgentsSessionUsage
  
  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
    
    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
  - 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
    
    A monetary amount in a specific currency.
  - output_tokens: optional number
    
    Total output tokens generated across all turns.
    
    format: int32
  - server_tool_use: optional BetaManagedAgentsServerToolUsage or null
    
    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
- 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.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-opus-5",
      "effort": {
        "type": "low"
      },
      "inference_geo": "inference_geo",
      "speed": "standard"
    },
    "multiagent": {
      "agents": [
        {
          "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
          "description": "A focused research subagent.",
          "mcp_servers": [
            {
              "name": "example-mcp",
              "type": "url",
              "url": "https://example-server.modelcontextprotocol.io/sse"
            }
          ],
          "model": {
            "id": "claude-opus-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_011CZkZFNu9hAbo3jZPRgTlx",
        "type": "custom",
        "version": "2"
      }
    ],
    "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
    "tools": [
      {
        "configs": [
          {
            "enabled": true,
            "name": "bash",
            "permission_policy": {
              "type": "always_allow"
            },
            "type": "bash"
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "type": "agent_toolset_20260401"
      }
    ],
    "type": "agent",
    "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_011CZkZRSw2kEfs6ncTVljxP",
      "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_011CZkZCKr6eXyl0gWMOdQiu",
      "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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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
  - 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 for additional details and options.
      - "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
      - string
    - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
      
      How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
      - 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. Not all models support fast; invalid combinations are rejected at create time.
      - "standard"
      - "fast"
  - multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
    
    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
        
        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.
        
        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.
  - 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
  
  A timestamp in RFC 3339 format
  
  format: date-time
- budget: BetaManagedAgentsBudgetLimit or null
  
  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
    
    A monetary amount in a specific currency.
    - 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
    
    A timestamp in RFC 3339 format
    
    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 an attached memory store.
      - "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 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
- status: "rescheduling" or "running" or "idle" or "terminated"
  
  SessionStatus enum
  - "rescheduling"
  - "running"
  - "idle"
  - "terminated"
- title: string or null
- updated_at: string
  
  A timestamp in RFC 3339 format
  
  format: date-time
- usage: BetaManagedAgentsSessionUsage
  
  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
    
    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
  - 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
    
    A monetary amount in a specific currency.
  - output_tokens: optional number
    
    Total output tokens generated across all turns.
    
    format: int32
  - server_tool_use: optional BetaManagedAgentsServerToolUsage or null
    
    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
- 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.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-opus-5",
      "effort": {
        "type": "low"
      },
      "inference_geo": "inference_geo",
      "speed": "standard"
    },
    "multiagent": {
      "agents": [
        {
          "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
          "description": "A focused research subagent.",
          "mcp_servers": [
            {
              "name": "example-mcp",
              "type": "url",
              "url": "https://example-server.modelcontextprotocol.io/sse"
            }
          ],
          "model": {
            "id": "claude-opus-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_011CZkZFNu9hAbo3jZPRgTlx",
        "type": "custom",
        "version": "2"
      }
    ],
    "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
    "tools": [
      {
        "configs": [
          {
            "enabled": true,
            "name": "bash",
            "permission_policy": {
              "type": "always_allow"
            },
            "type": "bash"
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "type": "agent_toolset_20260401"
      }
    ],
    "type": "agent",
    "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_011CZkZRSw2kEfs6ncTVljxP",
      "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_011CZkZCKr6eXyl0gWMOdQiu",
      "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 — see the sessions/threads/advisor spec.
  
  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, or a model_config object. Omit to use the agent's model.
  - BetaManagedAgentsModel = "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more or string
    
    The model that will power your agent.
    
    See models for additional details and options.
    - "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
      
      The model that will power your agent.
      
      See models for additional details and options.
      - "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
      - "claude-sonnet-5"
        
        High-performance model for coding and agents
      - "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
      - "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
      - "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
      - "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
      - "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
      - "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
      - "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
      - "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
      - "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
      - "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
      - "claude-sonnet-4-5"
        
        High-performance model for agents and coding
      - "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
    - string
  - BetaManagedAgentsModelConfigParams object
    
    An object that defines additional configuration control over model use
    - id: BetaManagedAgentsModel
      
      The model that will power your agent.
      
      See models 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.
      - BetaManagedAgentsEffortLevel = "low" or "medium" or "high" or 2 more
        
        How hard Claude works on each turn. Higher levels favor reasoning depth over latency. Not all models accept every level; invalid combinations are rejected at create time.
        
        "low"
        
        "medium"
        
        "high"
        
        "xhigh"
        
        "max"
      - 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. fast provides significantly faster output token generation at premium pricing. Not all models support fast; invalid combinations are rejected at create time.
      - "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 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"
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
        
        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 for all tools in a toolset.
      - 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
        
        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.
  - 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 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: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null
      
      Default configuration for all tools from an MCP 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
        
        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.
  - 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 for custom tool input parameters.
      - 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
  
  A monetary amount in a specific currency.
  - 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
  
  Regular text 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.
  
  format: uint32

# 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
    
    Regular text 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.
    
    format: uint32
- 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"

EventDeltaType enum
- "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/<file_id>.
  
  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/<repo-name>.
  
  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 an attached memory store.
  - "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 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.

# Beta Managed Agents Multiagent Params

BetaManagedAgentsMultiagentParams 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 — see the sessions/threads/advisor spec.
      
      minLength: 1, maxLength: 256

# 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 — see the sessions/threads/advisor spec.
    
    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
  
  A timestamp in RFC 3339 format
  
  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
  - 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 for additional details and options.
      - "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
      - string
    - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
      
      How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
      - 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. Not all models support fast; invalid combinations are rejected at create time.
      - "standard"
      - "fast"
  - multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
    
    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
        
        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.
        
        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.
  - 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
  
  A timestamp in RFC 3339 format
  
  format: date-time
- budget: BetaManagedAgentsBudgetLimit or null
  
  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
    
    A monetary amount in a specific currency.
    - 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
    
    A timestamp in RFC 3339 format
    
    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 an attached memory store.
      - "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 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
- status: "rescheduling" or "running" or "idle" or "terminated"
  
  SessionStatus enum
  - "rescheduling"
  - "running"
  - "idle"
  - "terminated"
- title: string or null
- updated_at: string
  
  A timestamp in RFC 3339 format
  
  format: date-time
- usage: BetaManagedAgentsSessionUsage
  
  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
    
    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
  - 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
    
    A monetary amount in a specific currency.
  - output_tokens: optional number
    
    Total output tokens generated across all turns.
    
    format: int32
  - server_tool_use: optional BetaManagedAgentsServerToolUsage or null
    
    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
- 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
- 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 for additional details and options.
    - "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
      
      The model that will power your agent.
      
      See models for additional details and options.
      - "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
      - "claude-sonnet-5"
        
        High-performance model for coding and agents
      - "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
      - "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
      - "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
      - "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
      - "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
      - "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
      - "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
      - "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
      - "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
      - "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
      - "claude-sonnet-4-5"
        
        High-performance model for agents and coding
      - "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
    - string
  - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
    
    How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
    - 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. Not all models support fast; invalid combinations are rejected at create time.
    - "standard"
    - "fast"
- multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
  
  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
      - 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.
        
        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.
- 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 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"
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
      - 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 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.
        
        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 for all tools in a toolset.
      - 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
        
        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.
  - 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 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: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null
      
      Default configuration for all tools from an MCP 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
        
        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.
  - 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 for custom tool input parameters.
      - 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 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
    - 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 for additional details and options.
        
        "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
        
        string
      - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
        
        How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
        
        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. 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.
        
        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 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
  
  A timestamp in RFC 3339 format
  
  format: date-time
- agent: optional BetaManagedAgentsSessionAgent or null
  
  Resolved agent definition for a session. Snapshot of the agent at session creation time.
  - type: "agent"
  - id: string
  - description: string or null
  - 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 for additional details and options.
      - "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
      - string
    - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
      
      How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
      - 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. Not all models support fast; invalid combinations are rejected at create time.
      - "standard"
      - "fast"
  - multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
    
    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
        
        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.
        
        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.
  - 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
  
  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
    
    A monetary amount in a specific currency.
    - 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
  
  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
- 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
  
  A monetary amount in a specific currency.
  - 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 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 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
  
  A timestamp in RFC 3339 format
  
  format: date-time
- usage: BetaManagedAgentsSessionUsageSnapshot
  
  Point-in-time snapshot of a session's cumulative usage.
  - 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
    
    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
  - 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
    
    A monetary amount in a specific currency.
    - 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 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
- budget: optional BetaManagedAgentsBudgetLimit or null
  
  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
    
    A monetary amount in a specific currency.

# 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

Regular text content.
- 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
  
  A timestamp in RFC 3339 format
  
  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 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
      
      Union type for image source variants.
      - 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
      
      Union type for document source variants.
      - 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 a 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
  
  A timestamp in RFC 3339 format
  
  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

Query parameter for limit

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 string

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.

# Headers

"anthropic-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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
        
        Union type for image source variants.
        
        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
        
        Union type for document source variants.
        
        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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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"
    
    UserToolConfirmationResult enum
    - "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 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
    
    A timestamp in RFC 3339 format
    
    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, which can be found in the last session.status_idle event's 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 a 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
    
    A timestamp in RFC 3339 format
    
    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.
  - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - evaluated_permission: optional "allow" or "ask" or "deny"
    
    AgentEvaluatedPermission enum
    - "allow"
    - "ask"
    - "deny"
  - evaluation: optional BetaManagedAgentsAgentToolEvaluation
    
    Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
    - 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 per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.
        
        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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - evaluated_permission: optional "allow" or "ask" or "deny"
    
    AgentEvaluatedPermission enum
    - "allow"
    - "ask"
    - "deny"
  - evaluation: optional BetaManagedAgentsAgentToolEvaluation
    
    Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
  - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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 5 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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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.
  - processed_at: string
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
    - 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"
- 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
    
    A timestamp in RFC 3339 format
    
    format: date-time
- BetaManagedAgentsSessionThreadCreatedEvent object
  
  Emitted when a subagent is spawned as a new thread. 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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - session_thread_id: string
    
    Public sthr_ ID of the newly created 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    Token usage for a single model request.
    - 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 mode. fast provides significantly faster output token generation at premium pricing. Not all models support fast; invalid combinations are rejected at create time.
      - "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
    
    A timestamp in RFC 3339 format
    
    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 a single model request.
  - processed_at: string
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric
    
    Rubric for grading the quality of an outcome.
    - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - session_thread_id: string
    
    Public sthr_ ID of the thread that went idle.
  - stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
    - 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.
- 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
    
    A timestamp in RFC 3339 format
    
    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 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - agent: optional BetaManagedAgentsSessionAgent or null
    
    Resolved agent definition for a session. Snapshot of the agent at session creation time.
    - type: "agent"
    - id: string
    - description: string or null
    - 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 for additional details and options.
        
        "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
        
        string
      - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
        
        How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
        
        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. Not all models support fast; invalid combinations are rejected at create time.
        
        "standard"
        
        "fast"
    - multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
      
      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
        
        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.
        
        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.
    - 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
    
    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
      
      A monetary amount in a specific currency.
      - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - usage: BetaManagedAgentsSessionUsageSnapshot
    
    Point-in-time snapshot of a session's cumulative usage.
    - 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
      
      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
    - 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
      
      A monetary amount in a specific currency.
    - output_tokens: optional number
      
      Total output tokens generated across all turns.
      
      format: int32
    - server_tool_use: optional BetaManagedAgentsServerToolUsage
      
      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
  - budget: optional BetaManagedAgentsBudgetLimit or null
    
    A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost.
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_011CZkZGOp0iBcp4kaQSihUmy",
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message",
      "processed_at": "2026-03-15T10:00:00Z"
    },
    {
      "id": "sevt_011CZkZHPq1jCdq5lbRTjiVnz",
      "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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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
        
        Union type for image source variants.
        
        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
        
        Union type for document source variants.
        
        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"
    
    UserToolConfirmationResult enum
    - "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 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, which can be found in the last session.status_idle event's 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 a 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
    
    Rubric for grading the quality of an outcome.
    - 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 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
        
        Union type for image source variants.
        
        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
        
        Union type for document source variants.
        
        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
      
      A timestamp in RFC 3339 format
      
      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
      
      A timestamp in RFC 3339 format
      
      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"
      
      UserToolConfirmationResult enum
      - "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 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
      
      A timestamp in RFC 3339 format
      
      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, which can be found in the last session.status_idle event's 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 a 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
      
      A timestamp in RFC 3339 format
      
      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
      
      A timestamp in RFC 3339 format
      
      format: date-time
    - rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric
      
      Rubric for grading the quality of an outcome.
      - 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 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
      
      A timestamp in RFC 3339 format
      
      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
      
      A timestamp in RFC 3339 format
      
      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_011CZkZGOp0iBcp4kaQSihUmy",
      "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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# Returns

BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 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
        
        Union type for image source variants.
        
        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
        
        Union type for document source variants.
        
        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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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"
    
    UserToolConfirmationResult enum
    - "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 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
    
    A timestamp in RFC 3339 format
    
    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, which can be found in the last session.status_idle event's 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 a 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
    
    A timestamp in RFC 3339 format
    
    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.
  - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - evaluated_permission: optional "allow" or "ask" or "deny"
    
    AgentEvaluatedPermission enum
    - "allow"
    - "ask"
    - "deny"
  - evaluation: optional BetaManagedAgentsAgentToolEvaluation
    
    Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
    - 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 per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.
        
        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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - evaluated_permission: optional "allow" or "ask" or "deny"
    
    AgentEvaluatedPermission enum
    - "allow"
    - "ask"
    - "deny"
  - evaluation: optional BetaManagedAgentsAgentToolEvaluation
    
    Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
  - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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 5 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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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.
  - processed_at: string
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
    - 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"
- 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
    
    A timestamp in RFC 3339 format
    
    format: date-time
- BetaManagedAgentsSessionThreadCreatedEvent object
  
  Emitted when a subagent is spawned as a new thread. 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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - session_thread_id: string
    
    Public sthr_ ID of the newly created 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    Token usage for a single model request.
    - 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 mode. fast provides significantly faster output token generation at premium pricing. Not all models support fast; invalid combinations are rejected at create time.
      - "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
    
    A timestamp in RFC 3339 format
    
    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 a single model request.
  - processed_at: string
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric
    
    Rubric for grading the quality of an outcome.
    - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - session_thread_id: string
    
    Public sthr_ ID of the thread that went idle.
  - stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
    - 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.
- 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
    
    A timestamp in RFC 3339 format
    
    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 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - agent: optional BetaManagedAgentsSessionAgent or null
    
    Resolved agent definition for a session. Snapshot of the agent at session creation time.
    - type: "agent"
    - id: string
    - description: string or null
    - 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 for additional details and options.
        
        "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
        
        string
      - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
        
        How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
        
        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. Not all models support fast; invalid combinations are rejected at create time.
        
        "standard"
        
        "fast"
    - multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
      
      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
        
        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.
        
        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.
    - 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
    
    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
      
      A monetary amount in a specific currency.
      - 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
      
      Regular text 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.
      
      format: uint32
  - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - usage: BetaManagedAgentsSessionUsageSnapshot
    
    Point-in-time snapshot of a session's cumulative usage.
    - 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
      
      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
    - 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
      
      A monetary amount in a specific currency.
    - output_tokens: optional number
      
      Total output tokens generated across all turns.
      
      format: int32
    - server_tool_use: optional BetaManagedAgentsServerToolUsage
      
      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
  - budget: optional BetaManagedAgentsBudgetLimit or null
    
    A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost.

# 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_011CZkZGOp0iBcp4kaQSihUmy",
  "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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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/<file_id>.

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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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 an attached memory store.
    - "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_011CZkZCKr6eXyl0gWMOdQiu",
      "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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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 an attached memory store.
  - "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_011CZkZCKr6eXyl0gWMOdQiu",
  "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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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 an attached memory store.
  - "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_011CZkZCKr6eXyl0gWMOdQiu",
  "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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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.

# Headers

"anthropic-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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
  
  The resolved agent a session thread runs: a saved-agent snapshot, the platform advisor entry, or an inline-defined (ephemeral) agent snapshot.
  - 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
    - 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 for additional details and options.
        
        "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
        
        string
      - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
        
        How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
        
        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. 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.
        
        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.
- archived_at: string or null
  
  A timestamp in RFC 3339 format
  
  format: date-time
- created_at: string
  
  A timestamp in RFC 3339 format
  
  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 a session thread.
  - 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
  
  SessionThreadStatus enum
  - "running"
  - "idle"
  - "rescheduling"
  - "terminated"
- updated_at: string
  
  A timestamp in RFC 3339 format
  
  format: date-time
- usage: BetaManagedAgentsSessionThreadUsage or null
  
  Cumulative token usage for a session thread across all turns.
  - 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
    
    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
  - 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
    
    A monetary amount in a specific currency.
    - 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 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
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_011CZkZVWa6oIjw0rgXZpnBt",
      "agent": {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "description": "A focused research subagent.",
        "mcp_servers": [
          {
            "name": "example-mcp",
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse"
          }
        ],
        "model": {
          "id": "claude-opus-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
        }
      }
    }
  ],
  "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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# Returns

BetaManagedAgentsSessionThread object

An execution thread within a session. Each session has one primary thread plus zero or more child threads spawned by the coordinator.
- type: "session_thread"
- id: string
  
  Unique identifier for this thread.
- agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
  
  The resolved agent a session thread runs: a saved-agent snapshot, the platform advisor entry, or an inline-defined (ephemeral) agent snapshot.
  - 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
    - 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 for additional details and options.
        
        "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
        
        string
      - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
        
        How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
        
        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. 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.
        
        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.
- archived_at: string or null
  
  A timestamp in RFC 3339 format
  
  format: date-time
- created_at: string
  
  A timestamp in RFC 3339 format
  
  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 a session thread.
  - 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
  
  SessionThreadStatus enum
  - "running"
  - "idle"
  - "rescheduling"
  - "terminated"
- updated_at: string
  
  A timestamp in RFC 3339 format
  
  format: date-time
- usage: BetaManagedAgentsSessionThreadUsage or null
  
  Cumulative token usage for a session thread across all turns.
  - 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
    
    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
  - 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
    
    A monetary amount in a specific currency.
    - 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 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

# 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_011CZkZVWa6oIjw0rgXZpnBt",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "description": "A focused research subagent.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-opus-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
    }
  }
}

# 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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# Returns

BetaManagedAgentsSessionThread object

An execution thread within a session. Each session has one primary thread plus zero or more child threads spawned by the coordinator.
- type: "session_thread"
- id: string
  
  Unique identifier for this thread.
- agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
  
  The resolved agent a session thread runs: a saved-agent snapshot, the platform advisor entry, or an inline-defined (ephemeral) agent snapshot.
  - 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
    - 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 for additional details and options.
        
        "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
        
        string
      - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
        
        How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
        
        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. 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.
        
        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.
- archived_at: string or null
  
  A timestamp in RFC 3339 format
  
  format: date-time
- created_at: string
  
  A timestamp in RFC 3339 format
  
  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 a session thread.
  - 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
  
  SessionThreadStatus enum
  - "running"
  - "idle"
  - "rescheduling"
  - "terminated"
- updated_at: string
  
  A timestamp in RFC 3339 format
  
  format: date-time
- usage: BetaManagedAgentsSessionThreadUsage or null
  
  Cumulative token usage for a session thread across all turns.
  - 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
    
    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
  - 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
    
    A monetary amount in a specific currency.
    - 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 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

# 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_011CZkZVWa6oIjw0rgXZpnBt",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "description": "A focused research subagent.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-opus-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
    }
  }
}

# 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

Query parameter for limit

format: int32
page: optional string

Query parameter for page

# Headers

"anthropic-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# 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
        
        Union type for image source variants.
        
        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
        
        Union type for document source variants.
        
        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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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"
    
    UserToolConfirmationResult enum
    - "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 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
    
    A timestamp in RFC 3339 format
    
    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, which can be found in the last session.status_idle event's 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 a 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
    
    A timestamp in RFC 3339 format
    
    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.
  - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - evaluated_permission: optional "allow" or "ask" or "deny"
    
    AgentEvaluatedPermission enum
    - "allow"
    - "ask"
    - "deny"
  - evaluation: optional BetaManagedAgentsAgentToolEvaluation
    
    Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
    - 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 per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.
        
        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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - evaluated_permission: optional "allow" or "ask" or "deny"
    
    AgentEvaluatedPermission enum
    - "allow"
    - "ask"
    - "deny"
  - evaluation: optional BetaManagedAgentsAgentToolEvaluation
    
    Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
  - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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 5 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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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.
  - processed_at: string
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
    - 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"
- 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
    
    A timestamp in RFC 3339 format
    
    format: date-time
- BetaManagedAgentsSessionThreadCreatedEvent object
  
  Emitted when a subagent is spawned as a new thread. 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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - session_thread_id: string
    
    Public sthr_ ID of the newly created 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    Token usage for a single model request.
    - 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 mode. fast provides significantly faster output token generation at premium pricing. Not all models support fast; invalid combinations are rejected at create time.
      - "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
    
    A timestamp in RFC 3339 format
    
    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 a single model request.
  - processed_at: string
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric
    
    Rubric for grading the quality of an outcome.
    - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - session_thread_id: string
    
    Public sthr_ ID of the thread that went idle.
  - stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
    - 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.
- 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
    
    A timestamp in RFC 3339 format
    
    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 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - agent: optional BetaManagedAgentsSessionAgent or null
    
    Resolved agent definition for a session. Snapshot of the agent at session creation time.
    - type: "agent"
    - id: string
    - description: string or null
    - 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 for additional details and options.
        
        "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
        
        string
      - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
        
        How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
        
        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. Not all models support fast; invalid combinations are rejected at create time.
        
        "standard"
        
        "fast"
    - multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
      
      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
        
        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.
        
        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.
    - 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
    
    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
      
      A monetary amount in a specific currency.
      - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - usage: BetaManagedAgentsSessionUsageSnapshot
    
    Point-in-time snapshot of a session's cumulative usage.
    - 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
      
      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
    - 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
      
      A monetary amount in a specific currency.
    - output_tokens: optional number
      
      Total output tokens generated across all turns.
      
      format: int32
    - server_tool_use: optional BetaManagedAgentsServerToolUsage
      
      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
  - budget: optional BetaManagedAgentsBudgetLimit or null
    
    A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost.
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_011CZkZGOp0iBcp4kaQSihUmy",
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message",
      "processed_at": "2026-03-15T10:00:00Z"
    }
  ],
  "next_page": "next_page"
}

# 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-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.
- string
- "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
  - "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"
"anthropic-workspace-id": optional string

# Returns

BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 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
        
        Union type for image source variants.
        
        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
        
        Union type for document source variants.
        
        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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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"
    
    UserToolConfirmationResult enum
    - "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 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
    
    A timestamp in RFC 3339 format
    
    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, which can be found in the last session.status_idle event's 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 a 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
    
    A timestamp in RFC 3339 format
    
    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.
  - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - evaluated_permission: optional "allow" or "ask" or "deny"
    
    AgentEvaluatedPermission enum
    - "allow"
    - "ask"
    - "deny"
  - evaluation: optional BetaManagedAgentsAgentToolEvaluation
    
    Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
    - 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 per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.
        
        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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - evaluated_permission: optional "allow" or "ask" or "deny"
    
    AgentEvaluatedPermission enum
    - "allow"
    - "ask"
    - "deny"
  - evaluation: optional BetaManagedAgentsAgentToolEvaluation
    
    Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
  - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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 5 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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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 in response to this error.
        
        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.
  - processed_at: string
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
    - 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"
- 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
    
    A timestamp in RFC 3339 format
    
    format: date-time
- BetaManagedAgentsSessionThreadCreatedEvent object
  
  Emitted when a subagent is spawned as a new thread. 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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - session_thread_id: string
    
    Public sthr_ ID of the newly created 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    Token usage for a single model request.
    - 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 mode. fast provides significantly faster output token generation at premium pricing. Not all models support fast; invalid combinations are rejected at create time.
      - "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
    
    A timestamp in RFC 3339 format
    
    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 a single model request.
  - processed_at: string
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric
    
    Rubric for grading the quality of an outcome.
    - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - session_thread_id: string
    
    Public sthr_ ID of the thread that went idle.
  - stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
    - 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.
- 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
    
    A timestamp in RFC 3339 format
    
    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 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - agent: optional BetaManagedAgentsSessionAgent or null
    
    Resolved agent definition for a session. Snapshot of the agent at session creation time.
    - type: "agent"
    - id: string
    - description: string or null
    - 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 for additional details and options.
        
        "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more
        
        The model that will power your agent.
        
        See models for additional details and options.
        
        "claude-fable-5-1"
        
        Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
        
        "claude-sonnet-5"
        
        High-performance model for coding and agents
        
        "claude-fable-5"
        
        Next generation of intelligence for the hardest knowledge work and coding problems
        
        "claude-opus-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-8"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-7"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-6"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-6"
        
        Best combination of speed and intelligence
        
        "claude-haiku-4-5"
        
        Fastest model with near-frontier intelligence
        
        "claude-haiku-4-5-20251001"
        
        Fastest model with near-frontier intelligence
        
        "claude-opus-4-5"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-opus-4-5-20251101"
        
        Powerful intelligence for long-running agents and coding
        
        "claude-sonnet-4-5"
        
        High-performance model for agents and coding
        
        "claude-sonnet-4-5-20250929"
        
        High-performance model for agents and coding
        
        string
      - effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
        
        How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.
        
        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. Not all models support fast; invalid combinations are rejected at create time.
        
        "standard"
        
        "fast"
    - multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
      
      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
        
        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.
        
        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.
    - 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
    
    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
      
      A monetary amount in a specific currency.
      - 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
      
      Regular text 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.
      
      format: uint32
  - 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
    
    A timestamp in RFC 3339 format
    
    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
    
    A timestamp in RFC 3339 format
    
    format: date-time
  - usage: BetaManagedAgentsSessionUsageSnapshot
    
    Point-in-time snapshot of a session's cumulative usage.
    - 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
      
      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
    - 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
      
      A monetary amount in a specific currency.
    - output_tokens: optional number
      
      Total output tokens generated across all turns.
      
      format: int32
    - server_tool_use: optional BetaManagedAgentsServerToolUsage
      
      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
  - budget: optional BetaManagedAgentsBudgetLimit or null
    
    A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost.

# 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_011CZkZGOp0iBcp4kaQSihUmy",
  "content": [
    {
      "text": "Where is my order #1234?",
      "type": "text"
    }
  ],
  "type": "user.message",
  "processed_at": "2026-03-15T10:00:00Z"
}