在聚合站上用工具调用搭一个最小天气 Agent

为什么用天气工具作为示例

工具调用（tool calls）是让 LLM 与外部世界交互的基础能力。天气查询是一个理想的入门示例：逻辑简单、结果明确、无需复杂鉴权，能让你专注于工具调用的核心流程。

在聚合站上，你用一个 API key 就能调用多个模型，而工具调用的接口规范在主流模型间基本一致，这让你可以轻松切换模型进行测试。

整体流程概览

一个最小的天气 Agent 包含以下步骤：

1. 声明工具：用 JSON Schema 描述天气查询函数，包括名称、描述和参数。
2. 第一轮请求：把用户问题和工具声明一起发给模型。
3. 解析 tool_calls：模型返回它想调用的工具及参数。
4. 本地执行：在你的代码中实际运行天气查询，得到结果。
5. 第二轮请求：把工具执行结果作为新消息回填，让模型生成最终回答。

第一步：声明 JSON Schema

工具声明需要告诉模型：工具叫什么、做什么、需要哪些参数。以下是一个天气查询工具的 schema 示例（参数为城市名）：

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "查询指定城市的当前天气",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "城市名称，例如：北京"
        }
      },
      "required": ["city"]
    }
  }
}

要点：

• description 要清晰，模型靠它判断何时调用。
• 参数类型和必填项要准确，避免模型生成无效参数。
• 工具名称用蛇形命名，保持可读性。

第二步：发起第一轮请求

将用户消息和工具声明一起发送。请求体大致如下：

{
  "model": "claude-3-5-sonnet",
  "messages": [
    {"role": "user", "content": "北京今天天气怎么样？"}
  ],
  "tools": [ /* 上面的 schema */ ]
}

模型不会直接回答天气，而是返回一个 toolcalls 结构，表示它想调用 getweather，并给出参数 {"city": "北京"}。

第三步：解析 tool_calls

响应中会包含类似这样的内容（结构因模型而异，但核心一致）：

{
  "choices": [{
    "message": {
      "role": "assistant",
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\": \"北京\"}"
        }
      }]
    }
  }]
}

你需要提取 name 和 arguments。注意 arguments 是 JSON 字符串，需要解析成对象。

第四步：本地执行工具

在你的代码中实现 get_weather 函数。它可以是调用真实天气 API，也可以是一个模拟函数。关键是要返回一个字符串结果，例如：

{"temperature": "25°C", "condition": "晴", "humidity": "40%"}

执行后，你得到工具的输出，准备回填。

第五步：发起第二轮请求

将助手的 tool_calls 消息和工具结果消息追加到对话历史，再次请求模型。消息结构示例：

[
  {"role": "user", "content": "北京今天天气怎么样？"},
  {"role": "assistant", "tool_calls": [ /* 原样保留 */ ]},
  {"role": "tool", "tool_call_id": "call_abc123", "content": "{\"temperature\": \"25°C\", \"condition\": \"晴\"}"}
]

注意：toolcallid 必须与第一轮返回的 id 一致，这样模型才知道这是对哪个调用的响应。

模型收到工具结果后，会生成自然语言回答，例如：“北京今天晴，气温 25°C，湿度 40%。”

常见问题与调试建议

• 模型不调用工具：检查工具描述是否清晰，或尝试在用户消息中明确要求使用工具。
• 参数解析失败：确保 arguments 是合法 JSON，必要时用 try-catch 处理。
• 多轮工具调用：如果模型在第二轮又返回 tool_calls，你需要重复执行和回填，直到模型返回普通文本。
• 模型差异：不同模型对工具调用的支持程度不同，但主流模型都遵循类似规范。在聚合站上切换模型时，注意测试兼容性。

在聚合站上的实践提示

聚合站的一个 API key 可以调用多个模型，方便你对比不同模型在工具调用上的表现。计费方面，用户按官方价 ×1.3 扣费；如果你贡献自己的 key，可以获得官方价 ×1.1（优质 ×1.2）的 USDC 返利。

工具调用是构建更复杂 Agent 的基石。掌握这个最小闭环后，你可以逐步添加更多工具，实现多步骤任务。