请求体

• namestring必填

  Human-readable name for the environment

• metadataobject可选

  User-provided metadata key-value pairs

• configobject可选

  Environment configuration

  ▸ 展开子字段（3）

  • typestring必填

    Self-hosted environment selector; unsupported here and rejected with 400. Use a cloud environment instead.

    取值 self_hosted
  • networkingobject可选

    Network configuration policy. Omit on update to preserve the existing value.

  • packagesobject可选

    Specify packages (and optionally their versions) available in this environment. When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. Under `limited` networking, requires `networking.allow_package_managers` to be `true`.

• descriptionstring可选

  Optional description of the environment

• scopestring可选

  The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. API organizations support only 'organization'; 'account' is rejected. If not specified, defaults based on organization type.

返回

200

支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT_PACKAGE_INSTALL_FAILED。self_hosted、scope 和跨会话包缓存尚不支持。

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

请求参数

• environment_idstring必填

  path: Environment id, as returned by environments.create or environments.list. Built-in environments can be read but not changed.

• namestring可选

  Updated name for the environment

• metadataobject可选

  User-provided metadata key-value pairs. Set a value to null or empty string to delete the key.

• configobject可选

  Updated environment configuration

  ▸ 展开子字段（3）

  • typestring必填

    Self-hosted environment selector; unsupported here and rejected with 400. Use a cloud environment instead.

    取值 self_hosted
  • networkingobject可选

    Network configuration policy. Omit on update to preserve the existing value.

  • packagesobject可选

    Specify packages (and optionally their versions) available in this environment. When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. Under `limited` networking, requires `networking.allow_package_managers` to be `true`.

• descriptionstring可选

  Updated description of the environment. Omit to preserve; null clears to null; an empty string is stored as an empty string.

• scopestring可选

  The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only.

返回

200

支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT_PACKAGE_INSTALL_FAILED。self_hosted、scope 和跨会话包缓存尚不支持。

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

请求参数

• environment_idstring必填

  path: Environment id, as returned by environments.create or environments.list. Built-in environments can be read but not changed.

返回

200

支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT_PACKAGE_INSTALL_FAILED。self_hosted、scope 和跨会话包缓存尚不支持。

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

请求体

• namestring必填

  Name of the entry or object.

• environment_idstring可选

  Environment recipe id; null or omitted when none was selected.

返回

201

Praxis 超集：MA 只有会话级临时容器与 memory_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment_id 是可空配方引用；电脑默认使用 light sandbox，sandbox_id 为 SDK 可用的公开 ID。分页包含归档电脑。

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

请求参数

• limitinteger可选
  默认 20

  query: Maximum number of items to return in this page: a positive integer, at most 100 (default 20; for session resources default and maximum are 1000). A larger value returns 400.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

返回

200

Praxis 超集：MA 只有会话级临时容器与 memory_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment_id 是可空配方引用；电脑默认使用 light sandbox，sandbox_id 为 SDK 可用的公开 ID。分页包含归档电脑。

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

请求参数

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

返回

200

Praxis 超集：MA 只有会话级临时容器与 memory_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment_id 是可空配方引用；电脑默认使用 light sandbox，sandbox_id 为 SDK 可用的公开 ID。分页包含归档电脑。

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

请求参数

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

• namestring必填

  Name of the entry or object.

返回

200

Praxis 超集：MA 只有会话级临时容器与 memory_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment_id 是可空配方引用；电脑默认使用 light sandbox，sandbox_id 为 SDK 可用的公开 ID。分页包含归档电脑。

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

请求参数

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

返回

200

Praxis 超集：MA 只有会话级临时容器与 memory_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment_id 是可空配方引用；电脑默认使用 light sandbox，sandbox_id 为 SDK 可用的公开 ID。分页包含归档电脑。

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

请求参数

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

返回

200

Praxis 扩展：Managed Agents 没有持久 Computer 的删除生命周期。仅允许已归档的电脑；active 返回 400 COMPUTER_ACTIVE（先归档），先销毁电脑数据再删除登记，成功返回 id 和 type=computer_deleted；不存在或跨租户返回 404。

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

请求参数

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

• pathstring可选
  默认 "/"

  query: Directory on the computer to list; absolute path as returned in the path field of an earlier listing. Omit it to list from the computer's root.

返回

200

Praxis 超集：MA 只有会话级临时容器与 memory_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment_id 是可空配方引用；电脑默认使用 light sandbox，sandbox_id 为 SDK 可用的公开 ID。分页包含归档电脑。

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

请求参数

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

• pathstring必填

  query: Absolute path of the file whose content to download, as returned in the path field of computers.files.list.

返回

200

Praxis 超集：MA 只有会话级临时容器与 memory_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment_id 是可空配方引用；电脑默认使用 light sandbox，sandbox_id 为 SDK 可用的公开 ID。分页包含归档电脑。

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

请求参数

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

返回

200

Praxis 自有扩展：Managed Agents 没有持久 Computer 连接。返回 SDK 可用的公开 sandbox_id、envd_access_token 和 template_id。归档电脑仍可连接；跨租户或不存在返回 404。连接凭证不可缓存。

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

请求参数

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

• namestring必填

  query: Single filename, at most 255 UTF-8 bytes, excluding slash, dot segments and control characters.

返回

201

Praxis 扩展：Managed Agents 没有持久 Computer 附件目录。用户上传可以覆盖同名附件，智能体始终只读；运行令牌调用上传返回 403 READ_ONLY。name 是单个文件名、最多 255 UTF-8 字节，MIME 始终按扩展名推断，上传的 Content-Type 不持久保存，digest 可省略。上限 16 MiB，超限 413、非法名字 400；归档电脑也可上传，跨租户 404。

错误按 Anthropic 错误格式返回（type / message / request_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.

• typestring必填

  query: Resource type selector for the body; only file resources are supported. Normally you send type inside the JSON body and omit this parameter.

  取值 file
• file_idstring必填

  ID of a previously uploaded file.

• mount_pathstring可选

  Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

返回

200

支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。

错误按 Anthropic 错误格式返回（type / message / request_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.

• limitnumber可选

  query: Number of items per page.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

返回

200

支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。

错误按 Anthropic 错误格式返回（type / message / request_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.

• resource_idstring必填

  path: Id of a resource attached to the session, as returned by sessions.resources.add or sessions.resources.list.

• session_idstring必填

  query: 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.

返回

200

支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。

错误按 Anthropic 错误格式返回（type / message / request_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.

• resource_idstring必填

  path: Id of a resource attached to the session, as returned by sessions.resources.add or sessions.resources.list.

• session_idstring必填

  query: 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.

返回

200

支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。

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

请求参数

• created_at[gte]string可选

  query: Return agents created at or after this time (inclusive).

• created_at[lte]string可选

  query: Return agents created at or before this time (inclusive).

• include_archivedboolean可选

  query: Include archived agents in results. Defaults to false.

• limitnumber可选

  query: Number of items per page.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

返回

200

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

请求体

• namestring必填

  智能体名称，1–255 个字符，工作区内可读。

• modelstring | object必填

  智能体使用的模型：直接写模型名字符串（如 claude-opus-5），或传对象做附加配置（见子字段）。

  ▸ 展开子字段（5）

  • idstring必填

    模型名字符串，如 claude-opus-5。

  • effortstring | object可选

    每次推理的思考力度：可传级别字符串（如 high）或 {type: high} 对象。创建时省略取该模型的默认值；更新时省略保持不变。

  • inference_geostring可选

    模型推理的地理区域；不传沿用工作区默认。model 是整体替换字段，更新时省略子字段即清除该项。

  • speedstring可选

    推理速度模式：fast 出字显著更快但按溢价计费；并非所有模型都支持，不支持的组合在创建时被拒。

  • settingsobject可选

    Platform model settings. Only reasoning is supported; other model controls return 400.

• systemstring可选

  智能体的系统提示词。

• metadataobject可选

  自定义元数据键值对，最多 16 个键、每个值最长 512 字符。

• descriptionstring可选

  智能体的用途说明。

• mcp_serversarray可选

  智能体连接的 MCP 服务器列表，最多 20 个，名称必须唯一；每个服务器都要被 tools 里的 mcp_toolset 引用，否则整笔请求被拒。

  ▸ 展开子字段（3）

  • typestring必填

    服务器类型，目前只支持 url。

    取值 url
  • namestring必填

    MCP 服务器在本列表内的唯一名称，1–255 个字符，供 mcp_toolset 配置引用。

  • urlstring必填

    MCP 服务器的端点地址。

• multiagentobject可选◐ 部分支持

  多智能体协作拓扑：会话主线程作为协调者，从 agents 名单派生会话线程执行工作。

  ▸ 展开子字段（2）

  • agentsarray必填

    协调者可以派生为会话线程的智能体名单，1–20 项；支持 ID 字符串、{type: agent, id, version?} 和最多一个 {type: self}。创建/更新时固定版本。成员须唯一、存在且未归档，不能自身带 multiagent。每个 coordinator 最多一个 advisor，模型须可用且不同于智能体模型；仅主会话可咨询，每次咨询为独立 advisor 线程，建议以 agent.thread_message_received 返回。

  • typestring必填

    拓扑类型，目前只有 coordinator。

    取值 coordinator
• skillsarray可选

  智能体可用的 Skill 列表。

• toolsarray可选

  智能体可用的工具配置，所有工具合计最多 128 个。

• computer_idstring可选

  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.

• ▸ 更多参数（2）

  • subagent_modelstring可选

    /agent/v1 扩展：智能体级子智能体默认模型 ID，随修订固定。省略保持，null 清除。调用 model 优先，其次本字段，再其次名册成员模型或内置类型的父会话模型。/anthropic 不接受或返回此字段。

  • modelsobject可选

    扩展：可切换模型列表，仅 /agent/v1 支持。

    ▸ 展开子字段（1）

    • allowedarray必填

      必须包含默认模型；创建时省略表示只能使用默认模型。更新时省略保持不变。会话使用其钉住版本的列表。

返回

200

agent_toolset_20260401 是原生工具集，包含 bash、edit、glob、grep、read、write、web_search、web_fetch，以及 TaskOutput、TaskStop、Monitor、Agent、SendMessage。新建智能体默认全部启用；configs 可逐个设置 name、enabled、permission_policy，未列出的工具遵循 default_config（默认启用）。后台任务、Monitor 和子智能体依赖 bash；启用任一后台工具时，bash 提供 run_in_background。兼容 API /anthropic 只接受和返回官方 8 个工具，经该入口创建的会话也只注册这 8 个工具。 支持文本提示词、模型、元数据与内置工具。model.settings.reasoning 可选 low、medium、high、xhigh、none，为会话提供默认思考档位；会话显式 thinking 优先，不支持的默认值回退到模型 default_effort。示例 model: {id: "deepseek-v4-flash", settings: {reasoning: "high"}}。Skills 及其它额外模型控制尚不支持，传入会返回 400。可在工具集 permissions 中设置 allow、ask、deny 规则，最多共 100 条，用于以后的对话。 multiagent 接受 null 或 coordinator 名册，1–20 项：智能体 ID、{type:"agent",id,version?} 或最多一个 {type:"self"}。创建/更新时固定版本；成员去重且须存在、未归档、不能自身带 multiagent。名册可启用 Agent，仍需启用 bash；SendMessage 遵循工具配置。每个 coordinator 最多一个 advisor，模型须可用且不同于智能体模型；仅主会话可咨询，每次咨询为独立 advisor 线程，建议以 agent.thread_message_received 返回。 /agent/v1 顶层 subagent_model 是可空模型 ID，随智能体版本保存；省略保留、null 清除。模型须存在。优先级为调用 model > subagent_model > 成员模型（内置类型用父会话模型）。/anthropic 不接受或返回此字段。

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

请求参数

• agent_idstring必填

  path: Agent id, as returned by agents.create or agents.list (for a session filter, the agent the session was created with). Not the agent name.

• versionnumber可选

  query: Agent version to read; omit for the latest. Integer of at least 1; versions are listed by agents.versions.list.

返回

200

tools 在一个 agent_toolset_20260401 条目中返回全部原生工具的有效配置，可原样用于更新。将示例中的资源 ID 替换成你创建的资源 ID。

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

请求参数

• agent_idstring必填

  path: Agent id, as returned by agents.create or agents.list (for a session filter, the agent the session was created with). Not the agent name.

• namestring可选

  智能体名称；省略保持不变，不能传空串清除。

• modelstring | object可选

  智能体使用的模型：直接写模型名字符串（如 claude-opus-5），或传对象做附加配置（见子字段）。

  ▸ 展开子字段（5）

  • idstring必填

    模型名字符串，如 claude-opus-5。

  • effortstring | object可选

    每次推理的思考力度：可传级别字符串（如 high）或 {type: high} 对象。创建时省略取该模型的默认值；更新时省略保持不变。

  • inference_geostring可选

    模型推理的地理区域；不传沿用工作区默认。model 是整体替换字段，更新时省略子字段即清除该项。

  • speedstring可选

    推理速度模式：fast 出字显著更快但按溢价计费；并非所有模型都支持，不支持的组合在创建时被拒。

  • settingsobject可选

    Platform model settings. Only reasoning is supported; other model controls return 400.

• systemstring可选

  系统提示词；省略保持不变，传空串或 null 清除。

• versionnumber可选

  智能体当前版本号，用于并发保护：必须与最近一次创建/读取返回的版本一致，否则返回冲突。

• metadataobject可选

  元数据补丁：键设为字符串即写入，设为 null 即删除；省略该字段保持不变。存储上限 16 个键、每个值 512 字符。

• descriptionstring可选

  用途说明；省略保持不变，传空串或 null 清除。

• mcp_serversarray可选

  整体替换的 MCP 服务器列表；省略保持不变，传空数组或 null 清除。

• multiagentobject可选◐ 部分支持

  多智能体协作拓扑：会话主线程作为协调者，从 agents 名单派生会话线程执行工作。

  ▸ 展开子字段（2）

  • agentsarray必填

    协调者可以派生为会话线程的智能体名单，1–20 项；支持 ID 字符串、{type: agent, id, version?} 和最多一个 {type: self}。创建/更新时固定版本。成员须唯一、存在且未归档，不能自身带 multiagent。每个 coordinator 最多一个 advisor，模型须可用且不同于智能体模型；仅主会话可咨询，每次咨询为独立 advisor 线程，建议以 agent.thread_message_received 返回。

  • typestring必填

    拓扑类型，目前只有 coordinator。

    取值 coordinator
• skillsarray可选

  整体替换的 Skill 列表；省略保持不变，传空数组或 null 清除。

• ▸ 更多参数（4）

  • toolsarray可选

    整体替换的工具配置；省略保持不变，传空数组或 null 清除。

  • computer_idstring可选

    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.

  • subagent_modelstring可选

    /agent/v1 扩展：智能体级子智能体默认模型 ID，随修订固定。省略保持，null 清除。调用 model 优先，其次本字段，再其次名册成员模型或内置类型的父会话模型。/anthropic 不接受或返回此字段。

  • modelsobject可选

    扩展：可切换模型列表，仅 /agent/v1 支持。

    ▸ 展开子字段（1）

    • allowedarray必填

      必须包含默认模型；创建时省略表示只能使用默认模型。更新时省略保持不变。会话使用其钉住版本的列表。

返回

200

通过 agent_toolset_20260401.configs 逐个开关原生工具并设置权限。未列出的工具遵循 default_config；后台任务、Monitor 和子智能体依赖 bash。version 可用于乐观并发控制，版本冲突返回 409；无变化的更新不增加版本。Skills 尚不支持。更新工具集 permissions 可把允许的同类操作保存到智能体的新版本，供以后的对话使用。 multiagent 接受 null 或 coordinator 名册，1–20 项：智能体 ID、{type:"agent",id,version?} 或最多一个 {type:"self"}。创建/更新时固定版本；成员去重且须存在、未归档、不能自身带 multiagent。名册可启用 Agent，仍需启用 bash；SendMessage 遵循工具配置。每个 coordinator 最多一个 advisor，模型须可用且不同于智能体模型；仅主会话可咨询，每次咨询为独立 advisor 线程，建议以 agent.thread_message_received 返回。 /agent/v1 顶层 subagent_model 是可空模型 ID，随智能体版本保存；省略保留、null 清除。模型须存在。优先级为调用 model > subagent_model > 成员模型（内置类型用父会话模型）。/anthropic 不接受或返回此字段。

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

请求参数

• agent_idstring必填

  path: Agent id, as returned by agents.create or agents.list (for a session filter, the agent the session was created with). Not the agent name.

• limitnumber可选

  query: Number of items per page.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

返回

200

将示例中的资源 ID 替换成你创建的资源 ID。

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

请求参数

• agent_idstring必填

  path: Agent id, as returned by agents.create or agents.list (for a session filter, the agent the session was created with). Not the agent name.

返回

200

归档后保留查询与历史版本，不能继续更新。请只归档自己的测试智能体。

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

请求参数

• agent_idstring可选

  query: Return only sessions created with this agent id (from agents.list or agents.create). This is one of the three filters sessions.list supports.

• agent_versionnumber可选

  query: 按智能体版本过滤；仅在同时设置 agent_id 时生效。

• created_at[gt]string可选

  query: Exclusive created-at lower bound for sessions. Declared by the Managed Agents shape but not supported here; sending it returns 400.

• created_at[gte]string可选

  query: Created-at lower bound for sessions. Declared by the Managed Agents shape but not supported here: sessions.list honors only limit, page and agent_id, and other filters return 400.

• created_at[lt]string可选

  query: Exclusive created-at upper bound for sessions. Declared by the Managed Agents shape but not supported here; sending it returns 400.

• created_at[lte]string可选

  query: Created-at upper bound for sessions. Declared by the Managed Agents shape but not supported here: sessions.list honors only limit, page and agent_id, and other filters return 400.

• deployment_idstring可选

  query: Declared by the Managed Agents shape but not supported by sessions.list; sending it returns 400.

• include_archivedboolean可选

  query: Declared by the Managed Agents shape but not supported by sessions.list; sending it returns 400. Archived sessions are retrievable by id.

• memory_store_idstring可选

  query: Declared by the Managed Agents shape but not supported by sessions.list; sending it returns 400.

• orderstring可选

  query: 按创建时间排序：asc 从旧到新，desc 从新到旧（默认）。

• ▸ 更多参数（3）

  • statusesarray可选

    query: 按会话状态过滤，可重复该参数匹配多种状态。

  • limitnumber可选

    query: Number of items per page.

  • pagestring可选

    query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

返回

200

支持 limit、page 与 agent_id；agent_version、时间范围、deployment_id、memory_store_id、include_archived、order、statuses 尚不支持，传入返回 400。

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

请求体

• modelstring可选

  智能体使用的模型：直接写模型名字符串（如 claude-opus-5），或传对象做附加配置（见子字段）。

• agentstring | object必填

  会话要运行的智能体：直接写智能体 ID 字符串（固定用最新版本），或传对象指定 id 与 version（见子字段）。

  ▸ 展开子字段（8）

  • idstring必填

    会话要运行的智能体 ID。

  • typestring必填

    引用类型，目前只有 agent。

    取值 agent_with_overrides
  • versionnumber可选

    固定使用的智能体版本；省略用最新版本。

  • mcp_serversarray可选

    替换本会话的 MCP 服务器列表：传入的数组整体生效；传空数组清除，省略沿用智能体的配置。

  • modelstring | object可选

    替换本会话的模型：模型名字符串（如 claude-opus-5）或配置对象；省略沿用智能体自身的模型。

  • skillsarray可选

    替换本会话的 Skill 列表；传空数组清除，省略沿用智能体的配置。

  • systemstring可选

    替换本会话的系统提示词，最长 100,000 字符；传 null 清除，省略沿用智能体的。

  • toolsarray可选

    替换本会话的工具配置；传空数组清除，省略沿用智能体的配置。

• environment_idstring可选

  会话运行所在的环境 ID，决定容器的基础环境。

• titlestring可选

  会话标题，便于在控制台辨认。

• metadataobject可选

  会话的自定义元数据键值对。

• budgetobject可选

  会话的预算上限设置。

  ▸ 展开子字段（2）

  • max_list_costobject必填

    预算内列表类调用的花费上限。

  • typestring必填

    预算类型，目前只有 max_list_cost。

    取值 limit
• initial_eventsarray可选

  创建时按顺序发给会话的初始事件，支持 user.message 与 user.define_outcome，一次最多 50 条。

• resourcesarray可选

  要挂载进会话容器的资源（如代码仓库、文件）。

• vault_idsarray可选

  保险库 ID 列表：会话里智能体可以使用这些已存凭据。

• cwdstring可选
  默认 "/home/user/workspace"

  Session working directory on any machine. Must be an absolute path within /home/user with no . or .. segments. Repeated and trailing slashes are normalized. Invalid values return 400 invalid_request_error with Invalid cwd.

• ▸ 更多参数（3）

  • computer_idstring可选

    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.

  • time_zonestring可选
    默认 "UTC"

    Praxis extension: the session's IANA time zone name (e.g. Asia/Shanghai) — the clock the runtime environment block renders for every turn. Absent means UTC. Only IANA names are accepted; fixed offsets ("+08:00") and unknown names return 400. Never stored in `metadata`.

  • 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.

      取值 lowmediumhighxhighnone

返回

200

可在创建时传 model（models.allowed 内的 ID 字符串；无 allowed 时只允许默认模型）与 thinking（{effort: "low|medium|high|xhigh|none"} 或 null），在首条 initial_events 执行前保存。省略或 null 继承智能体默认，再使用模型默认。档位必须在 model.thinking.efforts 内；none 要求 can_disable 为 true，否则返回 400 invalid_request_error。响应包含 thinking 与 model.thinking: {efforts, can_disable, default_effort}；未知能力为 null，默认档位也可为 null。示例：{"agent":"agent_123","model":"deepseek-v4-flash","thinking":{"effort":"xhigh"}}。这些选择字段只在 /agent/v1 提供。先创建智能体，将示例 agent_123 换成返回的 id。省略 environment_id 得到轻量机器（light），有默认或显式 computer_id 时使用该 Computer；指定 node22 或租户自建 cloud 环境则使用沙箱配方。无配方时响应省略 environment_id。不支持内联智能体覆盖、预算与凭据库。支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。

错误按 Anthropic 错误格式返回（type / message / request_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.

返回

200

将示例中的资源 ID 替换成你创建的资源 ID。

错误按 Anthropic 错误格式返回（type / message / request_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.

• 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），参见 错误码

请求参数

• 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.

返回

200

扩展：仅在 /agent/v1 提供，形状参照 Claude Agent SDK getContextUsage()，字段使用 snake_case。detail 固定为 summary：总量优先使用上次模型实测，各来源按本地估算占比摊分，used 分类之和等于 total_tokens。categories 只列非零来源，按 kind（used/free/buffer/deferred）判断用途。key 是稳定来源标识扩展；客户端须容忍未知 key 和新增来源，未知名称回退显示 name。MCP 按服务器归组，插件按 id 归组，摘要单独计量。excluded_items 暂为零。尚无测量时 total_tokens、total_tokens_source、measured_at 为 null，categories 为空，明细为零或空数组。切换模型后 max_tokens、auto_compact_threshold 与 free/buffer 立即按新模型重算，保留最近测量值。窗口未知或自动压缩熔断时 is_auto_compact_enabled 为 false。例如 model.thinking 为 {efforts: [high, xhigh], can_disable: true, default_effort: high}。model.thinking 返回 efforts（支持的档位）、can_disable（是否允许 none）及 default_effort（模型默认档位，可为 null）；能力未知时整个 thinking 为 null。会话不存在或调用者不可见时返回 404。

错误按 Anthropic 错误格式返回（type / message / request_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.

返回

200

仅在 /agent/v1 提供。kind 是开放字符串。subagent 行的 thread_id 指向对应子线程，其他 kind 为 null。completed 且 delivery=pending 显示 result_pending。notified_at 是系统通知批次被受理开轮的时间，无则 null。trigger_count 仅监视器返回已受理的事件批次数，无记录则 null。时间为 RFC3339。会话不存在或不可见返回 404。

错误按 Anthropic 错误格式返回（type / message / request_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.

• task_idstring必填

  path: Background task id (task_...), as listed by sessions.background_tasks.list.

• offsetinteger可选
  默认 0

  query: Byte offset into the task output to read from; start at 0 and continue with the next_offset of the previous response. Integer of at least 0, default 0.

• max_bytesinteger可选
  默认 65536

  query: Maximum number of bytes to return: an integer from 1 to 262144, default 65536.

返回

200

offset 默认 0；max_bytes 默认 65536，上限 262144。返回 text、next_offset、eof。沙箱已暂停或不存在时返回空 text、原 offset、eof=true、unavailable=true。读取不确认模型结果。

错误按 Anthropic 错误格式返回（type / message / request_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.

• task_idstring必填

  path: Background task id (task_...), as listed by sessions.background_tasks.list.

返回

200

复用 TaskStop：持久化 stop_requested_at 并终止进程组。返回 BackgroundTask；终止尚未观察到时仍可为 running，但不可取消。已结束或不支持停止的任务返回 409。

错误按 Anthropic 错误格式返回（type / message / request_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.

• instructionsstring可选

  Optional focus instructions for the summary, passed to the summarizing model unchanged.

返回

200

仅在 /agent/v1 提供。请求体可省略或为 {}，可选 instructions 必须为字符串且原样传递。Idempotency-Key 请求头原样传递；缺失时生成 UUID。响应为 { type: session_compaction, id, status, reason? }，id 是操作 ID。queued/running 返回 202；skipped/succeeded/failed 返回 200。非字符串 instructions 返回 400 invalid_request_error。不存在或不可见的托管会话返回 404 not_found_error。

错误按 Anthropic 错误格式返回（type / message / request_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.

• operation_idstring必填

  path: Compaction operation id returned by sessions.compact in the id field of the session_compaction object.

返回

200

仅在 /agent/v1 提供。响应为 { type: session_compaction, id, status, reason? }，所有状态均返回 200。操作不存在或会话不可见时返回 404 not_found_error。

错误按 Anthropic 错误格式返回（type / message / request_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.

返回

200

仅在 /agent/v1 提供。返回 { data: [...] }。每项包含 type、id、event_id、trigger、status、model、compacted_message_count、input_tokens_before、input_tokens_after、summary、error、created_at，字段按服务记录原样返回。不存在或不可见的托管会话返回 404 not_found_error。

错误按 Anthropic 错误格式返回（type / message / request_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.

• created_at[gt]string可选

  query: Return events created after this time (exclusive). Compared against the event's `processed_at` value.

• created_at[gte]string可选

  query: Return events created at or after this time (inclusive). Compared against the event's `processed_at` value.

• created_at[lt]string可选

  query: Return events created before this time (exclusive). Compared against the event's `processed_at` value.

• created_at[lte]string可选

  query: Return events created at or before this time (inclusive). Compared against the event's `processed_at` value.

• orderstring可选

  query: 按事件处理时间排序：asc 从早到晚（默认），desc 相反。

• typesarray可选

  query: 按事件类型过滤，取值与返回事件的 type 字段一致（如 user.message、agent.tool_use）；不传返回全部类型。

• limitnumber可选

  query: Number of items per page.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

返回

200

先发送消息再读取历史；处理完成前可能只看到已接纳的输入。支持分页、事件类型和时间过滤。会话等待工具授权时停在 session.status_idle，stop_reason 为 requires_action，event_ids 列出待确认的 agent.tool_use；运行失败时先出现 session.error，再出现 session.status_terminated。agent.thinking 带思考内容 content。使用网页搜索或读取网页时，/agent/v1 与 /anthropic 的工具结果均为官方 search_result 块；回答文本块的 citations 是 /agent/v1 的扩展字段，/anthropic 将回答引用显示为正文中的 [n]。

错误按 Anthropic 错误格式返回（type / message / request_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.

• eventsarray必填

  要发送给会话的事件列表。

返回

200

将 sesn_123 换成创建会话返回的 id。每条 user.message 只接受一个非空文本块。支持文本 user.message、user.interrupt 和工具确认；可发送 user.withdraw 并用 event_id 指向仍在排队的消息来撤回它，消息已开始处理时返回 409。运行中需要提前补充要求时，发送 user.steer 事件，并用 event_id 指向仍在排队的消息：当前工具继续执行，消息在下一次模型请求前进入当前回合。返回带 processed_at 的 user.steer 回执，重复标记返回同一回执；已开始或已撤回返回 409，事件不存在返回 404。有待授权时继续等待；若当前回合先结束，消息仍按普通队列处理。默认发送消息仍然排队，/anthropic 不接受 user.steer。其它事件变体尚不支持。返回的是已接纳事件；模型回复从事件历史或订阅读取。会话等待工具授权时发送的 user.message 会排队：返回的事件 processed_at 为 null，授权处理完成后按发送顺序执行。允许工具调用时可在 updated_permissions 中原样提交该调用的 permission_suggestions，让本次对话记住同类操作；危险操作不提供可记住的建议。使用网页搜索或读取网页时，/agent/v1 与 /anthropic 的工具结果均为官方 search_result 块；回答文本块的 citations 是 /agent/v1 的扩展字段，/anthropic 将回答引用显示为正文中的 [n]。

错误按 Anthropic 错误格式返回（type / message / request_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.

• event_deltasarray可选

  query: When set, this connection also receives streaming deltas (`event_start`, `event_delta`) while an event is being produced, before the event itself arrives. Deltas are best-effort; when the final event is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no final event — its terminal `span.model_request_end` closes the preview. Accepts one or more event types to preview and may be repeated: `agent.message` streams `content_delta` fragments; `agent.thinking` is start-only — a signal that the agent has begun extended thinking, concluded by the `agent.thinking` event itself. Only previews of the requested event types are sent.

返回

200

保持 SSE 连接以接收事件；请求不会像普通 JSON 接口一样立刻结束。先创建会话并替换 sesn_123，再从另一请求发送消息；停止按钮只断开订阅，不会停止智能体。SDK 0.124.0 会过滤 session.usage，完整用量请读历史。传 event_deltas[]=agent.message 或 event_deltas[]=agent.thinking 可在最终事件到达前收到逐段预览（event_start 与 event_delta）。传 event_deltas[]=agent.tool_use 可以在参数生成过程中收到 input_json_delta 片段。使用网页搜索或读取网页时，/agent/v1 与 /anthropic 的工具结果均为官方 search_result 块；回答文本块的 citations 是 /agent/v1 的扩展字段，/anthropic 将回答引用显示为正文中的 [n]。

错误按 Anthropic 错误格式返回（type / message / request_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。

    取值 limit
• 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.

    取值 lowmediumhighxhighnone

返回

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），参见 错误码

请求参数

• 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.

返回

200

归档后的会话拒绝新消息（400 invalid_request_error，写明会话已归档），读取与事件历史仍可用；重复归档幂等，archived_at 保持首次归档时间。

错误按 Anthropic 错误格式返回（type / message / request_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.

• limitnumber可选

  query: Number of items per page.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

返回

200

按 created_at 升序返回主线程及全部子线程。线程 id 为 sthr_ 加所属会话 id 的后缀；子线程的 parent_thread_id 指向主线程，session_id 始终为父会话。agent 是实际运行的定义，内置类型的 name 为类型名，未注册的 id/version 为 null。归档子线程的 status 为 terminated，archived_at 为归档时间；stats/usage 无线程级追踪时如实为 null。

错误按 Anthropic 错误格式返回（type / message / request_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.

• thread_idstring必填

  path: Execution thread id (sthr_...), as listed by sessions.threads.list; the primary thread id equals the session's own thread. Unknown or foreign ids return 404.

• session_idstring必填

  query: 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.

返回

200

返回本会话的主线程或子线程，与列表项逐字段一致。其他会话的线程、未知线程或非 sthr_ id 一律返回 404，不泄露其存在性。

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