更新会话

先调用「创建会话」，用返回的会话 ID 替换示例 ID。

POST /anthropic/v1/sessions/{session_id}◐ 部分支持

请求参数

session_idstring必填
path: 会话 ID（路径或查询参数）。
agentobject可选
会话要运行的智能体：直接写智能体 ID 字符串（固定用最新版本），或传对象指定 id 与 version（见子字段）。
▸ 展开子字段（2）
- mcp_serversarray可选
  替换本会话的 MCP 服务器列表：传入的数组整体生效；传空数组清除，省略沿用智能体的配置。
- toolsarray可选
  替换本会话的工具配置；传空数组清除，省略沿用智能体的配置。
budgetobject可选
A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
▸ 展开子字段（2）
- max_list_costobject必填
  预算内列表类调用的花费上限。
- typestring必填
  预算类型，目前只有 max_list_cost。
  取值 limit
metadataobject可选
Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.
titlestring可选
Human-readable session title.
vault_idsarray可选
Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use.

200

支持 title 与 metadata（官方补丁语义：字符串值写入、null 删除该键、整包 null 清空，未提及的键保留）。官方的 agent 覆盖（tools/mcp_servers）、budget 与 vault_ids 不支持，传入返回 400 并点名字段。归档后的会话更新返回 409。

错误按 Claude Managed Agents 格式返回，参见错误码

响应

HTTP 200

Successful response

application/json

名称	类型	说明
id	string
agent	object	Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
agent.id	string
agent.description	null \| string
agent.mcp_servers	array<object>
agent.model	object	Model identifier and configuration.
agent.multiagent	null \| object	Resolved coordinator topology with full agent definitions for each roster member.
agent.name	string
agent.skills	array<object>
agent.system	null \| string
agent.tools	array<object>
agent.type	string
agent.version	number
archived_at	null \| string	A timestamp in RFC 3339 format
budget	null \| object	A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
budget.max_list_cost	object	A monetary amount in a specific currency.
budget.type	string
created_at	string	A timestamp in RFC 3339 format
environment_id	string
metadata	object
outcome_evaluations	array<object>	Per-outcome evaluation state. One entry per `define_outcome` event sent to the session.
outcome_evaluations[].completed_at	null \| string	A timestamp in RFC 3339 format
outcome_evaluations[].description	string	What the agent should produce.
outcome_evaluations[].explanation	null \| string	Grader's verdict text from the most recent evaluation. For `satisfied`, explains why criteria are met; for `needs_revision` (intermediate), what's missing; for `failed`, why unrecoverable.
outcome_evaluations[].iteration	number	0-indexed revision cycle the outcome is currently on.
outcome_evaluations[].outcome_id	string	Server-generated outc_ ID for this outcome.
outcome_evaluations[].result	string	Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.
outcome_evaluations[].type	string
resources	array<object>
resources[].id	string
resources[].created_at	string	A timestamp in RFC 3339 format
resources[].mount_path	string \| null \| string	Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
resources[].type	string
resources[].updated_at	string	A timestamp in RFC 3339 format
resources[].url	string
resources[].checkout	null \| object
resources[].file_id	string
resources[].memory_store_id	string	The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
resources[].access	null \| string	Access mode for an attached memory store.
resources[].description	string	Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.
resources[].instructions	null \| string	Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
resources[].name	null \| string	Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
stats	object	Timing statistics for a session.
stats.active_seconds	number	Cumulative time in seconds the session spent in `running` status. Excludes idle time.
stats.duration_seconds	number	Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
status	string	SessionStatus enum - `rescheduling` - Transient error occurred, retrying automatically. - `running` - Agent is actively executing. - `idle` - Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `terminated` - Session has ended, either due to an error or completion.
title	null \| string
type	string
updated_at	string	A timestamp in RFC 3339 format
usage	object	Cumulative token usage for a session across all turns.
usage.active_seconds	number	Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on.
usage.cache_creation	object	Prompt-cache creation token usage broken down by cache lifetime.
usage.cache_read_input_tokens	number	Total tokens read from prompt cache.
usage.input_tokens	number	Total input tokens consumed across all turns.
usage.list_cost	null \| object	A monetary amount in a specific currency.
usage.output_tokens	number	Total output tokens generated across all turns.
usage.server_tool_use	null \| object	Cumulative count of server-executed tool invocations, broken down by tool.
vault_ids	array<string>	Vault IDs attached to the session at creation. Empty when no vaults were supplied.
deployment_id	null \| string	Deployment ID when the session was created from a deployment reference. Null otherwise.