更新会话
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: stringMCP 服务器的端点 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: stringMCP 服务器的名称。必须与 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 BetaManagedAgentsMCPToolsetDefaultConfigParamsMCP 服务器所有工具的默认配置。
-
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"工具输入模式必须为 '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 }一个 Managed Agents
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已解析的协调器拓扑，包含每个成员的完整代理定义。
-
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"工具输入模式必须为 '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: stringRFC 3339 格式的时间戳
-
created_at: stringRFC 3339 格式的时间戳
-
environment_id: string -
metadata: map[string] -
outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource每个结果的评估状态。发送到会话的每个 define_outcome 事件一个条目。
-
completed_at: stringRFC 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: stringRFC 3339 格式的时间戳
-
mount_path: string -
type: "github_repository""github_repository"
-
updated_at: stringRFC 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: stringRFC 3339 格式的时间戳
-
file_id: string -
mount_path: string -
type: "file""file"
-
updated_at: stringRFC 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 enum
-
"rescheduling" -
"running" -
"idle" -
"terminated"
-
-
title: string -
type: "session""session"
-
updated_at: stringRFC 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"
]
}