重要注意事项

在 Agent 场景下，如果出现模型效果不及预期、任务通过率下降、输出被截断或缓存命中率异常等情况，建议优先排查模型调用方式，正确的使用方式如下：

*

回传思考内容 ：按模型选择支持的回传方式。对需要回传思考内容加密原文的模型， 必须原样回传思考内容加密原文 。

*

配置关键参数 ：按推荐值配置输出长度参数、thinking 参数、reasoning_effort 参数、temperature 及 top_p 参数。

*

遵循缓存命中原则 ：在同一 Session 内保持采样参数、思考配置、工具定义与 System Prompt 的稳定，避免重置 Prefix Cache。

本文根据 Agent 场景下经常遇到的问题梳理可能原因，并给出推荐的使用方式，便于问题定位并修改。 |常见问题 |可能的原因 |[推荐使用方式](https://docs.volcengine.com/docs/82379/2636748#recommended-practice) | |---|---|---| |多轮工具调用效果随轮数增加而下降 |思考内容未回传，导致每一轮工具返回后丢失思考内容 |回传思考内容 | |相同模型、相同 Prompt 在不同实现下任务通过率差异明显 |参数配置未按推荐值；上下文回传不完整 |配置关键参数

回传思考内容 | |回答被截断、工具参数 JSON 不完整、`finish_reason` / `stop_reason` 为 `length` |`max_tokens` 未显式传入或值过小 |调整输出长度参数 | |Prompt Cache 命中率异常偏低 |System Prompt 或工具定义在轮次间发生变化；Session 内改动参数 |遵循缓存命中原则 | # 推荐使用方式三种接口在字段名、层级与默认返回策略上存在差异，请依据实际使用的接口对照下表进行配置。 |维度 |Chat API(OpenAI 兼容)

`/api/v3/chat/completions` |Responses API

`/api/v3/responses` |Anthropic 兼容 API

`/api/compatible/v1/messages` | |---|---|---|---| |回传思考内容原文（明文）支持的模型 |Doubao 模型：doubao\-seed\-1\-8\-251228、doubao\-seed\-2\-0\-pro\-260215、doubao\-seed\-2\-0\-lite\-260215、doubao\-seed\-2\-0\-mini\-260215

开源模型：deepseek\-v4\-pro\-260425、deepseek\-v4\-flash\-260425、deepseek\-v4\-flash\-ga\-260731、glm\-5\-2\-260617 ||| |回传思考内容原文对应的字段

> 需要将思考内容原文拼回下一轮请求 |`choices[].message.reasoning_content` |* 手动回传：`output[reasoning].summary[].text`

* 使用`previous_response_id`：配置 `store: true`，自动获取原始思考内容 |`content[thinking].thinking` | |**回传思考内容加密原文支持的模型** |Doubao 模型：doubao\-seed\-evolving、doubao\-seed\-2\-1\-pro\-260628、doubao\-seed\-2\-1\-turbo\-260628、doubao\-seed\-2\-0\-lite\-260428

注意

*

使用支持的模型时，需要 回传思考内容加密原文 ，回传时的关键规则及使用示例参见关键规则、回传思考内容加密块使用示例。模型调用时返回的内容是思考内容加密字段、明文摘要字段，不是思考内容原文。模型真正用于推理的完整思考内容存在于 加密字段 中。仅回传 reasoning_content 等摘要字段并不等同于回传了完整思考内容，会直接导致模型推理效果下降。

*

同一模型的不同版本可能属于不同类别：doubao-seed-2.0-lite-260215 回传思考内容原文(明文)，doubao-seed-2.0-lite-260428 起改为回传思考内容加密块。升级模型版本时，请务必同步更新调用代码，否则回传方式失效，且不会触发 API 报错。

||| |**回传思考内容加密原文对应的字段**

> 需要将思考内容加密原文拼回下一轮请求 |`choices[].message.encrypted_content` |* 手动回传：`output[reasoning].encrypted_content`

* 使用`previous_response_id`：配置 `store: true`，自动获取原始思考内容 |`content[thinking].signature` | |是否默认返回思考内容加密字段 |是 |否，需在 `include` 中显式声明 `reasoning.encrypted_content` |是 | |回传思考内容明文摘要对应的字段

> 不能只回传思考内容明文摘要，会导致模型效果下降。 |`choices[].message.reasoning_content` |`output[reasoning].summary[].text` |`content[thinking].thinking` | |配置输出长度参数 |`max_tokens` / `max_completion_tokens`

**推荐** ：必须显式传，Agent 场景建议 ≥ `128000` |`max_output_tokens`

**推荐** ：必须显式传，Agent 场景建议 ≥ `128000` |`max_tokens`

**推荐** ：必须显式传，Agent 场景建议 ≥ `128000` | |配置 thinking 参数 |`{"type": "enabled"}`

**推荐** ：Agent 场景下显式开启，不要使用 `auto` |`{"type": "enabled"}`

**推荐** ：Agent 场景下显式开启，不要使用 `auto` |`{"type": "enabled"}`

**推荐** ：Agent 场景下显式开启，不要使用 `auto` | |配置 reasoning_effort 参数 |`"reasoning_effort": "high"`

**推荐** ：Agent 场景建议 `high` 或以上 |`"reasoning": {"effort": "high"}`

**推荐** ：Agent 场景建议 `high` 或以上 |`"output_config": {"effort": "high"}`

**推荐** ：Agent 场景建议 `high` 或以上 | |配置 temperature / top_p 参数 |**推荐** `temperature=1`、`top_p=0.95` |**推荐** `temperature=1`、`top_p=0.95` |**推荐** `temperature=1`、`top_p=0.95` |

注意

请务必在同一 Session 内保持采样参数、思考配置、工具定义与 System Prompt 的稳定，任何中途修改都会重置 Prefix Cache。

# 核心机制：思考内容回传 ## 为什么需要回传思考内容在 Agent 场景中，一个任务通常会经历多轮“推理 \-\> 调用工具 \-\> 等待结果 \-\> 继续推理 \-\> 调用工具”，工具结果返回后，模型需要继续在该推理链路上把后续步骤做完。如果不回传思考内容，会有以下影响： * **推理连续性会被打断** ：工具结果返回后，模型只能根据可见对话文本重新构建上下文。对于复杂任务这些隐含的中间判断无法被完整还原，容易出现推理衔接不顺或逻辑断层的情况。 * **多步执行稳定性下降** ：由于缺少中间推理状态，模型可能重复做已做过的推导，或者在下一步采用与前一步不一致的假设，导致任务执行跑偏、步骤不稳定，影响结果的一致性与可复现性。 * **整体成本上升** ：回传的思考内容会与 tool result 一起参与缓存，更容易命中 Prompt Cache。对包含多次工具调用的场景来说，缓存命中意味着减少重复 token 消耗，从而降低整体成本。 ## 回传方式与支持模型方舟大模型的思考内容回传方式分为两类： * **回传思考内容原文（明文）** ：将响应中的思考内容原文直接拼回下一轮请求。 * **回传思考内容加密原文** ：将响应中的加密原文原样拼回下一轮请求。两类回传方式支持的模型不同，具体参见 [推荐使用方式](https://docs.volcengine.com/docs/82379/2636748#recommended-practice)。 ## 关键规则 * 思考内容加密字段 **要求原样、完整回传** 。任何篡改或截断都会返回 `Invalid signature` 错误。 * 不回传思考内容加密原文 **不会触发报错，但会影响推理效果** 。 * 思考内容加密字段 **优先级高于思考内容摘要** ：同时传入时，明文摘要会被忽略。 * 输出思考内容部分计费会按原始思考内容 token 计算，如果不回传思考内容加密原文，已付费的思考内容不仅没有起到效果，还可能会导致推理效果下降。 --- # 其他关键参数配置建议 |关键配置 |推荐配置 |配置错误的影响 |自检方式 | |---|---|---|---| |thinking |Agent 场景显式设置为 `enabled`，不建议使用 `auto`。 |`auto` 模式下模型可能判定简单直接回答，多步任务的规划能力因此下降。 |观察响应中是否包含思考内容块。 | |reasoning_effort |Agent 与多步工具调用场景设置为 `high` 或以上。 |低档位下思考不足，工具选择与工具参数构造的错误率会上升。 |\- | |temperature 与 top_p |`temperature=1`，`top_p=0.95` |会影响工具调用稳定性和推理质量。

> 不建议同时大幅调整 `temperature` 与 `top_p`，两者叠加影响难以定位。 |\- | |max_tokens |**必须显式传入** ，Agent 场景建议 ≥ `128000`。实际取值需结合模型 `max_output_tokens` 上限与业务场景。 |回答被截断、工具参数 JSON 不完整、Agent Loop 中断。 |观察 `finish_reason` / `stop_reason` 是否为 `length`。 | |缓存命中率 |System Prompt 与工具定义放在请求的最前部，且在同一 Session 内保持稳定不变。

注意

导致 Cache 失效的常见操作：修改 thinking 配置、修改 reasoning_effort、修改采样参数（temperature、top_p 等）、修改 System Prompt、修改工具定义。

|Cache 命中率下降，整体成本上升。 |观察响应中 Cache 命中的 token 数。 | # 回传思考内容加密块使用示例 Chat API（OpenAI 兼容） ### 非流式响应对于非流式响应，加密块位于 assistant 消息的**扁平字段** `encrypted_content`，与 `reasoning_content`、`tool_calls` 同级。`encrypted_content` 默认返回，无需额外声明。 **正确使用方式**：将响应中的 assistant message 对象整体加入到下一轮 `messages` 中，避免按字段挑选重建。 ```Bash curl https://ark.cn-beijing.volces.com/api/v3/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ARK_API_KEY" \ -d '{ "model": "doubao-seed-evolving", "thinking": {"type": "enabled"}, "temperature": 1, "top_p": 0.95, "max_tokens": 128000, "messages": [ {"role": "system", "content": "你是人工智能助手。"}, {"role": "user", "content": "今天是 2026-08-10（星期一）。明天北京天气怎么样？"}, { "role": "assistant", "reasoning_content": "用户问明天北京天气，明天是 2026-08-11，调用天气工具。", "encrypted_content": "<完整加密块，原样回传>", "tool_calls": [ { "id": "call_wiezxeyae8jzxl3jx8nhfgb5", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\":\"北京\",\"date\":\"2026-08-11\"}"} } ] }, { "role": "tool", "tool_call_id": "call_wiezxeyae8jzxl3jx8nhfgb5", "content": "2026-08-11 北京：阴，11~16°C，北风4级。" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "查询指定城市指定日期的天气", "parameters": { "type": "object", "properties": { "location": {"type": "string", "description": "城市名，如北京、上海"}, "date": {"type": "string", "description": "日期，格式 YYYY-MM-DD"} }, "required": ["location", "date"] } } } ] }' ``` ### 流式响应流式响应下，思考内容加密块由**独立的 chunk** 下发，时机是思考内容输出完成之后、正式应答开始之前。该 chunk 的 `content` 与 `reasoning_content`**可能均为空**。 **正确使用方式**：请务必在流式合并逻辑中对 `encrypted_content` 字段做处理。仅处理 `delta.content` 或 `delta.reasoning_content`，会直接导致丢失思考内容加密块，从而影响推理效果。 ```Bash curl https://ark.cn-beijing.volces.com/api/v3/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ARK_API_KEY" \ -d '{ "model": "doubao-seed-evolving", "stream": true, "thinking": {"type": "enabled"}, "max_tokens": 128000, "messages": [ {"role": "user", "content": "今天是 2026-08-10。明天北京天气怎么样？"} ] }' ``` 响应片段（示意）： ```text data: {"choices":[{"delta":{"reasoning_content":"用户问明天"}}]} data: {"choices":[{"delta":{"reasoning_content":"北京天气…"}}]} data: {"choices":[{"delta":{"content":"","reasoning_content":"","encrypted_content":"<完整加密块>"}}]} data: {"choices":[{"delta":{"content":"明天北京"}}]} data: [DONE] ``` Responses API ### 非流式响应对于非流式响应，加密块位于 `output` 数组内 `type == "reasoning"` 的 item。回传思考内容加密块的方式如下： * **previous_response_id**：**注意需显式配置 ** **`store: true`**。由服务端托管 session 状态，客户端无需自行搬运历史 item，自动获取思考内容加密块并回传给模型参与推理。 * **手动回传思考内容加密块**：**必须显式在 ** **`include`** ** 中声明 ** **`reasoning.encrypted_content`**，否则响应中不会返回加密块。手动回传思考内容加密块注意事项： * Reasoning item 的 **`id`** 必须原样带回，不能自行生成。 * 回放时 `content` 可以是空数组 `[]`，但 `encrypted_content` **不能为空**。 * 连续多次工具调用时，从最后一条 user message 之后的所有 item（`reasoning` / `function_call` / `function_call_output`）必须按原顺序全部带回，不能只带最后一个。手动回传思考内容加密块的示例如下： ```Bash curl https://ark.cn-beijing.volces.com/api/v3/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ARK_API_KEY" \ -d '{ "model": "doubao-seed-evolving", "store": false, "include": ["reasoning.encrypted_content"], "reasoning": {"effort": "high", "summary": "detailed"}, "max_output_tokens": 128000, "input": [ {"type": "message", "role": "user", "content": "今天是 2026-08-10（星期一）。明天天气怎么样？"}, { "id": "rs_0c2e0389c1bdc80f016a79c44c1fd08198bbdcb852ca75789b", "type": "reasoning", "content": [], "encrypted_content": "<完整加密块，原样回传>", "summary": [ {"type": "summary_text", "text": "先取用户所在城市，再查 2026-08-11 的天气。"} ] }, { "id": "fc_0c2e0389c1bdc80f016a79c44d9fac81988abe3597d1fbba88", "type": "function_call", "status": "completed", "call_id": "call_tjOpXT7tq4KbtdnpQYdBNTXz", "name": "get_location", "arguments": "{\"location_level\":\"city\"}" }, { "type": "function_call_output", "call_id": "call_tjOpXT7tq4KbtdnpQYdBNTXz", "output": "北京" }, { "id": "fc_0c2e0389c1bdc80f016a79c451d4348198a1c4eb858f8a858b", "type": "function_call", "status": "completed", "call_id": "call_cf3Sz3cE2fZkZBPdez5P9Ecb", "name": "get_weather", "arguments": "{\"location\":\"北京\",\"date\":\"2026-08-11\"}" }, { "type": "function_call_output", "call_id": "call_cf3Sz3cE2fZkZBPdez5P9Ecb", "output": "2026-08-11 北京：阴，11~16°C，北风4级。" } ], "tools": [ { "type": "function", "name": "get_location", "description": "获取用户当前位置", "parameters": { "type": "object", "properties": { "location_level": {"type": "string", "description": "所需粒度：country / province / city / street"} }, "required": ["location_level"], "additionalProperties": false }, "strict": true }, { "type": "function", "name": "get_weather", "description": "查询指定城市指定日期的天气", "parameters": { "type": "object", "properties": { "location": {"type": "string", "description": "城市名"}, "date": {"type": "string", "description": "日期，格式 YYYY-MM-DD"} }, "required": ["location", "date"], "additionalProperties": false }, "strict": true } ] }' ``` ### 流式响应对于流式响应，思考内容加密块通过 `response.output_item.added` / `response.output_item.done` / `response.completed` 等相关事件下发，需要按事件中 **encrypted_content** 字段非空过滤，并获取思考内容加密加密原文。获取到思考内容加密块后，回传方式参考上述示例。 Anthropic 兼容 API 加密内容位于 assistant content 数组中 `type == "thinking"` 的块的 **`signature`** 字段（Anthropic 协议原生命名）。 **正确使用方式**： * thinking 块必须**整块回传**（`thinking` 文本 + `signature` 一起），并保持在 `tool_use` 块**之前**的原始顺序。 * **请勿按 ** **`type == "thinking"`** ** 做白名单过滤后重新构造 content 数组**。顺序或块被改动会导致校验失败。 ```Bash curl https://ark.cn-beijing.volces.com/api/v3/compatible/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ARK_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "doubao-seed-evolving", "max_tokens": 128000, "thinking": {"type": "enabled"}, "messages": [ {"role": "user", "content": "今天是 2026-08-10（星期一）。明天天气怎么样？"}, { "role": "assistant", "content": [ { "type": "thinking", "thinking": "用户问明天天气，明天是 2026-08-11。需要先获取城市，再查天气。", "signature": "<完整加密块，原样回传>" }, { "type": "tool_use", "id": "tool_4U01J2huMeLhTlTKyrU5rhI5", "name": "get_location", "input": {"location_level": "city"} } ] }, { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "tool_4U01J2huMeLhTlTKyrU5rhI5", "content": "北京" } ] } ], "tools": [ { "name": "get_location", "description": "获取用户当前位置", "input_schema": { "type": "object", "properties": { "location_level": {"type": "string", "description": "所需粒度：country / province / city / street"} }, "required": ["location_level"] } }, { "name": "get_weather", "description": "查询指定城市指定日期的天气", "input_schema": { "type": "object", "properties": { "location": {"type": "string", "description": "城市名"}, "date": {"type": "string", "description": "日期，格式 YYYY-MM-DD"} }, "required": ["location", "date"] } } ] }' ```

火山方舟