Claude Sonnet 4.6 的 effort 与工具触发配置

一句话结论

Sonnet 4.6 的 effort 会同时影响文本、思考和工具调用 token；官方建议多数生产应用从 medium 起步并显式设置，避免默认 high 带来的不可预测延迟。

适用场景

• 适合的任务：Claude API/Agent 的成本、延迟和工具调用次数调优，多轮编码与企业文档任务。

• 不适合的任务：没有 eval 就把 low 当作“同等质量”；也不适合用 max 处理所有短问答。

• 适用的模型版本：Claude Sonnet 4.6，模型字符串为 claude-sonnet-4-6。

• 适用的客户端、Agent 或 API：Claude API、AWS Bedrock、Google Cloud、Microsoft Foundry 等支持平台；请求字段以目标平台为准。

• 推荐的推理档位和参数：medium 推荐默认；低延迟/非编码聊天用 low；复杂推理/代码用 high；max 仅在 eval 显示收益时用。Sonnet 4.6 支持 max，不在官方表中支持 xhigh。

可直接使用的内容

API 配置骨架（字段名依据 Anthropic 文档，部署前核对 SDK 版本）：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 8192,
  "output_config": {
    "effort": "medium"
  },
  "system": "完成任务时使用必要工具，不要只给建议。每次写入后验证结果；如果信息不足，明确说明。",
  "tools": [
    {
      "name": "search_docs",
      "description": "Search the approved corpus and return source IDs. Use when facts are missing or may have changed.",
      "input_schema": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"]
      }
    },
    {
      "name": "write_file",
      "description": "Write only the requested file path, then return its path and a verification summary.",
      "input_schema": {
        "type": "object",
        "properties": {"path": {"type": "string"}, "content": {"type": "string"}},
        "required": ["path", "content"]
      }
    }
  ]
}

配套系统提示建议使用正常、具体的“何时用工具”措辞：Use search_docs when external or user-specific facts are needed; use write_file only after the requested content is complete.

测试/工作流步骤

1. 固定输入、工具描述、max_tokens 和模型 snapshot，只扫描 effort=low/medium/high/max。

2. 记录完整响应 token、thinking token（如启用）、工具调用数量、首 token 延迟、总延迟和任务成功率。

3. 分别测试“建议修改”和“执行修改”两种指令，验证明确的 action wording 是否改变工具触发率。

4. 若使用 prompt caching，在同一会话保持 effort 不变；跨工作负载比较时再调整 effort。

5. 将写工具包在权限、路径 allowlist、内容审查和写后读取验证中。

原始证据与数据

• 官方 effort 文档写明 effort 影响响应中的所有 token，包括文本、工具参数和 thinking；较低 effort 通常更少工具调用、更直接行动和更短确认。

• Sonnet 4.6 默认 high；官方对 Sonnet 4.6 推荐 medium 作为大多数应用的速度/成本/性能平衡，low 用于高吞吐/延迟敏感任务，high 用于复杂推理，max 用于绝对能力优先。

• 官方说明 xhigh 不在 Sonnet 4.6 的可用列表中，而 max 可用。

• 官方提示工具触发要写成明确行动，而非“能否建议修改”；同时提醒过强的 MUST/CRITICAL 语言可能导致新模型过度触发工具。

• 官方说明在依赖缓存的长对话中改变 effort 会使此前缓存前缀失效，应该在一个缓存会话内保持稳定。

适用边界

• 不同云平台可能延迟支持 output_config.effort、thinking 或工具字段；以实际 endpoint 返回为准。

• effort 控制 token/工作量，不是可见答案长度的硬上限；需要控制篇幅时仍要在 prompt 和 max_tokens 中明确。

• 更少工具调用不一定更好；写任务必须以正确性和验证结果为主，而不是只优化调用数。

• max 没有“总是更正确”的证据；必须按真实业务 eval 计算增量质量与成本。

来源摘录或观察（仅做合规短引）

官方给 Sonnet 4.6 的建议是“Medium effort (recommended default)”（合规短引）。