# 智能体 API (/docs/api/native/agent)
## 基础地址 [#基础地址]
## 接入 [#接入]
智能体域的概念与整体介绍见[智能体服务](/docs/cloud/services/agent)；鉴权方式见[鉴权](/docs/api/authentication)。
## 端点 [#端点]
### 电脑（10 个端点，10 个可用） [#电脑10-个端点10-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ------ | ------------------------------------------------------------------------------------------------- | -------- | ---- |
| POST | [`/v1/computers`](/docs/api/native/agent/createComputer) | 创建电脑 | ● 支持 |
| GET | [`/v1/computers`](/docs/api/native/agent/listComputers) | 列出电脑 | ● 支持 |
| GET | [`/v1/computers/{computer_id}`](/docs/api/native/agent/retrieveComputer) | 读取电脑 | ● 支持 |
| POST | [`/v1/computers/{computer_id}`](/docs/api/native/agent/updateComputer) | 更新电脑 | ● 支持 |
| POST | [`/v1/computers/{computer_id}/archive`](/docs/api/native/agent/archiveComputer) | 归档电脑 | ● 支持 |
| DELETE | [`/v1/computers/{computer_id}`](/docs/api/native/agent/deleteComputer) | 删除已归档电脑 | ● 支持 |
| GET | [`/v1/computers/{computer_id}/files`](/docs/api/native/agent/listComputerFiles) | 浏览电脑文件 | ● 支持 |
| GET | [`/v1/computers/{computer_id}/files/content`](/docs/api/native/agent/retrieveComputerFileContent) | 读取电脑文件内容 | ● 支持 |
| POST | [`/v1/computers/{computer_id}/connect`](/docs/api/native/agent/connectComputer) | 连接电脑 | ● 支持 |
| POST | [`/v1/computers/{computer_id}/attachments`](/docs/api/native/agent/createComputerAttachment) | 上传电脑附件 | ● 支持 |
### 会话资源（4 个端点，4 个可用） [#会话资源4-个端点4-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ------ | ----------------------------------------------------------------------------------------------------- | ------ | ------ |
| POST | [`/v1/sessions/{session_id}/resources`](/docs/api/native/agent/addSessionResource) | 添加会话资源 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}/resources`](/docs/api/native/agent/listSessionResources) | 列出会话资源 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}/resources/{resource_id}`](/docs/api/native/agent/retrieveSessionResource) | 读取会话资源 | ◐ 部分支持 |
| DELETE | [`/v1/sessions/{session_id}/resources/{resource_id}`](/docs/api/native/agent/deleteSessionResource) | 删除会话资源 | ◐ 部分支持 |
### 智能体（6 个端点，6 个可用） [#智能体6-个端点6-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ---- | ---------------------------------------------------------------------------- | ----- | ------ |
| GET | [`/v1/agents`](/docs/api/native/agent/listAgents) | 列出智能体 | ● 支持 |
| POST | [`/v1/agents`](/docs/api/native/agent/createAgent) | 创建智能体 | ◐ 部分支持 |
| GET | [`/v1/agents/{agent_id}`](/docs/api/native/agent/retrieveAgent) | 读取智能体 | ● 支持 |
| POST | [`/v1/agents/{agent_id}`](/docs/api/native/agent/updateAgent) | 更新智能体 | ◐ 部分支持 |
| GET | [`/v1/agents/{agent_id}/versions`](/docs/api/native/agent/listAgentVersions) | 列出版本 | ● 支持 |
| POST | [`/v1/agents/{agent_id}/archive`](/docs/api/native/agent/archiveAgent) | 归档智能体 | ● 支持 |
### 会话与事件（16 个端点，16 个可用） [#会话与事件16-个端点16-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ---- | ---------------------------------------------------------------------------------------------------------------------- | ------------ | ------ |
| GET | [`/v1/sessions`](/docs/api/native/agent/listSessions) | 列出会话 | ◐ 部分支持 |
| POST | [`/v1/sessions`](/docs/api/native/agent/createSession) | 创建会话 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}`](/docs/api/native/agent/retrieveSession) | 读取会话 | ● 支持 |
| POST | [`/v1/sessions/{session_id}/fork`](/docs/api/native/agent/forkSession) | 分支会话（扩展） | ● 支持 |
| GET | [`/v1/sessions/{session_id}/context`](/docs/api/native/agent/getSessionContext) | 读取会话上下文（扩展） | ● 支持 |
| GET | [`/v1/sessions/{session_id}/background_tasks`](/docs/api/native/agent/listSessionBackgroundTasks) | 列出后台任务（扩展） | ● 支持 |
| GET | [`/v1/sessions/{session_id}/background_tasks/{task_id}/output`](/docs/api/native/agent/getSessionBackgroundTaskOutput) | 读取后台任务输出（扩展） | ● 支持 |
| POST | [`/v1/sessions/{session_id}/background_tasks/{task_id}/stop`](/docs/api/native/agent/stopSessionBackgroundTask) | 停止后台任务（扩展） | ● 支持 |
| POST | [`/v1/sessions/{session_id}/compact`](/docs/api/native/agent/compactSession) | 压缩会话（扩展） | ● 支持 |
| GET | [`/v1/sessions/{session_id}/compact/{operation_id}`](/docs/api/native/agent/getSessionCompaction) | 读取压缩操作（扩展） | ● 支持 |
| GET | [`/v1/sessions/{session_id}/compactions`](/docs/api/native/agent/listSessionCompactions) | 列出压缩历史（扩展） | ● 支持 |
| GET | [`/v1/sessions/{session_id}/events`](/docs/api/native/agent/listEvents) | 列出事件 | ● 支持 |
| POST | [`/v1/sessions/{session_id}/events`](/docs/api/native/agent/sendEvents) | 发送事件 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}/events/stream`](/docs/api/native/agent/streamEvents) | 订阅事件 | ◐ 部分支持 |
| POST | [`/v1/sessions/{session_id}`](/docs/api/native/agent/updateSession) | 更新会话 | ◐ 部分支持 |
| POST | [`/v1/sessions/{session_id}/archive`](/docs/api/native/agent/archiveSession) | 归档会话 | ● 支持 |
### 会话线程（5 个端点，5 个可用） [#会话线程5-个端点5-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ---- | ---------------------------------------------------------------------------------------------------------- | ------ | ------ |
| GET | [`/v1/sessions/{session_id}/threads`](/docs/api/native/agent/listSessionThreads) | 列出线程 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}/threads/{thread_id}`](/docs/api/native/agent/retrieveSessionThread) | 读取线程 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}/threads/{thread_id}/events`](/docs/api/native/agent/listSessionThreadEvents) | 列出线程事件 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}/threads/{thread_id}/stream`](/docs/api/native/agent/streamSessionThreadEvents) | 订阅线程事件 | ◐ 部分支持 |
| POST | [`/v1/sessions/{session_id}/threads/{thread_id}/archive`](/docs/api/native/agent/archiveSessionThread) | 归档线程 | ◐ 部分支持 |
### 执行环境（5 个端点，5 个可用） [#执行环境5-个端点5-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ---- | ---------------------------------------------------------------------------------------- | ---- | ------ |
| POST | [`/v1/environments`](/docs/api/native/agent/createEnvironment) | 创建环境 | ◐ 部分支持 |
| POST | [`/v1/environments/{environment_id}`](/docs/api/native/agent/updateEnvironment) | 更新环境 | ◐ 部分支持 |
| POST | [`/v1/environments/{environment_id}/archive`](/docs/api/native/agent/archiveEnvironment) | 归档环境 | ◐ 部分支持 |
| GET | [`/v1/environments`](/docs/api/native/agent/listEnvironments) | 列出环境 | ◐ 部分支持 |
| GET | [`/v1/environments/{environment_id}`](/docs/api/native/agent/retrieveEnvironment) | 读取环境 | ◐ 部分支持 |
### 工具集（1 个端点，1 个可用） [#工具集1-个端点1-个可用]
| 方法 | 路径 | 说明 | 支持 |
| --- | ----------------------------------------------------- | ----- | ---- |
| GET | [`/v1/toolsets`](/docs/api/native/agent/listToolsets) | 列出工具集 | ● 支持 |
## 与官方的差异 [#与官方的差异]
* 本面只声明列出的 30 个端点（含工具集目录、上下文快照、压缩操作与后台任务）：官方其余 Managed Agents 操作不在本面，调用得到 404。需要 Anthropic 协议兼容接入时用兼容面 /anthropic —— 官方有、平台未支持的操作在那里如实返回 501（not\_implemented\_error），不产生任何副作用。
* 创建环境：支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include\_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED。self\_hosted、scope 和跨会话包缓存尚不支持。
* 更新环境：支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include\_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED。self\_hosted、scope 和跨会话包缓存尚不支持。
* 归档环境：支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include\_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED。self\_hosted、scope 和跨会话包缓存尚不支持。
* 创建电脑：Praxis 超集：MA 只有会话级临时容器与 memory\_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment\_id 是可空配方引用；电脑默认使用 light sandbox，sandbox\_id 为 SDK 可用的公开 ID。分页包含归档电脑。
* 列出电脑：Praxis 超集：MA 只有会话级临时容器与 memory\_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment\_id 是可空配方引用；电脑默认使用 light sandbox，sandbox\_id 为 SDK 可用的公开 ID。分页包含归档电脑。
* 读取电脑：Praxis 超集：MA 只有会话级临时容器与 memory\_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment\_id 是可空配方引用；电脑默认使用 light sandbox，sandbox\_id 为 SDK 可用的公开 ID。分页包含归档电脑。
* 更新电脑：Praxis 超集：MA 只有会话级临时容器与 memory\_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment\_id 是可空配方引用；电脑默认使用 light sandbox，sandbox\_id 为 SDK 可用的公开 ID。分页包含归档电脑。
* 归档电脑：Praxis 超集：MA 只有会话级临时容器与 memory\_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment\_id 是可空配方引用；电脑默认使用 light sandbox，sandbox\_id 为 SDK 可用的公开 ID。分页包含归档电脑。
* 删除已归档电脑：Praxis 扩展：Managed Agents 没有持久 Computer 的删除生命周期。仅允许已归档的电脑；active 返回 400 COMPUTER\_ACTIVE（先归档），先销毁电脑数据再删除登记，成功返回 id 和 type=computer\_deleted；不存在或跨租户返回 404。
* 浏览电脑文件：Praxis 超集：MA 只有会话级临时容器与 memory\_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment\_id 是可空配方引用；电脑默认使用 light sandbox，sandbox\_id 为 SDK 可用的公开 ID。分页包含归档电脑。
* 读取电脑文件内容：Praxis 超集：MA 只有会话级临时容器与 memory\_stores，没有可长期存续、可浏览的整台电脑。归档后文件仍可读，但不能用于新会话。environment\_id 是可空配方引用；电脑默认使用 light sandbox，sandbox\_id 为 SDK 可用的公开 ID。分页包含归档电脑。
* 连接电脑：Praxis 自有扩展：Managed Agents 没有持久 Computer 连接。返回 SDK 可用的公开 sandbox\_id、envd\_access\_token 和 template\_id。归档电脑仍可连接；跨租户或不存在返回 404。连接凭证不可缓存。
* 上传电脑附件：Praxis 扩展：Managed Agents 没有持久 Computer 附件目录。用户上传可以覆盖同名附件，智能体始终只读；运行令牌调用上传返回 403 READ\_ONLY。name 是单个文件名、最多 255 UTF-8 字节，MIME 始终按扩展名推断，上传的 Content-Type 不持久保存，digest 可省略。上限 16 MiB，超限 413、非法名字 400；归档电脑也可上传，跨租户 404。
* 添加会话资源：支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/\，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
* 列出会话资源：支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/\，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
* 读取会话资源：支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/\，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
* 删除会话资源：支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/\，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
* 创建智能体：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 不接受或返回此字段。
* 读取智能体：tools 在一个 agent\_toolset\_20260401 条目中返回全部原生工具的有效配置，可原样用于更新。将示例中的资源 ID 替换成你创建的资源 ID。
* 更新智能体：通过 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 不接受或返回此字段。
* 列出版本：将示例中的资源 ID 替换成你创建的资源 ID。
* 归档智能体：归档后保留查询与历史版本，不能继续更新。请只归档自己的测试智能体。
* 列出会话：支持 limit、page 与 agent\_id；agent\_version、时间范围、deployment\_id、memory\_store\_id、include\_archived、order、statuses 尚不支持，传入返回 400。
* 创建会话：可在创建时传 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/\，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
* 读取会话：将示例中的资源 ID 替换成你创建的资源 ID。
* 分支会话（扩展）：仅在 /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。初始化失败时不公开新会话，并回收已分出的沙箱。
* 读取会话上下文（扩展）：扩展：仅在 /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。
* 列出后台任务（扩展）：仅在 /agent/v1 提供。kind 是开放字符串。subagent 行的 thread\_id 指向对应子线程，其他 kind 为 null。completed 且 delivery=pending 显示 result\_pending。notified\_at 是系统通知批次被受理开轮的时间，无则 null。trigger\_count 仅监视器返回已受理的事件批次数，无记录则 null。时间为 RFC3339。会话不存在或不可见返回 404。
* 读取后台任务输出（扩展）：offset 默认 0；max\_bytes 默认 65536，上限 262144。返回 text、next\_offset、eof。沙箱已暂停或不存在时返回空 text、原 offset、eof=true、unavailable=true。读取不确认模型结果。
* 停止后台任务（扩展）：复用 TaskStop：持久化 stop\_requested\_at 并终止进程组。返回 BackgroundTask；终止尚未观察到时仍可为 running，但不可取消。已结束或不支持停止的任务返回 409。
* 压缩会话（扩展）：仅在 /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。
* 读取压缩操作（扩展）：仅在 /agent/v1 提供。响应为 \{ type: session\_compaction, id, status, reason? }，所有状态均返回 200。操作不存在或会话不可见时返回 404 not\_found\_error。
* 列出压缩历史（扩展）：仅在 /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。
* 列出事件：先发送消息再读取历史；处理完成前可能只看到已接纳的输入。支持分页、事件类型和时间过滤。会话等待工具授权时停在 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]。
* 发送事件：将 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]。
* 订阅事件：保持 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]。
* 更新会话：可选 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。
* 归档会话：归档后的会话拒绝新消息（400 invalid\_request\_error，写明会话已归档），读取与事件历史仍可用；重复归档幂等，archived\_at 保持首次归档时间。
* 列出线程：按 created\_at 升序返回主线程及全部子线程。线程 id 为 sthr\_ 加所属会话 id 的后缀；子线程的 parent\_thread\_id 指向主线程，session\_id 始终为父会话。agent 是实际运行的定义，内置类型的 name 为类型名，未注册的 id/version 为 null。归档子线程的 status 为 terminated，archived\_at 为归档时间；stats/usage 无线程级追踪时如实为 null。
* 读取线程：返回本会话的主线程或子线程，与列表项逐字段一致。其他会话的线程、未知线程或非 sthr\_ id 一律返回 404，不泄露其存在性。
* 列出线程事件：读取所选线程自己的事件记录：主线程读主会话，子线程读对应子会话。沿用会话事件接口的查询参数、公开事件类型和 data + next\_page 信封。使用网页工具时，两个接口均返回 search\_result 块；回答 citations 为 /agent/v1 扩展，/anthropic 将引用显示为正文 \[n]。
* 订阅线程事件：订阅所选线程自己的实时事件流。复用会话 SSE 实现；/agent 接口支持同址只读 WebSocket。主会话流同时包含子线程创建、状态和消息事件，子线程审批带 session\_thread\_id 上浮；确认或中断携带该字段时路由到所属子线程。
* 归档线程：主线程沿用会话归档动作；子线程仅归档对应子会话，不归档父会话或其他子线程。子线程归档后 status 为 terminated，带 archived\_at；历史事件仍可读。
* 列出环境：支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include\_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED。self\_hosted、scope 和跨会话包缓存尚不支持。
* 读取环境：支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include\_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED。self\_hosted、scope 和跨会话包缓存尚不支持。
* 列出工具集：返回工具集说明、插件名称与版本，以及每个工具的名称、说明、参数定义、是否只读和默认授权方式。通过 /agent/v1/toolsets 读取此目录；目录不会更改智能体配置。agent\_toolset\_20260401 包含全部 13 个原生工具；TaskOutput、TaskStop、Monitor、Agent、SendMessage 与其他工具一样可逐个开关及设置权限，它们都依赖 bash。兼容 API 只提供官方 8 个工具。
原生工具与参数以本站各端点说明及 `/meta/v1/openapi.yaml` 为准；[Claude Managed Agents 官方文档](https://platform.claude.com/docs/en/managed-agents/overview)描述兼容 API 的官方字段。
错误按 Anthropic 错误格式返回（type / message / request\_id），参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。