请求体

• modelstring必填◐ 部分支持

  Body param: The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

  deepseek-v4-pro、glm-5.3-flash、qwen3.8-flash、claude-opus-5 可调用；deepseek-v4-flash 在此协议面返回 400。

• max_tokensnumber必填

  Body param: The maximum number of tokens to generate before stopping. Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response. Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.

  限制输出 token，思考也占用预算。

• messagesarray必填◐ 部分支持

  Body param: Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. Example with a single `user` message: ```json [{ "role": "user", "content": "Hello, Claude" }] ``` Example with multiple conversational turns: ```json [ { "role": "user", "content": "Hello there." }, { "role": "assistant", "content": "Hi, I'm Claude. How can I help you?" }, { "role": "user", "content": "Can you explain LLMs in plain English?" } ] ``` Example with a partially-filled response from Claude: ```json [ { "role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun" }, { "role": "assistant", "content": "The best answer is (" } ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: ```json { "role": "user", "content": "Hello, Claude" } ``` ```json { "role": "user", "content": [{ "type": "text", "text": "Hello, Claude" }] } ``` See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request.

  文本和工具往返生效；document 的托管 file_id 返回 400，qwen3.8-flash 可读取内联 PDF；图片有模型尺寸限制。

  ▸ 展开子字段（2）

  • contentstring | array必填

    Message content: a plain string (shorthand for one text block) or an array of content blocks such as text, image, document, tool_use and tool_result.

  • rolestring必填

    Who produced the message. Use user for your turns and assistant to replay earlier model turns; system-role messages are accepted by the shape but system instructions normally go in the top-level system field.

• streamboolean可选◐ 部分支持

  Body param: Whether to incrementally stream the response using server-sent events. See [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming) for details.

  流式正文和工具事件可用；可能在正文前出现额外 message_delta，message_start 的用量为 0。

• systemstring | array可选

  Body param: System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).

  已验证生效。

• temperaturenumber可选
• top_pnumber可选
• top_knumber可选
• stop_sequencesarray可选◐ 部分支持

  Body param: Custom text sequences that will cause the model to stop generating. Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence.

  deepseek-v4-pro、qwen3.8-flash 生效；glm-5.3-flash 文本截断但 stop_reason 和 stop_sequence 未准确反映。

• toolsarray可选

  Body param: Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: - `name`: Name of the tool. - `description`: Optional, but strongly-recommended description of the tool. - `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ] ``` And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": { "ticker": "^GSPC" } } ] ``` You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.

  已验证生效。

• ▸ 更多参数（16）

  • tool_choiceobject可选◐ 部分支持

    Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.

    qwen3.8-flash 四种模式生效；deepseek-v4-pro 忽略 any/tool/none；glm-5.3-flash 忽略 none。

    ▸ 展开子字段（3）

    • typestring必填
      取值 none
    • disable_parallel_tool_useboolean可选○ 当前不生效

      Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use.

      接受但当前不生效。true 仍可能返回多个工具调用。

    • namestring必填

      The name of the tool to use.

  • metadataobject可选◐ 部分支持

    Body param: An object describing metadata about the request.

    接受 metadata；metadata.user_id 由同协议线路传递，不承诺上游回显。

    ▸ 展开子字段（1）

    • user_idstring可选

      An external identifier for the user who is associated with the request. This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number.

  • cache_controlobject可选◐ 部分支持

    Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

    deepseek-v4-pro、qwen3.8-flash、glm-5.3-flash 有隐式缓存命中，但不能据此确认标记生效；claude-opus-5 未命中缓存，ttl=1h 未见效果。

    ▸ 展开子字段（2）

    • typestring必填

      Always `ephemeral`. Discriminator that marks this object as a CacheControlEphemeral in a `type`-tagged union.

      取值 ephemeral
    • ttlstring可选

      The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.

  • containerstring | object可选○ 当前不生效

    接受并忽略 container；平台尚未实现此能力。

    ▸ 展开子字段（2）

    • idstring可选

      Container id

    • skillsarray可选

      List of skills to load in the container

  • inference_geostring可选○ 当前不生效

    接受并忽略 inference_geo；平台尚未实现此能力。

  • output_configobject可选

    Body param: Configuration options for the model's output, such as the output format.

    ▸ 展开子字段（2）

    • effortstring可选◐ 部分支持

      All possible effort levels.

      deepseek-v4-pro 仅 high/xhigh 可用，其余返回 400；qwen3.8-flash 全档返回 400；glm-5.3-flash 接受各档但消耗不随档位单调变化。

    • formatobject可选◐ 部分支持

      A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

      json_schema 在 deepseek-v4-pro、qwen3.8-flash 生效；glm-5.3-flash 与 thinking 同传返回 400。

  • service_tierstring可选○ 当前不生效

    接受并忽略 service_tier；平台尚未实现此能力。

  • thinkingobject可选◐ 部分支持

    Body param: Configuration for enabling Claude's extended thinking. When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.

    disabled 在 deepseek-v4-pro、qwen3.8-flash 生效；glm-5.3-flash 携带任何 thinking 都返回 400。adaptive 在已测的 deepseek-v4-pro、qwen3.8-flash 也返回 400。

    ▸ 展开子字段（3）

    • budget_tokensnumber必填◐ 部分支持

      Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than `max_tokens`. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.

      deepseek-v4-pro、qwen3.8-flash 接受，但预算不构成可靠上限；glm-5.3-flash 返回 400。

    • typestring必填
      取值 adaptive
    • displaystring可选○ 当前不生效

      Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.

      接受但当前不生效。omitted 仍返回完整思考内容。

  • context_managementobject可选○ 当前不生效

    接受并忽略 context_management；平台尚未实现此能力。

  • diagnosticsobject可选○ 当前不生效

    接受并忽略 diagnostics；平台尚未实现此能力。

  • mcp_serversarray可选○ 当前不生效

    接受并忽略 mcp_servers；平台尚未实现此能力。

  • speedstring可选○ 当前不生效

    接受并忽略 speed；平台尚未实现此能力。

  • output_formatobject可选○ 当前不生效

    接受并忽略此旧字段；结构化输出使用 output_config.format。

  • compactionobject可选○ 未支持

    已识别 compaction；尚未实现，传入返回 400 并明确说明不支持。

  • fallback_credit_tokenstring可选○ 未支持

    已识别 fallback_credit_token；尚未实现，传入返回 400 并明确说明不支持。

  • fallbacksstring可选○ 未支持

    已识别 fallbacks；尚未实现，传入返回 400 并明确说明不支持。

返回

200

stream=true 时以 SSE 增量返回（text/event-stream）。

支持顶层 cache_control、top_k、metadata.user_id、output_config.format、thinking.display 与 anthropic-user-profile-id。仅原生 Anthropic 能表达的选项会限制路由；没有可保真供应时返回参数错误。anthropic-workspace-id 尚未支持，非空值返回 400。container、inference_geo 与 service_tier 接受并忽略；其他扩展见字段支持标注。 未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。

错误按 Anthropic 格式返回，参见 错误码

请求体

• modelstring必填

  Body param: The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

  必填并校验存在性，用于选择原生线路和本地分词器。

• messagesarray必填◐ 部分支持

  Body param: Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. Example with a single `user` message: ```json [{ "role": "user", "content": "Hello, Claude" }] ``` Example with multiple conversational turns: ```json [ { "role": "user", "content": "Hello there." }, { "role": "assistant", "content": "Hi, I'm Claude. How can I help you?" }, { "role": "user", "content": "Can you explain LLMs in plain English?" } ] ``` Example with a partially-filled response from Claude: ```json [ { "role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun" }, { "role": "assistant", "content": "The best answer is (" } ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: ```json { "role": "user", "content": "Hello, Claude" } ``` ```json { "role": "user", "content": [{ "type": "text", "text": "Hello, Claude" }] } ``` See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request.

  原生路径保留消息；本地使用 o200k 或按模型族校准的估算，图片按已知模型规则估算，未知尺寸使用近似额度；不下载图片 URL。

  ▸ 展开子字段（2）

  • contentstring | array必填

    Message content: a plain string (shorthand for one text block) or an array of content blocks such as text, image, document, tool_use and tool_result.

  • rolestring必填

    Who produced the message. Use user for your turns and assistant to replay earlier model turns; system-role messages are accepted by the shape but system instructions normally go in the top-level system field.

• systemstring | array可选◐ 部分支持

  Body param: System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).

  原生透传；本地计入估算。

• toolsarray可选◐ 部分支持

  Body param: Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: - `name`: Name of the tool. - `description`: Optional, but strongly-recommended description of the tool. - `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ] ``` And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": { "ticker": "^GSPC" } } ] ``` You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.

  原生透传；本地计入定义与包装的估算。

• tool_choiceobject可选◐ 部分支持

  Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.

  原生透传；本地计入估算。

  ▸ 展开子字段（3）

  • typestring必填

    Disable tool calls for this request.

    取值 none
  • disable_parallel_tool_useboolean可选

    Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use.

  • namestring必填

    The name of the tool to use.

• cache_controlobject可选◐ 部分支持

  Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

  原生路径保留消息内标记；计数不能预测缓存命中或计费。

  ▸ 展开子字段（2）

  • typestring必填

    Always `ephemeral`. Discriminator that marks this object as a CacheControlEphemeral in a `type`-tagged union.

    取值 ephemeral
  • ttlstring可选

    The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.

• output_configobject可选◐ 部分支持

  Body param: Configuration options for the model's output, such as the output format.

  原生路径透传；本地不承诺其附加模板的精确计数。

  ▸ 展开子字段（2）

  • effortstring可选

    All possible effort levels.

  • formatobject可选

    A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

• thinkingobject可选◐ 部分支持

  Body param: Configuration for enabling Claude's extended thinking. When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.

  原生路径透传；本地不承诺思考模板精确计数。

  ▸ 展开子字段（3）

  • budget_tokensnumber必填

    Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than `max_tokens`. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.

  • typestring必填

    Let the model choose its reasoning budget, subject to output_config.effort when supplied.

    取值 adaptive
  • displaystring可选

    Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.

返回

200

按模型族校准的估算值（包括中文和工具定义），响应头为 x-praxis-token-count: estimated；不能用作精确用量或计费依据。

错误按 Anthropic 格式返回，参见 错误码

请求参数

• limitnumber可选

  query: Number of items per page.

  已验证生效。

• before_idstring可选

  query:

  已验证生效。

• after_idstring可选

  query:

  已验证生效。

返回

200

始终返回 capabilities、max_input_tokens、max_tokens；目录无法确定的值为 null，不将总上下文窗口冒充独立输入上限。非空 anthropic-workspace-id 返回 400；尚不按 anthropic-beta 选择目录版本。

错误按 Anthropic 格式返回，参见 错误码

请求体

• filestring必填◐ 部分支持

  Body param: The file to upload. Only the final path component of the part's `filename` is kept; an absent or empty `filename` is replaced with `unnamed` plus the extension for the file's stored `mime_type`, when known.

  支持文本、PDF 和 PNG；按文件内容识别类型，不支持任意二进制。

• expires_in_secondsnumber可选◐ 部分支持

  Body param: Seconds from upload until the file expires and its bytes become permanently unavailable. Must be between 3600 (one hour) and 7776000 (ninety days).

  表单字段支持 3600–7776000 秒；作为查询参数传入返回 400，提示改放表单。

返回

200

SDK 0.128.0 上传参数为表单 file 和可选的表单 expires_in_seconds（3600–7776000 秒）。其他表单字段（包括 purpose）返回 400 invalid_request_error，消息形如 "purpose: Extra inputs are not permitted"；查询参数只接受 SDK 自带的 beta，其他查询参数返回 400，查询参数 expires_in_seconds 会提示改放表单。平台将上传文件记为 user_data；不支持 anthropic-workspace-id，请求携带该头时返回 400。

错误按 Anthropic 格式返回，参见 错误码

请求参数

• idsarray可选

  query: Query param: Restrict the result set to Files whose `id` is in this list. At most 100 entries (after de-duplication). Mutually exclusive with `page` and `limit`. When supplied, the response is always a single page (`next_page` is null). IDs that do not resolve to a visible File — including deleted Files — are silently omitted.

  已验证生效。

• scope_idstring可选◐ 部分支持

  query: Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID).

  需要 anthropic-beta: managed-agents-2026-04-01。非法 scope_id 返回 400，不存在的会话范围返回 404。

• limitnumber可选

  query: Number of items per page.

  已验证生效。

• pagestring可选

  query:

  已验证生效。

• after_idstring可选

  query: Return the page of files immediately after this file id (older files).

  返回该文件之后（更早创建）的一页；不能与 before_id 或 page 同时使用。

• before_idstring可选

  query: Return the page of files immediately before this file id (newer files).

  返回该文件之前（更新创建）的一页；不能与 after_id 或 page 同时使用。

返回

200

按创建时间从新到旧排列。用 after_id / before_id 与 limit 分页（两者同时给返回 400），也可以用 page 游标（next_page）；三者只能选一个。响应包含 data、has_more、first_id、last_id 与 next_page。ids（最多 100 个去重 ID）与 page、after_id、before_id、limit 互斥。scope_id 需要 anthropic-beta: managed-agents-2026-04-01 请求头；缺少该头返回 400，不存在的会话范围返回 404。anthropic-workspace-id 返回 400。

错误按 Anthropic 格式返回，参见 错误码

请求参数

• file_idstring必填

  path:

返回

200

错误按 Anthropic 格式返回，参见 错误码

请求参数

• file_idstring必填

  path:

返回

200

错误按 Anthropic 格式返回，参见 错误码

请求参数

• file_idstring必填

  path:

返回

400

只有代码执行工具生成的文件可以下载；你自己上传的文件（用途为 user_data）下载会返回 400 invalid_request_error，这与 Anthropic 官方的行为一致。

错误按 Anthropic 格式返回，参见 错误码

请求体

• namestring必填

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

• modelstring | object必填

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

  ▸ 展开子字段（4）

  • idstring必填

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

  • effortstring | object可选

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

  • inference_geostring可选

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

  • speedstring可选

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

• systemstring可选

  智能体的系统提示词。

• descriptionstring可选

  智能体的用途说明。

• mcp_serversarray可选○ 未支持

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

  ▸ 展开子字段（3）

  • namestring必填

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

  • typestring必填

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

    取值 url
  • urlstring必填

    MCP 服务器的端点地址。

• metadataobject可选

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

• 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 个。

返回

200

支持文本提示词、模型、元数据与内置工具。MCP、Skills 及额外模型控制尚不支持，传入会返回 400。 multiagent 接受 null 或 coordinator 名册，1–20 项：智能体 ID、{type:"agent",id,version?} 或最多一个 {type:"self"}。创建/更新时固定版本；成员去重且须存在、未归档、不能自身带 multiagent。兼容 API 只提供 bash、edit、glob、grep、read、write、web_search、web_fetch 这 8 个官方工具；configs 不接受其他工具名，经此入口创建的会话不提供后台任务、Monitor 或子智能体。完整原生工具请使用 /agent/v1。每个 coordinator 最多一个 advisor，模型须可用且不同于智能体模型；仅主会话可咨询，每次咨询为独立 advisor 线程，建议以 agent.thread_message_received 返回。

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• created_at[gte]string可选

  query: 只返回不早于该时间创建的记录。

• created_at[lte]string可选

  query: 只返回不晚于该时间创建的记录。

• include_archivedboolean可选

  query: 是否包含已归档的记录。

• limitnumber可选

  query: 每页返回的条数上限。

• pagestring可选

  query: 分页游标，取自上一页响应的 next_page。

返回

200

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• agent_idstring必填

  path: 按智能体 ID 过滤结果。

• versionnumber可选

  query: 路径参数：版本号。

返回

200

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

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• agent_idstring必填

  path: 按智能体 ID 过滤结果。

• namestring可选

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

• modelstring | object可选

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

  ▸ 展开子字段（4）

  • idstring必填

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

  • effortstring | object可选

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

  • inference_geostring可选

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

  • speedstring可选

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

• systemstring可选

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

• descriptionstring可选

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

• mcp_serversarray可选○ 未支持

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

• metadataobject可选

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

• 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 清除。

• toolsarray可选

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

• ▸ 更多参数（1）

  • versionnumber可选

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

返回

200

version 可用于乐观并发控制，版本冲突返回 409；无变化的更新不增加版本。MCP、Skills 尚不支持。 multiagent 接受 null 或 coordinator 名册，1–20 项：智能体 ID、{type:"agent",id,version?} 或最多一个 {type:"self"}。创建/更新时固定版本；成员去重且须存在、未归档、不能自身带 multiagent。兼容 API 只提供 bash、edit、glob、grep、read、write、web_search、web_fetch 这 8 个官方工具；configs 不接受其他工具名，经此入口创建的会话不提供后台任务、Monitor 或子智能体。完整原生工具请使用 /agent/v1。每个 coordinator 最多一个 advisor，模型须可用且不同于智能体模型；仅主会话可咨询，每次咨询为独立 advisor 线程，建议以 agent.thread_message_received 返回。

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• agent_idstring必填

  path: 按智能体 ID 过滤结果。

• limitnumber可选

  query: 每页返回的条数上限。

• pagestring可选

  query: 分页游标，取自上一页响应的 next_page。

返回

200

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

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• agent_idstring必填

  path: 按智能体 ID 过滤结果。

返回

200

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

错误按 Claude Managed Agents 格式返回，参见 错误码

请求体

• 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，决定容器的基础环境。

• budgetobject可选○ 未支持

  会话的预算上限设置。

  ▸ 展开子字段（2）

  • max_list_costobject必填

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

  • typestring必填

    预算类型，目前只有 max_list_cost。

    取值 limit
• initial_eventsarray可选

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

• metadataobject可选

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

• resourcesarray可选◐ 部分支持

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

• titlestring可选

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

• vault_idsarray可选○ 未支持

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

返回

200

先创建智能体，将示例 agent_123 换成返回的 id。Anthropic 兼容 API 的 environment_id 必填，可用 node22 或租户自建 cloud 环境；/agent/v1 可省略 environment_id 得到轻量机器。不支持内联智能体覆盖、预算与凭据库。 支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• agent_idstring可选

  query: 按智能体 ID 过滤结果。

• agent_versionnumber可选

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

• created_at[gt]string可选

  query: 只返回严格晚于该时间创建的记录。

• created_at[gte]string可选

  query: 只返回不早于该时间创建的记录。

• created_at[lt]string可选

  query: 只返回严格早于该时间创建的记录。

• created_at[lte]string可选

  query: 只返回不晚于该时间创建的记录。

• deployment_idstring可选

  query: 部署 ID（路径或查询参数）。

• include_archivedboolean可选

  query: 是否包含已归档的记录。

• memory_store_idstring可选

  query: 记忆库 ID（路径或查询参数）。

• orderstring可选

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

• ▸ 更多参数（3）

  • statusesarray可选

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

  • limitnumber可选

    query: 每页返回的条数上限。

  • pagestring可选

    query: 分页游标，取自上一页响应的 next_page。

返回

200

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

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• session_idstring必填

  path: 会话 ID（路径或查询参数）。

返回

200

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

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• session_idstring必填

  path: 会话 ID（路径或查询参数）。

• eventsarray必填

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

返回

200

将 sesn_123 换成创建会话返回的 id。每条 user.message 只接受一个非空文本块。支持文本 user.message、user.interrupt 和工具确认；其它事件变体尚不支持。返回的是已接纳事件；模型回复从事件历史或订阅读取。会话等待工具授权时发送的 user.message 会排队：返回的事件 processed_at 为 null，授权处理完成后按发送顺序执行。

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• session_idstring必填

  path: 会话 ID（路径或查询参数）。

• created_at[gt]string可选

  query: 只返回严格晚于该时间创建的记录。

• created_at[gte]string可选

  query: 只返回不早于该时间创建的记录。

• created_at[lt]string可选

  query: 只返回严格早于该时间创建的记录。

• created_at[lte]string可选

  query: 只返回不晚于该时间创建的记录。

• orderstring可选

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

• typesarray可选

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

• limitnumber可选

  query: 每页返回的条数上限。

• pagestring可选

  query: 分页游标，取自上一页响应的 next_page。

返回

200

先发送消息再读取历史；处理完成前可能只看到已接纳的输入。支持分页、事件类型和时间过滤。会话等待工具授权时停在 session.status_idle，stop_reason 为 requires_action，event_ids 列出待确认的 agent.tool_use；运行失败时先出现 session.error，再出现 session.status_terminated。agent.thinking 与官方一致，是不带内容的进度信号。

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• session_idstring必填

  path: 会话 ID（路径或查询参数）。

• event_deltasarray可选

  query: 设置后连接同时接收流式增量事件。

返回

200

保持 SSE 连接以接收事件；请求不会像普通 JSON 接口一样立刻结束。先创建会话并替换 sesn_123，再从另一请求发送消息；停止按钮只断开订阅，不会停止智能体。SDK 0.124.0 会过滤 session.usage，完整用量请读历史。传 event_deltas[]=agent.message 可在最终事件到达前收到逐段文本预览；agent.thinking 与官方一致，只有 event_start。

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• include_archivedboolean可选

  query: 是否包含已归档的记录。

• limitnumber可选

  query: 每页返回的条数上限。

• pagestring可选

  query: 分页游标，取自上一页响应的 next_page。

返回

200

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

错误按 Claude Managed Agents 格式返回，参见 错误码

请求体

• namestring必填

  Human-readable name for the environment

• configobject可选

  Environment configuration

  ▸ 展开子字段（3）

  • typestring必填

    Environment type

    取值 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

• metadataobject可选

  User-provided metadata key-value pairs

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

返回

501

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

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• environment_idstring必填

  path: 环境 ID（路径或查询参数）。

返回

200

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

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• environment_idstring必填

  path: 环境 ID（路径或查询参数）。

• namestring可选

  Updated name for the environment

• configobject可选

  Updated environment configuration

  ▸ 展开子字段（3）

  • typestring必填

    Environment type

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

• metadataobject可选

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

• scopestring可选

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

返回

501

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

错误按 Claude Managed Agents 格式返回，参见 错误码

请求参数

• environment_idstring必填

  path: 环境 ID（路径或查询参数）。

返回

501

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

错误按 Claude Managed Agents 格式返回，参见 错误码