火山方舟
火山方舟
文档指南
请输入
- 文档首页
火山方舟入门Agent 场景模型调用的正确姿势
复制全文
下载 pdfAgent 场景模型调用的正确姿势
文档反馈
问问助手重要注意事项
- 回传思考内容：按模型选择支持的回传方式。对需要回传思考内容加密原文的模型，必须原样回传思考内容加密原文。
- 配置关键参数：按推荐值配置输出长度参数、thinking 参数、reasoning_effort 参数、temperature 及 top_p 参数。
- 遵循缓存命中原则：在同一 Session 内保持采样参数、思考配置、工具定义与 System Prompt 的稳定，避免重置 Prefix Cache。
本文根据 Agent 场景下经常遇到的问题梳理可能原因，并给出推荐的使用方式，便于问题定位并修改。
说明
常见问题 | 可能的原因 | |
多轮工具调用效果随轮数增加而下降 | 思考内容未回传，导致每一轮工具返回后丢失思考内容 | 回传思考内容 |
相同模型、相同 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-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 |
| content[thinking].thinking |
支持回传思考内容加密原文的模型 | 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 注意
| | |
回传思考内容加密原文对应的字段 需要将思考内容加密原文拼回下一轮请求 | choices[].message.encrypted_content |
| content[thinking].signature |
是否默认返回思考内容加密字段 | 是 | 是 | 是 |
回传思考内容明文摘要对应的字段 不能只回传思考内容明文摘要，会导致模型效果下降。 | 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 消耗，从而降低整体成本。
回传方式与支持模型
方舟大模型的思考内容回传方式分为两类：
- 回传思考内容原文（明文）：将响应中的思考内容原文直接拼回下一轮请求。
- 回传思考内容加密原文：将响应中的加密原文原样拼回下一轮请求。
关键规则
- 思考内容加密字段要求原样、完整回传。任何篡改或截断都会返回 Invalid signature 错误。
- 不回传思考内容加密原文不会触发报错，但会影响推理效果。
- 思考内容加密字段优先级高于思考内容摘要：同时传入时，明文摘要会被忽略。
- 输出思考内容部分计费会按原始思考内容 token 计算，如果不回传思考内容加密原文，已付费的思考内容不仅没有起到效果，还可能会导致推理效果下降。
其他关键参数配置建议
回传思考内容加密块使用示例
非流式响应
对于非流式响应，加密块位于 assistant 消息的扁平字段 encrypted_content，与 reasoning_content、tool_calls 同级。encrypted_content 默认返回，无需额外声明。
正确使用方式：将响应中的 assistant message 对象整体加入到下一轮 messages 中，避免按字段挑选重建。
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，会直接导致丢失思考内容加密块，从而影响推理效果。
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。明天北京天气怎么样？"}
]
}'
响应片段（示意）：
data: {"choices":[{"delta":{"reasoning_content":"用户问明天"}}]}
data: {"choices":[{"delta":{"reasoning_content":"北京天气…"}}]}
data: {"choices":[{"delta":{"content":"","reasoning_content":"","encrypted_content":"<完整加密块>"}}]}
data: {"choices":[{"delta":{"content":"明天北京"}}]}
data: [DONE]
非流式响应
对于非流式响应，加密块位于 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）必须按原顺序全部带回，不能只带最后一个。
手动回传思考内容加密块的示例如下：
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 字段非空过滤，并获取思考内容加密加密原文。
获取到思考内容加密块后，回传方式参考上述示例。
加密内容位于 assistant content 数组中 type == "thinking" 的块的 signature 字段（Anthropic 协议原生命名）。
正确使用方式：
- thinking 块必须整块回传（thinking 文本 + signature 一起），并保持在 tool_use 块之前的原始顺序。
- 请勿按 type == "thinking" 做白名单过滤后重新构造 content 数组。顺序或块被改动会导致校验失败。
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"]
}
}
]
}'
最近更新时间：2026.09.29 16:48:43
这个页面对您有帮助吗？
有用
有用
无用
无用