Claude Extended Thinking 与 Tool Use 联合实战：构建复杂推理 Agent 的工程指南

2026 年，Anthropic 为 Claude 模型引入了 Extended Thinking（扩展思考）能力，允许模型在生成最终回答前进行长达 128K token 的深度推理。根据 Anthropic 开发者社区的统计，同时启用 Extended Thinking 和 Tool Use 的 Agent 任务完成率比单独使用任一特性高出 47%——但这种联合模式也引入了全新的工程挑战：思维链预算控制、thinking block 与 tool_use block 的交织处理、中间推理结果的缓存策略等。本文将深入拆解这套联合机制的工程实践，帮你构建真正能处理复杂推理任务的 AI Agent。

🧠 一、Extended Thinking 机制深度解析

1.1 工作原理与 API 结构

Extended Thinking 的核心思想是：让模型在回答之前先「想清楚」。与 OpenAI 的 o1/o3 系列不同，Claude 的 Extended Thinking 是显式可见的——你可以看到模型的完整思考过程，这对调试和审计至关重要。

// 基础 Extended Thinking 调用
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 16000,
  thinking: {
    type: 'enabled',
    budget_tokens: 10000  // 思考预算，最多 128000
  },
  messages: [
    {
      role: 'user',
      content: '分析以下 JSON 数据的嵌套结构，找出所有可能导致循环引用的路径：\n' +
        JSON.stringify({ a: { b: { c: 'ref:a' } }, d: { e: 'ref:d' } })
    }
  ]
});

// 响应包含两种 block 类型
for (const block of response.content) {
  if (block.type === 'thinking') {
    console.log('🧠 思考过程:', block.thinking);
  } else if (block.type === 'text') {
    console.log('💬 最终回答:', block.text);
  }
}

📌 记住：budget_tokens 不是最大 token 限制，而是模型的「思考预算」。模型可能用完全部预算，也可能提前结束思考。实际思考 token 数通过 usage.input_tokens 中的 thinking tokens 统计。

1.2 Thinking Block 的生命周期

理解 thinking block 的生命周期是构建可靠 Agent 的前提。Extended Thinking 的响应结构如下：

{
  "content": [
    {
      "type": "thinking",
      "thinking": "让我逐步分析这个 JSON 结构...\n首先看 a -> b -> c ...",
      "signature": "ErUBCkYI..."  // 加密签名，用于多轮对话中验证完整性
    },
    {
      "type": "text",
      "text": "经过分析，发现了两条循环引用路径..."
    }
  ],
  "usage": {
    "input_tokens": 150,
    "output_tokens": 5000,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

⚠️ **警告：**在多轮对话中，必须将之前的 thinking block（包括 signature 字段）原样传回 API。篡改或删除 thinking block 的签名会导致请求失败。这是 Anthropic 用于防止 thinking 内容注入攻击的安全机制。

1.3 预算控制策略

Extended Thinking 的成本模型与普通调用不同——thinking tokens 计入输出 token 计费。以 Claude Sonnet 4 为例：

⚡ **关键结论：**Extended Thinking + Tool Use 的单次调用成本是普通调用的 17 倍。必须通过预算控制和缓存策略来平衡推理质量与成本。

🔧 二、Extended Thinking + Tool Use 联合模式

2.1 联合调用的基本架构

当 Extended Thinking 遇上 Tool Use，响应中会交替出现 thinking、text 和 tool_use 三种 block 类型。处理这种交织结构需要专门的编排逻辑：

// 联合调用：Extended Thinking + Tool Use
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

// 定义工具
const tools = [
  {
    name: 'validate_json',
    description: '验证 JSON 字符串的合法性并返回解析结果',
    input_schema: {
      type: 'object' as const,
      properties: {
        json_string: { type: 'string', description: '待验证的 JSON 字符串' },
        strict: { type: 'boolean', description: '是否启用严格模式' }
      },
      required: ['json_string']
    }
  },
  {
    name: 'analyze_json_schema',
    description: '分析 JSON 数据并推断其 JSON Schema',
    input_schema: {
      type: 'object' as const,
      properties: {
        data: { type: 'string', description: 'JSON 数据字符串' }
      },
      required: ['data']
    }
  }
];

// 工具执行器
async function executeTool(name: string, input: Record<string, unknown>) {
  switch (name) {
    case 'validate_json': {
      try {
        const parsed = JSON.parse(input.json_string as string);
        return { valid: true, data: parsed, keys: Object.keys(parsed) };
      } catch (e) {
        return { valid: false, error: (e as Error).message };
      }
    }
    case 'analyze_json_schema': {
      const data = JSON.parse(input.data as string);
      const schema = inferSchema(data);
      return { schema, depth: getDepth(data), keyCount: countKeys(data) };
    }
    default:
      return { error: `Unknown tool: ${name}` };
  }
}

// Agent 循环：处理 thinking + tool_use 的交织响应
async function runAgent(userMessage: string, maxIterations = 5) {
  const messages: Anthropic.MessageParam[] = [
    { role: 'user', content: userMessage }
  ];

  for (let i = 0; i < maxIterations; i++) {
    const response = await anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 16000,
      thinking: { type: 'enabled', budget_tokens: 8000 },
      tools,
      messages
    });

    // 收集所有 block
    const thinkingBlocks: Anthropic.ThinkingBlock[] = [];
    const textParts: string[] = [];
    const toolCalls: Anthropic.ToolUseBlock[] = [];

    for (const block of response.content) {
      if (block.type === 'thinking') thinkingBlocks.push(block);
      if (block.type === 'text') textParts.push(block.text);
      if (block.type === 'tool_use') toolCalls.push(block);
    }

    // 如果没有工具调用，返回最终结果
    if (toolCalls.length === 0) {
      return {
        answer: textParts.join(''),
        thinking: thinkingBlocks.map(t => t.thinking),
        iterations: i + 1
      };
    }

    // 执行工具并将结果传回
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    for (const call of toolCalls) {
      const result = await executeTool(call.name, call.input as Record<string, unknown>);
      toolResults.push({
        type: 'tool_result',
        tool_use_id: call.id,
        content: JSON.stringify(result)
      });
    }

    // 关键：将完整的 assistant 响应（含 thinking blocks）传回
    messages.push({ role: 'assistant', content: response.content });
    messages.push({ role: 'user', content: toolResults });
  }

  throw new Error(`Agent exceeded max iterations (${maxIterations})`);
}

💡 **提示：**Agent 循环中，response.content 包含完整的 thinking + text + tool_use blocks。必须将整个 content 数组作为 assistant 消息传回，而不是只传 text 部分——否则 thinking context 会丢失，模型需要重新推理。

2.2 Thinking Budget 的动态调整

不同复杂度的任务需要不同的思考预算。固定预算会导致简单任务浪费 token、复杂任务预算不足。动态预算调整是生产级 Agent 的关键优化：

// 动态 Thinking Budget 管理器
interface BudgetConfig {
  simple: number;    // 简单任务：2000 tokens
  moderate: number;  // 中等任务：8000 tokens
  complex: number;   // 复杂任务：32000 tokens
  max: number;       // 硬上限：128000 tokens
}

const DEFAULT_BUDGET: BudgetConfig = {
  simple: 2000,
  moderate: 8000,
  complex: 32000,
  max: 128000
};

function estimateTaskComplexity(
  userMessage: string,
  toolCount: number,
  previousIterations: number
): 'simple' | 'moderate' | 'complex' {
  const signals = {
    length: userMessage.length > 500,
    multipleTools: toolCount > 2,
    hasAnalysis: /分析|比较|评估|诊断|推理/.test(userMessage),
    hasData: /\{.*\}/s.test(userMessage),
    retrying: previousIterations > 0
  };

  const complexity = Object.values(signals).filter(Boolean).length;
  if (complexity >= 3) return 'complex';
  if (complexity >= 1) return 'moderate';
  return 'simple';
}

function getBudgetForTask(
  userMessage: string,
  toolCount: number,
  previousIterations: number,
  config: BudgetConfig = DEFAULT_BUDGET
): number {
  const complexity = estimateTaskComplexity(userMessage, toolCount, previousIterations);

  // 如果是重试（工具调用失败后），增加预算
  const retryBonus = previousIterations * 2000;

  const baseBudget = {
    simple: config.simple,
    moderate: config.moderate,
    complex: config.complex
  }[complexity];

  return Math.min(baseBudget + retryBonus, config.max);
}

🏗️ 三、生产级工程实践

3.1 Thinking 缓存与 Prompt Cache 协同

Anthropic 提供了 Prompt Cache 机制——将 system prompt 和工具定义缓存，后续调用复用缓存可节省 90% 的输入 token 成本。结合 Extended Thinking，可以实现双重缓存优化：

// Prompt Cache + Thinking 缓存策略
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

// 带缓存控制的系统提示
const systemPrompt: Anthropic.MessageCreateParams['system'] = [
  {
    type: 'text',
    text: `你是一个 JSON 数据分析专家。你的任务是：
1. 验证输入数据的 JSON 合法性
2. 分析数据结构和嵌套深度
3. 检测潜在的数据质量问题
4. 提供优化建议

可用工具：validate_json, analyze_json_schema, detect_cycles`,
    cache_control: { type: 'ephemeral' }  // 标记为可缓存
  }
];

// 缓存命中率优化：工具定义也应缓存
const tools = [
  {
    name: 'validate_json',
    description: '验证 JSON 字符串的合法性',
    input_schema: { /* ... */ },
    cache_control: { type: 'ephemeral' } as const
  },
  {
    name: 'analyze_json_schema',
    description: '分析 JSON 数据并推断 Schema',
    input_schema: { /* ... */ },
    cache_control: { type: 'ephemeral' } as const
  }
];

// 带缓存的 Agent 调用
async function callWithCache(
  messages: Anthropic.MessageParam[],
  budgetTokens: number
) {
  const response = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 16000,
    thinking: { type: 'enabled', budget_tokens: budgetTokens },
    system: systemPrompt,
    tools,
    messages
  });

  // 监控缓存命中率
  const usage = response.usage;
  const cacheHitRate = usage.cache_read_input_tokens /
    (usage.input_tokens + usage.cache_read_input_tokens);

  console.log(`Cache hit rate: ${(cacheHitRate * 100).toFixed(1)}%`);
  console.log(`Thinking tokens: ${getThinkingTokens(response)}`);

  return response;
}

function getThinkingTokens(response: Anthropic.Message): number {
  return response.content
    .filter((b): b is Anthropic.ThinkingBlock => b.type === 'thinking')
    .reduce((sum, b) => sum + estimateTokens(b.thinking), 0);
}

function estimateTokens(text: string): number {
  // 粗略估算：中文约 1.5 token/字，英文约 0.75 token/word
  const chineseChars = (text.match(/[\u4e00-\u9fff]/g) || []).length;
  const otherChars = text.length - chineseChars;
  return Math.ceil(chineseChars * 1.5 + otherChars * 0.4);
}

⚠️ **警告：**Prompt Cache 的最小缓存单元是 1024 tokens（Claude Sonnet）或 2048 tokens（Claude Opus）。如果你的 system prompt + tools 定义总 token 数低于此阈值，缓存不会生效，反而会增加少量开销。

3.2 思维链审计与安全过滤

Extended Thinking 的透明性是一把双刃剑——它有助于调试，但也可能暴露敏感信息（如内部 API 地址、数据库结构）。生产环境需要对 thinking 内容做安全过滤：

// Thinking 内容安全过滤器
interface ThinkingFilter {
  patterns: RegExp[];
  replacement: string;
}

const SENSITIVE_FILTERS: ThinkingFilter[] = [
  // API 密钥和令牌
  { patterns: [/sk-[a-zA-Z0-9]{20,}/g, /Bearer\s+[a-zA-Z0-9._-]+/g], replacement: '[REDACTED_CREDENTIAL]' },
  // 内部 IP 和域名
  { patterns: [/10\.\d+\.\d+\.\d+/g, /192\.168\.\d+\.\d+/g, /\.internal\b/g], replacement: '[REDACTED_INTERNAL]' },
  // 数据库连接字符串
  { patterns: [/postgresql:\/\/[^\s]+/g, /mongodb:\/\/[^\s]+/g], replacement: '[REDACTED_DB_URL]' },
  // 文件系统路径（可选，根据安全要求）
  { patterns: [/\/home\/[a-z]+\//g, /\/etc\/[a-z]+/g], replacement: '[REDACTED_PATH]' }
];

function sanitizeThinking(
  thinking: string,
  filters: ThinkingFilter[] = SENSITIVE_FILTERS
): string {
  let sanitized = thinking;
  for (const filter of filters) {
    for (const pattern of filter.patterns) {
      sanitized = sanitized.replace(pattern, filter.replacement);
    }
  }
  return sanitized;
}

// 安全的 Agent 响应处理
interface SafeAgentResponse {
  answer: string;
  thinkingSummary: string;      // 过滤后的思考摘要
  thinkingTokenCount: number;
  toolCallsCount: number;
  iterations: number;
}

function createSafeResponse(
  response: Awaited<ReturnType<typeof runAgent>>
): SafeAgentResponse {
  const fullThinking = response.thinking.join('\n---\n');
  const sanitizedThinking = sanitizeThinking(fullThinking);

  return {
    answer: response.answer,
    thinkingSummary: sanitizedThinking.slice(0, 2000) + // 截断过长的思考
      (sanitizedThinking.length > 2000 ? '...[truncated]' : ''),
    thinkingTokenCount: estimateTokens(fullThinking),
    toolCallsCount: response.iterations - 1,
    iterations: response.iterations
  };
}

3.3 并行 Tool Use 与错误恢复

Claude 支持在单次响应中返回多个 tool_use block（并行工具调用）。结合 Extended Thinking，模型可以在思考后一次性请求多个工具调用，显著减少 Agent 循环次数：

// 并行工具执行与错误恢复
async function executeToolsParallel(
  toolCalls: Anthropic.ToolUseBlock[],
  executeTool: (name: string, input: Record<string, unknown>) => Promise<unknown>
): Promise<Anthropic.ToolResultBlockParam[]> {
  const results = await Promise.allSettled(
    toolCalls.map(async (call) => {
      const result = await executeTool(call.name, call.input as Record<string, unknown>);
      return { call, result };
    })
  );

  return results.map((result, index) => {
    const call = toolCalls[index];

    if (result.status === 'fulfilled') {
      return {
        type: 'tool_result' as const,
        tool_use_id: call.id,
        content: JSON.stringify(result.value.result)
      };
    } else {
      // 工具执行失败：返回错误信息让模型决定是否重试
      return {
        type: 'tool_result' as const,
        tool_use_id: call.id,
        is_error: true,  // 关键：标记为错误结果
        content: JSON.stringify({
          error: result.reason?.message || 'Tool execution failed',
          tool: call.name,
          hint: '请检查输入参数或尝试使用其他工具'
        })
      };
    }
  });
}

// 使用示例：处理包含并行工具调用的响应
async function handleResponse(response: Anthropic.Message) {
  const toolCalls = response.content.filter(
    (b): b is Anthropic.ToolUseBlock => b.type === 'tool_use'
  );

  if (toolCalls.length === 0) return null;

  // 并行执行所有工具（即使其中一个失败，其他仍继续）
  const toolResults = await executeToolsParallel(toolCalls, executeTool);

  // 统计执行结果
  const failures = toolResults.filter(r => r.is_error);
  if (failures.length > 0) {
    console.warn(`⚠️ ${failures.length}/${toolCalls.length} tool calls failed`);
  }

  return toolResults;
}

💡 **提示：**当 is_error: true 时，Claude 会收到错误信息并决定是否重试。大多数情况下，模型会调整参数后重试 1-2 次。如果连续失败 3 次以上，建议在应用层介入，而不是让模型无限重试。

📊 四、性能对比与最佳实践

4.1 三种 Agent 模式对比

在生产环境中，Extended Thinking + Tool Use 并非总是最优选择。以下是三种常见 Agent 模式的实测对比（基于 100 个 JSON 数据分析任务）：

⚡ **关键结论：**对于简单任务（JSON 格式化、字段提取），普通 Tool Use 已经足够，Extended Thinking 只会浪费成本。只有在需要多步推理 + 多工具协调的复杂任务中，联合模式的价值才真正体现。

4.2 决策树：何时启用 Extended Thinking

任务是否需要多步推理？
├── 否 → 普通 Tool Use（成本最低）
└── 是 → 推理步骤是否超过 3 步？
    ├── 否 → 普通 Tool Use + 详细 system prompt 引导
    └── 是 → 是否需要调用多个工具？
        ├── 否 → Extended Thinking（纯推理）
        └── 是 → Extended Thinking + Tool Use（最强组合）

4.3 生产环境 Checklist

• ✅ 始终设置 budget_tokens，避免无限制思考消耗
• ✅ 在多轮对话中完整传回 thinking blocks（含 signature）
• ✅ 对 thinking 内容做安全过滤，防止敏感信息泄露
• ✅ 使用 Prompt Cache 缓存 system prompt 和 tools 定义
• ✅ 并行工具调用时使用 Promise.allSettled 而非 Promise.all
• ✅ 工具失败时设置 is_error: true，让模型自主决定重试策略
• ✅ 监控 thinking token 消耗，设置成本告警阈值
• ❌ 不要在简单任务中启用 Extended Thinking——性价比极低
• ❌ 不要删除或篡改 thinking block 的 signature 字段
• ❌ 不要让 Agent 循环超过 5 轮——通常是陷入了推理死循环
• ⚠️ 注意 max_tokens 必须大于 budget_tokens——剩余空间用于生成最终回答

🎯 总结

Extended Thinking + Tool Use 的联合模式为 AI Agent 打开了处理复杂推理任务的大门，但它不是银弹。选择是否启用时，核心考量是任务复杂度 vs 成本预算的平衡。

推荐决策路径：

1. 大多数 JSON 处理任务（格式化、验证、转换）→ 普通 Tool Use，无需 Extended Thinking
2. 需要深度分析的任务（Schema 推断、数据质量诊断）→ Extended Thinking，按需使用
3. 复杂的多步 Agent 工作流（数据清洗 + 验证 + 转换 + 报告）→ 联合模式，配合动态预算

相关工具推荐：

• 🔧 Anthropic TypeScript SDK — 官方 SDK，原生支持 Extended Thinking + Tool Use
• 🔧 Vercel AI SDK — generateText() 支持 Claude Extended Thinking，简化 Agent 循环
• 🔧 LangChain.js — Agent 框架，内置工具编排和错误恢复
• 🔧 jsjson.com JSON 格式化工具 — 快速验证和格式化 LLM 返回的 JSON 数据

📌 **记住：**Extended Thinking 的价值在于「想清楚再做」，而不是「想很多再做」。一个好的 Agent 架构应该让模型在关键节点深度思考，而不是在每一步都过度思考。控制好 thinking budget，才能在推理质量和成本之间找到最优平衡点。