02 · 工具调用：让模型的“意图”变成真实的“动作”

const readFileTool = {
  name: 'read_file',
  // 描述是写给模型看的 prompt!模型靠它决定"什么时候、怎么用"这个工具。
  description: '读取指定路径的文件内容。当你需要查看某个文件时使用。',
  input_schema: {
    type: 'object',
    properties: {
      path: { type: 'string', description: '要读取的文件路径,相对于项目根目录' },
    },
    required: ['path'],
  },
} as const

const res = await client.messages.create({
  model: 'some-llm',
  max_tokens: 1024,
  tools: [readFileTool],                          // ← 告诉模型它有这个工具
  messages: [
    { role: 'user', content: 'src/index.ts 里导出了什么?' },
  ],
})

{
  role: 'assistant',
  content: [
    { type: 'text', text: '我来看一下这个文件。' },   // 可能先说一句
    {
      type: 'tool_use',                               // ← 全新的块类型!
      id: 'toolu_abc123',                             // ← 这次调用的唯一 ID,关键
      name: 'read_file',
      input: { path: 'src/index.ts' },                // ← 模型填好的参数
    },
  ],
  stop_reason: 'tool_use',                            // ← 不是 end_turn,是"我要用工具"
}

async function executeTool(name: string, input: any): Promise<string> {
  if (name === 'read_file') {
    return await fs.readFile(input.path, 'utf-8')   // ← 真正的动作发生在这里
  }
  throw new Error(`未知工具: ${name}`)
}

const toolUse = res.content.find(b => b.type === 'tool_use')
const result = await executeTool(toolUse.name, toolUse.input)

const messages = [
  { role: 'user', content: 'src/index.ts 里导出了什么?' },
  { role: 'assistant', content: res.content },         // 模型那条(含 tool_use)原样放回
  {
    role: 'user',                                       // 工具结果的角色是 user
    content: [
      {
        type: 'tool_result',
        tool_use_id: toolUse.id,                        // ← 必须回指那个 id,一一配对
        content: result,                                // 文件内容
      },
    ],
  },
]

const finalRes = await client.messages.create({
  model: 'some-llm', max_tokens: 1024, tools: [readFileTool], messages,
})
// => "src/index.ts 导出了 3 个函数:createServer、handleRequest 和 shutdown。"