智能体 API

基础地址

接入

加载中…

智能体域的概念与整体介绍见智能体服务；鉴权方式见鉴权。

端点

电脑（10 个端点，10 个可用）

会话资源（4 个端点，4 个可用）

智能体（6 个端点，6 个可用）

会话与事件（16 个端点，16 个可用）

会话线程（5 个端点，5 个可用）

执行环境（5 个端点，5 个可用）

工具集（1 个端点，1 个可用）

与官方的差异

• 本面只声明列出的 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_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
• 列出会话资源：支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
• 读取会话资源：支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
• 删除会话资源：支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
• 创建智能体：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/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
• 读取会话：将示例中的资源 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 官方文档描述兼容 API 的官方字段。

错误按 Anthropic 错误格式返回（type / message / request_id），参见错误；额度与响应头参见限流。