第 56 章：工具调用的双面人生

// → src/my-agent/tools.ts
export interface ToolDefinition {
  name: string;
  description: string;
  input_schema: {
    type: "object";
    properties: Record<string, {
      type: string;
      description: string;
      enum?: string[];
    }>;
    required: string[];
  };
}

export const weatherTool: ToolDefinition = {
  name: "get_weather",
  description: "获取指定城市的当前天气",
  input_schema: {
    type: "object",
    properties: {
      city: {
        type: "string",
        description: "城市名，如 北京、上海",
      },
    },
    required: ["city"],
  },
};

// → src/my-agent/tool-client.ts
const response = await client.createMessage({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "北京今天天气怎么样？" }],
  tools: [weatherTool],                    // 提供工具
  tool_choice: { type: "auto" },          // 让模型自己决定
});

// → src/my-agent/tool-client.ts
export function extractToolCalls(
  response: MessageResponse
): ToolUseBlock[] {
  return response.content.filter(
    (block): block is ToolUseBlock => block.type === "tool_use"
  );
}

// → src/my-agent/tool-executor.ts
export class ToolExecutor {
  private handlers = new Map<string, ToolHandler>();

  register(name: string, handler: ToolHandler): void {
    this.handlers.set(name, handler);
  }

  async execute(toolUse: ToolUseBlock): Promise<ToolResultBlock> {
    const handler = this.handlers.get(toolUse.name);
    if (!handler) {
      return {
        type: "tool_result",
        tool_use_id: toolUse.id,
        content: `Unknown tool: ${toolUse.name}`,
        is_error: true,
      };
    }

    try {
      const result = await handler(toolUse.input);
      return {
        type: "tool_result",
        tool_use_id: toolUse.id,
        content: JSON.stringify(result),
      };
    } catch (err) {
      return {
        type: "tool_result",
        tool_use_id: toolUse.id,
        content: `Tool execution error: ${(err as Error).message}`,
        is_error: true,
      };
    }
  }
}

// → src/my-agent/tool-loop.ts
export async function* toolUseLoop(
  client: ApiClient,
  params: MessageCreateParams & { tools: ToolDefinition[] },
  executor: ToolExecutor,
  maxIterations = 10
): AsyncGenerator<TurnEvent> {
  let messages = [...params.messages];
  let iterations = 0;

  while (iterations < maxIterations) {
    const response = await client.createMessage({
      ...params,
      messages,
    });

    yield { type: "response", response };

    if (response.stop_reason === "end_turn") {
      return response; // 完成
    }

    if (response.stop_reason === "tool_use") {
      const toolCalls = extractToolCalls(response);

      // 添加 assistant 的 tool_use 到历史
      messages.push({
        role: "assistant",
        content: response.content,
      });

      // 执行所有工具调用
      const results = await Promise.all(
        toolCalls.map(tc => executor.execute(tc))
      );

      yield { type: "tool_results", results };

      // 添加 tool_result 到历史
      messages.push({
        role: "user",
        content: results,
      });

      iterations++;
      continue;
    }

    // 其他 stop_reason：max_tokens 或 stop_sequence
    return response;
  }

  throw new Error(`超过最大迭代次数 ${maxIterations}`);
}

// → src/my-agent/tools/weather.ts
type ToolHandler = (input: Record<string, unknown>) => Promise<unknown>;

const weatherHandler: ToolHandler = async (input) => {
  const city = input.city as string;
  // 实际应用中，这里调用天气 API
  const weatherData = await fetch(
    `https://api.weather.example.com/current?city=${encodeURIComponent(city)}`
  );
  return weatherData.json();
};

executor.register("get_weather", weatherHandler);

// → src/my-agent/tools.ts
type ToolChoice =
  | { type: "auto"; disable_parallel_tool_use?: boolean }   // 默认
  | { type: "any"; disable_parallel_tool_use?: boolean }     // 必须用工具
  | { type: "tool"; name: string }                           // 必须用指定工具
  | { type: "none" };                                        // 禁止用工具

// → src/my-agent/tool-executor.ts
// 输入验证错误（让模型能自我纠正）
if (!input.city) {
  return {
    type: "tool_result",
    tool_use_id: toolUse.id,
    content: "错误：缺少必填参数 'city'。请提供城市名。",
    is_error: true,
  };
}