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

1次阅读

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

刚接触 Claude API 时，我最常遇到的报错就是 400 Bad Request，控制台输出的错误信息经常让人摸不着头脑。比如这种典型场景：明明按照文档发送了tool_use 请求，却得到空响应或者"error": "invalid tool specification"。后来才发现，这是因为工具调用的参数结构有严格规范，而新手最容易犯以下错误：

忘记在消息体中添加 tools 参数声明可用的工具列表
工具描述 JSON 中缺少必需的 name 或description字段
混淆了同步调用和异步调用的 endpoint

更隐蔽的问题是认证失败——虽然返回的是 200 状态码，但响应中根本没有包含预期的工具调用结果。这时候就需要检查 API 密钥是否配置正确，以及请求头中的 anthropic-version 是否匹配当前 API 版本。

sequenceDiagram
    participant Client
    participant ClaudeAPI
    Client->>ClaudeAPI: 请求携带 X -API-Key
    ClaudeAPI-->>Client: 401 Unauthorized（密钥错误）Client->>ClaudeAPI: 正确密钥 +anthropic-version
    ClaudeAPI-->>Client: 200 OK（认证通过）

维度	同步调用	异步调用
时延	高（等待完整响应）	低（先返回 acceptance）
吞吐量	受限于线程数	可批量提交
适用场景	即时交互工具	后台批处理任务
错误恢复	需手动重试	支持自动重试队列

import httpx
from pydantic import BaseModel

class ToolInput(BaseModel):
    name: str
    description: str
    parameters: dict

async def call_claude_tool():
    headers = {
        "x-api-key": "your_api_key",
        "anthropic-version": "2023-06-01",
        "content-type": "application/json"
    }

    # 工具声明（关键！）weather_tool = ToolInput(
        name="get_weather",
        description="查询城市天气",
        parameters={"type": "object", "properties": {"city": {"type": "string"}}}
    )

    # 请求体构建
    body = {
        "model": "claude-3-opus-20240229",
        "messages": [{"role": "user", "content": "上海今天天气如何？"}],
        "tools": [weather_tool.dict()],
        "temperature": 0.3  # 平衡创造性与稳定性
    }

    # 带异常处理的请求
    async with httpx.AsyncClient(timeout=30.0) as client:
        try:
            resp = await client.post(
                "https://api.anthropic.com/v1/messages",
                headers=headers,
                json=body
            )
            resp.raise_for_status()
            return resp.json()["content"]
        except httpx.HTTPStatusError as e:
            print(f"HTTP 错误: {e.response.status_code}")
            # 实现指数退避重试
            await asyncio.sleep(1)
            return await call_claude_tool()

temperature取值策略：
0.0-0.3：事实查询类工具
0.4-0.7：创意生成类工具
0.8-1.0：探索性场景
max_tokens设置：根据工具返回数据的平均长度增加 20% 缓冲

速率限制规避
使用 tenacity 库实现自适应重试
监控 X -RateLimit-Remaining 响应头

敏感数据过滤

import re

def sanitize_input(text: str) -> str:
    patterns = [r"\b\d{4}[-]?\d{4}[-]?\d{4}\b",  # 信用卡号
        r"\b\d{3}-?\d{2}-?\d{4}\b"       # SSN
    ]
    for pattern in patterns:
        text = re.sub(pattern, "[REDACTED]", text)
    return text