智能体
更新会话
修改一个会话的信息（如标题、元数据）。
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
POST
/agent/v1/sessions/{session_id}◐ 部分支持请求参数
session_idstring必填path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.
modelstring可选扩展：模型 ID 字符串，必须属于会话钉住版本的 models.allowed；没有列表时只能选默认模型。下一轮生效，在途一轮不受影响，此处不检查上下文窗口。
agentobject可选会话要运行的智能体：直接写智能体 ID 字符串（固定用最新版本），或传对象指定 id 与 version（见子字段）。
▸ 展开子字段（2）
mcp_serversarray可选替换本会话的 MCP 服务器列表：传入的数组整体生效；传空数组清除，省略沿用智能体的配置。
toolsarray可选替换本会话的工具配置；传空数组清除，省略沿用智能体的配置。
titlestring可选Human-readable session title.
metadataobject可选Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.
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。
vault_idsarray可选Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use.
thinkingobject可选Praxis extension: explicit session thinking effort; null inherits the pinned agent default, then the model default. none disables thinking only when model.thinking.can_disable is true. Unsupported efforts return 400 invalid_request_error.
▸ 展开子字段（1）
effortstring必填Thinking level for this session. The model must support the chosen effort; none requires can_disable. Null on thinking restores inheritance from the agent and model.
返回
200
可选 model 为钉住版本 allowed 内的 ID，thinking 为 {effort: "low|medium|high|xhigh|none"} 或 null。省略保留原值，null 恢复继承；仅换模型会清除不支持的会话档位。两者同时传入按新模型校验，不支持返回 400 且原选择不变。下一轮生效，在途一轮不变。示例：{"model":"deepseek-v4-flash","thinking":{"effort":"xhigh"}}。响应含 thinking 及 model.thinking: {efforts, can_disable, default_effort}，能力未知为 null。这些选择字段仅在 /agent/v1 提供。支持 title 与 metadata（官方补丁语义：字符串值写入、null 删除该键、整包 null 清空，未提及的键保留）。官方的 agent 覆盖（tools/mcp_servers）、budget 与 vault_ids 不支持，传入返回 400 并点名字段。归档后的会话更新返回 409。
错误按 Anthropic 错误格式返回（type / message / request_id），参见 错误码
响应
HTTP 200
Successful response
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Session id (sesn_...). Pass it as session_id in every session call. |
| agent | object | Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. |
| agent.id | string | Agent id (agent_...). Pass it as agent when creating a session and as agent_id in agent calls. |
| agent.description | null | string | Free-text description of what the agent is for; null when none was set. |
| agent.mcp_servers | array<object> | URL MCP servers the agent can call, paired one-to-one with mcp_toolset entries in tools and saved with the agent version. No credentials are stored here. |
| 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 | Display name of the agent, as set on create or update. It is a label, not a unique key. |
| agent.skills | array<object> | Skills attached to the agent. Setting skills is not supported on this platform and returns 400, so do not send this field on create or update. |
| agent.system | null | string | System prompt given to the model at the start of every session of this agent; null when none was set. |
| agent.tools | array<object> | Tools of the agent: one agent_toolset_20260401 entry for the native tools (all resolved settings are returned, ready to send back on update), plus mcp_toolset entries and custom tool definitions. |
| agent.type | string | Always `agent`. An agent definition. |
| agent.version | number | The agent's current version. Starts at 1 and increments each time the agent is modified. |
| 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 | Always `limit`. A spending limit. |
| created_at | string | A timestamp in RFC 3339 format |
| environment_id | string | Id of the environment recipe the session's sandbox was created from. Omitted when no recipe was selected, that is, for a light machine or the Computer chosen by computer_id. |
| metadata | object | Free-form string key/value pairs stored with the session, changed through sessions.update patch semantics. |
| 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 | Always `outcome_evaluation`. Record of one outcome evaluation. |
| resources | array<object> | Resources attached to the session, at most 500; each is a file reference mounted into the session's machine. |
| resources[].id | string | Resource id, the resource_id of sessions.resources calls. |
| resources[].created_at | string | A timestamp in RFC 3339 format |
| resources[].mount_path | string | null | string | Path inside the machine where the file is mounted; defaults to /mnt/session/uploads/<file_id>, and custom paths are rooted there. / 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 | Always `github_repository`. A GitHub repository resource; not supported on this platform. / Always `file`. A file resource: an uploaded file mounted into the session's machine. / Always `memory_store`. A memory store resource; not supported on this platform. |
| resources[].updated_at | string | A timestamp in RFC 3339 format |
| resources[].url | string | Repository URL. |
| resources[].checkout | null | object | Branch or commit to check out. |
| resources[].file_id | string | Id of the uploaded file; it must exist and belong to your tenant. |
| 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 | Title of the session, set on create or through sessions.update; null when none was set. |
| type | string | Always `session`. A session, one conversation of an agent on a machine. |
| 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. |
| cwd | string | Normalized session working directory; defaults to /home/user/workspace. Forks inherit this directory. |
| computer_id | string | Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. computer_id selects a tenant-owned active computer. Session selection overrides the agent default; a sandbox environment_id and computer_id cannot be combined. Omitted when no computer is selected. |
| model | object | 扩展 / Praxis extension: the currently selected session model. |
| model.id | string | Identifier of the object, as returned by the API; pass it in the path of follow-up calls on the same resource. |
| model.thinking | object | null | Supported thinking controls, or null when capability is unknown or unavailable. efforts lists selectable strengths; can_disable permits none; default_effort is nullable. |
| thinking | object | null | Praxis extension: explicit session thinking effort; null inherits the pinned agent default, then the model default. none disables thinking only when model.thinking.can_disable is true. Unsupported efforts return 400 invalid_request_error. |
| thinking.effort | string | Thinking level saved for this session: low, medium, high, xhigh, or none to turn thinking off. Null or absent means the session inherits the agent default and then the model default. |
| forked_from | object | null | Praxis extension: source of a forked session; null for other sessions. Available only on /agent/v1. |
| forked_from.session_id | string | Id of the parent session this session was forked from; it is left unchanged by the fork. |
| forked_from.message_id | string | message_id of the agent message in the parent session up to which the conversation was copied. |