Skip to main content

​
Claude 工具调用示例

以下示例展示如何使用Claude的 /v1/messages 接口进行工具调用（Tool Use），让Claude能够调用外部工具来获取信息或执行操作。

​
快速开始

只需要替换 <API-KEY> 为你的实际API密钥即可运行。 
curl -X POST "https://model-api.skyengine.com.cn/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API-KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "温度单位，默认为摄氏度"
            }
          },
          "required": ["city"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "北京今天的天气怎么样？"
      }
    ]
  }'

​
Claude工具调用的特点

​
1. 工具定义格式

Claude使用不同于OpenAI的工具定义格式： 
{
  "name": "tool_name",
  "description": "工具描述",
  "input_schema": {
    "type": "object",
    "properties": {
      "param": {
        "type": "string",
        "description": "参数描述"
      }
    },
    "required": ["param"]
  }
}

​
2. 响应结构

Claude的工具调用响应包含多种内容块：
  • text: 普通文本回复
  • tool_use: 工具调用请求
  • tool_result: 工具执行结果（用户返回）

​
3. 工作流程

  1. 用户发送带有工具定义的消息
  2. Claude分析是否需要使用工具
  3. Claude返回包含tool_use类型的内容块
  4. 客户端执行对应的工具函数
  5. 客户端将结果作为tool_result发送回Claude
  6. Claude基于工具结果生成最终回复

​
结果示例

200
{
  "id": "msg_01234567890",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "我来帮您查询北京的天气情况。"
    },
    {
      "type": "tool_use",
      "id": "toolu_01234567890",
      "name": "get_weather",
      "input": {
        "city": "北京",
        "unit": "celsius"
      }
    }
  ],
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 300,
    "output_tokens": 150
  }
}

​
高级特性

​
1. 工具链调用

Claude可以在一个回复中调用多个工具： 
# Claude可能会同时调用多个工具
tools_calls = [
    {"name": "get_weather", "input": {"city": "北京"}},
    {"name": "get_weather", "input": {"city": "上海"}},
    {"name": "calculate_math", "input": {"expression": "25*9/5+32"}}
]

​
2. 条件性工具使用

Claude会智能判断是否需要使用工具： 
# 不需要工具的查询
user_message = "你好，请介绍一下自己"
# Claude会直接回复，不调用任何工具

# 需要工具的查询
user_message = "北京今天几度？"
# Claude会调用get_weather工具

​
3. 工具结果验证

Claude会验证工具返回的结果并进行合理性检查： 
def get_weather(city):
    if city == "火星":
        return {"error": "无法获取火星天气信息"}
    # Claude会理解这个错误并相应地回复用户

​
应用场景

  • 实时信息查询: 天气、股价、新闻等
  • 计算服务: 数学计算、单位转换、统计分析
  • 数据操作: 数据库查询、文件操作
  • 外部API集成: 调用第三方服务
  • 业务流程自动化: 执行复杂的业务逻辑

​
最佳实践

​
1. 工具设计原则

  • 单一职责: 每个工具只负责一个明确的功能
  • 清晰描述: 提供详细的工具和参数描述
  • 错误处理: 妥善处理各种异常情况
  • 参数验证: 验证输入参数的有效性

​
2. 安全考虑

  • 输入验证: 严格验证所有输入参数
  • 权限控制: 限制工具的执行权限
  • 审计日志: 记录工具调用的详细信息
  • 资源限制: 防止资源耗尽攻击

​
3. 性能优化

  • 缓存机制: 对频繁调用的结果进行缓存
  • 异步处理: 对耗时操作使用异步执行
  • 超时控制: 设置合理的超时时间
  • 并发限制: 控制并发工具调用数量

​
注意事项

  1. API调用成本: 工具调用需要多次API请求，会增加成本
  2. 响应时间: 工具执行会增加整体响应时间
  3. 工具可靠性: 确保工具函数的稳定性和可靠性
  4. 错误传播: 工具错误会影响整个对话流程
  5. 调试复杂性: 工具调用链的调试比较复杂