English ← MyDocs

Sessions

创建会话

post /v1/sessions

创建会话

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

请求体参数

  • agent: string or BetaManagedAgentsAgentParams

    代理标识符。接受 agent ID 字符串（固定会话的最新版本），或同时指定 id 和 version 的 agent 对象。

    • string

    • BetaManagedAgentsAgentParams object { id, type, version }

      代理的规范。提供特定的 version 或使用简写 agent="agent_id" 获取最新版本

      • id: string

        agent 的 ID。

      • type: "agent"

        • "agent"

      • version: optional number

        要使用的特定 agent 版本。省略以使用最新版本。如果指定，必须至少为 1。

  • environment_id: string

    定义此会话容器配置的 environment 的 ID。

  • metadata: optional map[string]

    附加到会话的任意键值元数据。最多 16 对，键最多 64 个字符，值最多 512 个字符。

  • resources: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam

    要挂载到会话容器中的资源（例如仓库、文件）。

    • BetaManagedAgentsGitHubRepositoryResourceParams object { authorization_token, type, url, 2 more }

      将 GitHub 仓库挂载到会话容器中。

      • authorization_token: string

        用于克隆仓库的 GitHub 授权令牌。

      • type: "github_repository"

        • "github_repository"

      • url: string

        仓库的 GitHub URL

      • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

        要检出的分支或提交。默认为仓库的默认分支。

        • BetaManagedAgentsBranchCheckout object { name, type }

          • name: string

            要检出的分支名称。

          • type: "branch"

            • "branch"

        • BetaManagedAgentsCommitCheckout object { sha, type }

          • sha: string

            要检出的完整提交 SHA。

          • type: "commit"

            • "commit"

      • mount_path: optional string

        容器中的挂载路径。默认为 /workspace/<repo-name>。

    • BetaManagedAgentsFileResourceParams object { file_id, type, mount_path }

      将通过 Files API 上传的文件挂载到会话中。

      • file_id: string

        先前上传文件的 ID。

      • type: "file"

        • "file"

      • mount_path: optional string

        容器中的挂载路径。默认为 /mnt/session/uploads/<file_id>。

    • BetaManagedAgentsMemoryStoreResourceParam object { memory_store_id, type, access, instructions }

      将记忆存储附加到代理会话的参数。

      • memory_store_id: string

        记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

      • type: "memory_store"

        • "memory_store"

      • access: optional "read_write" or "read_only"

        附加记忆存储的访问模式。

        • "read_write"

        • "read_only"

      • instructions: optional string

        每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

  • title: optional string

    人类可读的会话标题。

  • vault_ids: optional array of string

    代理在会话期间可使用的存储凭据的 Vault ID。

返回值

  • BetaManagedAgentsSession object { id, agent, archived_at, 12 more }

    托管代理 session。

    • id: string

    • agent: BetaManagedAgentsSessionAgent

      为 session 解析的 agent 定义。session 创建时 agent 的快照。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

        解析的协调器拓扑，包含每个成员的完整 agent 定义。

        • agents: array of BetaManagedAgentsSessionThreadAgent

          协调器可能作为会话线程生成的完整 agent 定义。

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            模型标识符和配置。

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              已解析的 Anthropic 托管技能。

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              已解析的用户创建的自定义技能。

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  内置代理工具标识符。

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

                    • type: "always_ask"

                      • "always_ask"

              • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                代理工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                MCP 服务器所有工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              API 响应中返回的自定义工具。

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                自定义工具输入参数的 JSON Schema。

                • properties: optional map[unknown]

                  定义工具输入参数的 JSON Schema 属性。

                • required: optional array of string

                  必需属性名称列表。

                • type: optional "object"

                  工具输入 schema 必须为 'object'。

                  • "object"

              • name: string

              • type: "custom"

                • "custom"

          • type: "agent"

            • "agent"

          • version: number

        • type: "coordinator"

          • "coordinator"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      RFC 3339 格式的时间戳

    • created_at: string

      RFC 3339 格式的时间戳

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcome评估uationResource

      每个结果的评估状态。每个发送到会话的 define_outcome 事件对应一个条目。

      • completed_at: string

        RFC 3339 格式的时间戳

      • description: string

        代理应产出的内容。

      • explanation: string

        最近一次评估的评分者判定文本。对于 satisfied，解释为何满足标准；对于 needs_revision（中间状态），说明缺少什么；对于 failed，说明为何不可恢复。

      • iteration: number

        结果当前所处的从 0 开始的修订周期。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。

      • result: string

        当前评估状态。代理开始工作前为 pending；产出或修订时为 running；评分者评分时为 evaluating；satisfied/max_iterations_reached/failed/interrupted 为终止状态。

      • type: "outcome_evaluation"

        • "outcome_evaluation"

    • resources: array of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • mount_path: string

        • type: "github_repository"

          • "github_repository"

        • updated_at: string

          RFC 3339 格式的时间戳

        • url: string

        • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              要检出的分支名称。

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              要检出的完整提交 SHA。

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • file_id: string

        • mount_path: string

        • type: "file"

          • "file"

        • updated_at: string

          RFC 3339 格式的时间戳

      • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

        附加到代理会话的记忆存储。

        • memory_store_id: string

          记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

        • type: "memory_store"

          • "memory_store"

        • access: optional "read_write" or "read_only"

          附加记忆存储的访问模式。

          • "read_write"

          • "read_only"

        • description: optional string

          记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

        • instructions: optional string

          每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

        • mount_path: optional string

          存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

        • name: optional string

          记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

    • stats: BetaManagedAgentsSessionStats

      会话的计时统计。

      • active_seconds: optional number

        会话处于运行状态的累计时间（秒）。不包括空闲时间。

      • duration_seconds: optional number

        自会话创建以来的经过时间（秒）。对于已终止的会话，冻结在最终更新时。

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus 枚举

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • type: "session"

      • "session"

    • updated_at: string

      RFC 3339 格式的时间戳

    • usage: BetaManagedAgentsSessionUsage

      会话在所有轮次中的累计 token 使用量。

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        按缓存生命周期细分的提示缓存创建 token 使用量。

        • ephemeral_1h_input_tokens: optional number

          用于创建 1 小时临时缓存条目的 token 数。

        • ephemeral_5m_input_tokens: optional number

          用于创建 5 分钟临时缓存条目的 token 数。

      • cache_read_input_tokens: optional number

        从提示缓存读取的 token 总数。

      • input_tokens: optional number

        所有轮次消耗的输入 token 总数。

      • output_tokens: optional number

        所有轮次生成的输出 token 总数。

    • vault_ids: array of string

      创建时附加到会话的 Vault ID。未提供 Vault 时为空。

示例

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"
        }'

响应

{
  "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-sonnet-4-6",
      "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-sonnet-4-6",
            "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"
                  }
                }
              ],
              "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"
            }
          }
        ],
        "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",
  "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": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  },
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ]
}

列出会话

get /v1/sessions

列出会话

查询参数

  • agent_id: optional string

    按此 agent ID 筛选创建的会话。

  • agent_version: optional number

    按 agent 版本筛选。仅在同时设置了 agent_id 时适用。

  • "created_at[gt]": optional string

    返回在此时间之后创建的会话（不包含该时间点）。

  • "created_at[gte]": optional string

    返回在此时间或之后创建的会话（包含该时间点）。

  • "created_at[lt]": optional string

    返回在此之前创建的会话（不包含该时间点）。

  • "created_at[lte]": optional string

    返回在此时间或之前创建的会话（包含该时间点）。

  • include_archived: optional boolean

    为 true 时，包含已归档的会话。默认值：false（不包含已归档）。

  • limit: optional number

    返回的最大结果数。

  • memory_store_id: optional string

    筛选资源中包含此 memory store ID 的 memory_store 的会话。

  • order: optional "asc" or "desc"

    结果的排序方向，按 created_at 排序。默认为 desc（最新优先）。

    • "asc"

    • "desc"

  • page: optional string

    来自先前响应 next_page 的不透明分页游标。

  • statuses: optional array of "rescheduling" or "running" or "idle" or "terminated"

    按会话状态筛选。重复参数以匹配多个状态中的任意一个。

    • "rescheduling"

    • "running"

    • "idle"

    • "terminated"

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • data: optional array of BetaManagedAgentsSession

    会话列表。

    • id: string

    • agent: BetaManagedAgentsSessionAgent

      为 session 解析的 agent 定义。session 创建时 agent 的快照。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

        解析的协调器拓扑，包含每个成员的完整 agent 定义。

        • agents: array of BetaManagedAgentsSessionThreadAgent

          协调器可能作为会话线程生成的完整 agent 定义。

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            模型标识符和配置。

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              已解析的 Anthropic 托管技能。

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              已解析的用户创建的自定义技能。

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  内置代理工具标识符。

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

                    • type: "always_ask"

                      • "always_ask"

              • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                代理工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                MCP 服务器所有工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              API 响应中返回的自定义工具。

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                自定义工具输入参数的 JSON Schema。

                • properties: optional map[unknown]

                  定义工具输入参数的 JSON Schema 属性。

                • required: optional array of string

                  必需属性名称列表。

                • type: optional "object"

                  工具输入 schema 必须为 'object'。

                  • "object"

              • name: string

              • type: "custom"

                • "custom"

          • type: "agent"

            • "agent"

          • version: number

        • type: "coordinator"

          • "coordinator"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      RFC 3339 格式的时间戳

    • created_at: string

      RFC 3339 格式的时间戳

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcome评估uationResource

      每个结果的评估状态。每个发送到会话的 define_outcome 事件对应一个条目。

      • completed_at: string

        RFC 3339 格式的时间戳

      • description: string

        代理应产出的内容。

      • explanation: string

        最近一次评估的评分者判定文本。对于 satisfied，解释为何满足标准；对于 needs_revision（中间状态），说明缺少什么；对于 failed，说明为何不可恢复。

      • iteration: number

        结果当前所处的从 0 开始的修订周期。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。

      • result: string

        当前评估状态。代理开始工作前为 pending；产出或修订时为 running；评分者评分时为 evaluating；satisfied/max_iterations_reached/failed/interrupted 为终止状态。

      • type: "outcome_evaluation"

        • "outcome_evaluation"

    • resources: array of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • mount_path: string

        • type: "github_repository"

          • "github_repository"

        • updated_at: string

          RFC 3339 格式的时间戳

        • url: string

        • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              要检出的分支名称。

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              要检出的完整提交 SHA。

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • file_id: string

        • mount_path: string

        • type: "file"

          • "file"

        • updated_at: string

          RFC 3339 格式的时间戳

      • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

        附加到代理会话的记忆存储。

        • memory_store_id: string

          记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

        • type: "memory_store"

          • "memory_store"

        • access: optional "read_write" or "read_only"

          附加记忆存储的访问模式。

          • "read_write"

          • "read_only"

        • description: optional string

          记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

        • instructions: optional string

          每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

        • mount_path: optional string

          存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

        • name: optional string

          记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

    • stats: BetaManagedAgentsSessionStats

      会话的计时统计。

      • active_seconds: optional number

        会话处于运行状态的累计时间（秒）。不包括空闲时间。

      • duration_seconds: optional number

        自会话创建以来的经过时间（秒）。对于已终止的会话，冻结在最终更新时。

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus 枚举

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • type: "session"

      • "session"

    • updated_at: string

      RFC 3339 格式的时间戳

    • usage: BetaManagedAgentsSessionUsage

      会话在所有轮次中的累计 token 使用量。

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        按缓存生命周期细分的提示缓存创建 token 使用量。

        • ephemeral_1h_input_tokens: optional number

          用于创建 1 小时临时缓存条目的 token 数。

        • ephemeral_5m_input_tokens: optional number

          用于创建 5 分钟临时缓存条目的 token 数。

      • cache_read_input_tokens: optional number

        从提示缓存读取的 token 总数。

      • input_tokens: optional number

        所有轮次消耗的输入 token 总数。

      • output_tokens: optional number

        所有轮次生成的输出 token 总数。

    • vault_ids: array of string

      创建时附加到会话的 Vault ID。未提供 Vault 时为空。

  • next_page: optional string

    下一页的不透明游标。没有更多结果时为 null。

示例

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"

响应

{
  "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-sonnet-4-6",
          "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-sonnet-4-6",
                "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"
                      }
                    }
                  ],
                  "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"
                }
              }
            ],
            "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",
      "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": {
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 0
        },
        "cache_read_input_tokens": 0,
        "input_tokens": 0,
        "output_tokens": 0
      },
      "vault_ids": [
        "vlt_011CZkZDLs7fYzm1hXNPeRjv"
      ]
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}

获取会话

get /v1/sessions/{session_id}

获取会话

路径参数

  • session_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • BetaManagedAgentsSession object { id, agent, archived_at, 12 more }

    托管代理 session。

    • id: string

    • agent: BetaManagedAgentsSessionAgent

      为 session 解析的 agent 定义。session 创建时 agent 的快照。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

        解析的协调器拓扑，包含每个成员的完整 agent 定义。

        • agents: array of BetaManagedAgentsSessionThreadAgent

          协调器可能作为会话线程生成的完整 agent 定义。

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            模型标识符和配置。

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              已解析的 Anthropic 托管技能。

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              已解析的用户创建的自定义技能。

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  内置代理工具标识符。

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

                    • type: "always_ask"

                      • "always_ask"

              • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                代理工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                MCP 服务器所有工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              API 响应中返回的自定义工具。

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                自定义工具输入参数的 JSON Schema。

                • properties: optional map[unknown]

                  定义工具输入参数的 JSON Schema 属性。

                • required: optional array of string

                  必需属性名称列表。

                • type: optional "object"

                  工具输入 schema 必须为 'object'。

                  • "object"

              • name: string

              • type: "custom"

                • "custom"

          • type: "agent"

            • "agent"

          • version: number

        • type: "coordinator"

          • "coordinator"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      RFC 3339 格式的时间戳

    • created_at: string

      RFC 3339 格式的时间戳

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcome评估uationResource

      每个结果的评估状态。每个发送到会话的 define_outcome 事件对应一个条目。

      • completed_at: string

        RFC 3339 格式的时间戳

      • description: string

        代理应产出的内容。

      • explanation: string

        最近一次评估的评分者判定文本。对于 satisfied，解释为何满足标准；对于 needs_revision（中间状态），说明缺少什么；对于 failed，说明为何不可恢复。

      • iteration: number

        结果当前所处的从 0 开始的修订周期。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。

      • result: string

        当前评估状态。代理开始工作前为 pending；产出或修订时为 running；评分者评分时为 evaluating；satisfied/max_iterations_reached/failed/interrupted 为终止状态。

      • type: "outcome_evaluation"

        • "outcome_evaluation"

    • resources: array of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • mount_path: string

        • type: "github_repository"

          • "github_repository"

        • updated_at: string

          RFC 3339 格式的时间戳

        • url: string

        • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              要检出的分支名称。

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              要检出的完整提交 SHA。

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • file_id: string

        • mount_path: string

        • type: "file"

          • "file"

        • updated_at: string

          RFC 3339 格式的时间戳

      • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

        附加到代理会话的记忆存储。

        • memory_store_id: string

          记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

        • type: "memory_store"

          • "memory_store"

        • access: optional "read_write" or "read_only"

          附加记忆存储的访问模式。

          • "read_write"

          • "read_only"

        • description: optional string

          记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

        • instructions: optional string

          每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

        • mount_path: optional string

          存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

        • name: optional string

          记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

    • stats: BetaManagedAgentsSessionStats

      会话的计时统计。

      • active_seconds: optional number

        会话处于运行状态的累计时间（秒）。不包括空闲时间。

      • duration_seconds: optional number

        自会话创建以来的经过时间（秒）。对于已终止的会话，冻结在最终更新时。

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus 枚举

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • type: "session"

      • "session"

    • updated_at: string

      RFC 3339 格式的时间戳

    • usage: BetaManagedAgentsSessionUsage

      会话在所有轮次中的累计 token 使用量。

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        按缓存生命周期细分的提示缓存创建 token 使用量。

        • ephemeral_1h_input_tokens: optional number

          用于创建 1 小时临时缓存条目的 token 数。

        • ephemeral_5m_input_tokens: optional number

          用于创建 5 分钟临时缓存条目的 token 数。

      • cache_read_input_tokens: optional number

        从提示缓存读取的 token 总数。

      • input_tokens: optional number

        所有轮次消耗的输入 token 总数。

      • output_tokens: optional number

        所有轮次生成的输出 token 总数。

    • vault_ids: array of string

      创建时附加到会话的 Vault ID。未提供 Vault 时为空。

示例

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"

响应

{
  "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-sonnet-4-6",
      "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-sonnet-4-6",
            "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"
                  }
                }
              ],
              "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"
            }
          }
        ],
        "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",
  "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": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  },
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ]
}

更新会话

post /v1/sessions/{session_id}

更新会话

路径参数

  • session_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

请求体参数

  • agent: optional BetaManagedAgentsSessionAgentUpdate

    会话中途的代理配置更新。只有 tools 和 mcp_servers 可更新。完全替换：提供的数组成为新值。要保留现有条目，请 GET 会话，修改数组，然后 POST 回来。

    • mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams

      替换的 MCP 服务器列表。完全替换：提供的数组成为新值。发送空数组以清除；省略以保留。

      • name: string

        此服务器的唯一名称，由 mcp_toolset 配置引用。1-255 个字符。

      • type: "url"

        • "url"

      • url: string

        MCP 服务器的端点 URL。

    • tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams

      替换的工具列表。完全替换：提供的数组成为新值。发送空数组以清除；省略以保留。

      • BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }

        内置代理工具的配置。使用此配置启用或禁用代理可用的工具组。

        • type: "agent_toolset_20260401"

          • "agent_toolset_20260401"

        • configs: optional array of BetaManagedAgentsAgentToolConfigParams

          每个工具的配置覆盖。

          • name: "bash" or "edit" or "read" or 5 more

            内置代理工具标识符。

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • enabled: optional boolean

            此工具是否启用并对 Claude 可用。覆盖 default_config 设置。

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            工具执行的权限策略。

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              工具调用无需用户确认即自动批准。

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              工具调用在执行前需要用户确认。

              • type: "always_ask"

                • "always_ask"

        • default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams

          工具集中所有工具的默认配置。

          • enabled: optional boolean

            工具是否默认启用并对 Claude 可用。未指定时默认为 true。

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            工具执行的权限策略。

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              工具调用无需用户确认即自动批准。

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              工具调用在执行前需要用户确认。

      • BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }

        在 mcp_servers 中定义的 MCP 服务器的工具配置。

        • mcp_server_name: string

          MCP 服务器的名称。必须与 mcp_servers 数组中的服务器名称匹配。1-255 个字符。

        • type: "mcp_toolset"

          • "mcp_toolset"

        • configs: optional array of BetaManagedAgentsMCPToolConfigParams

          每个工具的配置覆盖。

          • name: string

            要配置的 MCP 工具名称。1-128 个字符。

          • enabled: optional boolean

            此工具是否启用。覆盖 default_config 设置。

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            工具执行的权限策略。

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              工具调用无需用户确认即自动批准。

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              工具调用在执行前需要用户确认。

        • default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams

          来自 MCP 服务器的所有工具的默认配置。

          • enabled: optional boolean

            工具是否默认启用。未指定时默认为 true。

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            工具执行的权限策略。

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              工具调用无需用户确认即自动批准。

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              工具调用在执行前需要用户确认。

      • BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }

        由 API 客户端而非代理执行的自定义工具。当代理调用此工具时，会发出 agent.custom_tool_use 事件，会话进入空闲状态，等待客户端通过 user.custom_tool_result 事件提供结果。

        • description: string

          工具功能的描述，显示给代理以帮助其决定何时使用该工具。1-1024 个字符。

        • input_schema: BetaManagedAgentsCustomToolInputSchema

          自定义工具输入参数的 JSON Schema。

          • properties: optional map[unknown]

            定义工具输入参数的 JSON Schema 属性。

          • required: optional array of string

            必需属性名称列表。

          • type: optional "object"

            工具输入 schema 必须为 'object'。

            • "object"

        • name: string

          工具的唯一名称。1-128 个字符；字母、数字、下划线和连字符。

        • type: "custom"

          • "custom"

  • metadata: optional map[string]

    元数据补丁。将键设置为字符串以更新或插入，设置为 null 以删除。省略该字段以保留。

  • title: optional string

    人类可读的会话标题。

  • vault_ids: optional array of string

    要附加到会话的 Vault ID（vlt_*）。尚不支持；设置此字段的请求将被拒绝。保留供将来使用。

返回值

  • BetaManagedAgentsSession object { id, agent, archived_at, 12 more }

    托管代理 session。

    • id: string

    • agent: BetaManagedAgentsSessionAgent

      为 session 解析的 agent 定义。session 创建时 agent 的快照。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

        解析的协调器拓扑，包含每个成员的完整 agent 定义。

        • agents: array of BetaManagedAgentsSessionThreadAgent

          协调器可能作为会话线程生成的完整 agent 定义。

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            模型标识符和配置。

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              已解析的 Anthropic 托管技能。

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              已解析的用户创建的自定义技能。

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  内置代理工具标识符。

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

                    • type: "always_ask"

                      • "always_ask"

              • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                代理工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                MCP 服务器所有工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              API 响应中返回的自定义工具。

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                自定义工具输入参数的 JSON Schema。

                • properties: optional map[unknown]

                  定义工具输入参数的 JSON Schema 属性。

                • required: optional array of string

                  必需属性名称列表。

                • type: optional "object"

                  工具输入 schema 必须为 'object'。

                  • "object"

              • name: string

              • type: "custom"

                • "custom"

          • type: "agent"

            • "agent"

          • version: number

        • type: "coordinator"

          • "coordinator"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      RFC 3339 格式的时间戳

    • created_at: string

      RFC 3339 格式的时间戳

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcome评估uationResource

      每个结果的评估状态。每个发送到会话的 define_outcome 事件对应一个条目。

      • completed_at: string

        RFC 3339 格式的时间戳

      • description: string

        代理应产出的内容。

      • explanation: string

        最近一次评估的评分者判定文本。对于 satisfied，解释为何满足标准；对于 needs_revision（中间状态），说明缺少什么；对于 failed，说明为何不可恢复。

      • iteration: number

        结果当前所处的从 0 开始的修订周期。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。

      • result: string

        当前评估状态。代理开始工作前为 pending；产出或修订时为 running；评分者评分时为 evaluating；satisfied/max_iterations_reached/failed/interrupted 为终止状态。

      • type: "outcome_evaluation"

        • "outcome_evaluation"

    • resources: array of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • mount_path: string

        • type: "github_repository"

          • "github_repository"

        • updated_at: string

          RFC 3339 格式的时间戳

        • url: string

        • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              要检出的分支名称。

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              要检出的完整提交 SHA。

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • file_id: string

        • mount_path: string

        • type: "file"

          • "file"

        • updated_at: string

          RFC 3339 格式的时间戳

      • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

        附加到代理会话的记忆存储。

        • memory_store_id: string

          记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

        • type: "memory_store"

          • "memory_store"

        • access: optional "read_write" or "read_only"

          附加记忆存储的访问模式。

          • "read_write"

          • "read_only"

        • description: optional string

          记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

        • instructions: optional string

          每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

        • mount_path: optional string

          存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

        • name: optional string

          记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

    • stats: BetaManagedAgentsSessionStats

      会话的计时统计。

      • active_seconds: optional number

        会话处于运行状态的累计时间（秒）。不包括空闲时间。

      • duration_seconds: optional number

        自会话创建以来的经过时间（秒）。对于已终止的会话，冻结在最终更新时。

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus 枚举

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • type: "session"

      • "session"

    • updated_at: string

      RFC 3339 格式的时间戳

    • usage: BetaManagedAgentsSessionUsage

      会话在所有轮次中的累计 token 使用量。

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        按缓存生命周期细分的提示缓存创建 token 使用量。

        • ephemeral_1h_input_tokens: optional number

          用于创建 1 小时临时缓存条目的 token 数。

        • ephemeral_5m_input_tokens: optional number

          用于创建 5 分钟临时缓存条目的 token 数。

      • cache_read_input_tokens: optional number

        从提示缓存读取的 token 总数。

      • input_tokens: optional number

        所有轮次消耗的输入 token 总数。

      • output_tokens: optional number

        所有轮次生成的输出 token 总数。

    • vault_ids: array of string

      创建时附加到会话的 Vault ID。未提供 Vault 时为空。

示例

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"
        }'

响应

{
  "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-sonnet-4-6",
      "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-sonnet-4-6",
            "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"
                  }
                }
              ],
              "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"
            }
          }
        ],
        "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",
  "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": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  },
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ]
}

删除会话

delete /v1/sessions/{session_id}

删除会话

路径参数

  • session_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • BetaManagedAgentsDeletedSession object { id, type }

    确认 session 已被永久删除。

    • id: string

    • type: "session_deleted"

      • "session_deleted"

示例

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"

响应

{
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "type": "session_deleted"
}

归档会话

post /v1/sessions/{session_id}/archive

归档会话

路径参数

  • session_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • BetaManagedAgentsSession object { id, agent, archived_at, 12 more }

    托管代理 session。

    • id: string

    • agent: BetaManagedAgentsSessionAgent

      为 session 解析的 agent 定义。session 创建时 agent 的快照。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

        解析的协调器拓扑，包含每个成员的完整 agent 定义。

        • agents: array of BetaManagedAgentsSessionThreadAgent

          协调器可能作为会话线程生成的完整 agent 定义。

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            模型标识符和配置。

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              已解析的 Anthropic 托管技能。

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              已解析的用户创建的自定义技能。

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  内置代理工具标识符。

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

                    • type: "always_ask"

                      • "always_ask"

              • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                代理工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                MCP 服务器所有工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              API 响应中返回的自定义工具。

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                自定义工具输入参数的 JSON Schema。

                • properties: optional map[unknown]

                  定义工具输入参数的 JSON Schema 属性。

                • required: optional array of string

                  必需属性名称列表。

                • type: optional "object"

                  工具输入 schema 必须为 'object'。

                  • "object"

              • name: string

              • type: "custom"

                • "custom"

          • type: "agent"

            • "agent"

          • version: number

        • type: "coordinator"

          • "coordinator"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      RFC 3339 格式的时间戳

    • created_at: string

      RFC 3339 格式的时间戳

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcome评估uationResource

      每个结果的评估状态。每个发送到会话的 define_outcome 事件对应一个条目。

      • completed_at: string

        RFC 3339 格式的时间戳

      • description: string

        代理应产出的内容。

      • explanation: string

        最近一次评估的评分者判定文本。对于 satisfied，解释为何满足标准；对于 needs_revision（中间状态），说明缺少什么；对于 failed，说明为何不可恢复。

      • iteration: number

        结果当前所处的从 0 开始的修订周期。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。

      • result: string

        当前评估状态。代理开始工作前为 pending；产出或修订时为 running；评分者评分时为 evaluating；satisfied/max_iterations_reached/failed/interrupted 为终止状态。

      • type: "outcome_evaluation"

        • "outcome_evaluation"

    • resources: array of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • mount_path: string

        • type: "github_repository"

          • "github_repository"

        • updated_at: string

          RFC 3339 格式的时间戳

        • url: string

        • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              要检出的分支名称。

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              要检出的完整提交 SHA。

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • file_id: string

        • mount_path: string

        • type: "file"

          • "file"

        • updated_at: string

          RFC 3339 格式的时间戳

      • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

        附加到代理会话的记忆存储。

        • memory_store_id: string

          记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

        • type: "memory_store"

          • "memory_store"

        • access: optional "read_write" or "read_only"

          附加记忆存储的访问模式。

          • "read_write"

          • "read_only"

        • description: optional string

          记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

        • instructions: optional string

          每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

        • mount_path: optional string

          存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

        • name: optional string

          记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

    • stats: BetaManagedAgentsSessionStats

      会话的计时统计。

      • active_seconds: optional number

        会话处于运行状态的累计时间（秒）。不包括空闲时间。

      • duration_seconds: optional number

        自会话创建以来的经过时间（秒）。对于已终止的会话，冻结在最终更新时。

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus 枚举

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • type: "session"

      • "session"

    • updated_at: string

      RFC 3339 格式的时间戳

    • usage: BetaManagedAgentsSessionUsage

      会话在所有轮次中的累计 token 使用量。

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        按缓存生命周期细分的提示缓存创建 token 使用量。

        • ephemeral_1h_input_tokens: optional number

          用于创建 1 小时临时缓存条目的 token 数。

        • ephemeral_5m_input_tokens: optional number

          用于创建 5 分钟临时缓存条目的 token 数。

      • cache_read_input_tokens: optional number

        从提示缓存读取的 token 总数。

      • input_tokens: optional number

        所有轮次消耗的输入 token 总数。

      • output_tokens: optional number

        所有轮次生成的输出 token 总数。

    • vault_ids: array of string

      创建时附加到会话的 Vault ID。未提供 Vault 时为空。

示例

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"

响应

{
  "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-sonnet-4-6",
      "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-sonnet-4-6",
            "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"
                  }
                }
              ],
              "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"
            }
          }
        ],
        "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",
  "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": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  },
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ]
}

领域类型

Beta Managed Agents Agent Params

  • BetaManagedAgentsAgentParams object { id, type, version }

    代理的规范。提供特定的 version 或使用简写 agent="agent_id" 获取最新版本

    • id: string

      agent 的 ID。

    • type: "agent"

      • "agent"

    • version: optional number

      要使用的特定 agent 版本。省略以使用最新版本。如果指定，必须至少为 1。

Beta Managed Agents Branch Checkout

  • BetaManagedAgentsBranchCheckout object { name, type }

    • name: string

      要检出的分支名称。

    • type: "branch"

      • "branch"

Beta Managed Agents Cache Creation Usage

  • BetaManagedAgentsCacheCreationUsage object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }

    按缓存生命周期细分的提示缓存创建 token 使用量。

    • ephemeral_1h_input_tokens: optional number

      用于创建 1 小时临时缓存条目的 token 数。

    • ephemeral_5m_input_tokens: optional number

      用于创建 5 分钟临时缓存条目的 token 数。

Beta Managed Agents Commit Checkout

  • BetaManagedAgentsCommitCheckout object { sha, type }

    • sha: string

      要检出的完整提交 SHA。

    • type: "commit"

      • "commit"

Beta Managed Agents Deleted Session

  • BetaManagedAgentsDeletedSession object { id, type }

    确认 session 已被永久删除。

    • id: string

    • type: "session_deleted"

      • "session_deleted"

Beta Managed Agents File Resource Params

  • BetaManagedAgentsFileResourceParams object { file_id, type, mount_path }

    将通过 Files API 上传的文件挂载到会话中。

    • file_id: string

      先前上传文件的 ID。

    • type: "file"

      • "file"

    • mount_path: optional string

      容器中的挂载路径。默认为 /mnt/session/uploads/<file_id>。

Beta Managed Agents GitHub Repository Resource Params

  • BetaManagedAgentsGitHubRepositoryResourceParams object { authorization_token, type, url, 2 more }

    将 GitHub 仓库挂载到会话容器中。

    • authorization_token: string

      用于克隆仓库的 GitHub 授权令牌。

    • type: "github_repository"

      • "github_repository"

    • url: string

      仓库的 GitHub URL

    • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

      要检出的分支或提交。默认为仓库的默认分支。

      • BetaManagedAgentsBranchCheckout object { name, type }

        • name: string

          要检出的分支名称。

        • type: "branch"

          • "branch"

      • BetaManagedAgentsCommitCheckout object { sha, type }

        • sha: string

          要检出的完整提交 SHA。

        • type: "commit"

          • "commit"

    • mount_path: optional string

      容器中的挂载路径。默认为 /workspace/<repo-name>。

Beta Managed Agents Memory Store Resource Param

  • BetaManagedAgentsMemoryStoreResourceParam object { memory_store_id, type, access, instructions }

    将记忆存储附加到代理会话的参数。

    • memory_store_id: string

      记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

    • type: "memory_store"

      • "memory_store"

    • access: optional "read_write" or "read_only"

      附加记忆存储的访问模式。

      • "read_write"

      • "read_only"

    • instructions: optional string

      每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

Beta Managed Agents Multiagent

  • BetaManagedAgentsMultiagent object { agents, type }

    解析的协调器拓扑，包含具体的代理名册。

    • agents: array of BetaManagedAgentsAgentReference

      协调器可能作为会话线程生成的代理，每个都解析到特定版本。

      • id: string

      • type: "agent"

        • "agent"

      • version: number

    • type: "coordinator"

      • "coordinator"

Beta Managed Agents Multiagent Params

  • BetaManagedAgentsMultiagentParams object { agents, type }

    协调器拓扑：会话的主线程通过生成会话线程来编排工作，每个线程运行从 agents 名册中提取的代理。

    • agents: array of BetaManagedAgentsMultiagentRosterEntryParams

      协调器可能作为会话线程生成的代理。1-20 个条目。每个条目是代理 ID 字符串、带版本的 {"type":"agent","id","version"} 引用，或 {"type":"self"} 以允许递归自调用。条目必须引用不同的代理（解析 self 和字符串形式后）；最多一个 self。引用的代理必须存在，不能被归档，且自身不能设置 multiagent（深度限制为 1）。

      • string

      • BetaManagedAgentsAgentParams object { id, type, version }

        代理的规范。提供特定的 version 或使用简写 agent="agent_id" 获取最新版本

        • id: string

          agent 的 ID。

        • type: "agent"

          • "agent"

        • version: optional number

          要使用的特定 agent 版本。省略以使用最新版本。如果指定，必须至少为 1。

      • BetaManagedAgentsMultiagentSelfParams object { type }

        哨兵名册条目，表示"拥有此配置的代理"。在服务器端解析为具体的代理引用。

        • type: "self"

          • "self"

    • type: "coordinator"

      • "coordinator"

Beta Managed Agents Multiagent Roster Entry Params

  • BetaManagedAgentsMultiagentRosterEntryParams = string or BetaManagedAgentsAgentParams or BetaManagedAgentsMultiagentSelfParams

    多代理名册中的条目：代理 ID 字符串、带版本的代理引用或 self。

    • string

    • BetaManagedAgentsAgentParams object { id, type, version }

      代理的规范。提供特定的 version 或使用简写 agent="agent_id" 获取最新版本

      • id: string

        agent 的 ID。

      • type: "agent"

        • "agent"

      • version: optional number

        要使用的特定 agent 版本。省略以使用最新版本。如果指定，必须至少为 1。

    • BetaManagedAgentsMultiagentSelfParams object { type }

      哨兵名册条目，表示"拥有此配置的代理"。在服务器端解析为具体的代理引用。

      • type: "self"

        • "self"

Beta Managed Agents Outcome 评估uation Resource

  • BetaManagedAgentsOutcome评估uationResource object { completed_at, description, explanation, 4 more }

    通过 define_outcome 事件定义的单个结果的评估状态。

    • completed_at: string

      RFC 3339 格式的时间戳

    • description: string

      代理应产出的内容。

    • explanation: string

      最近一次评估的评分者判定文本。对于 satisfied，解释为何满足标准；对于 needs_revision（中间状态），说明缺少什么；对于 failed，说明为何不可恢复。

    • iteration: number

      结果当前所处的从 0 开始的修订周期。

    • outcome_id: string

      服务器为此结果生成的 outc_ ID。

    • result: string

      当前评估状态。代理开始工作前为 pending；产出或修订时为 running；评分者评分时为 evaluating；satisfied/max_iterations_reached/failed/interrupted 为终止状态。

    • type: "outcome_evaluation"

      • "outcome_evaluation"

Beta Managed Agents Session

  • BetaManagedAgentsSession object { id, agent, archived_at, 12 more }

    托管代理 session。

    • id: string

    • agent: BetaManagedAgentsSessionAgent

      为 session 解析的 agent 定义。session 创建时 agent 的快照。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

        解析的协调器拓扑，包含每个成员的完整 agent 定义。

        • agents: array of BetaManagedAgentsSessionThreadAgent

          协调器可能作为会话线程生成的完整 agent 定义。

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            模型标识符和配置。

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              已解析的 Anthropic 托管技能。

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              已解析的用户创建的自定义技能。

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  内置代理工具标识符。

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

                    • type: "always_ask"

                      • "always_ask"

              • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                代理工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                MCP 服务器所有工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              API 响应中返回的自定义工具。

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                自定义工具输入参数的 JSON Schema。

                • properties: optional map[unknown]

                  定义工具输入参数的 JSON Schema 属性。

                • required: optional array of string

                  必需属性名称列表。

                • type: optional "object"

                  工具输入 schema 必须为 'object'。

                  • "object"

              • name: string

              • type: "custom"

                • "custom"

          • type: "agent"

            • "agent"

          • version: number

        • type: "coordinator"

          • "coordinator"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      RFC 3339 格式的时间戳

    • created_at: string

      RFC 3339 格式的时间戳

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcome评估uationResource

      每个结果的评估状态。每个发送到会话的 define_outcome 事件对应一个条目。

      • completed_at: string

        RFC 3339 格式的时间戳

      • description: string

        代理应产出的内容。

      • explanation: string

        最近一次评估的评分者判定文本。对于 satisfied，解释为何满足标准；对于 needs_revision（中间状态），说明缺少什么；对于 failed，说明为何不可恢复。

      • iteration: number

        结果当前所处的从 0 开始的修订周期。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。

      • result: string

        当前评估状态。代理开始工作前为 pending；产出或修订时为 running；评分者评分时为 evaluating；satisfied/max_iterations_reached/failed/interrupted 为终止状态。

      • type: "outcome_evaluation"

        • "outcome_evaluation"

    • resources: array of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • mount_path: string

        • type: "github_repository"

          • "github_repository"

        • updated_at: string

          RFC 3339 格式的时间戳

        • url: string

        • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              要检出的分支名称。

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              要检出的完整提交 SHA。

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • id: string

        • created_at: string

          RFC 3339 格式的时间戳

        • file_id: string

        • mount_path: string

        • type: "file"

          • "file"

        • updated_at: string

          RFC 3339 格式的时间戳

      • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

        附加到代理会话的记忆存储。

        • memory_store_id: string

          记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

        • type: "memory_store"

          • "memory_store"

        • access: optional "read_write" or "read_only"

          附加记忆存储的访问模式。

          • "read_write"

          • "read_only"

        • description: optional string

          记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

        • instructions: optional string

          每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

        • mount_path: optional string

          存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

        • name: optional string

          记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

    • stats: BetaManagedAgentsSessionStats

      会话的计时统计。

      • active_seconds: optional number

        会话处于运行状态的累计时间（秒）。不包括空闲时间。

      • duration_seconds: optional number

        自会话创建以来的经过时间（秒）。对于已终止的会话，冻结在最终更新时。

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus 枚举

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • type: "session"

      • "session"

    • updated_at: string

      RFC 3339 格式的时间戳

    • usage: BetaManagedAgentsSessionUsage

      会话在所有轮次中的累计 token 使用量。

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        按缓存生命周期细分的提示缓存创建 token 使用量。

        • ephemeral_1h_input_tokens: optional number

          用于创建 1 小时临时缓存条目的 token 数。

        • ephemeral_5m_input_tokens: optional number

          用于创建 5 分钟临时缓存条目的 token 数。

      • cache_read_input_tokens: optional number

        从提示缓存读取的 token 总数。

      • input_tokens: optional number

        所有轮次消耗的输入 token 总数。

      • output_tokens: optional number

        所有轮次生成的输出 token 总数。

    • vault_ids: array of string

      创建时附加到会话的 Vault ID。未提供 Vault 时为空。

Beta Managed Agents Session Agent

  • BetaManagedAgentsSessionAgent object { id, description, mcp_servers, 8 more }

    为 session 解析的 agent 定义。session 创建时 agent 的快照。

    • id: string

    • description: string

    • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

      • name: string

      • type: "url"

        • "url"

      • url: string

    • model: BetaManagedAgentsModelConfig

      模型标识符和配置。

      • id: BetaManagedAgentsModel

        驱动代理的模型。

        详情和选项请参阅 models。

        • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7"

            适用于长时间运行代理和编码的前沿智能

          • "claude-opus-4-6"

            用于构建代理和编码的最智能模型

          • "claude-sonnet-4-6"

            速度与智能的最佳组合

          • "claude-haiku-4-5"

            具有接近前沿智能的最快模型

          • "claude-haiku-4-5-20251001"

            具有接近前沿智能的最快模型

          • "claude-opus-4-5"

            结合最大智能与实用性能的高级模型

          • "claude-opus-4-5-20251101"

            结合最大智能与实用性能的高级模型

          • "claude-sonnet-4-5"

            适用于代理和编码的高性能模型

          • "claude-sonnet-4-5-20250929"

            适用于代理和编码的高性能模型

        • string

      • speed: optional "standard" or "fast"

        推理速度模式。fast 以高级定价提供显著更快的输出 token 生成。并非所有模型都支持 fast；无效组合在创建时会被拒绝。

        • "standard"

        • "fast"

    • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

      解析的协调器拓扑，包含每个成员的完整代理定义。

      • agents: array of BetaManagedAgentsSessionThreadAgent

        协调器可能作为会话线程生成的完整 agent 定义。

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          模型标识符和配置。

        • name: string

        • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            已解析的 Anthropic 托管技能。

            • skill_id: string

            • type: "anthropic"

              • "anthropic"

            • version: string

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            已解析的用户创建的自定义技能。

            • skill_id: string

            • type: "custom"

              • "custom"

            • version: string

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

            • configs: array of BetaManagedAgentsAgentToolConfig

              • enabled: boolean

              • name: "bash" or "edit" or "read" or 5 more

                内置代理工具标识符。

                • "bash"

                • "edit"

                • "read"

                • "write"

                • "glob"

                • "grep"

                • "web_fetch"

                • "web_search"

              • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                工具执行的权限策略。

                • BetaManagedAgentsAlwaysAllowPolicy object { type }

                  工具调用无需用户确认即自动批准。

                  • type: "always_allow"

                    • "always_allow"

                • BetaManagedAgentsAlwaysAskPolicy object { type }

                  工具调用在执行前需要用户确认。

                  • type: "always_ask"

                    • "always_ask"

            • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

              代理工具的已解析默认配置。

              • enabled: boolean

              • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                工具执行的权限策略。

                • BetaManagedAgentsAlwaysAllowPolicy object { type }

                  工具调用无需用户确认即自动批准。

                • BetaManagedAgentsAlwaysAskPolicy object { type }

                  工具调用在执行前需要用户确认。

            • type: "agent_toolset_20260401"

              • "agent_toolset_20260401"

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

            • configs: array of BetaManagedAgentsMCPToolConfig

              • enabled: boolean

              • name: string

              • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                工具执行的权限策略。

                • BetaManagedAgentsAlwaysAllowPolicy object { type }

                  工具调用无需用户确认即自动批准。

                • BetaManagedAgentsAlwaysAskPolicy object { type }

                  工具调用在执行前需要用户确认。

            • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

              来自 MCP 服务器的所有工具的已解析默认配置。

              • enabled: boolean

              • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                工具执行的权限策略。

                • BetaManagedAgentsAlwaysAllowPolicy object { type }

                  工具调用无需用户确认即自动批准。

                • BetaManagedAgentsAlwaysAskPolicy object { type }

                  工具调用在执行前需要用户确认。

            • mcp_server_name: string

            • type: "mcp_toolset"

              • "mcp_toolset"

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            API 响应中返回的自定义工具。

            • description: string

            • input_schema: BetaManagedAgentsCustomToolInputSchema

              自定义工具输入参数的 JSON Schema。

              • properties: optional map[unknown]

                定义工具输入参数的 JSON Schema 属性。

              • required: optional array of string

                必需属性名称列表。

              • type: optional "object"

                工具输入 schema 必须为 'object'。

                • "object"

            • name: string

            • type: "custom"

              • "custom"

        • type: "agent"

          • "agent"

        • version: number

      • type: "coordinator"

        • "coordinator"

    • name: string

    • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

      • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

        已解析的 Anthropic 托管技能。

      • BetaManagedAgentsCustomSkill object { skill_id, type, version }

        已解析的用户创建的自定义技能。

    • system: string

    • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

      • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

      • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

      • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

        API 响应中返回的自定义工具。

    • type: "agent"

      • "agent"

    • version: number

Beta Managed Agents Session Agent Update

  • BetaManagedAgentsSessionAgentUpdate object { mcp_servers, tools }

    会话中途的代理配置更新。只有 tools 和 mcp_servers 可更新。完全替换：提供的数组成为新值。要保留现有条目，请 GET 会话，修改数组，然后 POST 回来。

    • mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams

      替换的 MCP 服务器列表。完全替换：提供的数组成为新值。发送空数组以清除；省略以保留。

      • name: string

        此服务器的唯一名称，由 mcp_toolset 配置引用。1-255 个字符。

      • type: "url"

        • "url"

      • url: string

        MCP 服务器的端点 URL。

    • tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams

      替换的工具列表。完全替换：提供的数组成为新值。发送空数组以清除；省略以保留。

      • BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }

        内置代理工具的配置。使用此配置启用或禁用代理可用的工具组。

        • type: "agent_toolset_20260401"

          • "agent_toolset_20260401"

        • configs: optional array of BetaManagedAgentsAgentToolConfigParams

          每个工具的配置覆盖。

          • name: "bash" or "edit" or "read" or 5 more

            内置代理工具标识符。

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • enabled: optional boolean

            此工具是否启用并对 Claude 可用。覆盖 default_config 设置。

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            工具执行的权限策略。

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              工具调用无需用户确认即自动批准。

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              工具调用在执行前需要用户确认。

              • type: "always_ask"

                • "always_ask"

        • default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams

          工具集中所有工具的默认配置。

          • enabled: optional boolean

            工具是否默认启用并对 Claude 可用。未指定时默认为 true。

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            工具执行的权限策略。

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              工具调用无需用户确认即自动批准。

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              工具调用在执行前需要用户确认。

      • BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }

        在 mcp_servers 中定义的 MCP 服务器的工具配置。

        • mcp_server_name: string

          MCP 服务器的名称。必须与 mcp_servers 数组中的服务器名称匹配。1-255 个字符。

        • type: "mcp_toolset"

          • "mcp_toolset"

        • configs: optional array of BetaManagedAgentsMCPToolConfigParams

          每个工具的配置覆盖。

          • name: string

            要配置的 MCP 工具名称。1-128 个字符。

          • enabled: optional boolean

            此工具是否启用。覆盖 default_config 设置。

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            工具执行的权限策略。

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              工具调用无需用户确认即自动批准。

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              工具调用在执行前需要用户确认。

        • default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams

          来自 MCP 服务器的所有工具的默认配置。

          • enabled: optional boolean

            工具是否默认启用。未指定时默认为 true。

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            工具执行的权限策略。

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              工具调用无需用户确认即自动批准。

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              工具调用在执行前需要用户确认。

      • BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }

        由 API 客户端而非代理执行的自定义工具。当代理调用此工具时，会发出 agent.custom_tool_use 事件，会话进入空闲状态，等待客户端通过 user.custom_tool_result 事件提供结果。

        • description: string

          工具功能的描述，显示给代理以帮助其决定何时使用该工具。1-1024 个字符。

        • input_schema: BetaManagedAgentsCustomToolInputSchema

          自定义工具输入参数的 JSON Schema。

          • properties: optional map[unknown]

            定义工具输入参数的 JSON Schema 属性。

          • required: optional array of string

            必需属性名称列表。

          • type: optional "object"

            工具输入 schema 必须为 'object'。

            • "object"

        • name: string

          工具的唯一名称。1-128 个字符；字母、数字、下划线和连字符。

        • type: "custom"

          • "custom"

Beta Managed Agents Session Multiagent Coordinator

  • BetaManagedAgentsSessionMultiagentCoordinator object { agents, type }

    解析的协调器拓扑，包含每个成员的完整代理定义。

    • agents: array of BetaManagedAgentsSessionThreadAgent

      协调器可能作为会话线程生成的完整 agent 定义。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

          • skill_id: string

          • type: "anthropic"

            • "anthropic"

          • version: string

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

          • skill_id: string

          • type: "custom"

            • "custom"

          • version: string

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • configs: array of BetaManagedAgentsAgentToolConfig

            • enabled: boolean

            • name: "bash" or "edit" or "read" or 5 more

              内置代理工具标识符。

              • "bash"

              • "edit"

              • "read"

              • "write"

              • "glob"

              • "grep"

              • "web_fetch"

              • "web_search"

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

                • type: "always_allow"

                  • "always_allow"

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

                • type: "always_ask"

                  • "always_ask"

          • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

            代理工具的已解析默认配置。

            • enabled: boolean

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • type: "agent_toolset_20260401"

            • "agent_toolset_20260401"

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • configs: array of BetaManagedAgentsMCPToolConfig

            • enabled: boolean

            • name: string

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

            来自 MCP 服务器的所有工具的已解析默认配置。

            • enabled: boolean

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • mcp_server_name: string

          • type: "mcp_toolset"

            • "mcp_toolset"

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

          • description: string

          • input_schema: BetaManagedAgentsCustomToolInputSchema

            自定义工具输入参数的 JSON Schema。

            • properties: optional map[unknown]

              定义工具输入参数的 JSON Schema 属性。

            • required: optional array of string

              必需属性名称列表。

            • type: optional "object"

              工具输入 schema 必须为 'object'。

              • "object"

          • name: string

          • type: "custom"

            • "custom"

      • type: "agent"

        • "agent"

      • version: number

    • type: "coordinator"

      • "coordinator"

Beta Managed Agents Session Stats

  • BetaManagedAgentsSessionStats object { active_seconds, duration_seconds }

    会话的计时统计。

    • active_seconds: optional number

      会话处于运行状态的累计时间（秒）。不包括空闲时间。

    • duration_seconds: optional number

      自会话创建以来的经过时间（秒）。对于已终止的会话，冻结在最终更新时。

Beta Managed Agents Session Updated Event

  • BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 3 more }

    当 UpdateSession 请求更改了至少一个字段时发出。仅携带已更改的字段；未出现的字段不是更新的一部分。新配置从下一轮开始生效。

    • id: string

      此事件的唯一标识符。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "session.updated"

      • "session.updated"

    • agent: optional BetaManagedAgentsSessionAgent

      为 session 解析的 agent 定义。session 创建时 agent 的快照。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

        解析的协调器拓扑，包含每个成员的完整 agent 定义。

        • agents: array of BetaManagedAgentsSessionThreadAgent

          协调器可能作为会话线程生成的完整 agent 定义。

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            模型标识符和配置。

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              已解析的 Anthropic 托管技能。

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              已解析的用户创建的自定义技能。

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  内置代理工具标识符。

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

                    • type: "always_ask"

                      • "always_ask"

              • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                代理工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                MCP 服务器所有工具的解析默认配置。

                • enabled: boolean

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  工具执行的权限策略。

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    工具调用会自动批准，无需用户确认。

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    工具调用需要用户确认后才能执行。

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              API 响应中返回的自定义工具。

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                自定义工具输入参数的 JSON Schema。

                • properties: optional map[unknown]

                  定义工具输入参数的 JSON Schema 属性。

                • required: optional array of string

                  必需属性名称列表。

                • type: optional "object"

                  工具输入 schema 必须为 'object'。

                  • "object"

              • name: string

              • type: "custom"

                • "custom"

          • type: "agent"

            • "agent"

          • version: number

        • type: "coordinator"

          • "coordinator"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

      • type: "agent"

        • "agent"

      • version: number

    • metadata: optional map[string]

      更新后会话的完整元数据包。当更新设置了非空元数据时存在；当元数据未更改或清空时不存在。

    • title: optional string

      会话的新标题。仅在更新更改了标题时存在。

Beta Managed Agents Session Usage

  • BetaManagedAgentsSessionUsage object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }

    会话在所有轮次中的累计 token 使用量。

    • cache_creation: optional BetaManagedAgentsCacheCreationUsage

      按缓存生命周期细分的提示缓存创建 token 使用量。

      • ephemeral_1h_input_tokens: optional number

        用于创建 1 小时临时缓存条目的 token 数。

      • ephemeral_5m_input_tokens: optional number

        用于创建 5 分钟临时缓存条目的 token 数。

    • cache_read_input_tokens: optional number

      从提示缓存读取的 token 总数。

    • input_tokens: optional number

      所有轮次消耗的输入 token 总数。

    • output_tokens: optional number

      所有轮次生成的输出 token 总数。

Beta Managed Agents User Tool Result Event

  • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

    客户端发送的事件，提供代理工具集工具执行的结果。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

    • id: string

      此事件的唯一标识符。

    • tool_use_id: string

      此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

    • type: "user.tool_result"

      • "user.tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      工具返回的结果内容。

      • BetaManagedAgentsTextBlock object { text, type }

        常规文本内容。

        • text: string

          文本内容。

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        直接指定为 base64 数据或通过 URL 引用的图片内容。

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          图片源变体的联合类型。

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            Base64 编码的图片数据。

            • data: string

              Base64 编码的图片数据。

            • media_type: string

              图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsURLImageSource object { type, url }

            通过 URL 引用的图片。

            • type: "url"

              • "url"

            • url: string

              要获取的图片 URL。

          • BetaManagedAgentsFileImageSource object { file_id, type }

            通过文件 ID 引用的图片。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          文档源变体的联合类型。

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            Base64 编码的文档数据。

            • data: string

              Base64 编码的文档数据。

            • media_type: string

              文档的 MIME 类型（例如 "application/pdf"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

            纯文本文档内容。

            • data: string

              纯文本内容。

            • media_type: "text/plain"

              文本内容的 MIME 类型。必须为 "text/plain"。

              • "text/plain"

            • type: "text"

              • "text"

          • BetaManagedAgentsURLDocumentSource object { type, url }

            通过 URL 引用的文档。

            • type: "url"

              • "url"

            • url: string

              要获取的文档 URL。

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            通过文件 ID 引用的文档。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          为模型提供的关于文档的额外上下文。

        • title: optional string

          文档的标题。

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        包含网络搜索结果的块。

        • citations: BetaManagedAgentsSearchResultCitations

          搜索结果的引用设置。

          • enabled: boolean

            此搜索结果是否启用引用。

        • content: array of BetaManagedAgentsSearchResultContent

          搜索结果中的文本内容块数组。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • source: string

          搜索结果的 URL 来源。

        • title: string

          搜索结果的标题。

        • type: "search_result"

          • "search_result"

    • is_error: optional boolean

      工具执行是否导致错误。

    • processed_at: optional string

      RFC 3339 格式的时间戳

    • session_thread_id: optional string

      将此结果路由到子代理线程。从 agent.tool_use 事件的 session_thread_id 复制。

Events

列出事件

get /v1/sessions/{session_id}/events

列出事件

路径参数

  • session_id: string

查询参数

  • "created_at[gt]": optional string

    返回在此时间之后创建的事件（不包含）。

  • "created_at[gte]": optional string

    返回在此时间或之后创建的事件（包含）。

  • "created_at[lt]": optional string

    返回在此时间之前创建的事件（不包含）。

  • "created_at[lte]": optional string

    返回在此时间或之前创建的事件（包含）。

  • limit: optional number

    查询参数，用于限制返回数量

  • order: optional "asc" or "desc"

    结果的排序方向，按 created_at 排序。默认为 asc（按时间顺序）。

    • "asc"

    • "desc"

  • page: optional string

    来自先前响应 next_page 的不透明分页游标。

  • types: optional array of string

    按事件类型过滤。值与返回事件的 type 字段匹配（例如 user.message 或 agent.tool_use）。省略以返回所有事件类型。

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • data: optional array of BetaManagedAgentsSessionEvent

    会话的事件，按 created_at 排序。

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      会话对话中的用户消息事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        组成用户消息的内容块数组。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            图片源变体的联合类型。

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              Base64 编码的图片数据。

              • data: string

                Base64 编码的图片数据。

              • media_type: string

                图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsURLImageSource object { type, url }

              通过 URL 引用的图片。

              • type: "url"

                • "url"

              • url: string

                要获取的图片 URL。

            • BetaManagedAgentsFileImageSource object { file_id, type }

              通过文件 ID 引用的图片。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            文档源变体的联合类型。

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              Base64 编码的文档数据。

              • data: string

                Base64 编码的文档数据。

              • media_type: string

                文档的 MIME 类型（例如 "application/pdf"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

              纯文本文档内容。

              • data: string

                纯文本内容。

              • media_type: "text/plain"

                文本内容的 MIME 类型。必须为 "text/plain"。

                • "text/plain"

              • type: "text"

                • "text"

            • BetaManagedAgentsURLDocumentSource object { type, url }

              通过 URL 引用的文档。

              • type: "url"

                • "url"

              • url: string

                要获取的文档 URL。

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              通过文件 ID 引用的文档。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            为模型提供的关于文档的额外上下文。

          • title: optional string

            文档的标题。

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        RFC 3339 格式的时间戳

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      暂停代理执行并将控制权返回给用户的中断事件。

      • id: string

        此事件的唯一标识符。

      • type: "user.interrupt"

        • "user.interrupt"

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        如果省略，中断多代理会话中的每个未归档线程（或单代理会话中的主线程）。如果指定，仅中断指定的线程。

    • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

      批准或拒绝待处理工具执行的工具确认事件。

      • id: string

        此事件的唯一标识符。

      • result: "allow" or "deny"

        UserToolConfirmationResult 枚举

        • "allow"

        • "deny"

      • tool_use_id: string

        此结果对应的 agent.tool_use 或 agent.mcp_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        为 'deny' 决定提供上下文的可选消息。仅在 result 为 'deny' 时允许。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        设置后，确认将路由到此子代理的线程而非主线程。从触发批准的 agent.tool_use 或 agent.mcp_tool_use 事件上的 session_thread_id 回显此值。

    • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

      客户端发送的事件，提供自定义工具执行的结果。

      • id: string

        此事件的唯一标识符。

      • custom_tool_use_id: string

        此结果对应的 agent.custom_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

          • citations: BetaManagedAgentsSearchResultCitations

            搜索结果的引用设置。

            • enabled: boolean

              此搜索结果是否启用引用。

          • content: array of BetaManagedAgentsSearchResultContent

            搜索结果中的文本内容块数组。

            • text: string

              文本内容。

            • type: "text"

              • "text"

          • source: string

            搜索结果的 URL 来源。

          • title: string

            搜索结果的标题。

          • type: "search_result"

            • "search_result"

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.custom_tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      当代理调用自定义工具时发出的事件。会话进入空闲状态，直到客户端发送带有结果的 user.custom_tool_result 事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        被调用的自定义工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.custom_tool_use"

        • "agent.custom_tool_use"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其自定义工具使用。在线程自身事件上为空。在 user.custom_tool_result 事件上回显此值以将结果路由回来。

    • BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }

      会话对话中的代理响应事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock

        组成代理响应的文本块数组。

        • text: string

          文本内容。

        • type: "text"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.message"

        • "agent.message"

    • BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }

      表示代理通过扩展思考正在取得进展。这是一个进度信号，而非内容载体。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thinking"

        • "agent.thinking"

    • BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }

      当代理调用 MCP 服务器提供的工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • mcp_server_name: string

        提供工具的 MCP 服务器名称。

      • name: string

        正在使用的 MCP 工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_use"

        • "agent.mcp_tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }

      表示 MCP 工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • mcp_tool_use_id: string

        此结果对应的 agent.mcp_tool_use 事件的 ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_result"

        • "agent.mcp_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      代理调用内置代理工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        正在使用的代理工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.tool_use"

        • "agent.tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }

      表示代理工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID。

      • type: "agent.tool_result"

        • "agent.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      当代理间消息到达时写入目标线程输入流的传递事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • from_session_thread_id: string

        发送消息的线程的公共 sthr_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_message_received"

        • "agent.thread_message_received"

      • from_agent_name: optional string

        此消息来源的可调用代理名称。从主代理接收时为空。

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      发送代理间消息时发出到发送者输出流的可观察性事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • to_session_thread_id: string

        消息发送到的线程的公共 sthr_ ID。

      • type: "agent.thread_message_sent"

        • "agent.thread_message_sent"

      • to_agent_name: optional string

        此消息发送到的可调用代理名称。发送到主代理时为空。

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      表示会话期间发生了上下文压缩（摘要）。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_context_compacted"

        • "agent.thread_context_compacted"

    • BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }

      表示会话执行期间发生问题的错误事件。

      • id: string

        此事件的唯一标识符。

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more

        会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

        • BetaManagedAgentsUnknownError object { message, retry_status, type }

          会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

              • type: "retrying"

                • "retrying"

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          模型当前已过载。在自动重试耗尽后发出。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          模型请求被限流。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          模型请求因过载或限流以外的原因失败。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          连接 MCP 服务器失败。

          • mcp_server_name: string

            连接失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          MCP 服务器认证失败。

          • mcp_server_name: string

            认证失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          调用者的组织或工作区无法发出模型请求——额度不足或已达消费限额。使用相同凭据重试不会成功；调用者必须解决计费状态。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "billing_error"

            • "billing_error"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.error"

        • "session.error"

    • BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }

      表示会话正在从错误状态恢复，并已重新安排执行。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_rescheduled"

        • "session.status_rescheduled"

    • BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }

      表示会话正在积极运行，代理正在工作。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_running"

        • "session.status_running"

    • BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }

      表示代理已暂停，正在等待用户输入。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

          • event_ids: array of string

            代理被阻塞的事件 ID。解决少于全部事件时，会使用剩余事件重新发出 session.status_idle。

          • type: "requires_action"

            • "requires_action"

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

          • type: "retries_exhausted"

            • "retries_exhausted"

      • type: "session.status_idle"

        • "session.status_idle"

    • BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }

      表示会话已终止，无论是由于错误还是完成。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_terminated"

        • "session.status_terminated"

    • BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }

      当子代理作为新线程生成时发出。写入父线程的输出流，以便观察会话的客户端看到子线程创建。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的可调用代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        新创建线程的公共 sthr_ ID。

      • type: "session.thread_created"

        • "session.thread_created"

    • BetaManagedAgentsSpanOutcome评估uationStartEvent object { id, iteration, outcome_id, 2 more }

      当结果评估周期开始时发出。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期。0 是第一次评估；1 是第一次修订后的重新评估；以此类推。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_start"

        • "span.outcome_evaluation_start"

    • BetaManagedAgentsSpanOutcome评估uationEndEvent object { id, explanation, iteration, 6 more }

      当结果评估周期完成时发出。携带判定结果和聚合 token 使用量。判定为 needs_revision 意味着还有另一个评估周期；satisfied、max_iterations_reached、failed 或 interrupted 为终止状态——不会有更多评估周期。

      • id: string

        此事件的唯一标识符。

      • explanation: string

        判定结果的人类可读解释。对于 needs_revision，描述哪些标准未满足以及原因。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_evaluation_start_id: string

        对应的 span.outcome_evaluation_start 事件的 ID。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • result: string

        评估判定。 'satisfied': 标准已满足，会话进入空闲。 'needs_revision': 标准未满足，将进行另一个修订周期。 'max_iterations_reached': 评估预算耗尽但标准仍未满足 — 会话进入空闲前会有最后一个确认轮次，但不会进行更多评估。 'failed': 评分者确定评分标准不适用于交付物。 'interrupted': 用户在评估进行中发送了中断。

      • type: "span.outcome_evaluation_end"

        • "span.outcome_evaluation_end"

      • usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

        • cache_creation_input_tokens: number

          此请求中用于创建提示缓存的 token 数。

        • cache_read_input_tokens: number

          此请求中从提示缓存读取的 token 数。

        • input_tokens: number

          此请求消耗的输入 token 数。

        • output_tokens: number

          此请求生成的输出 token 数。

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      当代理发起模型请求时发出。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_start"

        • "span.model_request_start"

    • BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }

      当模型请求完成时发出。

      • id: string

        此事件的唯一标识符。

      • is_error: boolean

        模型请求是否导致错误。

      • model_request_start_id: string

        对应的 span.model_request_start 事件的 ID。

      • model_usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_end"

        • "span.model_request_end"

    • BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }

      在结果评估周期进行期间发出的定期心跳。在对应的 span.outcome_evaluation_start 和 span.outcome_evaluation_end 事件之间区分"评估正在积极运行"和"评估卡住"。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_ongoing"

        • "span.outcome_evaluation_ongoing"

    • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

      user.define_outcome 输入事件的回显。携带服务器生成的 outcome_id，后续的 span.outcome_evaluation_* 事件引用该 ID。

      • id: string

        此事件的唯一标识符。

      • description: string

        代理应产出的内容。 从输入事件复制。

      • max_iterations: number

        放弃前的评估-修订周期。默认 3，最大 20。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。被 span.outcome_evaluation_* 事件和会话的 outcome_evaluations 列表引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

        用于评估结果质量的评分标准。

        • BetaManagedAgentsFileRubric object { file_id, type }

          通过 Files API 上传的文件引用的评分标准。

          • file_id: string

            评分标准文件的 ID。

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          以文本形式内联提供的评分标准内容。

          • content: string

            评分标准内容。纯文本或 markdown——评分者将其视为自由格式文本。

          • type: "text"

            • "text"

      • type: "user.define_outcome"

        • "user.define_outcome"

    • BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }

      当会话被删除时发出。终止所有活动的事件流 — 不会再为此会话发出更多事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.deleted"

        • "session.deleted"

    • BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }

      会话线程已开始执行。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        开始运行的线程的公共 sthr_ ID。

      • type: "session.thread_status_running"

        • "session.thread_status_running"

    • BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }

      会话线程已让出并正在等待输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        进入空闲状态的线程的公共 sthr_ ID。

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

      • type: "session.thread_status_idle"

        • "session.thread_status_idle"

    • BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }

      会话线程已终止，不再接受输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        已终止线程的公共 sthr_ ID。

      • type: "session.thread_status_terminated"

        • "session.thread_status_terminated"

    • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

      客户端发送的事件，提供代理工具集工具执行的结果。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

      • id: string

        此事件的唯一标识符。

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      会话线程遇到瞬态错误，正在自动重试。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        正在重试的线程的公共 sthr_ ID。

      • type: "session.thread_status_rescheduled"

        • "session.thread_status_rescheduled"

    • BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 3 more }

      当 UpdateSession 请求更改了至少一个字段时发出。仅携带已更改的字段；未出现的字段不是更新的一部分。新配置从下一轮开始生效。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.updated"

        • "session.updated"

      • agent: optional BetaManagedAgentsSessionAgent

        为 session 解析的 agent 定义。session 创建时 agent 的快照。

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          模型标识符和配置。

          • id: BetaManagedAgentsModel

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              驱动代理的模型。

              详情和选项请参阅 models。

              • "claude-opus-4-7"

                适用于长时间运行代理和编码的前沿智能

              • "claude-opus-4-6"

                用于构建代理和编码的最智能模型

              • "claude-sonnet-4-6"

                速度与智能的最佳组合

              • "claude-haiku-4-5"

                具有接近前沿智能的最快模型

              • "claude-haiku-4-5-20251001"

                具有接近前沿智能的最快模型

              • "claude-opus-4-5"

                结合最大智能与实用性能的高端模型

              • "claude-opus-4-5-20251101"

                结合最大智能与实用性能的高端模型

              • "claude-sonnet-4-5"

                用于代理和编码的高性能模型

              • "claude-sonnet-4-5-20250929"

                用于代理和编码的高性能模型

            • string

          • speed: optional "standard" or "fast"

            推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

            • "standard"

            • "fast"

        • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

          解析的协调器拓扑，包含每个成员的完整 agent 定义。

          • agents: array of BetaManagedAgentsSessionThreadAgent

            协调器可能作为会话线程生成的完整 agent 定义。

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              模型标识符和配置。

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                已解析的 Anthropic 托管技能。

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                已解析的用户创建的自定义技能。

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    内置代理工具标识符。

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                      • type: "always_ask"

                        • "always_ask"

                • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                  代理工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                  MCP 服务器所有工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                API 响应中返回的自定义工具。

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  自定义工具输入参数的 JSON Schema。

                  • properties: optional map[unknown]

                    定义工具输入参数的 JSON Schema 属性。

                  • required: optional array of string

                    必需属性名称列表。

                  • type: optional "object"

                    工具输入 schema 必须为 'object'。

                    • "object"

                • name: string

                • type: "custom"

                  • "custom"

            • type: "agent"

              • "agent"

            • version: number

          • type: "coordinator"

            • "coordinator"

        • name: string

        • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            已解析的 Anthropic 托管技能。

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            已解析的用户创建的自定义技能。

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            API 响应中返回的自定义工具。

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        更新后会话的完整元数据包。当更新设置了非空元数据时存在；当元数据未更改或清空时不存在。

      • title: optional string

        会话的新标题。仅在更新更改了标题时存在。

  • next_page: optional string

    下一页的不透明游标。没有更多结果时为 null。

示例

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"

响应

{
  "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="
}

发送事件

post /v1/sessions/{session_id}/events

发送事件

路径参数

  • session_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

请求体参数

  • events: array of BetaManagedAgentsEventParams

    要发送到 session 的事件。

    • BetaManagedAgentsUserMessageEventParams object { content, type }

      向会话发送用户消息的参数。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        用户消息的内容块数组。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            图片源变体的联合类型。

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              Base64 编码的图片数据。

              • data: string

                Base64 编码的图片数据。

              • media_type: string

                图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsURLImageSource object { type, url }

              通过 URL 引用的图片。

              • type: "url"

                • "url"

              • url: string

                要获取的图片 URL。

            • BetaManagedAgentsFileImageSource object { file_id, type }

              通过文件 ID 引用的图片。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            文档源变体的联合类型。

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              Base64 编码的文档数据。

              • data: string

                Base64 编码的文档数据。

              • media_type: string

                文档的 MIME 类型（例如 "application/pdf"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

              纯文本文档内容。

              • data: string

                纯文本内容。

              • media_type: "text/plain"

                文本内容的 MIME 类型。必须为 "text/plain"。

                • "text/plain"

              • type: "text"

                • "text"

            • BetaManagedAgentsURLDocumentSource object { type, url }

              通过 URL 引用的文档。

              • type: "url"

                • "url"

              • url: string

                要获取的文档 URL。

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              通过文件 ID 引用的文档。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            为模型提供的关于文档的额外上下文。

          • title: optional string

            文档的标题。

      • type: "user.message"

        • "user.message"

    • BetaManagedAgentsUserInterruptEventParams object { type, session_thread_id }

      发送中断以暂停代理的参数。

      • type: "user.interrupt"

        • "user.interrupt"

      • session_thread_id: optional string

        如果省略，中断多代理会话中的每个未归档线程（或单代理会话中的主线程）。如果指定，仅中断指定的线程。

    • BetaManagedAgentsUserToolConfirmationEventParams object { result, tool_use_id, type, deny_message }

      确认或拒绝工具执行请求的参数。

      • result: "allow" or "deny"

        UserToolConfirmationResult 枚举

        • "allow"

        • "deny"

      • tool_use_id: string

        此结果对应的 agent.tool_use 或 agent.mcp_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        为 'deny' 决定提供上下文的可选消息。仅在 result 为 'deny' 时允许。

    • BetaManagedAgentsUserCustomToolResultEventParams object { custom_tool_use_id, type, content, is_error }

      提供自定义工具执行结果的参数。

      • custom_tool_use_id: string

        此结果对应的 agent.custom_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

          • citations: BetaManagedAgentsSearchResultCitations

            搜索结果的引用设置。

            • enabled: boolean

              此搜索结果是否启用引用。

          • content: array of BetaManagedAgentsSearchResultContent

            搜索结果中的文本内容块数组。

            • text: string

              文本内容。

            • type: "text"

              • "text"

          • source: string

            搜索结果的 URL 来源。

          • title: string

            搜索结果的标题。

          • type: "search_result"

            • "search_result"

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }

      定义代理应努力达成的结果的参数。代理在收到后开始工作。

      • description: string

        代理应产出的内容。这是任务规范。

      • rubric: BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams

        用于评估结果质量的评分标准。

        • BetaManagedAgentsFileRubricParams object { file_id, type }

          通过 Files API 上传的文件引用的评分标准。

          • file_id: string

            评分标准文件的 ID。

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubricParams object { content, type }

          以文本形式内联提供的评分标准内容。

          • content: string

            评分标准内容。纯文本或 markdown——评分者将其视为自由格式文本。 最多 262144 个字符。

          • type: "text"

            • "text"

      • type: "user.define_outcome"

        • "user.define_outcome"

      • max_iterations: optional number

        评估→-修订周期，直到放弃。默认 3，最大 20。

    • BetaManagedAgentsUserToolResultEventParams object { tool_use_id, type, content, is_error }

      提供代理工具集工具执行结果的参数。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

返回值

  • BetaManagedAgentsSendSessionEvents object { data }

    已成功发送到会话的事件。

    • data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 3 more

      Sent events

      • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

        会话对话中的用户消息事件。

        • id: string

          此事件的唯一标识符。

        • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

          组成用户消息的内容块数组。

          • BetaManagedAgentsTextBlock object { text, type }

            常规文本内容。

            • text: string

              文本内容。

            • type: "text"

              • "text"

          • BetaManagedAgentsImageBlock object { source, type }

            直接指定为 base64 数据或通过 URL 引用的图片内容。

            • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

              图片源变体的联合类型。

              • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

                Base64 编码的图片数据。

                • data: string

                  Base64 编码的图片数据。

                • media_type: string

                  图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

                • type: "base64"

                  • "base64"

              • BetaManagedAgentsURLImageSource object { type, url }

                通过 URL 引用的图片。

                • type: "url"

                  • "url"

                • url: string

                  要获取的图片 URL。

              • BetaManagedAgentsFileImageSource object { file_id, type }

                通过文件 ID 引用的图片。

                • file_id: string

                  先前上传文件的 ID。

                • type: "file"

                  • "file"

            • type: "image"

              • "image"

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

            • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

              文档源变体的联合类型。

              • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

                Base64 编码的文档数据。

                • data: string

                  Base64 编码的文档数据。

                • media_type: string

                  文档的 MIME 类型（例如 "application/pdf"）。

                • type: "base64"

                  • "base64"

              • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

                纯文本文档内容。

                • data: string

                  纯文本内容。

                • media_type: "text/plain"

                  文本内容的 MIME 类型。必须为 "text/plain"。

                  • "text/plain"

                • type: "text"

                  • "text"

              • BetaManagedAgentsURLDocumentSource object { type, url }

                通过 URL 引用的文档。

                • type: "url"

                  • "url"

                • url: string

                  要获取的文档 URL。

              • BetaManagedAgentsFileDocumentSource object { file_id, type }

                通过文件 ID 引用的文档。

                • file_id: string

                  先前上传文件的 ID。

                • type: "file"

                  • "file"

            • type: "document"

              • "document"

            • context: optional string

              为模型提供的关于文档的额外上下文。

            • title: optional string

              文档的标题。

        • type: "user.message"

          • "user.message"

        • processed_at: optional string

          RFC 3339 格式的时间戳

      • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

        暂停代理执行并将控制权返回给用户的中断事件。

        • id: string

          此事件的唯一标识符。

        • type: "user.interrupt"

          • "user.interrupt"

        • processed_at: optional string

          RFC 3339 格式的时间戳

        • session_thread_id: optional string

          如果省略，中断多代理会话中的每个未归档线程（或单代理会话中的主线程）。如果指定，仅中断指定的线程。

      • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

        批准或拒绝待处理工具执行的工具确认事件。

        • id: string

          此事件的唯一标识符。

        • result: "allow" or "deny"

          UserToolConfirmationResult 枚举

          • "allow"

          • "deny"

        • tool_use_id: string

          此结果对应的 agent.tool_use 或 agent.mcp_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

        • type: "user.tool_confirmation"

          • "user.tool_confirmation"

        • deny_message: optional string

          为 'deny' 决定提供上下文的可选消息。仅在 result 为 'deny' 时允许。

        • processed_at: optional string

          RFC 3339 格式的时间戳

        • session_thread_id: optional string

          设置后，确认将路由到此子代理的线程而非主线程。从触发批准的 agent.tool_use 或 agent.mcp_tool_use 事件上的 session_thread_id 回显此值。

      • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

        客户端发送的事件，提供自定义工具执行的结果。

        • id: string

          此事件的唯一标识符。

        • custom_tool_use_id: string

          此结果对应的 agent.custom_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

        • type: "user.custom_tool_result"

          • "user.custom_tool_result"

        • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

          工具返回的结果内容。

          • BetaManagedAgentsTextBlock object { text, type }

            常规文本内容。

          • BetaManagedAgentsImageBlock object { source, type }

            直接指定为 base64 数据或通过 URL 引用的图片内容。

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

            包含网络搜索结果的块。

            • citations: BetaManagedAgentsSearchResultCitations

              搜索结果的引用设置。

              • enabled: boolean

                此搜索结果是否启用引用。

            • content: array of BetaManagedAgentsSearchResultContent

              搜索结果中的文本内容块数组。

              • text: string

                文本内容。

              • type: "text"

                • "text"

            • source: string

              搜索结果的 URL 来源。

            • title: string

              搜索结果的标题。

            • type: "search_result"

              • "search_result"

        • is_error: optional boolean

          工具执行是否导致错误。

        • processed_at: optional string

          RFC 3339 格式的时间戳

        • session_thread_id: optional string

          将此结果路由到子代理线程。从 agent.custom_tool_use 事件的 session_thread_id 复制。

      • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

        user.define_outcome 输入事件的回显。携带服务器生成的 outcome_id，后续的 span.outcome_evaluation_* 事件引用该 ID。

        • id: string

          此事件的唯一标识符。

        • description: string

          代理应产出的内容。 从输入事件复制。

        • max_iterations: number

          放弃前的评估-修订周期。默认 3，最大 20。

        • outcome_id: string

          服务器为此结果生成的 outc_ ID。被 span.outcome_evaluation_* 事件和会话的 outcome_evaluations 列表引用。

        • processed_at: string

          RFC 3339 格式的时间戳

        • rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

          用于评估结果质量的评分标准。

          • BetaManagedAgentsFileRubric object { file_id, type }

            通过 Files API 上传的文件引用的评分标准。

            • file_id: string

              评分标准文件的 ID。

            • type: "file"

              • "file"

          • BetaManagedAgentsTextRubric object { content, type }

            以文本形式内联提供的评分标准内容。

            • content: string

              评分标准内容。纯文本或 markdown——评分者将其视为自由格式文本。

            • type: "text"

              • "text"

        • type: "user.define_outcome"

          • "user.define_outcome"

      • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

        客户端发送的事件，提供代理工具集工具执行的结果。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

        • id: string

          此事件的唯一标识符。

        • tool_use_id: string

          此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

        • type: "user.tool_result"

          • "user.tool_result"

        • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

          工具返回的结果内容。

          • BetaManagedAgentsTextBlock object { text, type }

            常规文本内容。

          • BetaManagedAgentsImageBlock object { source, type }

            直接指定为 base64 数据或通过 URL 引用的图片内容。

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

            包含网络搜索结果的块。

        • is_error: optional boolean

          工具执行是否导致错误。

        • processed_at: optional string

          RFC 3339 格式的时间戳

        • session_thread_id: optional string

          将此结果路由到子代理线程。从 agent.tool_use 事件的 session_thread_id 复制。

示例

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"
            }
          ]
        }'

响应

{
  "data": [
    {
      "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message",
      "processed_at": "2026-03-15T10:00:00Z"
    }
  ]
}

流式事件

get /v1/sessions/{session_id}/events/stream

流式事件

路径参数

  • session_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 30 more

    会话流中的服务器发送事件。

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      会话对话中的用户消息事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        组成用户消息的内容块数组。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            图片源变体的联合类型。

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              Base64 编码的图片数据。

              • data: string

                Base64 编码的图片数据。

              • media_type: string

                图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsURLImageSource object { type, url }

              通过 URL 引用的图片。

              • type: "url"

                • "url"

              • url: string

                要获取的图片 URL。

            • BetaManagedAgentsFileImageSource object { file_id, type }

              通过文件 ID 引用的图片。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            文档源变体的联合类型。

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              Base64 编码的文档数据。

              • data: string

                Base64 编码的文档数据。

              • media_type: string

                文档的 MIME 类型（例如 "application/pdf"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

              纯文本文档内容。

              • data: string

                纯文本内容。

              • media_type: "text/plain"

                文本内容的 MIME 类型。必须为 "text/plain"。

                • "text/plain"

              • type: "text"

                • "text"

            • BetaManagedAgentsURLDocumentSource object { type, url }

              通过 URL 引用的文档。

              • type: "url"

                • "url"

              • url: string

                要获取的文档 URL。

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              通过文件 ID 引用的文档。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            为模型提供的关于文档的额外上下文。

          • title: optional string

            文档的标题。

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        RFC 3339 格式的时间戳

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      暂停代理执行并将控制权返回给用户的中断事件。

      • id: string

        此事件的唯一标识符。

      • type: "user.interrupt"

        • "user.interrupt"

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        如果省略，中断多代理会话中的每个未归档线程（或单代理会话中的主线程）。如果指定，仅中断指定的线程。

    • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

      批准或拒绝待处理工具执行的工具确认事件。

      • id: string

        此事件的唯一标识符。

      • result: "allow" or "deny"

        UserToolConfirmationResult 枚举

        • "allow"

        • "deny"

      • tool_use_id: string

        此结果对应的 agent.tool_use 或 agent.mcp_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        为 'deny' 决定提供上下文的可选消息。仅在 result 为 'deny' 时允许。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        设置后，确认将路由到此子代理的线程而非主线程。从触发批准的 agent.tool_use 或 agent.mcp_tool_use 事件上的 session_thread_id 回显此值。

    • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

      客户端发送的事件，提供自定义工具执行的结果。

      • id: string

        此事件的唯一标识符。

      • custom_tool_use_id: string

        此结果对应的 agent.custom_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

          • citations: BetaManagedAgentsSearchResultCitations

            搜索结果的引用设置。

            • enabled: boolean

              此搜索结果是否启用引用。

          • content: array of BetaManagedAgentsSearchResultContent

            搜索结果中的文本内容块数组。

            • text: string

              文本内容。

            • type: "text"

              • "text"

          • source: string

            搜索结果的 URL 来源。

          • title: string

            搜索结果的标题。

          • type: "search_result"

            • "search_result"

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.custom_tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      当代理调用自定义工具时发出的事件。会话进入空闲状态，直到客户端发送带有结果的 user.custom_tool_result 事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        被调用的自定义工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.custom_tool_use"

        • "agent.custom_tool_use"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其自定义工具使用。在线程自身事件上为空。在 user.custom_tool_result 事件上回显此值以将结果路由回来。

    • BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }

      会话对话中的代理响应事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock

        组成代理响应的文本块数组。

        • text: string

          文本内容。

        • type: "text"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.message"

        • "agent.message"

    • BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }

      表示代理通过扩展思考正在取得进展。这是一个进度信号，而非内容载体。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thinking"

        • "agent.thinking"

    • BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }

      当代理调用 MCP 服务器提供的工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • mcp_server_name: string

        提供工具的 MCP 服务器名称。

      • name: string

        正在使用的 MCP 工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_use"

        • "agent.mcp_tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }

      表示 MCP 工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • mcp_tool_use_id: string

        此结果对应的 agent.mcp_tool_use 事件的 ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_result"

        • "agent.mcp_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      代理调用内置代理工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        正在使用的代理工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.tool_use"

        • "agent.tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }

      表示代理工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID。

      • type: "agent.tool_result"

        • "agent.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      当代理间消息到达时写入目标线程输入流的传递事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • from_session_thread_id: string

        发送消息的线程的公共 sthr_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_message_received"

        • "agent.thread_message_received"

      • from_agent_name: optional string

        此消息来源的可调用代理名称。从主代理接收时为空。

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      发送代理间消息时发出到发送者输出流的可观察性事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • to_session_thread_id: string

        消息发送到的线程的公共 sthr_ ID。

      • type: "agent.thread_message_sent"

        • "agent.thread_message_sent"

      • to_agent_name: optional string

        此消息发送到的可调用代理名称。发送到主代理时为空。

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      表示会话期间发生了上下文压缩（摘要）。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_context_compacted"

        • "agent.thread_context_compacted"

    • BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }

      表示会话执行期间发生问题的错误事件。

      • id: string

        此事件的唯一标识符。

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more

        会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

        • BetaManagedAgentsUnknownError object { message, retry_status, type }

          会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

              • type: "retrying"

                • "retrying"

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          模型当前已过载。在自动重试耗尽后发出。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          模型请求被限流。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          模型请求因过载或限流以外的原因失败。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          连接 MCP 服务器失败。

          • mcp_server_name: string

            连接失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          MCP 服务器认证失败。

          • mcp_server_name: string

            认证失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          调用者的组织或工作区无法发出模型请求——额度不足或已达消费限额。使用相同凭据重试不会成功；调用者必须解决计费状态。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "billing_error"

            • "billing_error"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.error"

        • "session.error"

    • BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }

      表示会话正在从错误状态恢复，并已重新安排执行。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_rescheduled"

        • "session.status_rescheduled"

    • BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }

      表示会话正在积极运行，代理正在工作。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_running"

        • "session.status_running"

    • BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }

      表示代理已暂停，正在等待用户输入。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

          • event_ids: array of string

            代理被阻塞的事件 ID。解决少于全部事件时，会使用剩余事件重新发出 session.status_idle。

          • type: "requires_action"

            • "requires_action"

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

          • type: "retries_exhausted"

            • "retries_exhausted"

      • type: "session.status_idle"

        • "session.status_idle"

    • BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }

      表示会话已终止，无论是由于错误还是完成。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_terminated"

        • "session.status_terminated"

    • BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }

      当子代理作为新线程生成时发出。写入父线程的输出流，以便观察会话的客户端看到子线程创建。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的可调用代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        新创建线程的公共 sthr_ ID。

      • type: "session.thread_created"

        • "session.thread_created"

    • BetaManagedAgentsSpanOutcome评估uationStartEvent object { id, iteration, outcome_id, 2 more }

      当结果评估周期开始时发出。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期。0 是第一次评估；1 是第一次修订后的重新评估；以此类推。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_start"

        • "span.outcome_evaluation_start"

    • BetaManagedAgentsSpanOutcome评估uationEndEvent object { id, explanation, iteration, 6 more }

      当结果评估周期完成时发出。携带判定结果和聚合 token 使用量。判定为 needs_revision 意味着还有另一个评估周期；satisfied、max_iterations_reached、failed 或 interrupted 为终止状态——不会有更多评估周期。

      • id: string

        此事件的唯一标识符。

      • explanation: string

        判定结果的人类可读解释。对于 needs_revision，描述哪些标准未满足以及原因。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_evaluation_start_id: string

        对应的 span.outcome_evaluation_start 事件的 ID。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • result: string

        评估判定。 'satisfied': 标准已满足，会话进入空闲。 'needs_revision': 标准未满足，将进行另一个修订周期。 'max_iterations_reached': 评估预算耗尽但标准仍未满足 — 会话进入空闲前会有最后一个确认轮次，但不会进行更多评估。 'failed': 评分者确定评分标准不适用于交付物。 'interrupted': 用户在评估进行中发送了中断。

      • type: "span.outcome_evaluation_end"

        • "span.outcome_evaluation_end"

      • usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

        • cache_creation_input_tokens: number

          此请求中用于创建提示缓存的 token 数。

        • cache_read_input_tokens: number

          此请求中从提示缓存读取的 token 数。

        • input_tokens: number

          此请求消耗的输入 token 数。

        • output_tokens: number

          此请求生成的输出 token 数。

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      当代理发起模型请求时发出。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_start"

        • "span.model_request_start"

    • BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }

      当模型请求完成时发出。

      • id: string

        此事件的唯一标识符。

      • is_error: boolean

        模型请求是否导致错误。

      • model_request_start_id: string

        对应的 span.model_request_start 事件的 ID。

      • model_usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_end"

        • "span.model_request_end"

    • BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }

      在结果评估周期进行期间发出的定期心跳。在对应的 span.outcome_evaluation_start 和 span.outcome_evaluation_end 事件之间区分"评估正在积极运行"和"评估卡住"。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_ongoing"

        • "span.outcome_evaluation_ongoing"

    • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

      user.define_outcome 输入事件的回显。携带服务器生成的 outcome_id，后续的 span.outcome_evaluation_* 事件引用该 ID。

      • id: string

        此事件的唯一标识符。

      • description: string

        代理应产出的内容。 从输入事件复制。

      • max_iterations: number

        放弃前的评估-修订周期。默认 3，最大 20。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。被 span.outcome_evaluation_* 事件和会话的 outcome_evaluations 列表引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

        用于评估结果质量的评分标准。

        • BetaManagedAgentsFileRubric object { file_id, type }

          通过 Files API 上传的文件引用的评分标准。

          • file_id: string

            评分标准文件的 ID。

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          以文本形式内联提供的评分标准内容。

          • content: string

            评分标准内容。纯文本或 markdown——评分者将其视为自由格式文本。

          • type: "text"

            • "text"

      • type: "user.define_outcome"

        • "user.define_outcome"

    • BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }

      当会话被删除时发出。终止所有活动的事件流 — 不会再为此会话发出更多事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.deleted"

        • "session.deleted"

    • BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }

      会话线程已开始执行。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        开始运行的线程的公共 sthr_ ID。

      • type: "session.thread_status_running"

        • "session.thread_status_running"

    • BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }

      会话线程已让出并正在等待输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        进入空闲状态的线程的公共 sthr_ ID。

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

      • type: "session.thread_status_idle"

        • "session.thread_status_idle"

    • BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }

      会话线程已终止，不再接受输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        已终止线程的公共 sthr_ ID。

      • type: "session.thread_status_terminated"

        • "session.thread_status_terminated"

    • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

      客户端发送的事件，提供代理工具集工具执行的结果。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

      • id: string

        此事件的唯一标识符。

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      会话线程遇到瞬态错误，正在自动重试。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        正在重试的线程的公共 sthr_ ID。

      • type: "session.thread_status_rescheduled"

        • "session.thread_status_rescheduled"

    • BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 3 more }

      当 UpdateSession 请求更改了至少一个字段时发出。仅携带已更改的字段；未出现的字段不是更新的一部分。新配置从下一轮开始生效。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.updated"

        • "session.updated"

      • agent: optional BetaManagedAgentsSessionAgent

        为 session 解析的 agent 定义。session 创建时 agent 的快照。

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          模型标识符和配置。

          • id: BetaManagedAgentsModel

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              驱动代理的模型。

              详情和选项请参阅 models。

              • "claude-opus-4-7"

                适用于长时间运行代理和编码的前沿智能

              • "claude-opus-4-6"

                用于构建代理和编码的最智能模型

              • "claude-sonnet-4-6"

                速度与智能的最佳组合

              • "claude-haiku-4-5"

                具有接近前沿智能的最快模型

              • "claude-haiku-4-5-20251001"

                具有接近前沿智能的最快模型

              • "claude-opus-4-5"

                结合最大智能与实用性能的高端模型

              • "claude-opus-4-5-20251101"

                结合最大智能与实用性能的高端模型

              • "claude-sonnet-4-5"

                用于代理和编码的高性能模型

              • "claude-sonnet-4-5-20250929"

                用于代理和编码的高性能模型

            • string

          • speed: optional "standard" or "fast"

            推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

            • "standard"

            • "fast"

        • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

          解析的协调器拓扑，包含每个成员的完整 agent 定义。

          • agents: array of BetaManagedAgentsSessionThreadAgent

            协调器可能作为会话线程生成的完整 agent 定义。

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              模型标识符和配置。

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                已解析的 Anthropic 托管技能。

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                已解析的用户创建的自定义技能。

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    内置代理工具标识符。

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                      • type: "always_ask"

                        • "always_ask"

                • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                  代理工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                  MCP 服务器所有工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                API 响应中返回的自定义工具。

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  自定义工具输入参数的 JSON Schema。

                  • properties: optional map[unknown]

                    定义工具输入参数的 JSON Schema 属性。

                  • required: optional array of string

                    必需属性名称列表。

                  • type: optional "object"

                    工具输入 schema 必须为 'object'。

                    • "object"

                • name: string

                • type: "custom"

                  • "custom"

            • type: "agent"

              • "agent"

            • version: number

          • type: "coordinator"

            • "coordinator"

        • name: string

        • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            已解析的 Anthropic 托管技能。

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            已解析的用户创建的自定义技能。

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            API 响应中返回的自定义工具。

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        更新后会话的完整元数据包。当更新设置了非空元数据时存在；当元数据未更改或清空时不存在。

      • title: optional string

        会话的新标题。仅在更新更改了标题时存在。

示例

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"

响应

{
  "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
  "content": [
    {
      "text": "Where is my order #1234?",
      "type": "text"
    }
  ],
  "type": "user.message",
  "processed_at": "2026-03-15T10:00:00Z"
}

领域类型

Beta Managed Agents Agent Custom Tool Use Event

  • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

    当代理调用自定义工具时发出的事件。会话进入空闲状态，直到客户端发送带有结果的 user.custom_tool_result 事件。

    • id: string

      此事件的唯一标识符。

    • input: map[unknown]

      工具调用的输入参数。

    • name: string

      被调用的自定义工具名称。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "agent.custom_tool_use"

      • "agent.custom_tool_use"

    • session_thread_id: optional string

      设置后，此事件从子代理线程交叉发布到主线程流以显示其自定义工具使用。在线程自身事件上为空。在 user.custom_tool_result 事件上回显此值以将结果路由回来。

Beta Managed Agents Agent MCP Tool Result Event

  • BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }

    表示 MCP 工具执行结果的事件。

    • id: string

      此事件的唯一标识符。

    • mcp_tool_use_id: string

      此结果对应的 agent.mcp_tool_use 事件的 ID。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "agent.mcp_tool_result"

      • "agent.mcp_tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      工具返回的结果内容。

      • BetaManagedAgentsTextBlock object { text, type }

        常规文本内容。

        • text: string

          文本内容。

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        直接指定为 base64 数据或通过 URL 引用的图片内容。

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          图片源变体的联合类型。

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            Base64 编码的图片数据。

            • data: string

              Base64 编码的图片数据。

            • media_type: string

              图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsURLImageSource object { type, url }

            通过 URL 引用的图片。

            • type: "url"

              • "url"

            • url: string

              要获取的图片 URL。

          • BetaManagedAgentsFileImageSource object { file_id, type }

            通过文件 ID 引用的图片。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          文档源变体的联合类型。

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            Base64 编码的文档数据。

            • data: string

              Base64 编码的文档数据。

            • media_type: string

              文档的 MIME 类型（例如 "application/pdf"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

            纯文本文档内容。

            • data: string

              纯文本内容。

            • media_type: "text/plain"

              文本内容的 MIME 类型。必须为 "text/plain"。

              • "text/plain"

            • type: "text"

              • "text"

          • BetaManagedAgentsURLDocumentSource object { type, url }

            通过 URL 引用的文档。

            • type: "url"

              • "url"

            • url: string

              要获取的文档 URL。

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            通过文件 ID 引用的文档。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          为模型提供的关于文档的额外上下文。

        • title: optional string

          文档的标题。

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        包含网络搜索结果的块。

        • citations: BetaManagedAgentsSearchResultCitations

          搜索结果的引用设置。

          • enabled: boolean

            此搜索结果是否启用引用。

        • content: array of BetaManagedAgentsSearchResultContent

          搜索结果中的文本内容块数组。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • source: string

          搜索结果的 URL 来源。

        • title: string

          搜索结果的标题。

        • type: "search_result"

          • "search_result"

    • is_error: optional boolean

      工具执行是否导致错误。

Beta Managed Agents Agent MCP Tool Use Event

  • BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }

    当代理调用 MCP 服务器提供的工具时发出的事件。

    • id: string

      此事件的唯一标识符。

    • input: map[unknown]

      工具调用的输入参数。

    • mcp_server_name: string

      提供工具的 MCP 服务器名称。

    • name: string

      正在使用的 MCP 工具名称。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "agent.mcp_tool_use"

      • "agent.mcp_tool_use"

    • evaluated_permission: optional "allow" or "ask" or "deny"

      Agent评估uatedPermission 枚举

      • "allow"

      • "ask"

      • "deny"

    • session_thread_id: optional string

      设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

Beta Managed Agents Agent Message Event

  • BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }

    会话对话中的代理响应事件。

    • id: string

      此事件的唯一标识符。

    • content: array of BetaManagedAgentsTextBlock

      组成代理响应的文本块数组。

      • text: string

        文本内容。

      • type: "text"

        • "text"

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "agent.message"

      • "agent.message"

Beta Managed Agents Agent Thinking Event

  • BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }

    表示代理通过扩展思考正在取得进展。这是一个进度信号，而非内容载体。

    • id: string

      此事件的唯一标识符。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "agent.thinking"

      • "agent.thinking"

Beta Managed Agents Agent Thread Context Compacted Event

  • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

    表示会话期间发生了上下文压缩（摘要）。

    • id: string

      此事件的唯一标识符。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "agent.thread_context_compacted"

      • "agent.thread_context_compacted"

Beta Managed Agents Agent Thread Message Received Event

  • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

    当代理间消息到达时写入目标线程输入流的传递事件。

    • id: string

      此事件的唯一标识符。

    • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

      消息内容块。

      • BetaManagedAgentsTextBlock object { text, type }

        常规文本内容。

        • text: string

          文本内容。

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        直接指定为 base64 数据或通过 URL 引用的图片内容。

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          图片源变体的联合类型。

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            Base64 编码的图片数据。

            • data: string

              Base64 编码的图片数据。

            • media_type: string

              图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsURLImageSource object { type, url }

            通过 URL 引用的图片。

            • type: "url"

              • "url"

            • url: string

              要获取的图片 URL。

          • BetaManagedAgentsFileImageSource object { file_id, type }

            通过文件 ID 引用的图片。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          文档源变体的联合类型。

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            Base64 编码的文档数据。

            • data: string

              Base64 编码的文档数据。

            • media_type: string

              文档的 MIME 类型（例如 "application/pdf"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

            纯文本文档内容。

            • data: string

              纯文本内容。

            • media_type: "text/plain"

              文本内容的 MIME 类型。必须为 "text/plain"。

              • "text/plain"

            • type: "text"

              • "text"

          • BetaManagedAgentsURLDocumentSource object { type, url }

            通过 URL 引用的文档。

            • type: "url"

              • "url"

            • url: string

              要获取的文档 URL。

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            通过文件 ID 引用的文档。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          为模型提供的关于文档的额外上下文。

        • title: optional string

          文档的标题。

    • from_session_thread_id: string

      发送消息的线程的公共 sthr_ ID。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "agent.thread_message_received"

      • "agent.thread_message_received"

    • from_agent_name: optional string

      此消息来源的可调用代理名称。从主代理接收时不存在。

Beta Managed Agents Agent Thread Message Sent Event

  • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

    当代理间消息发送时，发出到发送者输出流的可观察性事件。

    • id: string

      此事件的唯一标识符。

    • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

      消息内容块。

      • BetaManagedAgentsTextBlock object { text, type }

        常规文本内容。

        • text: string

          文本内容。

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        直接指定为 base64 数据或通过 URL 引用的图片内容。

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          图片源变体的联合类型。

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            Base64 编码的图片数据。

            • data: string

              Base64 编码的图片数据。

            • media_type: string

              图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsURLImageSource object { type, url }

            通过 URL 引用的图片。

            • type: "url"

              • "url"

            • url: string

              要获取的图片 URL。

          • BetaManagedAgentsFileImageSource object { file_id, type }

            通过文件 ID 引用的图片。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          文档源变体的联合类型。

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            Base64 编码的文档数据。

            • data: string

              Base64 编码的文档数据。

            • media_type: string

              文档的 MIME 类型（例如 "application/pdf"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

            纯文本文档内容。

            • data: string

              纯文本内容。

            • media_type: "text/plain"

              文本内容的 MIME 类型。必须为 "text/plain"。

              • "text/plain"

            • type: "text"

              • "text"

          • BetaManagedAgentsURLDocumentSource object { type, url }

            通过 URL 引用的文档。

            • type: "url"

              • "url"

            • url: string

              要获取的文档 URL。

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            通过文件 ID 引用的文档。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          为模型提供的关于文档的额外上下文。

        • title: optional string

          文档的标题。

    • processed_at: string

      RFC 3339 格式的时间戳

    • to_session_thread_id: string

      消息发送目标线程的公共 sthr_ ID。

    • type: "agent.thread_message_sent"

      • "agent.thread_message_sent"

    • to_agent_name: optional string

      消息发送目标的可调用代理名称。发送到主代理时不存在。

Beta Managed Agents Agent Tool Result Event

  • BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }

    表示代理工具执行结果的事件。

    • id: string

      此事件的唯一标识符。

    • processed_at: string

      RFC 3339 格式的时间戳

    • tool_use_id: string

      此结果对应的 agent.tool_use 事件的 ID。

    • type: "agent.tool_result"

      • "agent.tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      工具返回的结果内容。

      • BetaManagedAgentsTextBlock object { text, type }

        常规文本内容。

        • text: string

          文本内容。

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        直接指定为 base64 数据或通过 URL 引用的图片内容。

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          图片源变体的联合类型。

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            Base64 编码的图片数据。

            • data: string

              Base64 编码的图片数据。

            • media_type: string

              图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsURLImageSource object { type, url }

            通过 URL 引用的图片。

            • type: "url"

              • "url"

            • url: string

              要获取的图片 URL。

          • BetaManagedAgentsFileImageSource object { file_id, type }

            通过文件 ID 引用的图片。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          文档源变体的联合类型。

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            Base64 编码的文档数据。

            • data: string

              Base64 编码的文档数据。

            • media_type: string

              文档的 MIME 类型（例如 "application/pdf"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

            纯文本文档内容。

            • data: string

              纯文本内容。

            • media_type: "text/plain"

              文本内容的 MIME 类型。必须为 "text/plain"。

              • "text/plain"

            • type: "text"

              • "text"

          • BetaManagedAgentsURLDocumentSource object { type, url }

            通过 URL 引用的文档。

            • type: "url"

              • "url"

            • url: string

              要获取的文档 URL。

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            通过文件 ID 引用的文档。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          为模型提供的关于文档的额外上下文。

        • title: optional string

          文档的标题。

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        包含网络搜索结果的块。

        • citations: BetaManagedAgentsSearchResultCitations

          搜索结果的引用设置。

          • enabled: boolean

            此搜索结果是否启用引用。

        • content: array of BetaManagedAgentsSearchResultContent

          搜索结果中的文本内容块数组。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • source: string

          搜索结果的 URL 来源。

        • title: string

          搜索结果的标题。

        • type: "search_result"

          • "search_result"

    • is_error: optional boolean

      工具执行是否导致错误。

Beta Managed Agents Agent Tool Use Event

  • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

    当代理调用内置代理工具时发出的事件。

    • id: string

      此事件的唯一标识符。

    • input: map[unknown]

      工具调用的输入参数。

    • name: string

      正在使用的代理工具名称。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "agent.tool_use"

      • "agent.tool_use"

    • evaluated_permission: optional "allow" or "ask" or "deny"

      Agent评估uatedPermission 枚举

      • "allow"

      • "ask"

      • "deny"

    • session_thread_id: optional string

      设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

Beta Managed Agents Base64 Document Source

  • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

    Base64 编码的文档数据。

    • data: string

      Base64 编码的文档数据。

    • media_type: string

      文档的 MIME 类型（例如 "application/pdf"）。

    • type: "base64"

      • "base64"

Beta Managed Agents Base64 Image Source

  • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

    Base64 编码的图片数据。

    • data: string

      Base64 编码的图片数据。

    • media_type: string

      图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

    • type: "base64"

      • "base64"

Beta Managed Agents Billing Error

  • BetaManagedAgentsBillingError object { message, retry_status, type }

    调用者的组织或工作区无法发出模型请求——额度不足或已达消费限额。使用相同凭据重试不会成功；调用者必须解决计费状态。

    • message: string

      人类可读的错误描述。

    • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      客户端应对此错误采取的下一步操作。

      • BetaManagedAgentsRetryStatusRetrying object { type }

        服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

        • type: "retrying"

          • "retrying"

      • BetaManagedAgentsRetryStatusExhausted object { type }

        此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        会话遇到终止性错误，将转换为 terminated 状态。

        • type: "terminal"

          • "terminal"

    • type: "billing_error"

      • "billing_error"

Beta Managed Agents Document Block

  • BetaManagedAgentsDocumentBlock object { source, type, context, title }

    文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

    • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

      文档源变体的联合类型。

      • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

        Base64 编码的文档数据。

        • data: string

          Base64 编码的文档数据。

        • media_type: string

          文档的 MIME 类型（例如 "application/pdf"）。

        • type: "base64"

          • "base64"

      • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

        纯文本文档内容。

        • data: string

          纯文本内容。

        • media_type: "text/plain"

          文本内容的 MIME 类型。必须为 "text/plain"。

          • "text/plain"

        • type: "text"

          • "text"

      • BetaManagedAgentsURLDocumentSource object { type, url }

        通过 URL 引用的文档。

        • type: "url"

          • "url"

        • url: string

          要获取的文档 URL。

      • BetaManagedAgentsFileDocumentSource object { file_id, type }

        通过文件 ID 引用的文档。

        • file_id: string

          先前上传文件的 ID。

        • type: "file"

          • "file"

    • type: "document"

      • "document"

    • context: optional string

      为模型提供的关于文档的额外上下文。

    • title: optional string

      文档的标题。

Beta Managed Agents Event Params

  • BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserInterruptEventParams or BetaManagedAgentsUserToolConfirmationEventParams or 3 more

    可发送到会话的事件参数的联合类型。

    • BetaManagedAgentsUserMessageEventParams object { content, type }

      向会话发送用户消息的参数。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        用户消息的内容块数组。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            图片源变体的联合类型。

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              Base64 编码的图片数据。

              • data: string

                Base64 编码的图片数据。

              • media_type: string

                图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsURLImageSource object { type, url }

              通过 URL 引用的图片。

              • type: "url"

                • "url"

              • url: string

                要获取的图片 URL。

            • BetaManagedAgentsFileImageSource object { file_id, type }

              通过文件 ID 引用的图片。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            文档源变体的联合类型。

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              Base64 编码的文档数据。

              • data: string

                Base64 编码的文档数据。

              • media_type: string

                文档的 MIME 类型（例如 "application/pdf"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

              纯文本文档内容。

              • data: string

                纯文本内容。

              • media_type: "text/plain"

                文本内容的 MIME 类型。必须为 "text/plain"。

                • "text/plain"

              • type: "text"

                • "text"

            • BetaManagedAgentsURLDocumentSource object { type, url }

              通过 URL 引用的文档。

              • type: "url"

                • "url"

              • url: string

                要获取的文档 URL。

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              通过文件 ID 引用的文档。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            为模型提供的关于文档的额外上下文。

          • title: optional string

            文档的标题。

      • type: "user.message"

        • "user.message"

    • BetaManagedAgentsUserInterruptEventParams object { type, session_thread_id }

      发送中断以暂停代理的参数。

      • type: "user.interrupt"

        • "user.interrupt"

      • session_thread_id: optional string

        如果省略，中断多代理会话中的每个未归档线程（或单代理会话中的主线程）。如果指定，仅中断指定的线程。

    • BetaManagedAgentsUserToolConfirmationEventParams object { result, tool_use_id, type, deny_message }

      确认或拒绝工具执行请求的参数。

      • result: "allow" or "deny"

        UserToolConfirmationResult 枚举

        • "allow"

        • "deny"

      • tool_use_id: string

        此结果对应的 agent.tool_use 或 agent.mcp_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        为 'deny' 决定提供上下文的可选消息。仅在 result 为 'deny' 时允许。

    • BetaManagedAgentsUserCustomToolResultEventParams object { custom_tool_use_id, type, content, is_error }

      提供自定义工具执行结果的参数。

      • custom_tool_use_id: string

        此结果对应的 agent.custom_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

          • citations: BetaManagedAgentsSearchResultCitations

            搜索结果的引用设置。

            • enabled: boolean

              此搜索结果是否启用引用。

          • content: array of BetaManagedAgentsSearchResultContent

            搜索结果中的文本内容块数组。

            • text: string

              文本内容。

            • type: "text"

              • "text"

          • source: string

            搜索结果的 URL 来源。

          • title: string

            搜索结果的标题。

          • type: "search_result"

            • "search_result"

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }

      定义代理应努力达成的结果的参数。代理在收到后开始工作。

      • description: string

        代理应产出的内容。这是任务规范。

      • rubric: BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams

        用于评估结果质量的评分标准。

        • BetaManagedAgentsFileRubricParams object { file_id, type }

          通过 Files API 上传的文件引用的评分标准。

          • file_id: string

            评分标准文件的 ID。

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubricParams object { content, type }

          以文本形式内联提供的评分标准内容。

          • content: string

            评分标准内容。纯文本或 markdown——评分者将其视为自由格式文本。 最多 262144 个字符。

          • type: "text"

            • "text"

      • type: "user.define_outcome"

        • "user.define_outcome"

      • max_iterations: optional number

        评估→-修订周期，直到放弃。默认 3，最大 20。

    • BetaManagedAgentsUserToolResultEventParams object { tool_use_id, type, content, is_error }

      提供代理工具集工具执行结果的参数。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

Beta Managed Agents File Document Source

  • BetaManagedAgentsFileDocumentSource object { file_id, type }

    通过文件 ID 引用的文档。

    • file_id: string

      先前上传文件的 ID。

    • type: "file"

      • "file"

Beta Managed Agents File Image Source

  • BetaManagedAgentsFileImageSource object { file_id, type }

    通过文件 ID 引用的图片。

    • file_id: string

      先前上传文件的 ID。

    • type: "file"

      • "file"

Beta Managed Agents File Rubric

  • BetaManagedAgentsFileRubric object { file_id, type }

    通过 Files API 上传的文件引用的评分标准。

    • file_id: string

      评分标准文件的 ID。

    • type: "file"

      • "file"

Beta Managed Agents File Rubric Params

  • BetaManagedAgentsFileRubricParams object { file_id, type }

    通过 Files API 上传的文件引用的评分标准。

    • file_id: string

      评分标准文件的 ID。

    • type: "file"

      • "file"

Beta Managed Agents Image Block

  • BetaManagedAgentsImageBlock object { source, type }

    直接指定为 base64 数据或通过 URL 引用的图片内容。

    • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

      图片源变体的联合类型。

      • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

        Base64 编码的图片数据。

        • data: string

          Base64 编码的图片数据。

        • media_type: string

          图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

        • type: "base64"

          • "base64"

      • BetaManagedAgentsURLImageSource object { type, url }

        通过 URL 引用的图片。

        • type: "url"

          • "url"

        • url: string

          要获取的图片 URL。

      • BetaManagedAgentsFileImageSource object { file_id, type }

        通过文件 ID 引用的图片。

        • file_id: string

          先前上传文件的 ID。

        • type: "file"

          • "file"

    • type: "image"

      • "image"

Beta Managed Agents MCP Authentication Failed Error

  • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

    MCP 服务器认证失败。

    • mcp_server_name: string

      认证失败的 MCP 服务器名称。

    • message: string

      人类可读的错误描述。

    • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      客户端应对此错误采取的下一步操作。

      • BetaManagedAgentsRetryStatusRetrying object { type }

        服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

        • type: "retrying"

          • "retrying"

      • BetaManagedAgentsRetryStatusExhausted object { type }

        此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        会话遇到终止性错误，将转换为 terminated 状态。

        • type: "terminal"

          • "terminal"

    • type: "mcp_authentication_failed_error"

      • "mcp_authentication_failed_error"

Beta Managed Agents MCP Connection Failed Error

  • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

    连接 MCP 服务器失败。

    • mcp_server_name: string

      连接失败的 MCP 服务器名称。

    • message: string

      人类可读的错误描述。

    • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      客户端应对此错误采取的下一步操作。

      • BetaManagedAgentsRetryStatusRetrying object { type }

        服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

        • type: "retrying"

          • "retrying"

      • BetaManagedAgentsRetryStatusExhausted object { type }

        此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        会话遇到终止性错误，将转换为 terminated 状态。

        • type: "terminal"

          • "terminal"

    • type: "mcp_connection_failed_error"

      • "mcp_connection_failed_error"

Beta Managed Agents Model Overloaded Error

  • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

    模型当前已过载。在自动重试耗尽后发出。

    • message: string

      人类可读的错误描述。

    • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      客户端应对此错误采取的下一步操作。

      • BetaManagedAgentsRetryStatusRetrying object { type }

        服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

        • type: "retrying"

          • "retrying"

      • BetaManagedAgentsRetryStatusExhausted object { type }

        此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        会话遇到终止性错误，将转换为 terminated 状态。

        • type: "terminal"

          • "terminal"

    • type: "model_overloaded_error"

      • "model_overloaded_error"

Beta Managed Agents Model Rate Limited Error

  • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

    模型请求被限流。

    • message: string

      人类可读的错误描述。

    • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      客户端应对此错误采取的下一步操作。

      • BetaManagedAgentsRetryStatusRetrying object { type }

        服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

        • type: "retrying"

          • "retrying"

      • BetaManagedAgentsRetryStatusExhausted object { type }

        此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        会话遇到终止性错误，将转换为 terminated 状态。

        • type: "terminal"

          • "terminal"

    • type: "model_rate_limited_error"

      • "model_rate_limited_error"

Beta Managed Agents Model Request Failed Error

  • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

    模型请求因过载或限流以外的原因失败。

    • message: string

      人类可读的错误描述。

    • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      客户端应对此错误采取的下一步操作。

      • BetaManagedAgentsRetryStatusRetrying object { type }

        服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

        • type: "retrying"

          • "retrying"

      • BetaManagedAgentsRetryStatusExhausted object { type }

        此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        会话遇到终止性错误，将转换为 terminated 状态。

        • type: "terminal"

          • "terminal"

    • type: "model_request_failed_error"

      • "model_request_failed_error"

Beta Managed Agents Plain Text Document Source

  • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

    纯文本文档内容。

    • data: string

      纯文本内容。

    • media_type: "text/plain"

      文本内容的 MIME 类型。必须为 "text/plain"。

      • "text/plain"

    • type: "text"

      • "text"

Beta Managed Agents Retry Status Exhausted

  • BetaManagedAgentsRetryStatusExhausted object { type }

    此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

    • type: "exhausted"

      • "exhausted"

Beta Managed Agents Retry Status Retrying

  • BetaManagedAgentsRetryStatusRetrying object { type }

    服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

    • type: "retrying"

      • "retrying"

Beta Managed Agents Retry Status Terminal

  • BetaManagedAgentsRetryStatusTerminal object { type }

    会话遇到终止性错误，将转换为 terminated 状态。

    • type: "terminal"

      • "terminal"

Beta Managed Agents Search Result Block

  • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

    包含网络搜索结果的块。

    • citations: BetaManagedAgentsSearchResultCitations

      搜索结果的引用设置。

      • enabled: boolean

        此搜索结果是否启用引用。

    • content: array of BetaManagedAgentsSearchResultContent

      搜索结果中的文本内容块数组。

      • text: string

        文本内容。

      • type: "text"

        • "text"

    • source: string

      搜索结果的 URL 来源。

    • title: string

      搜索结果的标题。

    • type: "search_result"

      • "search_result"

Beta Managed Agents Search Result Citations

  • BetaManagedAgentsSearchResultCitations object { enabled }

    搜索结果的引用设置。

    • enabled: boolean

      此搜索结果是否启用引用。

Beta Managed Agents Search Result Content

  • BetaManagedAgentsSearchResultContent object { text, type }

    搜索结果中的文本内容。

    • text: string

      文本内容。

    • type: "text"

      • "text"

Beta Managed Agents Send Session Events

  • BetaManagedAgentsSendSessionEvents object { data }

    已成功发送到会话的事件。

    • data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 3 more

      Sent events

      • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

        会话对话中的用户消息事件。

        • id: string

          此事件的唯一标识符。

        • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

          组成用户消息的内容块数组。

          • BetaManagedAgentsTextBlock object { text, type }

            常规文本内容。

            • text: string

              文本内容。

            • type: "text"

              • "text"

          • BetaManagedAgentsImageBlock object { source, type }

            直接指定为 base64 数据或通过 URL 引用的图片内容。

            • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

              图片源变体的联合类型。

              • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

                Base64 编码的图片数据。

                • data: string

                  Base64 编码的图片数据。

                • media_type: string

                  图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

                • type: "base64"

                  • "base64"

              • BetaManagedAgentsURLImageSource object { type, url }

                通过 URL 引用的图片。

                • type: "url"

                  • "url"

                • url: string

                  要获取的图片 URL。

              • BetaManagedAgentsFileImageSource object { file_id, type }

                通过文件 ID 引用的图片。

                • file_id: string

                  先前上传文件的 ID。

                • type: "file"

                  • "file"

            • type: "image"

              • "image"

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

            • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

              文档源变体的联合类型。

              • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

                Base64 编码的文档数据。

                • data: string

                  Base64 编码的文档数据。

                • media_type: string

                  文档的 MIME 类型（例如 "application/pdf"）。

                • type: "base64"

                  • "base64"

              • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

                纯文本文档内容。

                • data: string

                  纯文本内容。

                • media_type: "text/plain"

                  文本内容的 MIME 类型。必须为 "text/plain"。

                  • "text/plain"

                • type: "text"

                  • "text"

              • BetaManagedAgentsURLDocumentSource object { type, url }

                通过 URL 引用的文档。

                • type: "url"

                  • "url"

                • url: string

                  要获取的文档 URL。

              • BetaManagedAgentsFileDocumentSource object { file_id, type }

                通过文件 ID 引用的文档。

                • file_id: string

                  先前上传文件的 ID。

                • type: "file"

                  • "file"

            • type: "document"

              • "document"

            • context: optional string

              为模型提供的关于文档的额外上下文。

            • title: optional string

              文档的标题。

        • type: "user.message"

          • "user.message"

        • processed_at: optional string

          RFC 3339 格式的时间戳

      • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

        暂停代理执行并将控制权返回给用户的中断事件。

        • id: string

          此事件的唯一标识符。

        • type: "user.interrupt"

          • "user.interrupt"

        • processed_at: optional string

          RFC 3339 格式的时间戳

        • session_thread_id: optional string

          如果省略，中断多代理会话中的每个未归档线程（或单代理会话中的主线程）。如果指定，仅中断指定的线程。

      • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

        批准或拒绝待处理工具执行的工具确认事件。

        • id: string

          此事件的唯一标识符。

        • result: "allow" or "deny"

          UserToolConfirmationResult 枚举

          • "allow"

          • "deny"

        • tool_use_id: string

          此结果对应的 agent.tool_use 或 agent.mcp_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

        • type: "user.tool_confirmation"

          • "user.tool_confirmation"

        • deny_message: optional string

          为 'deny' 决定提供上下文的可选消息。仅在 result 为 'deny' 时允许。

        • processed_at: optional string

          RFC 3339 格式的时间戳

        • session_thread_id: optional string

          设置后，确认将路由到此子代理的线程而非主线程。从触发批准的 agent.tool_use 或 agent.mcp_tool_use 事件上的 session_thread_id 回显此值。

      • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

        客户端发送的事件，提供自定义工具执行的结果。

        • id: string

          此事件的唯一标识符。

        • custom_tool_use_id: string

          此结果对应的 agent.custom_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

        • type: "user.custom_tool_result"

          • "user.custom_tool_result"

        • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

          工具返回的结果内容。

          • BetaManagedAgentsTextBlock object { text, type }

            常规文本内容。

          • BetaManagedAgentsImageBlock object { source, type }

            直接指定为 base64 数据或通过 URL 引用的图片内容。

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

            包含网络搜索结果的块。

            • citations: BetaManagedAgentsSearchResultCitations

              搜索结果的引用设置。

              • enabled: boolean

                此搜索结果是否启用引用。

            • content: array of BetaManagedAgentsSearchResultContent

              搜索结果中的文本内容块数组。

              • text: string

                文本内容。

              • type: "text"

                • "text"

            • source: string

              搜索结果的 URL 来源。

            • title: string

              搜索结果的标题。

            • type: "search_result"

              • "search_result"

        • is_error: optional boolean

          工具执行是否导致错误。

        • processed_at: optional string

          RFC 3339 格式的时间戳

        • session_thread_id: optional string

          将此结果路由到子代理线程。从 agent.custom_tool_use 事件的 session_thread_id 复制。

      • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

        user.define_outcome 输入事件的回显。携带服务器生成的 outcome_id，后续的 span.outcome_evaluation_* 事件引用该 ID。

        • id: string

          此事件的唯一标识符。

        • description: string

          代理应产出的内容。 从输入事件复制。

        • max_iterations: number

          放弃前的评估-修订周期。默认 3，最大 20。

        • outcome_id: string

          服务器为此结果生成的 outc_ ID。被 span.outcome_evaluation_* 事件和会话的 outcome_evaluations 列表引用。

        • processed_at: string

          RFC 3339 格式的时间戳

        • rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

          用于评估结果质量的评分标准。

          • BetaManagedAgentsFileRubric object { file_id, type }

            通过 Files API 上传的文件引用的评分标准。

            • file_id: string

              评分标准文件的 ID。

            • type: "file"

              • "file"

          • BetaManagedAgentsTextRubric object { content, type }

            以文本形式内联提供的评分标准内容。

            • content: string

              评分标准内容。纯文本或 markdown——评分者将其视为自由格式文本。

            • type: "text"

              • "text"

        • type: "user.define_outcome"

          • "user.define_outcome"

      • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

        客户端发送的事件，提供代理工具集工具执行的结果。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

        • id: string

          此事件的唯一标识符。

        • tool_use_id: string

          此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

        • type: "user.tool_result"

          • "user.tool_result"

        • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

          工具返回的结果内容。

          • BetaManagedAgentsTextBlock object { text, type }

            常规文本内容。

          • BetaManagedAgentsImageBlock object { source, type }

            直接指定为 base64 数据或通过 URL 引用的图片内容。

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

            包含网络搜索结果的块。

        • is_error: optional boolean

          工具执行是否导致错误。

        • processed_at: optional string

          RFC 3339 格式的时间戳

        • session_thread_id: optional string

          将此结果路由到子代理线程。从 agent.tool_use 事件的 session_thread_id 复制。

Beta Managed Agents Session Deleted Event

  • BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }

    当会话被删除时发出。终止所有活动的事件流 — 不会再为此会话发出更多事件。

    • id: string

      此事件的唯一标识符。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "session.deleted"

      • "session.deleted"

Beta Managed Agents Session End Turn

  • BetaManagedAgentsSessionEndTurn object { type }

    代理自然完成了其轮次，准备接收下一条用户消息。

    • type: "end_turn"

      • "end_turn"

Beta Managed Agents Session Error Event

  • BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }

    表示会话执行期间出现问题的错误事件。

    • id: string

      此事件的唯一标识符。

    • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more

      会话执行期间发生未知或意外错误。 回退变体；无法识别新错误代码的客户端可以仅匹配'retry_status 和 message。

      • BetaManagedAgentsUnknownError object { message, retry_status, type }

        会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

        • message: string

          人类可读的错误描述。

        • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          客户端应对此错误采取的下一步操作。

          • BetaManagedAgentsRetryStatusRetrying object { type }

            服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • type: "retrying"

              • "retrying"

          • BetaManagedAgentsRetryStatusExhausted object { type }

            此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • type: "exhausted"

              • "exhausted"

          • BetaManagedAgentsRetryStatusTerminal object { type }

            会话遇到终止性错误，将转换为 terminated 状态。

            • type: "terminal"

              • "terminal"

        • type: "unknown_error"

          • "unknown_error"

      • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

        模型当前已过载。在自动重试耗尽后发出。

        • message: string

          人类可读的错误描述。

        • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          客户端应对此错误采取的下一步操作。

          • BetaManagedAgentsRetryStatusRetrying object { type }

            服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

          • BetaManagedAgentsRetryStatusExhausted object { type }

            此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

          • BetaManagedAgentsRetryStatusTerminal object { type }

            会话遇到终止性错误，将转换为 terminated 状态。

        • type: "model_overloaded_error"

          • "model_overloaded_error"

      • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

        模型请求被限流。

        • message: string

          人类可读的错误描述。

        • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          客户端应对此错误采取的下一步操作。

          • BetaManagedAgentsRetryStatusRetrying object { type }

            服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

          • BetaManagedAgentsRetryStatusExhausted object { type }

            此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

          • BetaManagedAgentsRetryStatusTerminal object { type }

            会话遇到终止性错误，将转换为 terminated 状态。

        • type: "model_rate_limited_error"

          • "model_rate_limited_error"

      • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

        模型请求因过载或限流以外的原因失败。

        • message: string

          人类可读的错误描述。

        • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          客户端应对此错误采取的下一步操作。

          • BetaManagedAgentsRetryStatusRetrying object { type }

            服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

          • BetaManagedAgentsRetryStatusExhausted object { type }

            此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

          • BetaManagedAgentsRetryStatusTerminal object { type }

            会话遇到终止性错误，将转换为 terminated 状态。

        • type: "model_request_failed_error"

          • "model_request_failed_error"

      • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

        连接 MCP 服务器失败。

        • mcp_server_name: string

          连接失败的 MCP 服务器名称。

        • message: string

          人类可读的错误描述。

        • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          客户端应对此错误采取的下一步操作。

          • BetaManagedAgentsRetryStatusRetrying object { type }

            服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

          • BetaManagedAgentsRetryStatusExhausted object { type }

            此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

          • BetaManagedAgentsRetryStatusTerminal object { type }

            会话遇到终止性错误，将转换为 terminated 状态。

        • type: "mcp_connection_failed_error"

          • "mcp_connection_failed_error"

      • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

        MCP 服务器认证失败。

        • mcp_server_name: string

          认证失败的 MCP 服务器名称。

        • message: string

          人类可读的错误描述。

        • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          客户端应对此错误采取的下一步操作。

          • BetaManagedAgentsRetryStatusRetrying object { type }

            服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

          • BetaManagedAgentsRetryStatusExhausted object { type }

            此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

          • BetaManagedAgentsRetryStatusTerminal object { type }

            会话遇到终止性错误，将转换为 terminated 状态。

        • type: "mcp_authentication_failed_error"

          • "mcp_authentication_failed_error"

      • BetaManagedAgentsBillingError object { message, retry_status, type }

        调用者的组织或工作区无法发出模型请求——额度不足或已达消费限额。使用相同凭据重试不会成功；调用者必须解决计费状态。

        • message: string

          人类可读的错误描述。

        • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          客户端应对此错误采取的下一步操作。

          • BetaManagedAgentsRetryStatusRetrying object { type }

            服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

          • BetaManagedAgentsRetryStatusExhausted object { type }

            此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

          • BetaManagedAgentsRetryStatusTerminal object { type }

            会话遇到终止性错误，将转换为 terminated 状态。

        • type: "billing_error"

          • "billing_error"

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "session.error"

      • "session.error"

Beta Managed Agents Session Event

  • BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 30 more

    会话中所有事件类型的联合类型。

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      会话对话中的用户消息事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        组成用户消息的内容块数组。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            图片源变体的联合类型。

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              Base64 编码的图片数据。

              • data: string

                Base64 编码的图片数据。

              • media_type: string

                图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsURLImageSource object { type, url }

              通过 URL 引用的图片。

              • type: "url"

                • "url"

              • url: string

                要获取的图片 URL。

            • BetaManagedAgentsFileImageSource object { file_id, type }

              通过文件 ID 引用的图片。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            文档源变体的联合类型。

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              Base64 编码的文档数据。

              • data: string

                Base64 编码的文档数据。

              • media_type: string

                文档的 MIME 类型（例如 "application/pdf"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

              纯文本文档内容。

              • data: string

                纯文本内容。

              • media_type: "text/plain"

                文本内容的 MIME 类型。必须为 "text/plain"。

                • "text/plain"

              • type: "text"

                • "text"

            • BetaManagedAgentsURLDocumentSource object { type, url }

              通过 URL 引用的文档。

              • type: "url"

                • "url"

              • url: string

                要获取的文档 URL。

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              通过文件 ID 引用的文档。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            为模型提供的关于文档的额外上下文。

          • title: optional string

            文档的标题。

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        RFC 3339 格式的时间戳

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      暂停代理执行并将控制权返回给用户的中断事件。

      • id: string

        此事件的唯一标识符。

      • type: "user.interrupt"

        • "user.interrupt"

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        如果省略，中断多代理会话中的每个未归档线程（或单代理会话中的主线程）。如果指定，仅中断指定的线程。

    • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

      批准或拒绝待处理工具执行的工具确认事件。

      • id: string

        此事件的唯一标识符。

      • result: "allow" or "deny"

        UserToolConfirmationResult 枚举

        • "allow"

        • "deny"

      • tool_use_id: string

        此结果对应的 agent.tool_use 或 agent.mcp_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        为 'deny' 决定提供上下文的可选消息。仅在 result 为 'deny' 时允许。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        设置后，确认将路由到此子代理的线程而非主线程。从触发批准的 agent.tool_use 或 agent.mcp_tool_use 事件上的 session_thread_id 回显此值。

    • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

      客户端发送的事件，提供自定义工具执行的结果。

      • id: string

        此事件的唯一标识符。

      • custom_tool_use_id: string

        此结果对应的 agent.custom_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

          • citations: BetaManagedAgentsSearchResultCitations

            搜索结果的引用设置。

            • enabled: boolean

              此搜索结果是否启用引用。

          • content: array of BetaManagedAgentsSearchResultContent

            搜索结果中的文本内容块数组。

            • text: string

              文本内容。

            • type: "text"

              • "text"

          • source: string

            搜索结果的 URL 来源。

          • title: string

            搜索结果的标题。

          • type: "search_result"

            • "search_result"

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.custom_tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      当代理调用自定义工具时发出的事件。会话进入空闲状态，直到客户端发送带有结果的 user.custom_tool_result 事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        被调用的自定义工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.custom_tool_use"

        • "agent.custom_tool_use"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其自定义工具使用。在线程自身事件上为空。在 user.custom_tool_result 事件上回显此值以将结果路由回来。

    • BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }

      会话对话中的代理响应事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock

        组成代理响应的文本块数组。

        • text: string

          文本内容。

        • type: "text"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.message"

        • "agent.message"

    • BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }

      表示代理通过扩展思考正在取得进展。这是一个进度信号，而非内容载体。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thinking"

        • "agent.thinking"

    • BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }

      当代理调用 MCP 服务器提供的工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • mcp_server_name: string

        提供工具的 MCP 服务器名称。

      • name: string

        正在使用的 MCP 工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_use"

        • "agent.mcp_tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }

      表示 MCP 工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • mcp_tool_use_id: string

        此结果对应的 agent.mcp_tool_use 事件的 ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_result"

        • "agent.mcp_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      代理调用内置代理工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        正在使用的代理工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.tool_use"

        • "agent.tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }

      表示代理工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID。

      • type: "agent.tool_result"

        • "agent.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      当代理间消息到达时写入目标线程输入流的传递事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • from_session_thread_id: string

        发送消息的线程的公共 sthr_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_message_received"

        • "agent.thread_message_received"

      • from_agent_name: optional string

        此消息来源的可调用代理名称。从主代理接收时为空。

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      发送代理间消息时发出到发送者输出流的可观察性事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • to_session_thread_id: string

        消息发送到的线程的公共 sthr_ ID。

      • type: "agent.thread_message_sent"

        • "agent.thread_message_sent"

      • to_agent_name: optional string

        此消息发送到的可调用代理名称。发送到主代理时为空。

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      表示会话期间发生了上下文压缩（摘要）。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_context_compacted"

        • "agent.thread_context_compacted"

    • BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }

      表示会话执行期间发生问题的错误事件。

      • id: string

        此事件的唯一标识符。

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more

        会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

        • BetaManagedAgentsUnknownError object { message, retry_status, type }

          会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

              • type: "retrying"

                • "retrying"

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          模型当前已过载。在自动重试耗尽后发出。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          模型请求被限流。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          模型请求因过载或限流以外的原因失败。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          连接 MCP 服务器失败。

          • mcp_server_name: string

            连接失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          MCP 服务器认证失败。

          • mcp_server_name: string

            认证失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          调用者的组织或工作区无法发出模型请求——额度不足或已达消费限额。使用相同凭据重试不会成功；调用者必须解决计费状态。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "billing_error"

            • "billing_error"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.error"

        • "session.error"

    • BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }

      表示会话正在从错误状态恢复，并已重新安排执行。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_rescheduled"

        • "session.status_rescheduled"

    • BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }

      表示会话正在积极运行，代理正在工作。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_running"

        • "session.status_running"

    • BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }

      表示代理已暂停，正在等待用户输入。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

          • event_ids: array of string

            代理被阻塞的事件 ID。解决少于全部事件时，会使用剩余事件重新发出 session.status_idle。

          • type: "requires_action"

            • "requires_action"

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

          • type: "retries_exhausted"

            • "retries_exhausted"

      • type: "session.status_idle"

        • "session.status_idle"

    • BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }

      表示会话已终止，无论是由于错误还是完成。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_terminated"

        • "session.status_terminated"

    • BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }

      当子代理作为新线程生成时发出。写入父线程的输出流，以便观察会话的客户端看到子线程创建。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的可调用代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        新创建线程的公共 sthr_ ID。

      • type: "session.thread_created"

        • "session.thread_created"

    • BetaManagedAgentsSpanOutcome评估uationStartEvent object { id, iteration, outcome_id, 2 more }

      当结果评估周期开始时发出。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期。0 是第一次评估；1 是第一次修订后的重新评估；以此类推。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_start"

        • "span.outcome_evaluation_start"

    • BetaManagedAgentsSpanOutcome评估uationEndEvent object { id, explanation, iteration, 6 more }

      当结果评估周期完成时发出。携带判定结果和聚合 token 使用量。判定为 needs_revision 意味着还有另一个评估周期；satisfied、max_iterations_reached、failed 或 interrupted 为终止状态——不会有更多评估周期。

      • id: string

        此事件的唯一标识符。

      • explanation: string

        判定结果的人类可读解释。对于 needs_revision，描述哪些标准未满足以及原因。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_evaluation_start_id: string

        对应的 span.outcome_evaluation_start 事件的 ID。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • result: string

        评估判定。 'satisfied': 标准已满足，会话进入空闲。 'needs_revision': 标准未满足，将进行另一个修订周期。 'max_iterations_reached': 评估预算耗尽但标准仍未满足 — 会话进入空闲前会有最后一个确认轮次，但不会进行更多评估。 'failed': 评分者确定评分标准不适用于交付物。 'interrupted': 用户在评估进行中发送了中断。

      • type: "span.outcome_evaluation_end"

        • "span.outcome_evaluation_end"

      • usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

        • cache_creation_input_tokens: number

          此请求中用于创建提示缓存的 token 数。

        • cache_read_input_tokens: number

          此请求中从提示缓存读取的 token 数。

        • input_tokens: number

          此请求消耗的输入 token 数。

        • output_tokens: number

          此请求生成的输出 token 数。

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      当代理发起模型请求时发出。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_start"

        • "span.model_request_start"

    • BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }

      当模型请求完成时发出。

      • id: string

        此事件的唯一标识符。

      • is_error: boolean

        模型请求是否导致错误。

      • model_request_start_id: string

        对应的 span.model_request_start 事件的 ID。

      • model_usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_end"

        • "span.model_request_end"

    • BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }

      在结果评估周期进行期间发出的定期心跳。在对应的 span.outcome_evaluation_start 和 span.outcome_evaluation_end 事件之间区分"评估正在积极运行"和"评估卡住"。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_ongoing"

        • "span.outcome_evaluation_ongoing"

    • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

      user.define_outcome 输入事件的回显。携带服务器生成的 outcome_id，后续的 span.outcome_evaluation_* 事件引用该 ID。

      • id: string

        此事件的唯一标识符。

      • description: string

        代理应产出的内容。 从输入事件复制。

      • max_iterations: number

        放弃前的评估-修订周期。默认 3，最大 20。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。被 span.outcome_evaluation_* 事件和会话的 outcome_evaluations 列表引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

        用于评估结果质量的评分标准。

        • BetaManagedAgentsFileRubric object { file_id, type }

          通过 Files API 上传的文件引用的评分标准。

          • file_id: string

            评分标准文件的 ID。

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          以文本形式内联提供的评分标准内容。

          • content: string

            评分标准内容。纯文本或 markdown——评分者将其视为自由格式文本。

          • type: "text"

            • "text"

      • type: "user.define_outcome"

        • "user.define_outcome"

    • BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }

      当会话被删除时发出。终止所有活动的事件流 — 不会再为此会话发出更多事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.deleted"

        • "session.deleted"

    • BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }

      会话线程已开始执行。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        开始运行的线程的公共 sthr_ ID。

      • type: "session.thread_status_running"

        • "session.thread_status_running"

    • BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }

      会话线程已让出并正在等待输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        进入空闲状态的线程的公共 sthr_ ID。

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

      • type: "session.thread_status_idle"

        • "session.thread_status_idle"

    • BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }

      会话线程已终止，不再接受输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        已终止线程的公共 sthr_ ID。

      • type: "session.thread_status_terminated"

        • "session.thread_status_terminated"

    • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

      客户端发送的事件，提供代理工具集工具执行的结果。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

      • id: string

        此事件的唯一标识符。

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      会话线程遇到瞬态错误，正在自动重试。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        正在重试的线程的公共 sthr_ ID。

      • type: "session.thread_status_rescheduled"

        • "session.thread_status_rescheduled"

    • BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 3 more }

      当 UpdateSession 请求更改了至少一个字段时发出。仅携带已更改的字段；未出现的字段不是更新的一部分。新配置从下一轮开始生效。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.updated"

        • "session.updated"

      • agent: optional BetaManagedAgentsSessionAgent

        为 session 解析的 agent 定义。session 创建时 agent 的快照。

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          模型标识符和配置。

          • id: BetaManagedAgentsModel

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              驱动代理的模型。

              详情和选项请参阅 models。

              • "claude-opus-4-7"

                适用于长时间运行代理和编码的前沿智能

              • "claude-opus-4-6"

                用于构建代理和编码的最智能模型

              • "claude-sonnet-4-6"

                速度与智能的最佳组合

              • "claude-haiku-4-5"

                具有接近前沿智能的最快模型

              • "claude-haiku-4-5-20251001"

                具有接近前沿智能的最快模型

              • "claude-opus-4-5"

                结合最大智能与实用性能的高端模型

              • "claude-opus-4-5-20251101"

                结合最大智能与实用性能的高端模型

              • "claude-sonnet-4-5"

                用于代理和编码的高性能模型

              • "claude-sonnet-4-5-20250929"

                用于代理和编码的高性能模型

            • string

          • speed: optional "standard" or "fast"

            推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

            • "standard"

            • "fast"

        • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

          解析的协调器拓扑，包含每个成员的完整 agent 定义。

          • agents: array of BetaManagedAgentsSessionThreadAgent

            协调器可能作为会话线程生成的完整 agent 定义。

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              模型标识符和配置。

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                已解析的 Anthropic 托管技能。

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                已解析的用户创建的自定义技能。

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    内置代理工具标识符。

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                      • type: "always_ask"

                        • "always_ask"

                • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                  代理工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                  MCP 服务器所有工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                API 响应中返回的自定义工具。

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  自定义工具输入参数的 JSON Schema。

                  • properties: optional map[unknown]

                    定义工具输入参数的 JSON Schema 属性。

                  • required: optional array of string

                    必需属性名称列表。

                  • type: optional "object"

                    工具输入 schema 必须为 'object'。

                    • "object"

                • name: string

                • type: "custom"

                  • "custom"

            • type: "agent"

              • "agent"

            • version: number

          • type: "coordinator"

            • "coordinator"

        • name: string

        • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            已解析的 Anthropic 托管技能。

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            已解析的用户创建的自定义技能。

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            API 响应中返回的自定义工具。

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        更新后会话的完整元数据包。当更新设置了非空元数据时存在；当元数据未更改或清空时不存在。

      • title: optional string

        会话的新标题。仅在更新更改了标题时存在。

Beta Managed Agents Session Requires Action

  • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

    代理处于空闲状态，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

    • event_ids: array of string

      代理被阻塞的事件 ID。未全部解决时，会重新发出包含剩余事件的 session.status_idle。

    • type: "requires_action"

      • "requires_action"

Beta Managed Agents Session Retries Exhausted

  • BetaManagedAgentsSessionRetriesExhausted object { type }

    轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

    • type: "retries_exhausted"

      • "retries_exhausted"

Beta Managed Agents Session Status Idle Event

  • BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }

    表示代理已暂停，正在等待用户输入。

    • id: string

      此事件的唯一标识符。

    • processed_at: string

      RFC 3339 格式的时间戳

    • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

      代理自然完成了其轮次，准备接收下一条用户消息。

      • BetaManagedAgentsSessionEndTurn object { type }

        代理自然完成了其轮次，准备接收下一条用户消息。

        • type: "end_turn"

          • "end_turn"

      • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

        代理处于空闲状态，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

        • event_ids: array of string

          代理被阻塞的事件 ID。未全部解决时，会重新发出包含剩余事件的 session.status_idle。

        • type: "requires_action"

          • "requires_action"

      • BetaManagedAgentsSessionRetriesExhausted object { type }

        轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

        • type: "retries_exhausted"

          • "retries_exhausted"

    • type: "session.status_idle"

      • "session.status_idle"

Beta Managed Agents Session Status Rescheduled Event

  • BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }

    表示会话正在从错误状态恢复，并已重新安排执行。

    • id: string

      此事件的唯一标识符。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "session.status_rescheduled"

      • "session.status_rescheduled"

Beta Managed Agents Session Status Running Event

  • BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }

    表示会话正在积极运行，代理正在工作。

    • id: string

      此事件的唯一标识符。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "session.status_running"

      • "session.status_running"

Beta Managed Agents Session Status Terminated Event

  • BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }

    表示会话已终止，无论是由于错误还是完成。

    • id: string

      此事件的唯一标识符。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "session.status_terminated"

      • "session.status_terminated"

Beta Managed Agents Session Thread Created Event

  • BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }

    当子代理作为新线程生成时发出。写入父线程的输出流，以便观察会话的客户端看到子线程创建。

    • id: string

      此事件的唯一标识符。

    • agent_name: string

      线程运行的可调用代理名称。

    • processed_at: string

      RFC 3339 格式的时间戳

    • session_thread_id: string

      新创建线程的公共 sthr_ ID。

    • type: "session.thread_created"

      • "session.thread_created"

Beta Managed Agents Session Thread Status Idle Event

  • BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }

    会话线程已让出并正在等待输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

    • id: string

      此事件的唯一标识符。

    • agent_name: string

      线程运行的代理名称。

    • processed_at: string

      RFC 3339 格式的时间戳

    • session_thread_id: string

      进入空闲状态的线程的公共 sthr_ ID。

    • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

      代理自然完成了其轮次，准备接收下一条用户消息。

      • BetaManagedAgentsSessionEndTurn object { type }

        代理自然完成了其轮次，准备接收下一条用户消息。

        • type: "end_turn"

          • "end_turn"

      • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

        代理处于空闲状态，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

        • event_ids: array of string

          代理被阻塞的事件 ID。未全部解决时，会重新发出包含剩余事件的 session.status_idle。

        • type: "requires_action"

          • "requires_action"

      • BetaManagedAgentsSessionRetriesExhausted object { type }

        轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

        • type: "retries_exhausted"

          • "retries_exhausted"

    • type: "session.thread_status_idle"

      • "session.thread_status_idle"

Beta Managed Agents Session Thread Status Rescheduled Event

  • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

    会话线程遇到瞬态错误，正在自动重试。在线程'自身的流上发出，并交叉发布到子线程的主流。

    • id: string

      此事件的唯一标识符。

    • agent_name: string

      线程运行的代理名称。

    • processed_at: string

      RFC 3339 格式的时间戳

    • session_thread_id: string

      正在重试的线程的公共 sthr_ ID。

    • type: "session.thread_status_rescheduled"

      • "session.thread_status_rescheduled"

Beta Managed Agents Session Thread Status Running Event

  • BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }

    会话线程已开始执行。在线程'自身的流上发出，并交叉发布到子线程的主流。

    • id: string

      此事件的唯一标识符。

    • agent_name: string

      线程运行的代理名称。

    • processed_at: string

      RFC 3339 格式的时间戳

    • session_thread_id: string

      开始运行的线程的公共 sthr_ ID。

    • type: "session.thread_status_running"

      • "session.thread_status_running"

Beta Managed Agents Session Thread Status Terminated Event

  • BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }

    会话线程已终止，不再接受输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

    • id: string

      此事件的唯一标识符。

    • agent_name: string

      线程运行的代理名称。

    • processed_at: string

      RFC 3339 格式的时间戳

    • session_thread_id: string

      已终止线程的公共 sthr_ ID。

    • type: "session.thread_status_terminated"

      • "session.thread_status_terminated"

Beta Managed Agents Span Model Request End Event

  • BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }

    当模型请求完成时发出。

    • id: string

      此事件的唯一标识符。

    • is_error: boolean

      模型请求是否导致错误。

    • model_request_start_id: string

      对应的 span.model_request_start 事件的 ID。

    • model_usage: BetaManagedAgentsSpanModelUsage

      单个模型请求的 token 使用量。

      • cache_creation_input_tokens: number

        此请求中用于创建提示缓存的 token 数。

      • cache_read_input_tokens: number

        此请求中从提示缓存读取的 token 数。

      • input_tokens: number

        此请求消耗的输入 token 数。

      • output_tokens: number

        此请求生成的输出 token 数。

      • speed: optional "standard" or "fast"

        推理速度模式。fast 以高级定价提供显著更快的输出 token 生成。并非所有模型都支持 fast；无效组合在创建时会被拒绝。

        • "standard"

        • "fast"

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "span.model_request_end"

      • "span.model_request_end"

Beta Managed Agents Span Model Request Start Event

  • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

    当代理发起模型请求时发出。

    • id: string

      此事件的唯一标识符。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "span.model_request_start"

      • "span.model_request_start"

Beta Managed Agents Span Model Usage

  • BetaManagedAgentsSpanModelUsage object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }

    单个模型请求的 token 使用量。

    • cache_creation_input_tokens: number

      此请求中用于创建提示缓存的 token 数。

    • cache_read_input_tokens: number

      此请求中从提示缓存读取的 token 数。

    • input_tokens: number

      此请求消耗的输入 token 数。

    • output_tokens: number

      此请求生成的输出 token 数。

    • speed: optional "standard" or "fast"

      推理速度模式。fast 以高级定价提供显著更快的输出 token 生成。并非所有模型都支持 fast；无效组合在创建时会被拒绝。

      • "standard"

      • "fast"

Beta Managed Agents Span Outcome 评估uation End Event

  • BetaManagedAgentsSpanOutcome评估uationEndEvent object { id, explanation, iteration, 6 more }

    当结果评估周期完成时发出。携带判定结果和聚合 token 使用量。判定为 needs_revision 表示将进行另一个评估周期；satisfied、max_iterations_reached、failed 或 interrupted 为终止状态——不会再有后续评估周期。

    • id: string

      此事件的唯一标识符。

    • explanation: string

      判定结果的人类可读解释。对于 needs_revision，描述哪些标准未满足以及原因。

    • iteration: number

      从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

    • outcome_evaluation_start_id: string

      对应的 span.outcome_evaluation_start 事件的 ID。

    • outcome_id: string

      正在评估的结果的 outc_ ID。

    • processed_at: string

      RFC 3339 格式的时间戳

    • result: string

      评估判定。 'satisfied': 标准已满足，会话进入空闲。 'needs_revision': 标准未满足，将进行另一个修订周期。 'max_iterations_reached': 评估预算耗尽但标准仍未满足 — 会话进入空闲前会有最后一个确认轮次，但不会进行更多评估。 'failed': 评分者确定评分标准不适用于交付物。 'interrupted': 用户在评估进行中发送了中断。

    • type: "span.outcome_evaluation_end"

      • "span.outcome_evaluation_end"

    • usage: BetaManagedAgentsSpanModelUsage

      单个模型请求的 token 使用量。

      • cache_creation_input_tokens: number

        此请求中用于创建提示缓存的 token 数。

      • cache_read_input_tokens: number

        此请求中从提示缓存读取的 token 数。

      • input_tokens: number

        此请求消耗的输入 token 数。

      • output_tokens: number

        此请求生成的输出 token 数。

      • speed: optional "standard" or "fast"

        推理速度模式。fast 以高级定价提供显著更快的输出 token 生成。并非所有模型都支持 fast；无效组合在创建时会被拒绝。

        • "standard"

        • "fast"

Beta Managed Agents Span Outcome 评估uation Ongoing Event

  • BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }

    在结果评估周期进行期间发出的定期心跳。在对应的 span.outcome_evaluation_start 和 span.outcome_evaluation_end 事件之间区分"评估正在积极运行"和"评估卡住"。

    • id: string

      此事件的唯一标识符。

    • iteration: number

      从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

    • outcome_id: string

      正在评估的结果的 outc_ ID。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "span.outcome_evaluation_ongoing"

      • "span.outcome_evaluation_ongoing"

Beta Managed Agents Span Outcome 评估uation Start Event

  • BetaManagedAgentsSpanOutcome评估uationStartEvent object { id, iteration, outcome_id, 2 more }

    当结果评估周期开始时发出。

    • id: string

      此事件的唯一标识符。

    • iteration: number

      从 0 开始的修订周期。0 是第一次评估；1 是第一次修订后的重新评估；以此类推。

    • outcome_id: string

      正在评估的结果的 outc_ ID。

    • processed_at: string

      RFC 3339 格式的时间戳

    • type: "span.outcome_evaluation_start"

      • "span.outcome_evaluation_start"

Beta Managed Agents Stream Session Events

  • BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 30 more

    会话流中的服务器发送事件。

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      会话对话中的用户消息事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        组成用户消息的内容块数组。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            图片源变体的联合类型。

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              Base64 编码的图片数据。

              • data: string

                Base64 编码的图片数据。

              • media_type: string

                图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsURLImageSource object { type, url }

              通过 URL 引用的图片。

              • type: "url"

                • "url"

              • url: string

                要获取的图片 URL。

            • BetaManagedAgentsFileImageSource object { file_id, type }

              通过文件 ID 引用的图片。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            文档源变体的联合类型。

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              Base64 编码的文档数据。

              • data: string

                Base64 编码的文档数据。

              • media_type: string

                文档的 MIME 类型（例如 "application/pdf"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

              纯文本文档内容。

              • data: string

                纯文本内容。

              • media_type: "text/plain"

                文本内容的 MIME 类型。必须为 "text/plain"。

                • "text/plain"

              • type: "text"

                • "text"

            • BetaManagedAgentsURLDocumentSource object { type, url }

              通过 URL 引用的文档。

              • type: "url"

                • "url"

              • url: string

                要获取的文档 URL。

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              通过文件 ID 引用的文档。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            为模型提供的关于文档的额外上下文。

          • title: optional string

            文档的标题。

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        RFC 3339 格式的时间戳

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      暂停代理执行并将控制权返回给用户的中断事件。

      • id: string

        此事件的唯一标识符。

      • type: "user.interrupt"

        • "user.interrupt"

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        如果省略，中断多代理会话中的每个未归档线程（或单代理会话中的主线程）。如果指定，仅中断指定的线程。

    • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

      批准或拒绝待处理工具执行的工具确认事件。

      • id: string

        此事件的唯一标识符。

      • result: "allow" or "deny"

        UserToolConfirmationResult 枚举

        • "allow"

        • "deny"

      • tool_use_id: string

        此结果对应的 agent.tool_use 或 agent.mcp_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        为 'deny' 决定提供上下文的可选消息。仅在 result 为 'deny' 时允许。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        设置后，确认将路由到此子代理的线程而非主线程。从触发批准的 agent.tool_use 或 agent.mcp_tool_use 事件上的 session_thread_id 回显此值。

    • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

      客户端发送的事件，提供自定义工具执行的结果。

      • id: string

        此事件的唯一标识符。

      • custom_tool_use_id: string

        此结果对应的 agent.custom_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

          • citations: BetaManagedAgentsSearchResultCitations

            搜索结果的引用设置。

            • enabled: boolean

              此搜索结果是否启用引用。

          • content: array of BetaManagedAgentsSearchResultContent

            搜索结果中的文本内容块数组。

            • text: string

              文本内容。

            • type: "text"

              • "text"

          • source: string

            搜索结果的 URL 来源。

          • title: string

            搜索结果的标题。

          • type: "search_result"

            • "search_result"

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.custom_tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      当代理调用自定义工具时发出的事件。会话进入空闲状态，直到客户端发送带有结果的 user.custom_tool_result 事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        被调用的自定义工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.custom_tool_use"

        • "agent.custom_tool_use"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其自定义工具使用。在线程自身事件上为空。在 user.custom_tool_result 事件上回显此值以将结果路由回来。

    • BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }

      会话对话中的代理响应事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock

        组成代理响应的文本块数组。

        • text: string

          文本内容。

        • type: "text"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.message"

        • "agent.message"

    • BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }

      表示代理通过扩展思考正在取得进展。这是一个进度信号，而非内容载体。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thinking"

        • "agent.thinking"

    • BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }

      当代理调用 MCP 服务器提供的工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • mcp_server_name: string

        提供工具的 MCP 服务器名称。

      • name: string

        正在使用的 MCP 工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_use"

        • "agent.mcp_tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }

      表示 MCP 工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • mcp_tool_use_id: string

        此结果对应的 agent.mcp_tool_use 事件的 ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_result"

        • "agent.mcp_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      代理调用内置代理工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        正在使用的代理工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.tool_use"

        • "agent.tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }

      表示代理工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID。

      • type: "agent.tool_result"

        • "agent.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      当代理间消息到达时写入目标线程输入流的传递事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • from_session_thread_id: string

        发送消息的线程的公共 sthr_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_message_received"

        • "agent.thread_message_received"

      • from_agent_name: optional string

        此消息来源的可调用代理名称。从主代理接收时为空。

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      发送代理间消息时发出到发送者输出流的可观察性事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • to_session_thread_id: string

        消息发送到的线程的公共 sthr_ ID。

      • type: "agent.thread_message_sent"

        • "agent.thread_message_sent"

      • to_agent_name: optional string

        此消息发送到的可调用代理名称。发送到主代理时为空。

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      表示会话期间发生了上下文压缩（摘要）。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_context_compacted"

        • "agent.thread_context_compacted"

    • BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }

      表示会话执行期间发生问题的错误事件。

      • id: string

        此事件的唯一标识符。

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more

        会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

        • BetaManagedAgentsUnknownError object { message, retry_status, type }

          会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

              • type: "retrying"

                • "retrying"

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          模型当前已过载。在自动重试耗尽后发出。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          模型请求被限流。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          模型请求因过载或限流以外的原因失败。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          连接 MCP 服务器失败。

          • mcp_server_name: string

            连接失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          MCP 服务器认证失败。

          • mcp_server_name: string

            认证失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          调用者的组织或工作区无法发出模型请求——额度不足或已达消费限额。使用相同凭据重试不会成功；调用者必须解决计费状态。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "billing_error"

            • "billing_error"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.error"

        • "session.error"

    • BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }

      表示会话正在从错误状态恢复，并已重新安排执行。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_rescheduled"

        • "session.status_rescheduled"

    • BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }

      表示会话正在积极运行，代理正在工作。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_running"

        • "session.status_running"

    • BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }

      表示代理已暂停，正在等待用户输入。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

          • event_ids: array of string

            代理被阻塞的事件 ID。解决少于全部事件时，会使用剩余事件重新发出 session.status_idle。

          • type: "requires_action"

            • "requires_action"

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

          • type: "retries_exhausted"

            • "retries_exhausted"

      • type: "session.status_idle"

        • "session.status_idle"

    • BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }

      表示会话已终止，无论是由于错误还是完成。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_terminated"

        • "session.status_terminated"

    • BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }

      当子代理作为新线程生成时发出。写入父线程的输出流，以便观察会话的客户端看到子线程创建。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的可调用代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        新创建线程的公共 sthr_ ID。

      • type: "session.thread_created"

        • "session.thread_created"

    • BetaManagedAgentsSpanOutcome评估uationStartEvent object { id, iteration, outcome_id, 2 more }

      当结果评估周期开始时发出。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期。0 是第一次评估；1 是第一次修订后的重新评估；以此类推。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_start"

        • "span.outcome_evaluation_start"

    • BetaManagedAgentsSpanOutcome评估uationEndEvent object { id, explanation, iteration, 6 more }

      当结果评估周期完成时发出。携带判定结果和聚合 token 使用量。判定为 needs_revision 意味着还有另一个评估周期；satisfied、max_iterations_reached、failed 或 interrupted 为终止状态——不会有更多评估周期。

      • id: string

        此事件的唯一标识符。

      • explanation: string

        判定结果的人类可读解释。对于 needs_revision，描述哪些标准未满足以及原因。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_evaluation_start_id: string

        对应的 span.outcome_evaluation_start 事件的 ID。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • result: string

        评估判定。 'satisfied': 标准已满足，会话进入空闲。 'needs_revision': 标准未满足，将进行另一个修订周期。 'max_iterations_reached': 评估预算耗尽但标准仍未满足 — 会话进入空闲前会有最后一个确认轮次，但不会进行更多评估。 'failed': 评分者确定评分标准不适用于交付物。 'interrupted': 用户在评估进行中发送了中断。

      • type: "span.outcome_evaluation_end"

        • "span.outcome_evaluation_end"

      • usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

        • cache_creation_input_tokens: number

          此请求中用于创建提示缓存的 token 数。

        • cache_read_input_tokens: number

          此请求中从提示缓存读取的 token 数。

        • input_tokens: number

          此请求消耗的输入 token 数。

        • output_tokens: number

          此请求生成的输出 token 数。

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      当代理发起模型请求时发出。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_start"

        • "span.model_request_start"

    • BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }

      当模型请求完成时发出。

      • id: string

        此事件的唯一标识符。

      • is_error: boolean

        模型请求是否导致错误。

      • model_request_start_id: string

        对应的 span.model_request_start 事件的 ID。

      • model_usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_end"

        • "span.model_request_end"

    • BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }

      在结果评估周期进行期间发出的定期心跳。在对应的 span.outcome_evaluation_start 和 span.outcome_evaluation_end 事件之间区分"评估正在积极运行"和"评估卡住"。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_ongoing"

        • "span.outcome_evaluation_ongoing"

    • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

      user.define_outcome 输入事件的回显。携带服务器生成的 outcome_id，后续的 span.outcome_evaluation_* 事件引用该 ID。

      • id: string

        此事件的唯一标识符。

      • description: string

        代理应产出的内容。 从输入事件复制。

      • max_iterations: number

        放弃前的评估-修订周期。默认 3，最大 20。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。被 span.outcome_evaluation_* 事件和会话的 outcome_evaluations 列表引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

        用于评估结果质量的评分标准。

        • BetaManagedAgentsFileRubric object { file_id, type }

          通过 Files API 上传的文件引用的评分标准。

          • file_id: string

            评分标准文件的 ID。

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          以文本形式内联提供的评分标准内容。

          • content: string

            评分标准内容。纯文本或 markdown——评分者将其视为自由格式文本。

          • type: "text"

            • "text"

      • type: "user.define_outcome"

        • "user.define_outcome"

    • BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }

      当会话被删除时发出。终止所有活动的事件流 — 不会再为此会话发出更多事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.deleted"

        • "session.deleted"

    • BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }

      会话线程已开始执行。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        开始运行的线程的公共 sthr_ ID。

      • type: "session.thread_status_running"

        • "session.thread_status_running"

    • BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }

      会话线程已让出并正在等待输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        进入空闲状态的线程的公共 sthr_ ID。

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

      • type: "session.thread_status_idle"

        • "session.thread_status_idle"

    • BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }

      会话线程已终止，不再接受输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        已终止线程的公共 sthr_ ID。

      • type: "session.thread_status_terminated"

        • "session.thread_status_terminated"

    • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

      客户端发送的事件，提供代理工具集工具执行的结果。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

      • id: string

        此事件的唯一标识符。

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      会话线程遇到瞬态错误，正在自动重试。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        正在重试的线程的公共 sthr_ ID。

      • type: "session.thread_status_rescheduled"

        • "session.thread_status_rescheduled"

    • BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 3 more }

      当 UpdateSession 请求更改了至少一个字段时发出。仅携带已更改的字段；未出现的字段不是更新的一部分。新配置从下一轮开始生效。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.updated"

        • "session.updated"

      • agent: optional BetaManagedAgentsSessionAgent

        为 session 解析的 agent 定义。session 创建时 agent 的快照。

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          模型标识符和配置。

          • id: BetaManagedAgentsModel

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              驱动代理的模型。

              详情和选项请参阅 models。

              • "claude-opus-4-7"

                适用于长时间运行代理和编码的前沿智能

              • "claude-opus-4-6"

                用于构建代理和编码的最智能模型

              • "claude-sonnet-4-6"

                速度与智能的最佳组合

              • "claude-haiku-4-5"

                具有接近前沿智能的最快模型

              • "claude-haiku-4-5-20251001"

                具有接近前沿智能的最快模型

              • "claude-opus-4-5"

                结合最大智能与实用性能的高端模型

              • "claude-opus-4-5-20251101"

                结合最大智能与实用性能的高端模型

              • "claude-sonnet-4-5"

                用于代理和编码的高性能模型

              • "claude-sonnet-4-5-20250929"

                用于代理和编码的高性能模型

            • string

          • speed: optional "standard" or "fast"

            推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

            • "standard"

            • "fast"

        • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

          解析的协调器拓扑，包含每个成员的完整 agent 定义。

          • agents: array of BetaManagedAgentsSessionThreadAgent

            协调器可能作为会话线程生成的完整 agent 定义。

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              模型标识符和配置。

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                已解析的 Anthropic 托管技能。

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                已解析的用户创建的自定义技能。

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    内置代理工具标识符。

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                      • type: "always_ask"

                        • "always_ask"

                • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                  代理工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                  MCP 服务器所有工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                API 响应中返回的自定义工具。

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  自定义工具输入参数的 JSON Schema。

                  • properties: optional map[unknown]

                    定义工具输入参数的 JSON Schema 属性。

                  • required: optional array of string

                    必需属性名称列表。

                  • type: optional "object"

                    工具输入 schema 必须为 'object'。

                    • "object"

                • name: string

                • type: "custom"

                  • "custom"

            • type: "agent"

              • "agent"

            • version: number

          • type: "coordinator"

            • "coordinator"

        • name: string

        • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            已解析的 Anthropic 托管技能。

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            已解析的用户创建的自定义技能。

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            API 响应中返回的自定义工具。

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        更新后会话的完整元数据包。当更新设置了非空元数据时存在；当元数据未更改或清空时不存在。

      • title: optional string

        会话的新标题。仅在更新更改了标题时存在。

Beta Managed Agents Text Block

  • BetaManagedAgentsTextBlock object { text, type }

    常规文本内容。

    • text: string

      文本内容。

    • type: "text"

      • "text"

Beta Managed Agents Text Rubric

  • BetaManagedAgentsTextRubric object { content, type }

    以文本形式内联提供的评分标准内容。

    • content: string

      评分标准内容。纯文本或 markdown — 评分者将其视为自由格式文本。

    • type: "text"

      • "text"

Beta Managed Agents Text Rubric Params

  • BetaManagedAgentsTextRubricParams object { content, type }

    以文本形式内联提供的评分标准内容。

    • content: string

      评分标准内容。纯文本或 markdown — 评分者将其视为自由格式文本。 最多 262144 个字符。

    • type: "text"

      • "text"

Beta Managed Agents Unknown Error

  • BetaManagedAgentsUnknownError object { message, retry_status, type }

    会话执行期间发生未知或意外错误。 回退变体；无法识别新错误代码的客户端可以仅匹配'retry_status 和 message。

    • message: string

      人类可读的错误描述。

    • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      客户端应对此错误采取的下一步操作。

      • BetaManagedAgentsRetryStatusRetrying object { type }

        服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

        • type: "retrying"

          • "retrying"

      • BetaManagedAgentsRetryStatusExhausted object { type }

        此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        会话遇到终止性错误，将转换为 terminated 状态。

        • type: "terminal"

          • "terminal"

    • type: "unknown_error"

      • "unknown_error"

Beta Managed Agents URL Document Source

  • BetaManagedAgentsURLDocumentSource object { type, url }

    通过 URL 引用的文档。

    • type: "url"

      • "url"

    • url: string

      要获取的文档 URL。

Beta Managed Agents URL Image Source

  • BetaManagedAgentsURLImageSource object { type, url }

    通过 URL 引用的图片。

    • type: "url"

      • "url"

    • url: string

      要获取的图片 URL。

Beta Managed Agents User Custom Tool Result Event

  • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

    客户端发送的事件，提供自定义工具执行的结果。

    • id: string

      此事件的唯一标识符。

    • custom_tool_use_id: string

      ?????? agent.custom_tool_use ??? ID??????? session.status_idle ??? stop_reason.event_ids ??????

    • type: "user.custom_tool_result"

      • "user.custom_tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      工具返回的结果内容。

      • BetaManagedAgentsTextBlock object { text, type }

        常规文本内容。

        • text: string

          文本内容。

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        直接指定为 base64 数据或通过 URL 引用的图片内容。

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          图片源变体的联合类型。

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            Base64 编码的图片数据。

            • data: string

              Base64 编码的图片数据。

            • media_type: string

              图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsURLImageSource object { type, url }

            通过 URL 引用的图片。

            • type: "url"

              • "url"

            • url: string

              要获取的图片 URL。

          • BetaManagedAgentsFileImageSource object { file_id, type }

            通过文件 ID 引用的图片。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          文档源变体的联合类型。

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            Base64 编码的文档数据。

            • data: string

              Base64 编码的文档数据。

            • media_type: string

              文档的 MIME 类型（例如 "application/pdf"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

            纯文本文档内容。

            • data: string

              纯文本内容。

            • media_type: "text/plain"

              文本内容的 MIME 类型。必须为 "text/plain"。

              • "text/plain"

            • type: "text"

              • "text"

          • BetaManagedAgentsURLDocumentSource object { type, url }

            通过 URL 引用的文档。

            • type: "url"

              • "url"

            • url: string

              要获取的文档 URL。

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            通过文件 ID 引用的文档。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          为模型提供的关于文档的额外上下文。

        • title: optional string

          文档的标题。

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        包含网络搜索结果的块。

        • citations: BetaManagedAgentsSearchResultCitations

          搜索结果的引用设置。

          • enabled: boolean

            此搜索结果是否启用引用。

        • content: array of BetaManagedAgentsSearchResultContent

          搜索结果中的文本内容块数组。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • source: string

          搜索结果的 URL 来源。

        • title: string

          搜索结果的标题。

        • type: "search_result"

          • "search_result"

    • is_error: optional boolean

      工具执行是否导致错误。

    • processed_at: optional string

      RFC 3339 格式的时间戳

    • session_thread_id: optional string

      将此结果路由到子代理线程。从 agent.custom_tool_use 事件的 session_thread_id 复制。

Beta Managed Agents User Custom Tool Result Event Params

  • BetaManagedAgentsUserCustomToolResultEventParams object { custom_tool_use_id, type, content, is_error }

    提供自定义工具执行结果的参数。

    • custom_tool_use_id: string

      ?????? agent.custom_tool_use ??? ID??????? session.status_idle ??? stop_reason.event_ids ??????

    • type: "user.custom_tool_result"

      • "user.custom_tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      工具返回的结果内容。

      • BetaManagedAgentsTextBlock object { text, type }

        常规文本内容。

        • text: string

          文本内容。

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        直接指定为 base64 数据或通过 URL 引用的图片内容。

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          图片源变体的联合类型。

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            Base64 编码的图片数据。

            • data: string

              Base64 编码的图片数据。

            • media_type: string

              图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsURLImageSource object { type, url }

            通过 URL 引用的图片。

            • type: "url"

              • "url"

            • url: string

              要获取的图片 URL。

          • BetaManagedAgentsFileImageSource object { file_id, type }

            通过文件 ID 引用的图片。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          文档源变体的联合类型。

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            Base64 编码的文档数据。

            • data: string

              Base64 编码的文档数据。

            • media_type: string

              文档的 MIME 类型（例如 "application/pdf"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

            纯文本文档内容。

            • data: string

              纯文本内容。

            • media_type: "text/plain"

              文本内容的 MIME 类型。必须为 "text/plain"。

              • "text/plain"

            • type: "text"

              • "text"

          • BetaManagedAgentsURLDocumentSource object { type, url }

            通过 URL 引用的文档。

            • type: "url"

              • "url"

            • url: string

              要获取的文档 URL。

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            通过文件 ID 引用的文档。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          为模型提供的关于文档的额外上下文。

        • title: optional string

          文档的标题。

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        包含网络搜索结果的块。

        • citations: BetaManagedAgentsSearchResultCitations

          搜索结果的引用设置。

          • enabled: boolean

            此搜索结果是否启用引用。

        • content: array of BetaManagedAgentsSearchResultContent

          搜索结果中的文本内容块数组。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • source: string

          搜索结果的 URL 来源。

        • title: string

          搜索结果的标题。

        • type: "search_result"

          • "search_result"

    • is_error: optional boolean

      工具执行是否导致错误。

Beta Managed Agents User Define Outcome Event

  • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

    user.define_outcome 输入事件的回显。携带服务器生成的 outcome_id，后续的 span.outcome_evaluation_* 事件引用该 ID。

    • id: string

      此事件的唯一标识符。

    • description: string

      代理应产出的内容。 从输入事件复制。

    • max_iterations: number

      放弃前的评估-修订周期。默认 3，最大 20。

    • outcome_id: string

      服务器为此结果生成的 outc_ ID。被 span.outcome_evaluation_* 事件和会话的 outcome_evaluations 列表引用。

    • processed_at: string

      RFC 3339 格式的时间戳

    • rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

      用于评估结果质量的评分标准。

      • BetaManagedAgentsFileRubric object { file_id, type }

        通过 Files API 上传的文件引用的评分标准。

        • file_id: string

          评分标准文件的 ID。

        • type: "file"

          • "file"

      • BetaManagedAgentsTextRubric object { content, type }

        以文本形式内联提供的评分标准内容。

        • content: string

          评分标准内容。纯文本或 markdown — 评分者将其视为自由格式文本。

        • type: "text"

          • "text"

    • type: "user.define_outcome"

      • "user.define_outcome"

Beta Managed Agents User Define Outcome Event Params

  • BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }

    定义代理应努力达成的结果的参数。代理在收到后即开始工作。

    • description: string

      代理应产出的内容。 这是任务规范。

    • rubric: BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams

      用于评估结果质量的评分标准。

      • BetaManagedAgentsFileRubricParams object { file_id, type }

        通过 Files API 上传的文件引用的评分标准。

        • file_id: string

          评分标准文件的 ID。

        • type: "file"

          • "file"

      • BetaManagedAgentsTextRubricParams object { content, type }

        以文本形式内联提供的评分标准内容。

        • content: string

          评分标准内容。纯文本或 markdown — 评分者将其视为自由格式文本。 最多 262144 个字符。

        • type: "text"

          • "text"

    • type: "user.define_outcome"

      • "user.define_outcome"

    • max_iterations: optional number

      评估→-修订周期，直到放弃。默认 3，最大 20。

Beta Managed Agents User Interrupt Event

  • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

    暂停代理执行并将控制权返回给用户的中断事件。

    • id: string

      此事件的唯一标识符。

    • type: "user.interrupt"

      • "user.interrupt"

    • processed_at: optional string

      RFC 3339 格式的时间戳

    • session_thread_id: optional string

      如果不存在，中断多代理会话中每个未归档的线程（或单代理会话中仅中断主线程）。如果存在，仅中断指定的线程。

Beta Managed Agents User Interrupt Event Params

  • BetaManagedAgentsUserInterruptEventParams object { type, session_thread_id }

    发送中断以暂停代理的参数。

    • type: "user.interrupt"

      • "user.interrupt"

    • session_thread_id: optional string

      如果不存在，中断多代理会话中每个未归档的线程（或单代理会话中仅中断主线程）。如果存在，仅中断指定的线程。

Beta Managed Agents User Message Event

  • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

    会话对话中的用户消息事件。

    • id: string

      此事件的唯一标识符。

    • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

      组成用户消息的内容块数组。

      • BetaManagedAgentsTextBlock object { text, type }

        常规文本内容。

        • text: string

          文本内容。

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        直接指定为 base64 数据或通过 URL 引用的图片内容。

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          图片源变体的联合类型。

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            Base64 编码的图片数据。

            • data: string

              Base64 编码的图片数据。

            • media_type: string

              图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsURLImageSource object { type, url }

            通过 URL 引用的图片。

            • type: "url"

              • "url"

            • url: string

              要获取的图片 URL。

          • BetaManagedAgentsFileImageSource object { file_id, type }

            通过文件 ID 引用的图片。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          文档源变体的联合类型。

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            Base64 编码的文档数据。

            • data: string

              Base64 编码的文档数据。

            • media_type: string

              文档的 MIME 类型（例如 "application/pdf"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

            纯文本文档内容。

            • data: string

              纯文本内容。

            • media_type: "text/plain"

              文本内容的 MIME 类型。必须为 "text/plain"。

              • "text/plain"

            • type: "text"

              • "text"

          • BetaManagedAgentsURLDocumentSource object { type, url }

            通过 URL 引用的文档。

            • type: "url"

              • "url"

            • url: string

              要获取的文档 URL。

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            通过文件 ID 引用的文档。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          为模型提供的关于文档的额外上下文。

        • title: optional string

          文档的标题。

    • type: "user.message"

      • "user.message"

    • processed_at: optional string

      RFC 3339 格式的时间戳

Beta Managed Agents User Message Event Params

  • BetaManagedAgentsUserMessageEventParams object { content, type }

    向会话发送用户消息的参数。

    • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

      用户消息的内容块数组。

      • BetaManagedAgentsTextBlock object { text, type }

        常规文本内容。

        • text: string

          文本内容。

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        直接指定为 base64 数据或通过 URL 引用的图片内容。

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          图片源变体的联合类型。

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            Base64 编码的图片数据。

            • data: string

              Base64 编码的图片数据。

            • media_type: string

              图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsURLImageSource object { type, url }

            通过 URL 引用的图片。

            • type: "url"

              • "url"

            • url: string

              要获取的图片 URL。

          • BetaManagedAgentsFileImageSource object { file_id, type }

            通过文件 ID 引用的图片。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          文档源变体的联合类型。

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            Base64 编码的文档数据。

            • data: string

              Base64 编码的文档数据。

            • media_type: string

              文档的 MIME 类型（例如 "application/pdf"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

            纯文本文档内容。

            • data: string

              纯文本内容。

            • media_type: "text/plain"

              文本内容的 MIME 类型。必须为 "text/plain"。

              • "text/plain"

            • type: "text"

              • "text"

          • BetaManagedAgentsURLDocumentSource object { type, url }

            通过 URL 引用的文档。

            • type: "url"

              • "url"

            • url: string

              要获取的文档 URL。

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            通过文件 ID 引用的文档。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          为模型提供的关于文档的额外上下文。

        • title: optional string

          文档的标题。

    • type: "user.message"

      • "user.message"

Beta Managed Agents User Tool Confirmation Event

  • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

    批准或拒绝待处理工具执行的工具确认事件。

    • id: string

      此事件的唯一标识符。

    • result: "allow" or "deny"

      UserToolConfirmationResult 枚举

      • "allow"

      • "deny"

    • tool_use_id: string

      ?????? agent.tool_use ? agent.mcp_tool_use ??? ID??????? session.status_idle ??? stop_reason.event_ids ??????

    • type: "user.tool_confirmation"

      • "user.tool_confirmation"

    • deny_message: optional string

      可选消息，为 'deny' 决定提供上下文。仅在结果为 'deny' 时允许。

    • processed_at: optional string

      RFC 3339 格式的时间戳

    • session_thread_id: optional string

      设置后，确认路由到此子代理的线程而非主线程。从触发批准的 agent.tool_use 或 agent.mcp_tool_use 事件的 session_thread_id 回显此值。

Beta Managed Agents User Tool Confirmation Event Params

  • BetaManagedAgentsUserToolConfirmationEventParams object { result, tool_use_id, type, deny_message }

    确认或拒绝工具执行请求的参数。

    • result: "allow" or "deny"

      UserToolConfirmationResult 枚举

      • "allow"

      • "deny"

    • tool_use_id: string

      ?????? agent.tool_use ? agent.mcp_tool_use ??? ID??????? session.status_idle ??? stop_reason.event_ids ??????

    • type: "user.tool_confirmation"

      • "user.tool_confirmation"

    • deny_message: optional string

      可选消息，为 'deny' 决定提供上下文。仅在结果为 'deny' 时允许。

Beta Managed Agents User Tool Result Event Params

  • BetaManagedAgentsUserToolResultEventParams object { tool_use_id, type, content, is_error }

    提供代理工具集工具执行结果的参数。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

    • tool_use_id: string

      此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

    • type: "user.tool_result"

      • "user.tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      工具返回的结果内容。

      • BetaManagedAgentsTextBlock object { text, type }

        常规文本内容。

        • text: string

          文本内容。

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        直接指定为 base64 数据或通过 URL 引用的图片内容。

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          图片源变体的联合类型。

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            Base64 编码的图片数据。

            • data: string

              Base64 编码的图片数据。

            • media_type: string

              图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsURLImageSource object { type, url }

            通过 URL 引用的图片。

            • type: "url"

              • "url"

            • url: string

              要获取的图片 URL。

          • BetaManagedAgentsFileImageSource object { file_id, type }

            通过文件 ID 引用的图片。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          文档源变体的联合类型。

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            Base64 编码的文档数据。

            • data: string

              Base64 编码的文档数据。

            • media_type: string

              文档的 MIME 类型（例如 "application/pdf"）。

            • type: "base64"

              • "base64"

          • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

            纯文本文档内容。

            • data: string

              纯文本内容。

            • media_type: "text/plain"

              文本内容的 MIME 类型。必须为 "text/plain"。

              • "text/plain"

            • type: "text"

              • "text"

          • BetaManagedAgentsURLDocumentSource object { type, url }

            通过 URL 引用的文档。

            • type: "url"

              • "url"

            • url: string

              要获取的文档 URL。

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            通过文件 ID 引用的文档。

            • file_id: string

              先前上传文件的 ID。

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          为模型提供的关于文档的额外上下文。

        • title: optional string

          文档的标题。

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        包含网络搜索结果的块。

        • citations: BetaManagedAgentsSearchResultCitations

          搜索结果的引用设置。

          • enabled: boolean

            此搜索结果是否启用引用。

        • content: array of BetaManagedAgentsSearchResultContent

          搜索结果中的文本内容块数组。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • source: string

          搜索结果的 URL 来源。

        • title: string

          搜索结果的标题。

        • type: "search_result"

          • "search_result"

    • is_error: optional boolean

      工具执行是否导致错误。

Resources

添加会话资源

post /v1/sessions/{session_id}/resources

添加会话资源

路径参数

  • session_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

请求体参数

  • file_id: string

    先前上传文件的 ID。

  • type: "file"

    • "file"

  • mount_path: optional string

    容器中的挂载路径。默认为 /mnt/session/uploads/<file_id>。

返回值

  • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

    • id: string

    • created_at: string

      RFC 3339 格式的时间戳

    • file_id: string

    • mount_path: string

    • type: "file"

      • "file"

    • updated_at: string

      RFC 3339 格式的时间戳

示例

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"
        }'

响应

{
  "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"
}

列出会话资源

get /v1/sessions/{session_id}/resources

列出会话资源

路径参数

  • session_id: string

查询参数

  • limit: optional number

    每页返回的最大资源数（最多 1000）。如果省略，返回所有资源。

  • page: optional string

    来自先前响应 next_page 字段的不透明游标。

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • data: array of BetaManagedAgentsSessionResource

    会话的资源，按 created_at 排序。

    • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

      • id: string

      • created_at: string

        RFC 3339 格式的时间戳

      • mount_path: string

      • type: "github_repository"

        • "github_repository"

      • updated_at: string

        RFC 3339 格式的时间戳

      • url: string

      • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

        • BetaManagedAgentsBranchCheckout object { name, type }

          • name: string

            要检出的分支名称。

          • type: "branch"

            • "branch"

        • BetaManagedAgentsCommitCheckout object { sha, type }

          • sha: string

            要检出的完整提交 SHA。

          • type: "commit"

            • "commit"

    • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

      • id: string

      • created_at: string

        RFC 3339 格式的时间戳

      • file_id: string

      • mount_path: string

      • type: "file"

        • "file"

      • updated_at: string

        RFC 3339 格式的时间戳

    • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

      附加到代理会话的记忆存储。

      • memory_store_id: string

        记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

      • type: "memory_store"

        • "memory_store"

      • access: optional "read_write" or "read_only"

        附加记忆存储的访问模式。

        • "read_write"

        • "read_only"

      • description: optional string

        记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

      • instructions: optional string

        每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

      • mount_path: optional string

        存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

      • name: optional string

        记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

  • next_page: optional string

    下一页的不透明游标。没有更多结果时为 null。

示例

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"

响应

{
  "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 /v1/sessions/{session_id}/resources/{resource_id}

获取会话 Resource

路径参数

  • session_id: string

  • resource_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

    • id: string

    • created_at: string

      RFC 3339 格式的时间戳

    • mount_path: string

    • type: "github_repository"

      • "github_repository"

    • updated_at: string

      RFC 3339 格式的时间戳

    • url: string

    • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

      • BetaManagedAgentsBranchCheckout object { name, type }

        • name: string

          要检出的分支名称。

        • type: "branch"

          • "branch"

      • BetaManagedAgentsCommitCheckout object { sha, type }

        • sha: string

          要检出的完整提交 SHA。

        • type: "commit"

          • "commit"

  • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

    • id: string

    • created_at: string

      RFC 3339 格式的时间戳

    • file_id: string

    • mount_path: string

    • type: "file"

      • "file"

    • updated_at: string

      RFC 3339 格式的时间戳

  • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

    附加到代理会话的记忆存储。

    • memory_store_id: string

      记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

    • type: "memory_store"

      • "memory_store"

    • access: optional "read_write" or "read_only"

      附加记忆存储的访问模式。

      • "read_write"

      • "read_only"

    • description: optional string

      记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

    • instructions: optional string

      每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

    • mount_path: optional string

      存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

    • name: optional string

      记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

示例

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"

响应

{
  "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"
  }
}

更新会话资源

post /v1/sessions/{session_id}/resources/{resource_id}

更新会话 Resource

路径参数

  • session_id: string

  • resource_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

请求体参数

  • authorization_token: string

    资源的新授权令牌。目前只有 github_repository 资源支持令牌轮换。

返回值

  • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

    • id: string

    • created_at: string

      RFC 3339 格式的时间戳

    • mount_path: string

    • type: "github_repository"

      • "github_repository"

    • updated_at: string

      RFC 3339 格式的时间戳

    • url: string

    • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

      • BetaManagedAgentsBranchCheckout object { name, type }

        • name: string

          要检出的分支名称。

        • type: "branch"

          • "branch"

      • BetaManagedAgentsCommitCheckout object { sha, type }

        • sha: string

          要检出的完整提交 SHA。

        • type: "commit"

          • "commit"

  • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

    • id: string

    • created_at: string

      RFC 3339 格式的时间戳

    • file_id: string

    • mount_path: string

    • type: "file"

      • "file"

    • updated_at: string

      RFC 3339 格式的时间戳

  • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

    附加到代理会话的记忆存储。

    • memory_store_id: string

      记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

    • type: "memory_store"

      • "memory_store"

    • access: optional "read_write" or "read_only"

      附加记忆存储的访问模式。

      • "read_write"

      • "read_only"

    • description: optional string

      记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

    • instructions: optional string

      每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

    • mount_path: optional string

      存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

    • name: optional string

      记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

示例

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"
        }'

响应

{
  "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 /v1/sessions/{session_id}/resources/{resource_id}

删除会话 Resource

路径参数

  • session_id: string

  • resource_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • BetaManagedAgentsDeleteSessionResource object { id, type }

    确认资源已删除。

    • id: string

    • type: "session_resource_deleted"

      • "session_resource_deleted"

示例

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"

响应

{
  "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
  "type": "session_resource_deleted"
}

领域类型

Beta Managed Agents 删除会话 Resource

  • BetaManagedAgentsDeleteSessionResource object { id, type }

    确认资源已删除。

    • id: string

    • type: "session_resource_deleted"

      • "session_resource_deleted"

Beta Managed Agents File Resource

  • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

    • id: string

    • created_at: string

      RFC 3339 格式的时间戳

    • file_id: string

    • mount_path: string

    • type: "file"

      • "file"

    • updated_at: string

      RFC 3339 格式的时间戳

Beta Managed Agents GitHub Repository Resource

  • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

    • id: string

    • created_at: string

      RFC 3339 格式的时间戳

    • mount_path: string

    • type: "github_repository"

      • "github_repository"

    • updated_at: string

      RFC 3339 格式的时间戳

    • url: string

    • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

      • BetaManagedAgentsBranchCheckout object { name, type }

        • name: string

          要检出的分支名称。

        • type: "branch"

          • "branch"

      • BetaManagedAgentsCommitCheckout object { sha, type }

        • sha: string

          要检出的完整提交 SHA。

        • type: "commit"

          • "commit"

Beta Managed Agents Memory Store Resource

  • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

    附加到代理会话的记忆存储。

    • memory_store_id: string

      记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

    • type: "memory_store"

      • "memory_store"

    • access: optional "read_write" or "read_only"

      附加记忆存储的访问模式。

      • "read_write"

      • "read_only"

    • description: optional string

      记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

    • instructions: optional string

      每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

    • mount_path: optional string

      存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

    • name: optional string

      记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

Beta Managed Agents Session Resource

  • BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource or BetaManagedAgentsMemoryStoreResource

    附加到代理会话的记忆存储。

    • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

      • id: string

      • created_at: string

        RFC 3339 格式的时间戳

      • mount_path: string

      • type: "github_repository"

        • "github_repository"

      • updated_at: string

        RFC 3339 格式的时间戳

      • url: string

      • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

        • BetaManagedAgentsBranchCheckout object { name, type }

          • name: string

            要检出的分支名称。

          • type: "branch"

            • "branch"

        • BetaManagedAgentsCommitCheckout object { sha, type }

          • sha: string

            要检出的完整提交 SHA。

          • type: "commit"

            • "commit"

    • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

      • id: string

      • created_at: string

        RFC 3339 格式的时间戳

      • file_id: string

      • mount_path: string

      • type: "file"

        • "file"

      • updated_at: string

        RFC 3339 格式的时间戳

    • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

      附加到代理会话的记忆存储。

      • memory_store_id: string

        记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

      • type: "memory_store"

        • "memory_store"

      • access: optional "read_write" or "read_only"

        附加记忆存储的访问模式。

        • "read_write"

        • "read_only"

      • description: optional string

        记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

      • instructions: optional string

        每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

      • mount_path: optional string

        存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

      • name: optional string

        记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

Resource Retrieve 响应

  • ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource or BetaManagedAgentsMemoryStoreResource

    请求的会话资源。

    • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

      • id: string

      • created_at: string

        RFC 3339 格式的时间戳

      • mount_path: string

      • type: "github_repository"

        • "github_repository"

      • updated_at: string

        RFC 3339 格式的时间戳

      • url: string

      • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

        • BetaManagedAgentsBranchCheckout object { name, type }

          • name: string

            要检出的分支名称。

          • type: "branch"

            • "branch"

        • BetaManagedAgentsCommitCheckout object { sha, type }

          • sha: string

            要检出的完整提交 SHA。

          • type: "commit"

            • "commit"

    • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

      • id: string

      • created_at: string

        RFC 3339 格式的时间戳

      • file_id: string

      • mount_path: string

      • type: "file"

        • "file"

      • updated_at: string

        RFC 3339 格式的时间戳

    • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

      附加到代理会话的记忆存储。

      • memory_store_id: string

        记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

      • type: "memory_store"

        • "memory_store"

      • access: optional "read_write" or "read_only"

        附加记忆存储的访问模式。

        • "read_write"

        • "read_only"

      • description: optional string

        记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

      • instructions: optional string

        每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

      • mount_path: optional string

        存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

      • name: optional string

        记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

Resource Update 响应

  • ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource or BetaManagedAgentsMemoryStoreResource

    更新后的会话资源。

    • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

      • id: string

      • created_at: string

        RFC 3339 格式的时间戳

      • mount_path: string

      • type: "github_repository"

        • "github_repository"

      • updated_at: string

        RFC 3339 格式的时间戳

      • url: string

      • checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

        • BetaManagedAgentsBranchCheckout object { name, type }

          • name: string

            要检出的分支名称。

          • type: "branch"

            • "branch"

        • BetaManagedAgentsCommitCheckout object { sha, type }

          • sha: string

            要检出的完整提交 SHA。

          • type: "commit"

            • "commit"

    • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

      • id: string

      • created_at: string

        RFC 3339 格式的时间戳

      • file_id: string

      • mount_path: string

      • type: "file"

        • "file"

      • updated_at: string

        RFC 3339 格式的时间戳

    • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

      附加到代理会话的记忆存储。

      • memory_store_id: string

        记忆存储 ID（memstore_...）。必须属于调用者的组织和工作区。

      • type: "memory_store"

        • "memory_store"

      • access: optional "read_write" or "read_only"

        附加记忆存储的访问模式。

        • "read_write"

        • "read_only"

      • description: optional string

        记忆存储的描述，在附加时快照。渲染到代理的系统提示中。存储无描述时为空字符串。

      • instructions: optional string

        每次附加时对代理如何使用此存储的指导。渲染到系统提示的记忆部分。最多 4096 个字符。

      • mount_path: optional string

        存储在会话容器中挂载的文件系统路径，例如 /mnt/memory/user-preferences。从存储名称派生。仅输出。

      • name: optional string

        记忆存储的显示名称，在附加时快照。后续对存储名称的编辑不会传播到此资源。

Threads

列出会话线程

get /v1/sessions/{session_id}/threads

列出会话线程

路径参数

  • session_id: string

查询参数

  • limit: optional number

    每页最大结果数。默认为 1000。

  • page: optional string

    来自先前响应 next_page 的不透明分页游标。 Forward-only.

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • data: optional array of BetaManagedAgentsSessionThread

    会话中的线程，主线程在前，然后按生成顺序排列子线程。

    • id: string

      此线程的唯一标识符。

    • agent: BetaManagedAgentsSessionThreadAgent

      单个 session_thread 的已解析 agent 定义。线程创建时代理的快照。多代理名册不在此重复；请从 Session.agent 读取。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

          • skill_id: string

          • type: "anthropic"

            • "anthropic"

          • version: string

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

          • skill_id: string

          • type: "custom"

            • "custom"

          • version: string

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • configs: array of BetaManagedAgentsAgentToolConfig

            • enabled: boolean

            • name: "bash" or "edit" or "read" or 5 more

              内置代理工具标识符。

              • "bash"

              • "edit"

              • "read"

              • "write"

              • "glob"

              • "grep"

              • "web_fetch"

              • "web_search"

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

                • type: "always_allow"

                  • "always_allow"

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

                • type: "always_ask"

                  • "always_ask"

          • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

            代理工具的已解析默认配置。

            • enabled: boolean

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • type: "agent_toolset_20260401"

            • "agent_toolset_20260401"

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • configs: array of BetaManagedAgentsMCPToolConfig

            • enabled: boolean

            • name: string

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

            来自 MCP 服务器的所有工具的已解析默认配置。

            • enabled: boolean

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • mcp_server_name: string

          • type: "mcp_toolset"

            • "mcp_toolset"

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

          • description: string

          • input_schema: BetaManagedAgentsCustomToolInputSchema

            自定义工具输入参数的 JSON Schema。

            • properties: optional map[unknown]

              定义工具输入参数的 JSON Schema 属性。

            • required: optional array of string

              必需属性名称列表。

            • type: optional "object"

              工具输入 schema 必须为 'object'。

              • "object"

          • name: string

          • type: "custom"

            • "custom"

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      RFC 3339 格式的时间戳

    • created_at: string

      RFC 3339 格式的时间戳

    • parent_thread_id: string

      生成此线程的父线程。主线程为 null。

    • session_id: string

      此线程所属的会话。

    • stats: BetaManagedAgentsSessionThreadStats

      会话线程的计时统计。

      • active_seconds: optional number

        线程积极运行的累计时间（秒）。不包括空闲时间。

      • duration_seconds: optional number

        自线程创建以来的经过时间（秒）。对于已归档的线程，冻结在最终更新时。

      • startup_seconds: optional number

        线程开始运行的时间（秒）。子线程为零，因为它们立即启动。

    • status: BetaManagedAgentsSessionThreadStatus

      SessionThreadStatus 枚举

      • "running"

      • "idle"

      • "rescheduling"

      • "terminated"

    • type: "session_thread"

      • "session_thread"

    • updated_at: string

      RFC 3339 格式的时间戳

    • usage: BetaManagedAgentsSessionThreadUsage

      会话线程在所有轮次中的累计 token 使用量。

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        按缓存生命周期细分的提示缓存创建 token 使用量。

        • ephemeral_1h_input_tokens: optional number

          用于创建 1 小时临时缓存条目的 token 数。

        • ephemeral_5m_input_tokens: optional number

          用于创建 5 分钟临时缓存条目的 token 数。

      • cache_read_input_tokens: optional number

        从提示缓存读取的 token 总数。

      • input_tokens: optional number

        所有轮次消耗的输入 token 总数。

      • output_tokens: optional number

        所有轮次生成的输出 token 总数。

  • next_page: optional string

    下一页的不透明游标。没有更多结果时为 null。

示例

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"

响应

{
  "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-sonnet-4-6",
          "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"
                }
              }
            ],
            "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": {
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 0
        },
        "cache_read_input_tokens": 0,
        "input_tokens": 0,
        "output_tokens": 0
      }
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}

获取会话线程

get /v1/sessions/{session_id}/threads/{thread_id}

获取会话 Thread

路径参数

  • session_id: string

  • thread_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • BetaManagedAgentsSessionThread object { id, agent, archived_at, 8 more }

    session 中的执行线程。每个会话有一个主线程加上协调器生成的零个或多个子线程。

    • id: string

      此线程的唯一标识符。

    • agent: BetaManagedAgentsSessionThreadAgent

      单个 session_thread 的已解析 agent 定义。线程创建时代理的快照。多代理名册不在此重复；请从 Session.agent 读取。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

          • skill_id: string

          • type: "anthropic"

            • "anthropic"

          • version: string

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

          • skill_id: string

          • type: "custom"

            • "custom"

          • version: string

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • configs: array of BetaManagedAgentsAgentToolConfig

            • enabled: boolean

            • name: "bash" or "edit" or "read" or 5 more

              内置代理工具标识符。

              • "bash"

              • "edit"

              • "read"

              • "write"

              • "glob"

              • "grep"

              • "web_fetch"

              • "web_search"

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

                • type: "always_allow"

                  • "always_allow"

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

                • type: "always_ask"

                  • "always_ask"

          • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

            代理工具的已解析默认配置。

            • enabled: boolean

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • type: "agent_toolset_20260401"

            • "agent_toolset_20260401"

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • configs: array of BetaManagedAgentsMCPToolConfig

            • enabled: boolean

            • name: string

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

            来自 MCP 服务器的所有工具的已解析默认配置。

            • enabled: boolean

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • mcp_server_name: string

          • type: "mcp_toolset"

            • "mcp_toolset"

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

          • description: string

          • input_schema: BetaManagedAgentsCustomToolInputSchema

            自定义工具输入参数的 JSON Schema。

            • properties: optional map[unknown]

              定义工具输入参数的 JSON Schema 属性。

            • required: optional array of string

              必需属性名称列表。

            • type: optional "object"

              工具输入 schema 必须为 'object'。

              • "object"

          • name: string

          • type: "custom"

            • "custom"

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      RFC 3339 格式的时间戳

    • created_at: string

      RFC 3339 格式的时间戳

    • parent_thread_id: string

      生成此线程的父线程。主线程为 null。

    • session_id: string

      此线程所属的会话。

    • stats: BetaManagedAgentsSessionThreadStats

      会话线程的计时统计。

      • active_seconds: optional number

        线程积极运行的累计时间（秒）。不包括空闲时间。

      • duration_seconds: optional number

        自线程创建以来的经过时间（秒）。对于已归档的线程，冻结在最终更新时。

      • startup_seconds: optional number

        线程开始运行的时间（秒）。子线程为零，因为它们立即启动。

    • status: BetaManagedAgentsSessionThreadStatus

      SessionThreadStatus 枚举

      • "running"

      • "idle"

      • "rescheduling"

      • "terminated"

    • type: "session_thread"

      • "session_thread"

    • updated_at: string

      RFC 3339 格式的时间戳

    • usage: BetaManagedAgentsSessionThreadUsage

      会话线程在所有轮次中的累计 token 使用量。

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        按缓存生命周期细分的提示缓存创建 token 使用量。

        • ephemeral_1h_input_tokens: optional number

          用于创建 1 小时临时缓存条目的 token 数。

        • ephemeral_5m_input_tokens: optional number

          用于创建 5 分钟临时缓存条目的 token 数。

      • cache_read_input_tokens: optional number

        从提示缓存读取的 token 总数。

      • input_tokens: optional number

        所有轮次消耗的输入 token 总数。

      • output_tokens: optional number

        所有轮次生成的输出 token 总数。

示例

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"

响应

{
  "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-sonnet-4-6",
      "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"
            }
          }
        ],
        "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": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  }
}

归档会话线程

post /v1/sessions/{session_id}/threads/{thread_id}/archive

归档会话 Thread

路径参数

  • session_id: string

  • thread_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • BetaManagedAgentsSessionThread object { id, agent, archived_at, 8 more }

    session 中的执行线程。每个会话有一个主线程加上协调器生成的零个或多个子线程。

    • id: string

      此线程的唯一标识符。

    • agent: BetaManagedAgentsSessionThreadAgent

      单个 session_thread 的已解析 agent 定义。线程创建时代理的快照。多代理名册不在此重复；请从 Session.agent 读取。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

          • skill_id: string

          • type: "anthropic"

            • "anthropic"

          • version: string

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

          • skill_id: string

          • type: "custom"

            • "custom"

          • version: string

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • configs: array of BetaManagedAgentsAgentToolConfig

            • enabled: boolean

            • name: "bash" or "edit" or "read" or 5 more

              内置代理工具标识符。

              • "bash"

              • "edit"

              • "read"

              • "write"

              • "glob"

              • "grep"

              • "web_fetch"

              • "web_search"

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

                • type: "always_allow"

                  • "always_allow"

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

                • type: "always_ask"

                  • "always_ask"

          • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

            代理工具的已解析默认配置。

            • enabled: boolean

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • type: "agent_toolset_20260401"

            • "agent_toolset_20260401"

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • configs: array of BetaManagedAgentsMCPToolConfig

            • enabled: boolean

            • name: string

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

            来自 MCP 服务器的所有工具的已解析默认配置。

            • enabled: boolean

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • mcp_server_name: string

          • type: "mcp_toolset"

            • "mcp_toolset"

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

          • description: string

          • input_schema: BetaManagedAgentsCustomToolInputSchema

            自定义工具输入参数的 JSON Schema。

            • properties: optional map[unknown]

              定义工具输入参数的 JSON Schema 属性。

            • required: optional array of string

              必需属性名称列表。

            • type: optional "object"

              工具输入 schema 必须为 'object'。

              • "object"

          • name: string

          • type: "custom"

            • "custom"

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      RFC 3339 格式的时间戳

    • created_at: string

      RFC 3339 格式的时间戳

    • parent_thread_id: string

      生成此线程的父线程。主线程为 null。

    • session_id: string

      此线程所属的会话。

    • stats: BetaManagedAgentsSessionThreadStats

      会话线程的计时统计。

      • active_seconds: optional number

        线程积极运行的累计时间（秒）。不包括空闲时间。

      • duration_seconds: optional number

        自线程创建以来的经过时间（秒）。对于已归档的线程，冻结在最终更新时。

      • startup_seconds: optional number

        线程开始运行的时间（秒）。子线程为零，因为它们立即启动。

    • status: BetaManagedAgentsSessionThreadStatus

      SessionThreadStatus 枚举

      • "running"

      • "idle"

      • "rescheduling"

      • "terminated"

    • type: "session_thread"

      • "session_thread"

    • updated_at: string

      RFC 3339 格式的时间戳

    • usage: BetaManagedAgentsSessionThreadUsage

      会话线程在所有轮次中的累计 token 使用量。

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        按缓存生命周期细分的提示缓存创建 token 使用量。

        • ephemeral_1h_input_tokens: optional number

          用于创建 1 小时临时缓存条目的 token 数。

        • ephemeral_5m_input_tokens: optional number

          用于创建 5 分钟临时缓存条目的 token 数。

      • cache_read_input_tokens: optional number

        从提示缓存读取的 token 总数。

      • input_tokens: optional number

        所有轮次消耗的输入 token 总数。

      • output_tokens: optional number

        所有轮次生成的输出 token 总数。

示例

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"

响应

{
  "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-sonnet-4-6",
      "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"
            }
          }
        ],
        "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": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  }
}

领域类型

Beta Managed Agents Session Thread

  • BetaManagedAgentsSessionThread object { id, agent, archived_at, 8 more }

    session 中的执行线程。每个会话有一个主线程加上协调器生成的零个或多个子线程。

    • id: string

      此线程的唯一标识符。

    • agent: BetaManagedAgentsSessionThreadAgent

      单个 session_thread 的已解析 agent 定义。线程创建时代理的快照。多代理名册不在此重复；请从 Session.agent 读取。

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        模型标识符和配置。

        • id: BetaManagedAgentsModel

          驱动代理的模型。

          详情和选项请参阅 models。

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7"

              适用于长时间运行代理和编码的前沿智能

            • "claude-opus-4-6"

              用于构建代理和编码的最智能模型

            • "claude-sonnet-4-6"

              速度与智能的最佳组合

            • "claude-haiku-4-5"

              具有接近前沿智能的最快模型

            • "claude-haiku-4-5-20251001"

              具有接近前沿智能的最快模型

            • "claude-opus-4-5"

              结合最大智能与实用性能的高端模型

            • "claude-opus-4-5-20251101"

              结合最大智能与实用性能的高端模型

            • "claude-sonnet-4-5"

              用于代理和编码的高性能模型

            • "claude-sonnet-4-5-20250929"

              用于代理和编码的高性能模型

          • string

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

      • name: string

      • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          已解析的 Anthropic 托管技能。

          • skill_id: string

          • type: "anthropic"

            • "anthropic"

          • version: string

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          已解析的用户创建的自定义技能。

          • skill_id: string

          • type: "custom"

            • "custom"

          • version: string

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • configs: array of BetaManagedAgentsAgentToolConfig

            • enabled: boolean

            • name: "bash" or "edit" or "read" or 5 more

              内置代理工具标识符。

              • "bash"

              • "edit"

              • "read"

              • "write"

              • "glob"

              • "grep"

              • "web_fetch"

              • "web_search"

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

                • type: "always_allow"

                  • "always_allow"

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

                • type: "always_ask"

                  • "always_ask"

          • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

            代理工具的已解析默认配置。

            • enabled: boolean

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • type: "agent_toolset_20260401"

            • "agent_toolset_20260401"

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • configs: array of BetaManagedAgentsMCPToolConfig

            • enabled: boolean

            • name: string

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

            来自 MCP 服务器的所有工具的已解析默认配置。

            • enabled: boolean

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              工具执行的权限策略。

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                工具调用无需用户确认即自动批准。

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                工具调用在执行前需要用户确认。

          • mcp_server_name: string

          • type: "mcp_toolset"

            • "mcp_toolset"

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          API 响应中返回的自定义工具。

          • description: string

          • input_schema: BetaManagedAgentsCustomToolInputSchema

            自定义工具输入参数的 JSON Schema。

            • properties: optional map[unknown]

              定义工具输入参数的 JSON Schema 属性。

            • required: optional array of string

              必需属性名称列表。

            • type: optional "object"

              工具输入 schema 必须为 'object'。

              • "object"

          • name: string

          • type: "custom"

            • "custom"

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      RFC 3339 格式的时间戳

    • created_at: string

      RFC 3339 格式的时间戳

    • parent_thread_id: string

      生成此线程的父线程。主线程为 null。

    • session_id: string

      此线程所属的会话。

    • stats: BetaManagedAgentsSessionThreadStats

      会话线程的计时统计。

      • active_seconds: optional number

        线程积极运行的累计时间（秒）。不包括空闲时间。

      • duration_seconds: optional number

        自线程创建以来的经过时间（秒）。对于已归档的线程，冻结在最终更新时。

      • startup_seconds: optional number

        线程开始运行的时间（秒）。子线程为零，因为它们立即启动。

    • status: BetaManagedAgentsSessionThreadStatus

      SessionThreadStatus 枚举

      • "running"

      • "idle"

      • "rescheduling"

      • "terminated"

    • type: "session_thread"

      • "session_thread"

    • updated_at: string

      RFC 3339 格式的时间戳

    • usage: BetaManagedAgentsSessionThreadUsage

      会话线程在所有轮次中的累计 token 使用量。

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        按缓存生命周期细分的提示缓存创建 token 使用量。

        • ephemeral_1h_input_tokens: optional number

          用于创建 1 小时临时缓存条目的 token 数。

        • ephemeral_5m_input_tokens: optional number

          用于创建 5 分钟临时缓存条目的 token 数。

      • cache_read_input_tokens: optional number

        从提示缓存读取的 token 总数。

      • input_tokens: optional number

        所有轮次消耗的输入 token 总数。

      • output_tokens: optional number

        所有轮次生成的输出 token 总数。

Beta Managed Agents Session Thread Stats

  • BetaManagedAgentsSessionThreadStats object { active_seconds, duration_seconds, startup_seconds }

    会话线程的计时统计。

    • active_seconds: optional number

      线程积极运行的累计时间（秒）。不包括空闲时间。

    • duration_seconds: optional number

      自线程创建以来的经过时间（秒）。对于已归档的线程，冻结在最终更新时。

    • startup_seconds: optional number

      线程开始运行的时间（秒）。子线程为零，因为它们立即启动。

Beta Managed Agents Session Thread Status

  • BetaManagedAgentsSessionThreadStatus = "running" or "idle" or "rescheduling" or "terminated"

    SessionThreadStatus 枚举

    • "running"

    • "idle"

    • "rescheduling"

    • "terminated"

Beta Managed Agents Session Thread Usage

  • BetaManagedAgentsSessionThreadUsage object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }

    会话线程在所有轮次中的累计 token 使用量。

    • cache_creation: optional BetaManagedAgentsCacheCreationUsage

      按缓存生命周期细分的提示缓存创建 token 使用量。

      • ephemeral_1h_input_tokens: optional number

        用于创建 1 小时临时缓存条目的 token 数。

      • ephemeral_5m_input_tokens: optional number

        用于创建 5 分钟临时缓存条目的 token 数。

    • cache_read_input_tokens: optional number

      从提示缓存读取的 token 总数。

    • input_tokens: optional number

      所有轮次消耗的输入 token 总数。

    • output_tokens: optional number

      所有轮次生成的输出 token 总数。

Beta Managed Agents 流式会话线程事件

  • BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 30 more

    单个线程流中的服务器发送事件。

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      会话对话中的用户消息事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        组成用户消息的内容块数组。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            图片源变体的联合类型。

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              Base64 编码的图片数据。

              • data: string

                Base64 编码的图片数据。

              • media_type: string

                图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsURLImageSource object { type, url }

              通过 URL 引用的图片。

              • type: "url"

                • "url"

              • url: string

                要获取的图片 URL。

            • BetaManagedAgentsFileImageSource object { file_id, type }

              通过文件 ID 引用的图片。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            文档源变体的联合类型。

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              Base64 编码的文档数据。

              • data: string

                Base64 编码的文档数据。

              • media_type: string

                文档的 MIME 类型（例如 "application/pdf"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

              纯文本文档内容。

              • data: string

                纯文本内容。

              • media_type: "text/plain"

                文本内容的 MIME 类型。必须为 "text/plain"。

                • "text/plain"

              • type: "text"

                • "text"

            • BetaManagedAgentsURLDocumentSource object { type, url }

              通过 URL 引用的文档。

              • type: "url"

                • "url"

              • url: string

                要获取的文档 URL。

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              通过文件 ID 引用的文档。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            为模型提供的关于文档的额外上下文。

          • title: optional string

            文档的标题。

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        RFC 3339 格式的时间戳

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      暂停代理执行并将控制权返回给用户的中断事件。

      • id: string

        此事件的唯一标识符。

      • type: "user.interrupt"

        • "user.interrupt"

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        如果省略，中断多代理会话中的每个未归档线程（或单代理会话中的主线程）。如果指定，仅中断指定的线程。

    • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

      批准或拒绝待处理工具执行的工具确认事件。

      • id: string

        此事件的唯一标识符。

      • result: "allow" or "deny"

        UserToolConfirmationResult 枚举

        • "allow"

        • "deny"

      • tool_use_id: string

        此结果对应的 agent.tool_use 或 agent.mcp_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        为 'deny' 决定提供上下文的可选消息。仅在 result 为 'deny' 时允许。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        设置后，确认将路由到此子代理的线程而非主线程。从触发批准的 agent.tool_use 或 agent.mcp_tool_use 事件上的 session_thread_id 回显此值。

    • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

      客户端发送的事件，提供自定义工具执行的结果。

      • id: string

        此事件的唯一标识符。

      • custom_tool_use_id: string

        此结果对应的 agent.custom_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

          • citations: BetaManagedAgentsSearchResultCitations

            搜索结果的引用设置。

            • enabled: boolean

              此搜索结果是否启用引用。

          • content: array of BetaManagedAgentsSearchResultContent

            搜索结果中的文本内容块数组。

            • text: string

              文本内容。

            • type: "text"

              • "text"

          • source: string

            搜索结果的 URL 来源。

          • title: string

            搜索结果的标题。

          • type: "search_result"

            • "search_result"

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.custom_tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      当代理调用自定义工具时发出的事件。会话进入空闲状态，直到客户端发送带有结果的 user.custom_tool_result 事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        被调用的自定义工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.custom_tool_use"

        • "agent.custom_tool_use"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其自定义工具使用。在线程自身事件上为空。在 user.custom_tool_result 事件上回显此值以将结果路由回来。

    • BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }

      会话对话中的代理响应事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock

        组成代理响应的文本块数组。

        • text: string

          文本内容。

        • type: "text"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.message"

        • "agent.message"

    • BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }

      表示代理通过扩展思考正在取得进展。这是一个进度信号，而非内容载体。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thinking"

        • "agent.thinking"

    • BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }

      当代理调用 MCP 服务器提供的工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • mcp_server_name: string

        提供工具的 MCP 服务器名称。

      • name: string

        正在使用的 MCP 工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_use"

        • "agent.mcp_tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }

      表示 MCP 工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • mcp_tool_use_id: string

        此结果对应的 agent.mcp_tool_use 事件的 ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_result"

        • "agent.mcp_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      代理调用内置代理工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        正在使用的代理工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.tool_use"

        • "agent.tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }

      表示代理工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID。

      • type: "agent.tool_result"

        • "agent.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      当代理间消息到达时写入目标线程输入流的传递事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • from_session_thread_id: string

        发送消息的线程的公共 sthr_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_message_received"

        • "agent.thread_message_received"

      • from_agent_name: optional string

        此消息来源的可调用代理名称。从主代理接收时为空。

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      发送代理间消息时发出到发送者输出流的可观察性事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • to_session_thread_id: string

        消息发送到的线程的公共 sthr_ ID。

      • type: "agent.thread_message_sent"

        • "agent.thread_message_sent"

      • to_agent_name: optional string

        此消息发送到的可调用代理名称。发送到主代理时为空。

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      表示会话期间发生了上下文压缩（摘要）。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_context_compacted"

        • "agent.thread_context_compacted"

    • BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }

      表示会话执行期间发生问题的错误事件。

      • id: string

        此事件的唯一标识符。

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more

        会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

        • BetaManagedAgentsUnknownError object { message, retry_status, type }

          会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

              • type: "retrying"

                • "retrying"

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          模型当前已过载。在自动重试耗尽后发出。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          模型请求被限流。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          模型请求因过载或限流以外的原因失败。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          连接 MCP 服务器失败。

          • mcp_server_name: string

            连接失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          MCP 服务器认证失败。

          • mcp_server_name: string

            认证失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          调用者的组织或工作区无法发出模型请求——额度不足或已达消费限额。使用相同凭据重试不会成功；调用者必须解决计费状态。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "billing_error"

            • "billing_error"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.error"

        • "session.error"

    • BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }

      表示会话正在从错误状态恢复，并已重新安排执行。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_rescheduled"

        • "session.status_rescheduled"

    • BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }

      表示会话正在积极运行，代理正在工作。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_running"

        • "session.status_running"

    • BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }

      表示代理已暂停，正在等待用户输入。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

          • event_ids: array of string

            代理被阻塞的事件 ID。解决少于全部事件时，会使用剩余事件重新发出 session.status_idle。

          • type: "requires_action"

            • "requires_action"

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

          • type: "retries_exhausted"

            • "retries_exhausted"

      • type: "session.status_idle"

        • "session.status_idle"

    • BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }

      表示会话已终止，无论是由于错误还是完成。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_terminated"

        • "session.status_terminated"

    • BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }

      当子代理作为新线程生成时发出。写入父线程的输出流，以便观察会话的客户端看到子线程创建。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的可调用代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        新创建线程的公共 sthr_ ID。

      • type: "session.thread_created"

        • "session.thread_created"

    • BetaManagedAgentsSpanOutcome评估uationStartEvent object { id, iteration, outcome_id, 2 more }

      当结果评估周期开始时发出。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期。0 是第一次评估；1 是第一次修订后的重新评估；以此类推。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_start"

        • "span.outcome_evaluation_start"

    • BetaManagedAgentsSpanOutcome评估uationEndEvent object { id, explanation, iteration, 6 more }

      当结果评估周期完成时发出。携带判定结果和聚合 token 使用量。判定为 needs_revision 意味着还有另一个评估周期；satisfied、max_iterations_reached、failed 或 interrupted 为终止状态——不会有更多评估周期。

      • id: string

        此事件的唯一标识符。

      • explanation: string

        判定结果的人类可读解释。对于 needs_revision，描述哪些标准未满足以及原因。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_evaluation_start_id: string

        对应的 span.outcome_evaluation_start 事件的 ID。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • result: string

        评估判定。 'satisfied': 标准已满足，会话进入空闲。 'needs_revision': 标准未满足，将进行另一个修订周期。 'max_iterations_reached': 评估预算耗尽但标准仍未满足 — 会话进入空闲前会有最后一个确认轮次，但不会进行更多评估。 'failed': 评分者确定评分标准不适用于交付物。 'interrupted': 用户在评估进行中发送了中断。

      • type: "span.outcome_evaluation_end"

        • "span.outcome_evaluation_end"

      • usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

        • cache_creation_input_tokens: number

          此请求中用于创建提示缓存的 token 数。

        • cache_read_input_tokens: number

          此请求中从提示缓存读取的 token 数。

        • input_tokens: number

          此请求消耗的输入 token 数。

        • output_tokens: number

          此请求生成的输出 token 数。

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      当代理发起模型请求时发出。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_start"

        • "span.model_request_start"

    • BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }

      当模型请求完成时发出。

      • id: string

        此事件的唯一标识符。

      • is_error: boolean

        模型请求是否导致错误。

      • model_request_start_id: string

        对应的 span.model_request_start 事件的 ID。

      • model_usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_end"

        • "span.model_request_end"

    • BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }

      在结果评估周期进行期间发出的定期心跳。在对应的 span.outcome_evaluation_start 和 span.outcome_evaluation_end 事件之间区分"评估正在积极运行"和"评估卡住"。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_ongoing"

        • "span.outcome_evaluation_ongoing"

    • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

      user.define_outcome 输入事件的回显。携带服务器生成的 outcome_id，后续的 span.outcome_evaluation_* 事件引用该 ID。

      • id: string

        此事件的唯一标识符。

      • description: string

        代理应产出的内容。 从输入事件复制。

      • max_iterations: number

        放弃前的评估-修订周期。默认 3，最大 20。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。被 span.outcome_evaluation_* 事件和会话的 outcome_evaluations 列表引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

        用于评估结果质量的评分标准。

        • BetaManagedAgentsFileRubric object { file_id, type }

          通过 Files API 上传的文件引用的评分标准。

          • file_id: string

            评分标准文件的 ID。

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          以文本形式内联提供的评分标准内容。

          • content: string

            评分标准内容。纯文本或 markdown——评分者将其视为自由格式文本。

          • type: "text"

            • "text"

      • type: "user.define_outcome"

        • "user.define_outcome"

    • BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }

      当会话被删除时发出。终止所有活动的事件流 — 不会再为此会话发出更多事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.deleted"

        • "session.deleted"

    • BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }

      会话线程已开始执行。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        开始运行的线程的公共 sthr_ ID。

      • type: "session.thread_status_running"

        • "session.thread_status_running"

    • BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }

      会话线程已让出并正在等待输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        进入空闲状态的线程的公共 sthr_ ID。

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

      • type: "session.thread_status_idle"

        • "session.thread_status_idle"

    • BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }

      会话线程已终止，不再接受输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        已终止线程的公共 sthr_ ID。

      • type: "session.thread_status_terminated"

        • "session.thread_status_terminated"

    • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

      客户端发送的事件，提供代理工具集工具执行的结果。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

      • id: string

        此事件的唯一标识符。

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      会话线程遇到瞬态错误，正在自动重试。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        正在重试的线程的公共 sthr_ ID。

      • type: "session.thread_status_rescheduled"

        • "session.thread_status_rescheduled"

    • BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 3 more }

      当 UpdateSession 请求更改了至少一个字段时发出。仅携带已更改的字段；未出现的字段不是更新的一部分。新配置从下一轮开始生效。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.updated"

        • "session.updated"

      • agent: optional BetaManagedAgentsSessionAgent

        为 session 解析的 agent 定义。session 创建时 agent 的快照。

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          模型标识符和配置。

          • id: BetaManagedAgentsModel

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              驱动代理的模型。

              详情和选项请参阅 models。

              • "claude-opus-4-7"

                适用于长时间运行代理和编码的前沿智能

              • "claude-opus-4-6"

                用于构建代理和编码的最智能模型

              • "claude-sonnet-4-6"

                速度与智能的最佳组合

              • "claude-haiku-4-5"

                具有接近前沿智能的最快模型

              • "claude-haiku-4-5-20251001"

                具有接近前沿智能的最快模型

              • "claude-opus-4-5"

                结合最大智能与实用性能的高端模型

              • "claude-opus-4-5-20251101"

                结合最大智能与实用性能的高端模型

              • "claude-sonnet-4-5"

                用于代理和编码的高性能模型

              • "claude-sonnet-4-5-20250929"

                用于代理和编码的高性能模型

            • string

          • speed: optional "standard" or "fast"

            推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

            • "standard"

            • "fast"

        • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

          解析的协调器拓扑，包含每个成员的完整 agent 定义。

          • agents: array of BetaManagedAgentsSessionThreadAgent

            协调器可能作为会话线程生成的完整 agent 定义。

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              模型标识符和配置。

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                已解析的 Anthropic 托管技能。

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                已解析的用户创建的自定义技能。

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    内置代理工具标识符。

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                      • type: "always_ask"

                        • "always_ask"

                • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                  代理工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                  MCP 服务器所有工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                API 响应中返回的自定义工具。

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  自定义工具输入参数的 JSON Schema。

                  • properties: optional map[unknown]

                    定义工具输入参数的 JSON Schema 属性。

                  • required: optional array of string

                    必需属性名称列表。

                  • type: optional "object"

                    工具输入 schema 必须为 'object'。

                    • "object"

                • name: string

                • type: "custom"

                  • "custom"

            • type: "agent"

              • "agent"

            • version: number

          • type: "coordinator"

            • "coordinator"

        • name: string

        • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            已解析的 Anthropic 托管技能。

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            已解析的用户创建的自定义技能。

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            API 响应中返回的自定义工具。

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        更新后会话的完整元数据包。当更新设置了非空元数据时存在；当元数据未更改或清空时不存在。

      • title: optional string

        会话的新标题。仅在更新更改了标题时存在。

Events

列出会话线程事件

get /v1/sessions/{session_id}/threads/{thread_id}/events

列出会话线程事件

路径参数

  • session_id: string

  • thread_id: string

查询参数

  • limit: optional number

    查询参数，用于限制返回数量

  • page: optional string

    分页查询参数

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • data: optional array of BetaManagedAgentsSessionEvent

    线程的事件，按 created_at 排序。

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      会话对话中的用户消息事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        组成用户消息的内容块数组。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            图片源变体的联合类型。

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              Base64 编码的图片数据。

              • data: string

                Base64 编码的图片数据。

              • media_type: string

                图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsURLImageSource object { type, url }

              通过 URL 引用的图片。

              • type: "url"

                • "url"

              • url: string

                要获取的图片 URL。

            • BetaManagedAgentsFileImageSource object { file_id, type }

              通过文件 ID 引用的图片。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            文档源变体的联合类型。

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              Base64 编码的文档数据。

              • data: string

                Base64 编码的文档数据。

              • media_type: string

                文档的 MIME 类型（例如 "application/pdf"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

              纯文本文档内容。

              • data: string

                纯文本内容。

              • media_type: "text/plain"

                文本内容的 MIME 类型。必须为 "text/plain"。

                • "text/plain"

              • type: "text"

                • "text"

            • BetaManagedAgentsURLDocumentSource object { type, url }

              通过 URL 引用的文档。

              • type: "url"

                • "url"

              • url: string

                要获取的文档 URL。

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              通过文件 ID 引用的文档。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            为模型提供的关于文档的额外上下文。

          • title: optional string

            文档的标题。

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        RFC 3339 格式的时间戳

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      暂停代理执行并将控制权返回给用户的中断事件。

      • id: string

        此事件的唯一标识符。

      • type: "user.interrupt"

        • "user.interrupt"

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        如果省略，中断多代理会话中的每个未归档线程（或单代理会话中的主线程）。如果指定，仅中断指定的线程。

    • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

      批准或拒绝待处理工具执行的工具确认事件。

      • id: string

        此事件的唯一标识符。

      • result: "allow" or "deny"

        UserToolConfirmationResult 枚举

        • "allow"

        • "deny"

      • tool_use_id: string

        此结果对应的 agent.tool_use 或 agent.mcp_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        为 'deny' 决定提供上下文的可选消息。仅在 result 为 'deny' 时允许。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        设置后，确认将路由到此子代理的线程而非主线程。从触发批准的 agent.tool_use 或 agent.mcp_tool_use 事件上的 session_thread_id 回显此值。

    • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

      客户端发送的事件，提供自定义工具执行的结果。

      • id: string

        此事件的唯一标识符。

      • custom_tool_use_id: string

        此结果对应的 agent.custom_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

          • citations: BetaManagedAgentsSearchResultCitations

            搜索结果的引用设置。

            • enabled: boolean

              此搜索结果是否启用引用。

          • content: array of BetaManagedAgentsSearchResultContent

            搜索结果中的文本内容块数组。

            • text: string

              文本内容。

            • type: "text"

              • "text"

          • source: string

            搜索结果的 URL 来源。

          • title: string

            搜索结果的标题。

          • type: "search_result"

            • "search_result"

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.custom_tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      当代理调用自定义工具时发出的事件。会话进入空闲状态，直到客户端发送带有结果的 user.custom_tool_result 事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        被调用的自定义工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.custom_tool_use"

        • "agent.custom_tool_use"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其自定义工具使用。在线程自身事件上为空。在 user.custom_tool_result 事件上回显此值以将结果路由回来。

    • BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }

      会话对话中的代理响应事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock

        组成代理响应的文本块数组。

        • text: string

          文本内容。

        • type: "text"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.message"

        • "agent.message"

    • BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }

      表示代理通过扩展思考正在取得进展。这是一个进度信号，而非内容载体。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thinking"

        • "agent.thinking"

    • BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }

      当代理调用 MCP 服务器提供的工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • mcp_server_name: string

        提供工具的 MCP 服务器名称。

      • name: string

        正在使用的 MCP 工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_use"

        • "agent.mcp_tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }

      表示 MCP 工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • mcp_tool_use_id: string

        此结果对应的 agent.mcp_tool_use 事件的 ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_result"

        • "agent.mcp_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      代理调用内置代理工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        正在使用的代理工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.tool_use"

        • "agent.tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }

      表示代理工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID。

      • type: "agent.tool_result"

        • "agent.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      当代理间消息到达时写入目标线程输入流的传递事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • from_session_thread_id: string

        发送消息的线程的公共 sthr_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_message_received"

        • "agent.thread_message_received"

      • from_agent_name: optional string

        此消息来源的可调用代理名称。从主代理接收时为空。

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      发送代理间消息时发出到发送者输出流的可观察性事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • to_session_thread_id: string

        消息发送到的线程的公共 sthr_ ID。

      • type: "agent.thread_message_sent"

        • "agent.thread_message_sent"

      • to_agent_name: optional string

        此消息发送到的可调用代理名称。发送到主代理时为空。

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      表示会话期间发生了上下文压缩（摘要）。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_context_compacted"

        • "agent.thread_context_compacted"

    • BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }

      表示会话执行期间发生问题的错误事件。

      • id: string

        此事件的唯一标识符。

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more

        会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

        • BetaManagedAgentsUnknownError object { message, retry_status, type }

          会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

              • type: "retrying"

                • "retrying"

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          模型当前已过载。在自动重试耗尽后发出。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          模型请求被限流。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          模型请求因过载或限流以外的原因失败。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          连接 MCP 服务器失败。

          • mcp_server_name: string

            连接失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          MCP 服务器认证失败。

          • mcp_server_name: string

            认证失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          调用者的组织或工作区无法发出模型请求——额度不足或已达消费限额。使用相同凭据重试不会成功；调用者必须解决计费状态。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "billing_error"

            • "billing_error"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.error"

        • "session.error"

    • BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }

      表示会话正在从错误状态恢复，并已重新安排执行。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_rescheduled"

        • "session.status_rescheduled"

    • BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }

      表示会话正在积极运行，代理正在工作。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_running"

        • "session.status_running"

    • BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }

      表示代理已暂停，正在等待用户输入。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

          • event_ids: array of string

            代理被阻塞的事件 ID。解决少于全部事件时，会使用剩余事件重新发出 session.status_idle。

          • type: "requires_action"

            • "requires_action"

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

          • type: "retries_exhausted"

            • "retries_exhausted"

      • type: "session.status_idle"

        • "session.status_idle"

    • BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }

      表示会话已终止，无论是由于错误还是完成。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_terminated"

        • "session.status_terminated"

    • BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }

      当子代理作为新线程生成时发出。写入父线程的输出流，以便观察会话的客户端看到子线程创建。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的可调用代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        新创建线程的公共 sthr_ ID。

      • type: "session.thread_created"

        • "session.thread_created"

    • BetaManagedAgentsSpanOutcome评估uationStartEvent object { id, iteration, outcome_id, 2 more }

      当结果评估周期开始时发出。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期。0 是第一次评估；1 是第一次修订后的重新评估；以此类推。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_start"

        • "span.outcome_evaluation_start"

    • BetaManagedAgentsSpanOutcome评估uationEndEvent object { id, explanation, iteration, 6 more }

      当结果评估周期完成时发出。携带判定结果和聚合 token 使用量。判定为 needs_revision 意味着还有另一个评估周期；satisfied、max_iterations_reached、failed 或 interrupted 为终止状态——不会有更多评估周期。

      • id: string

        此事件的唯一标识符。

      • explanation: string

        判定结果的人类可读解释。对于 needs_revision，描述哪些标准未满足以及原因。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_evaluation_start_id: string

        对应的 span.outcome_evaluation_start 事件的 ID。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • result: string

        评估判定。 'satisfied': 标准已满足，会话进入空闲。 'needs_revision': 标准未满足，将进行另一个修订周期。 'max_iterations_reached': 评估预算耗尽但标准仍未满足 — 会话进入空闲前会有最后一个确认轮次，但不会进行更多评估。 'failed': 评分者确定评分标准不适用于交付物。 'interrupted': 用户在评估进行中发送了中断。

      • type: "span.outcome_evaluation_end"

        • "span.outcome_evaluation_end"

      • usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

        • cache_creation_input_tokens: number

          此请求中用于创建提示缓存的 token 数。

        • cache_read_input_tokens: number

          此请求中从提示缓存读取的 token 数。

        • input_tokens: number

          此请求消耗的输入 token 数。

        • output_tokens: number

          此请求生成的输出 token 数。

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      当代理发起模型请求时发出。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_start"

        • "span.model_request_start"

    • BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }

      当模型请求完成时发出。

      • id: string

        此事件的唯一标识符。

      • is_error: boolean

        模型请求是否导致错误。

      • model_request_start_id: string

        对应的 span.model_request_start 事件的 ID。

      • model_usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_end"

        • "span.model_request_end"

    • BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }

      在结果评估周期进行期间发出的定期心跳。在对应的 span.outcome_evaluation_start 和 span.outcome_evaluation_end 事件之间区分"评估正在积极运行"和"评估卡住"。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_ongoing"

        • "span.outcome_evaluation_ongoing"

    • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

      user.define_outcome 输入事件的回显。携带服务器生成的 outcome_id，后续的 span.outcome_evaluation_* 事件引用该 ID。

      • id: string

        此事件的唯一标识符。

      • description: string

        代理应产出的内容。 从输入事件复制。

      • max_iterations: number

        放弃前的评估-修订周期。默认 3，最大 20。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。被 span.outcome_evaluation_* 事件和会话的 outcome_evaluations 列表引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

        用于评估结果质量的评分标准。

        • BetaManagedAgentsFileRubric object { file_id, type }

          通过 Files API 上传的文件引用的评分标准。

          • file_id: string

            评分标准文件的 ID。

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          以文本形式内联提供的评分标准内容。

          • content: string

            评分标准内容。纯文本或 markdown——评分者将其视为自由格式文本。

          • type: "text"

            • "text"

      • type: "user.define_outcome"

        • "user.define_outcome"

    • BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }

      当会话被删除时发出。终止所有活动的事件流 — 不会再为此会话发出更多事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.deleted"

        • "session.deleted"

    • BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }

      会话线程已开始执行。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        开始运行的线程的公共 sthr_ ID。

      • type: "session.thread_status_running"

        • "session.thread_status_running"

    • BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }

      会话线程已让出并正在等待输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        进入空闲状态的线程的公共 sthr_ ID。

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

      • type: "session.thread_status_idle"

        • "session.thread_status_idle"

    • BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }

      会话线程已终止，不再接受输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        已终止线程的公共 sthr_ ID。

      • type: "session.thread_status_terminated"

        • "session.thread_status_terminated"

    • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

      客户端发送的事件，提供代理工具集工具执行的结果。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

      • id: string

        此事件的唯一标识符。

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      会话线程遇到瞬态错误，正在自动重试。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        正在重试的线程的公共 sthr_ ID。

      • type: "session.thread_status_rescheduled"

        • "session.thread_status_rescheduled"

    • BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 3 more }

      当 UpdateSession 请求更改了至少一个字段时发出。仅携带已更改的字段；未出现的字段不是更新的一部分。新配置从下一轮开始生效。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.updated"

        • "session.updated"

      • agent: optional BetaManagedAgentsSessionAgent

        为 session 解析的 agent 定义。session 创建时 agent 的快照。

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          模型标识符和配置。

          • id: BetaManagedAgentsModel

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              驱动代理的模型。

              详情和选项请参阅 models。

              • "claude-opus-4-7"

                适用于长时间运行代理和编码的前沿智能

              • "claude-opus-4-6"

                用于构建代理和编码的最智能模型

              • "claude-sonnet-4-6"

                速度与智能的最佳组合

              • "claude-haiku-4-5"

                具有接近前沿智能的最快模型

              • "claude-haiku-4-5-20251001"

                具有接近前沿智能的最快模型

              • "claude-opus-4-5"

                结合最大智能与实用性能的高端模型

              • "claude-opus-4-5-20251101"

                结合最大智能与实用性能的高端模型

              • "claude-sonnet-4-5"

                用于代理和编码的高性能模型

              • "claude-sonnet-4-5-20250929"

                用于代理和编码的高性能模型

            • string

          • speed: optional "standard" or "fast"

            推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

            • "standard"

            • "fast"

        • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

          解析的协调器拓扑，包含每个成员的完整 agent 定义。

          • agents: array of BetaManagedAgentsSessionThreadAgent

            协调器可能作为会话线程生成的完整 agent 定义。

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              模型标识符和配置。

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                已解析的 Anthropic 托管技能。

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                已解析的用户创建的自定义技能。

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    内置代理工具标识符。

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                      • type: "always_ask"

                        • "always_ask"

                • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                  代理工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                  MCP 服务器所有工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                API 响应中返回的自定义工具。

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  自定义工具输入参数的 JSON Schema。

                  • properties: optional map[unknown]

                    定义工具输入参数的 JSON Schema 属性。

                  • required: optional array of string

                    必需属性名称列表。

                  • type: optional "object"

                    工具输入 schema 必须为 'object'。

                    • "object"

                • name: string

                • type: "custom"

                  • "custom"

            • type: "agent"

              • "agent"

            • version: number

          • type: "coordinator"

            • "coordinator"

        • name: string

        • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            已解析的 Anthropic 托管技能。

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            已解析的用户创建的自定义技能。

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            API 响应中返回的自定义工具。

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        更新后会话的完整元数据包。当更新设置了非空元数据时存在；当元数据未更改或清空时不存在。

      • title: optional string

        会话的新标题。仅在更新更改了标题时存在。

  • next_page: optional string

    下一页的不透明游标。没有更多结果时为 null。

示例

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"

响应

{
  "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"
}

流式会话线程事件

get /v1/sessions/{session_id}/threads/{thread_id}/stream

流式会话线程事件

路径参数

  • session_id: string

  • thread_id: string

请求头参数

  • "anthropic-beta": optional array of AnthropicBeta

    可选的请求头，用于指定要使用的 beta 版本。

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

返回值

  • BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 30 more

    单个线程流中的服务器发送事件。

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      会话对话中的用户消息事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        组成用户消息的内容块数组。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

          • text: string

            文本内容。

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            图片源变体的联合类型。

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              Base64 编码的图片数据。

              • data: string

                Base64 编码的图片数据。

              • media_type: string

                图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsURLImageSource object { type, url }

              通过 URL 引用的图片。

              • type: "url"

                • "url"

              • url: string

                要获取的图片 URL。

            • BetaManagedAgentsFileImageSource object { file_id, type }

              通过文件 ID 引用的图片。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            文档源变体的联合类型。

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              Base64 编码的文档数据。

              • data: string

                Base64 编码的文档数据。

              • media_type: string

                文档的 MIME 类型（例如 "application/pdf"）。

              • type: "base64"

                • "base64"

            • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

              纯文本文档内容。

              • data: string

                纯文本内容。

              • media_type: "text/plain"

                文本内容的 MIME 类型。必须为 "text/plain"。

                • "text/plain"

              • type: "text"

                • "text"

            • BetaManagedAgentsURLDocumentSource object { type, url }

              通过 URL 引用的文档。

              • type: "url"

                • "url"

              • url: string

                要获取的文档 URL。

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              通过文件 ID 引用的文档。

              • file_id: string

                先前上传文件的 ID。

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            为模型提供的关于文档的额外上下文。

          • title: optional string

            文档的标题。

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        RFC 3339 格式的时间戳

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      暂停代理执行并将控制权返回给用户的中断事件。

      • id: string

        此事件的唯一标识符。

      • type: "user.interrupt"

        • "user.interrupt"

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        如果省略，中断多代理会话中的每个未归档线程（或单代理会话中的主线程）。如果指定，仅中断指定的线程。

    • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

      批准或拒绝待处理工具执行的工具确认事件。

      • id: string

        此事件的唯一标识符。

      • result: "allow" or "deny"

        UserToolConfirmationResult 枚举

        • "allow"

        • "deny"

      • tool_use_id: string

        此结果对应的 agent.tool_use 或 agent.mcp_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        为 'deny' 决定提供上下文的可选消息。仅在 result 为 'deny' 时允许。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        设置后，确认将路由到此子代理的线程而非主线程。从触发批准的 agent.tool_use 或 agent.mcp_tool_use 事件上的 session_thread_id 回显此值。

    • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

      客户端发送的事件，提供自定义工具执行的结果。

      • id: string

        此事件的唯一标识符。

      • custom_tool_use_id: string

        此结果对应的 agent.custom_tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

          • citations: BetaManagedAgentsSearchResultCitations

            搜索结果的引用设置。

            • enabled: boolean

              此搜索结果是否启用引用。

          • content: array of BetaManagedAgentsSearchResultContent

            搜索结果中的文本内容块数组。

            • text: string

              文本内容。

            • type: "text"

              • "text"

          • source: string

            搜索结果的 URL 来源。

          • title: string

            搜索结果的标题。

          • type: "search_result"

            • "search_result"

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.custom_tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      当代理调用自定义工具时发出的事件。会话进入空闲状态，直到客户端发送带有结果的 user.custom_tool_result 事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        被调用的自定义工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.custom_tool_use"

        • "agent.custom_tool_use"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其自定义工具使用。在线程自身事件上为空。在 user.custom_tool_result 事件上回显此值以将结果路由回来。

    • BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }

      会话对话中的代理响应事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock

        组成代理响应的文本块数组。

        • text: string

          文本内容。

        • type: "text"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.message"

        • "agent.message"

    • BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }

      表示代理通过扩展思考正在取得进展。这是一个进度信号，而非内容载体。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thinking"

        • "agent.thinking"

    • BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }

      当代理调用 MCP 服务器提供的工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • mcp_server_name: string

        提供工具的 MCP 服务器名称。

      • name: string

        正在使用的 MCP 工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_use"

        • "agent.mcp_tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }

      表示 MCP 工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • mcp_tool_use_id: string

        此结果对应的 agent.mcp_tool_use 事件的 ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.mcp_tool_result"

        • "agent.mcp_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      代理调用内置代理工具时发出的事件。

      • id: string

        此事件的唯一标识符。

      • input: map[unknown]

        工具调用的输入参数。

      • name: string

        正在使用的代理工具名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.tool_use"

        • "agent.tool_use"

      • evaluated_permission: optional "allow" or "ask" or "deny"

        Agent评估uatedPermission 枚举

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        设置后，此事件从子代理线程交叉发布到主线程流以显示其权限请求。在线程自身事件上为空。在 user.tool_confirmation 事件上回显此值以将批准路由回来。

    • BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }

      表示代理工具执行结果的事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID。

      • type: "agent.tool_result"

        • "agent.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      当代理间消息到达时写入目标线程输入流的传递事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • from_session_thread_id: string

        发送消息的线程的公共 sthr_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_message_received"

        • "agent.thread_message_received"

      • from_agent_name: optional string

        此消息来源的可调用代理名称。从主代理接收时为空。

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      发送代理间消息时发出到发送者输出流的可观察性事件。

      • id: string

        此事件的唯一标识符。

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        消息内容块。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • to_session_thread_id: string

        消息发送到的线程的公共 sthr_ ID。

      • type: "agent.thread_message_sent"

        • "agent.thread_message_sent"

      • to_agent_name: optional string

        此消息发送到的可调用代理名称。发送到主代理时为空。

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      表示会话期间发生了上下文压缩（摘要）。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "agent.thread_context_compacted"

        • "agent.thread_context_compacted"

    • BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }

      表示会话执行期间发生问题的错误事件。

      • id: string

        此事件的唯一标识符。

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 4 more

        会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

        • BetaManagedAgentsUnknownError object { message, retry_status, type }

          会话执行期间发生未知或意外错误。回退变体；无法识别新错误代码的客户端可以仅匹配 retry_status 和 message。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

              • type: "retrying"

                • "retrying"

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          模型当前已过载。在自动重试耗尽后发出。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          模型请求被限流。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          模型请求因过载或限流以外的原因失败。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          连接 MCP 服务器失败。

          • mcp_server_name: string

            连接失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          MCP 服务器认证失败。

          • mcp_server_name: string

            认证失败的 MCP 服务器名称。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          调用者的组织或工作区无法发出模型请求——额度不足或已达消费限额。使用相同凭据重试不会成功；调用者必须解决计费状态。

          • message: string

            人类可读的错误描述。

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            客户端应如何响应此错误。

            • BetaManagedAgentsRetryStatusRetrying object { type }

              服务器正在自动重试。客户端应等待；相同的错误类型可能再次作为重试触发，然后在重试预算耗尽时触发一次耗尽。

            • BetaManagedAgentsRetryStatusExhausted object { type }

              此轮已结束；排队的输入被刷新，会话返回空闲状态。客户端可以发送新的提示。

            • BetaManagedAgentsRetryStatusTerminal object { type }

              会话遇到终止性错误，将转换为 terminated 状态。

          • type: "billing_error"

            • "billing_error"

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.error"

        • "session.error"

    • BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }

      表示会话正在从错误状态恢复，并已重新安排执行。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_rescheduled"

        • "session.status_rescheduled"

    • BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }

      表示会话正在积极运行，代理正在工作。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_running"

        • "session.status_running"

    • BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }

      表示代理已暂停，正在等待用户输入。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

          • event_ids: array of string

            代理被阻塞的事件 ID。解决少于全部事件时，会使用剩余事件重新发出 session.status_idle。

          • type: "requires_action"

            • "requires_action"

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

          • type: "retries_exhausted"

            • "retries_exhausted"

      • type: "session.status_idle"

        • "session.status_idle"

    • BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }

      表示会话已终止，无论是由于错误还是完成。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.status_terminated"

        • "session.status_terminated"

    • BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }

      当子代理作为新线程生成时发出。写入父线程的输出流，以便观察会话的客户端看到子线程创建。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的可调用代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        新创建线程的公共 sthr_ ID。

      • type: "session.thread_created"

        • "session.thread_created"

    • BetaManagedAgentsSpanOutcome评估uationStartEvent object { id, iteration, outcome_id, 2 more }

      当结果评估周期开始时发出。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期。0 是第一次评估；1 是第一次修订后的重新评估；以此类推。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_start"

        • "span.outcome_evaluation_start"

    • BetaManagedAgentsSpanOutcome评估uationEndEvent object { id, explanation, iteration, 6 more }

      当结果评估周期完成时发出。携带判定结果和聚合 token 使用量。判定为 needs_revision 意味着还有另一个评估周期；satisfied、max_iterations_reached、failed 或 interrupted 为终止状态——不会有更多评估周期。

      • id: string

        此事件的唯一标识符。

      • explanation: string

        判定结果的人类可读解释。对于 needs_revision，描述哪些标准未满足以及原因。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_evaluation_start_id: string

        对应的 span.outcome_evaluation_start 事件的 ID。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • result: string

        评估判定。 'satisfied': 标准已满足，会话进入空闲。 'needs_revision': 标准未满足，将进行另一个修订周期。 'max_iterations_reached': 评估预算耗尽但标准仍未满足 — 会话进入空闲前会有最后一个确认轮次，但不会进行更多评估。 'failed': 评分者确定评分标准不适用于交付物。 'interrupted': 用户在评估进行中发送了中断。

      • type: "span.outcome_evaluation_end"

        • "span.outcome_evaluation_end"

      • usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

        • cache_creation_input_tokens: number

          此请求中用于创建提示缓存的 token 数。

        • cache_read_input_tokens: number

          此请求中从提示缓存读取的 token 数。

        • input_tokens: number

          此请求消耗的输入 token 数。

        • output_tokens: number

          此请求生成的输出 token 数。

        • speed: optional "standard" or "fast"

          推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

          • "standard"

          • "fast"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      当代理发起模型请求时发出。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_start"

        • "span.model_request_start"

    • BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }

      当模型请求完成时发出。

      • id: string

        此事件的唯一标识符。

      • is_error: boolean

        模型请求是否导致错误。

      • model_request_start_id: string

        对应的 span.model_request_start 事件的 ID。

      • model_usage: BetaManagedAgentsSpanModelUsage

        单个模型请求的 token 使用量。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.model_request_end"

        • "span.model_request_end"

    • BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }

      在结果评估周期进行期间发出的定期心跳。在对应的 span.outcome_evaluation_start 和 span.outcome_evaluation_end 事件之间区分"评估正在积极运行"和"评估卡住"。

      • id: string

        此事件的唯一标识符。

      • iteration: number

        从 0 开始的修订周期，与对应的 span.outcome_evaluation_start 匹配。

      • outcome_id: string

        正在评估的结果的 outc_ ID。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "span.outcome_evaluation_ongoing"

        • "span.outcome_evaluation_ongoing"

    • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

      user.define_outcome 输入事件的回显。携带服务器生成的 outcome_id，后续的 span.outcome_evaluation_* 事件引用该 ID。

      • id: string

        此事件的唯一标识符。

      • description: string

        代理应产出的内容。 从输入事件复制。

      • max_iterations: number

        放弃前的评估-修订周期。默认 3，最大 20。

      • outcome_id: string

        服务器为此结果生成的 outc_ ID。被 span.outcome_evaluation_* 事件和会话的 outcome_evaluations 列表引用。

      • processed_at: string

        RFC 3339 格式的时间戳

      • rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

        用于评估结果质量的评分标准。

        • BetaManagedAgentsFileRubric object { file_id, type }

          通过 Files API 上传的文件引用的评分标准。

          • file_id: string

            评分标准文件的 ID。

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          以文本形式内联提供的评分标准内容。

          • content: string

            评分标准内容。纯文本或 markdown——评分者将其视为自由格式文本。

          • type: "text"

            • "text"

      • type: "user.define_outcome"

        • "user.define_outcome"

    • BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }

      当会话被删除时发出。终止所有活动的事件流 — 不会再为此会话发出更多事件。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.deleted"

        • "session.deleted"

    • BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }

      会话线程已开始执行。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        开始运行的线程的公共 sthr_ ID。

      • type: "session.thread_status_running"

        • "session.thread_status_running"

    • BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }

      会话线程已让出并正在等待输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        进入空闲状态的线程的公共 sthr_ ID。

      • stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionEndTurn object { type }

          代理自然完成了其轮次，准备接收下一条用户消息。

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          代理空闲，等待一个或多个阻塞的用户输入事件（工具确认、自定义工具结果等）。解决所有这些事件后，会话将转换回运行状态。

        • BetaManagedAgentsSessionRetriesExhausted object { type }

          轮次因重试预算耗尽而结束（达到 max_iterations 或错误升级为 retry_status: 'exhausted'）。

      • type: "session.thread_status_idle"

        • "session.thread_status_idle"

    • BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }

      会话线程已终止，不再接受输入。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        已终止线程的公共 sthr_ ID。

      • type: "session.thread_status_terminated"

        • "session.thread_status_terminated"

    • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

      客户端发送的事件，提供代理工具集工具执行的结果。仅在 self_hosted 环境中有效，其中沙箱路由的工具由客户端而非服务器执行。

      • id: string

        此事件的唯一标识符。

      • tool_use_id: string

        此结果对应的 agent.tool_use 事件的 ID，可在最后一个 session.status_idle 事件的 stop_reason.event_ids 字段中找到。

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        工具返回的结果内容。

        • BetaManagedAgentsTextBlock object { text, type }

          常规文本内容。

        • BetaManagedAgentsImageBlock object { source, type }

          直接指定为 base64 数据或通过 URL 引用的图片内容。

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          文档内容，直接指定为 base64 数据、文本或通过 URL 引用。

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          包含网络搜索结果的块。

      • is_error: optional boolean

        工具执行是否导致错误。

      • processed_at: optional string

        RFC 3339 格式的时间戳

      • session_thread_id: optional string

        将此结果路由到子代理线程。从 agent.tool_use 事件的 session_thread_id 复制。

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      会话线程遇到瞬态错误，正在自动重试。在线程'自身的流上发出，并交叉发布到子线程的主流。

      • id: string

        此事件的唯一标识符。

      • agent_name: string

        线程运行的代理名称。

      • processed_at: string

        RFC 3339 格式的时间戳

      • session_thread_id: string

        正在重试的线程的公共 sthr_ ID。

      • type: "session.thread_status_rescheduled"

        • "session.thread_status_rescheduled"

    • BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 3 more }

      当 UpdateSession 请求更改了至少一个字段时发出。仅携带已更改的字段；未出现的字段不是更新的一部分。新配置从下一轮开始生效。

      • id: string

        此事件的唯一标识符。

      • processed_at: string

        RFC 3339 格式的时间戳

      • type: "session.updated"

        • "session.updated"

      • agent: optional BetaManagedAgentsSessionAgent

        为 session 解析的 agent 定义。session 创建时 agent 的快照。

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          模型标识符和配置。

          • id: BetaManagedAgentsModel

            驱动代理的模型。

            详情和选项请参阅 models。

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              驱动代理的模型。

              详情和选项请参阅 models。

              • "claude-opus-4-7"

                适用于长时间运行代理和编码的前沿智能

              • "claude-opus-4-6"

                用于构建代理和编码的最智能模型

              • "claude-sonnet-4-6"

                速度与智能的最佳组合

              • "claude-haiku-4-5"

                具有接近前沿智能的最快模型

              • "claude-haiku-4-5-20251001"

                具有接近前沿智能的最快模型

              • "claude-opus-4-5"

                结合最大智能与实用性能的高端模型

              • "claude-opus-4-5-20251101"

                结合最大智能与实用性能的高端模型

              • "claude-sonnet-4-5"

                用于代理和编码的高性能模型

              • "claude-sonnet-4-5-20250929"

                用于代理和编码的高性能模型

            • string

          • speed: optional "standard" or "fast"

            推理速度模式。fast 以更高的价格提供显著更快的输出 token 生成速度。并非所有模型都支持 fast；无效的组合会在创建时被拒绝。

            • "standard"

            • "fast"

        • multiagent: BetaManagedAgentsSessionMultiagentCoordinator

          解析的协调器拓扑，包含每个成员的完整 agent 定义。

          • agents: array of BetaManagedAgentsSessionThreadAgent

            协调器可能作为会话线程生成的完整 agent 定义。

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              模型标识符和配置。

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                已解析的 Anthropic 托管技能。

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                已解析的用户创建的自定义技能。

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    内置代理工具标识符。

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                      • type: "always_ask"

                        • "always_ask"

                • default_config: BetaManagedAgentsAgentToolsetDefaultConfig

                  代理工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • default_config: BetaManagedAgentsMCPToolsetDefaultConfig

                  MCP 服务器所有工具的解析默认配置。

                  • enabled: boolean

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    工具执行的权限策略。

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      工具调用会自动批准，无需用户确认。

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      工具调用需要用户确认后才能执行。

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                API 响应中返回的自定义工具。

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  自定义工具输入参数的 JSON Schema。

                  • properties: optional map[unknown]

                    定义工具输入参数的 JSON Schema 属性。

                  • required: optional array of string

                    必需属性名称列表。

                  • type: optional "object"

                    工具输入 schema 必须为 'object'。

                    • "object"

                • name: string

                • type: "custom"

                  • "custom"

            • type: "agent"

              • "agent"

            • version: number

          • type: "coordinator"

            • "coordinator"

        • name: string

        • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            已解析的 Anthropic 托管技能。

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            已解析的用户创建的自定义技能。

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            API 响应中返回的自定义工具。

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        更新后会话的完整元数据包。当更新设置了非空元数据时存在；当元数据未更改或清空时不存在。

      • title: optional string

        会话的新标题。仅在更新更改了标题时存在。

示例

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"

响应

{
  "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
  "content": [
    {
      "text": "Where is my order #1234?",
      "type": "text"
    }
  ],
  "type": "user.message",
  "processed_at": "2026-03-15T10:00:00Z"
}