分支会话（扩展）

POST /agent/v1/sessions/{session_id}/fork● 支持

请求参数

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.
message_idstring必填
分支点的 UI 消息 ID，取自自有面事件的 message_id 字段；须为成功完成轮次的最后一条助手消息。

201

仅在 /agent/v1 提供。message_id 来自 /agent/v1 事件的同名字段，不是事件 id。复制截至并包含该消息的全部对话与工具调用结果；父会话不变，其他轮次正在运行不影响已有完成轮次的分支。新会话沿用智能体及版本、当前模型与思考设置和 cwd 工作目录，标题为父标题加「的分支」，作为普通根会话出现在列表中。父会话有沙箱时复制沙箱及内存快照，新会话独立拥有该沙箱；继承的运行中后台任务被终止，门铃目标只保留新会话，新后台任务表为空。父会话没有沙箱时保留懒创建。返回 201，响应与读取会话相同，forked_from 为 {session_id, message_id}，普通会话为 null。新会话历史末尾有 session.forked 事件，包含 forked_from_session_id 与 forked_from_message_id。上述字段和事件仅在 /agent/v1 可见。非法请求返回 400；不满足分支条件返回 409 FORK_TARGET_INVALID；会话不存在或不属于调用者返回 404。初始化失败时不公开新会话，并回收已分出的沙箱。

错误按 Anthropic 错误格式返回（type / message / request_id），参见错误码

响应

HTTP 201

Forked session (same shape as session retrieval)

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.