Claude API工具调用实战：解决’code不会调用工具’的入门指南

1次阅读

共计 2733 个字符，预计需要花费 7 分钟才能阅读完成。

作为一名刚开始接触 Claude API 的开发者，最近在集成工具调用功能时踩了不少坑。最让我头疼的就是明明按照文档写了代码，但总是遇到各种调用失败的问题。今天就把这些经验总结出来，希望能帮到同样遇到困难的伙伴们。

刚开始尝试调用工具时，经常遇到以下几种典型问题：

HTTP 400 Bad Request：这是最常见的错误，通常是因为请求体格式不符合 API 规范。我遇到过因为漏写 tool_choice 参数导致整个请求被拒绝的情况。

# 错误示例（缺少必要参数）response = client.post('/v1/messages', json={
    "model": "claude-2.1",
    "messages": [...]
})  # 会返回 400 错误

空响应或部分响应 ：有时候 API 返回了 200 状态码，但响应体里就是没有预期的tool_use 事件。后来发现是因为 temperature 参数设得太高（>1.0），导致输出过于随机。
超时无响应：特别是在网络环境不稳定时，如果没设置合理的超时时间，程序就会一直卡住。

理解认证流程是成功调用的第一步。Claude API 采用 Bearer Token 认证，整个流程可以简化为：

获取 API 密钥（在 Anthropic 控制台生成）
在请求头中加入 Authorization
服务端验证令牌有效性
执行工具调用

sequenceDiagram
    开发者 ->>Claude API: POST 请求 (带 Bearer Token)
    Claude API->> 开发者: 401 Unauthorized (如果 Token 无效)
    Claude API->> 开发者: 200 OK + tool_use 事件 (认证成功)

根据我的实测经验，两种调用方式的主要区别如下：

对比维度	同步调用	异步调用
时延	较高（等待完整响应）	较低（流式返回）
吞吐量	适合低频场景	适合高并发场景
错误处理	即时抛出异常	需要回调函数处理
适用场景	简单查询、开发调试	生产环境、复杂任务

下面是一个完整的 Python 示例，包含了所有必备元素：

import os
from anthropic import Anthropic, APIStatusError
import backoff  # 用于重试机制

# 初始化客户端（记得设置环境变量 ANTHROPIC_API_KEY）client = Anthropic(
    max_retries=3,  # 默认重试次数
    timeout=10.0    # 单位：秒
)

@backoff.on_exception(backoff.expo, APIStatusError, max_tries=3)
def call_tool():
    try:
        response = client.beta.tools.messages.create(
            model="claude-3-opus-20240229",
            max_tokens=1024,
            temperature=0.7,  # 建议 0.3-0.7 之间，平衡确定性和创造性
            tools=[{
                "name": "get_weather",
                "description": "查询指定城市的天气",
                "input_schema": {
                    "type": "object",
                    "properties": {"city": {"type": "string"}
                    },
                    "required": ["city"]
                }
            }],
            messages=[{"role": "user", "content": "上海明天天气怎么样？"}],
            tool_choice="auto"  # 关键参数！指定自动选择工具
        )

        # 处理工具调用事件
        for event in response:
            if event.type == "tool_use":
                print(f"工具调用: {event.name}")
                print(f"输入参数: {event.input}")

    except Exception as e:
        print(f"调用失败: {str(e)}")
        raise

关键参数说明：

temperature：
<0.3：输出确定性高但可能呆板
0.3-0.7：最佳实践范围
1.0：创造性高但可能偏离预期
tool_choice：
“auto”：让模型决定是否调用工具
{“name”: “tool_name”}：强制调用特定工具
“none”：禁止工具调用

Claude API 的默认速率限制较严格，建议：

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(5),
    wait=wait_exponential(multiplier=1, min=4, max=10)
)
def api_call_with_retry():
    # 实现带指数退避的重试逻辑
    pass

在日志记录前过滤敏感信息：

import re

def sanitize_log(content):
    # 移除 API 密钥
    content = re.sub(r'(?i)(api[_-]?key|auth[_-]?token)[=:]\s*\w+', 
                    '[REDACTED]', content)
    # 移除邮箱
    content = re.sub(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b',
                    '[EMAIL]', content)
    return content

建议采用 JSON 格式记录完整上下文：

import json
import logging

logging.basicConfig(format='{"time":"%(asctime)s","level":"%(levelname)s","message":%(message)s}')

log_data = {"request": sanitize_log(str(request)),
    "response": sanitize_log(str(response)),
    "duration_ms": duration
}
logging.info(json.dumps(log_data))