# Agent 场景模型调用的正确姿势 > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 > **警告：重要注意事项** > > 在 Agent 场景下，如果出现模型效果不及预期、任务通过率下降、输出被截断或缓存命中率异常等情况，建议优先排查模型调用方式，[正确的使用方式](/docs/agent-model-invocation-practice#recommended-practice) 如下： > * **回传思考内容**：按模型选择支持的回传方式。对需要回传思考内容加密原文的模型，**必须原样回传思考内容加密原文**。 > * **配置关键参数**：按推荐值配置输出长度参数、thinking 参数、reasoning_effort 参数、temperature 及 top_p 参数。 > * **遵循缓存命中原则**：在同一 Session 内保持采样参数、思考配置、工具定义与 System Prompt 的稳定，避免重置 Prefix Cache。 本文根据 Agent 场景下经常遇到的问题梳理可能原因，并给出推荐的使用方式，便于问题定位并修改。 > **说明** > > 本文聚焦"调用方式"层面的问题定位与参数配置。如需从零到一的完整接入流程（参数配置、Harness 接入、突发流量爬坡、生产上量监控），请参考 [模型接入指南（LLM） - 标准流程](/docs/go-live-access-sop)。 | 常见问题 | 可能的原因 | [推荐使用方式](/docs/agent-model-invocation-practice#recommended-practice) | | --- | --- | --- | | 多轮工具调用效果随轮数增加而下降 | 思考内容未回传，导致每一轮工具返回后丢失思考内容 | 回传思考内容 | | 相同模型、相同 Prompt 在不同实现下任务通过率差异明显 | 参数配置未按推荐值；上下文回传不完整 | 配置关键参数 | \ | | | 回传思考内容 | | 回答被截断、工具参数 JSON 不完整、`finish_reason` / `stop_reason` 为 `length` | `max_tokens` 未显式传入或值过小 | 调整输出长度参数 | | Prompt Cache 命中率异常偏低 | System Prompt 或工具定义在轮次间发生变化；Session 内改动参数 | 遵循缓存命中原则 | # 推荐使用方式 三种接口在字段名、层级与默认返回策略上存在差异，请依据实际使用的接口对照下表进行配置。 | 维度 | Chat API(OpenAI 兼容) | Responses API | Anthropic 兼容 API | \ | | `/api/v3/chat/completions` |`/api/v3/responses` |`/api/compatible/v1/messages` | | --- | --- | --- | --- | | 支持回传思考内容原文（明文）的模型 | Doubao 模型：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-ga-260731、deepseek-v4-1-flash-260910、glm-5-2-260617 ||| | 回传思考内容原文对应的字段 | `choices[].message.reasoning_content` |* 手动回传：`output[reasoning].summary[].text` | `content[thinking].thinking` | \ |> 需要将思考内容原文拼回下一轮请求 | |* 使用 `previous_response_id`：配置 `store: true`，自动获取原始思考内容 | | | **支持回传思考内容加密原文的模型** | Doubao 模型：doubao-seed-evolving、doubao-seed-2-1-pro-260915、doubao-seed-2-1-lite-260915、doubao-seed-2-1-pro-260628、doubao-seed-2-1-turbo-260628、doubao-seed-2-0-lite-260428 ||| \ | | ||| \ | |* 使用支持的模型时，需要**回传思考内容加密原文**，回传时的关键规则及使用示例参见 [关键规则](/docs/agent-model-invocation-practice#key-rules)、[回传思考内容加密块使用示例](/docs/agent-model-invocation-practice#encrypted-thinking-block-examples)。模型调用时返回的内容是思考内容加密字段、明文摘要字段，不是思考内容原文。模型真正用于推理的完整思考内容存在于**加密字段**中。仅回传 `reasoning_content` 等摘要字段并不等同于回传了完整思考内容，会直接导致模型推理效果下降。 ||| \ | |* 同一模型的不同版本可能属于不同类别：`doubao-seed-2.0-lite-260215` 回传思考内容原文(明文)，`doubao-seed-2.0-lite-260428` 起改为回传思考内容加密块。升级模型版本时，请务必同步更新调用代码，否则回传方式失效，且不会触发 API 报错。 ||| \ | | ||| | **回传思考内容加密原文对应的字段** | `choices[].message.encrypted_content` |* 手动回传：`output[reasoning].encrypted_content` | `content[thinking].signature` | \ |> 需要将思考内容加密原文拼回下一轮请求 | |* 使用 `previous_response_id`：配置 `store: true`，自动获取原始思考内容 | | | 是否默认返回思考内容加密字段 | 是 | 是 | 是 | | 回传思考内容明文摘要对应的字段 | `choices[].message.reasoning_content` | `output[reasoning].summary[].text` | `content[thinking].thinking` | \ | > 不能只回传思考内容明文摘要，会导致模型效果下降。| | | | | 配置输出长度参数 | `max_tokens` / `max_completion_tokens` | `max_output_tokens` | `max_tokens` | \ | | **推荐**：必须显式传，Agent 场景建议 ≥ `128000` | **推荐**：必须显式传，Agent 场景建议 ≥ `128000` | **推荐**：必须显式传，Agent 场景建议 ≥ `128000` | | 配置 thinking 参数 | `{"type": "enabled"}` | `{"type": "enabled"}` | `{"type": "enabled"}` | \ | | **推荐**：Agent 场景下显式开启，不要使用 `auto` | **推荐**：Agent 场景下显式开启，不要使用 `auto` | **推荐**：Agent 场景下显式开启，不要使用 `auto` | |配置 reasoning_effort 参数 | `"reasoning_effort": "high"` | `"reasoning": {"effort": "high"}` | `"output_config": {"effort": "high"}` | \ | | **推荐**：Agent 场景建议 `high` 或以上 | **推荐**：Agent 场景建议 `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 消耗，从而降低整体成本。 ## 回传方式与支持模型 方舟大模型的思考内容回传方式分为两类： - **回传思考内容原文（明文）**：将响应中的思考内容原文直接拼回下一轮请求。 - **回传思考内容加密原文**：将响应中的加密原文原样拼回下一轮请求。 两类回传方式支持的模型不同，具体参见 [推荐使用方式](/docs/agent-model-invocation-practice#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 命中率下降，整体成本上升。 | 观察响应中 Cache 命中的 token 数。 | \ | |:::warning| | | \ | |导致 Cache 失效的常见操作：修改 `thinking` 配置、修改 `reasoning_effort`、修改采样参数（`temperature`、`top_p` 等）、修改 System Prompt、修改工具定义。 | | | \ | |::: | | | # 回传思考内容加密块使用示例 **选项：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，自动获取思考内容加密块并回传给模型参与推理。 - **手动回传思考内容加密块**：从响应中获取 Reasoning item，并在后续请求中原样回传 `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, "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"] } } ] }' ```