Claude 工具调用与 Computer Use
本文档详细说明通过 UniGateway 使用 Anthropic Messages API(POST /v1/messages)进行工具调用(Tool Use / Function Calling)与计算机使用(Computer Use)的完整规范,涵盖参数定义、代际演进、选择策略及多轮执行循环。
章节导引
本篇为 Anthropic Messages API 参考的第 5 章节:
- Messages 概述与快速开始
- 请求参数与消息格式
- 扩展推理 Thinking
- 提示词缓存 Prompt Caching
- 工具调用与 Computer Use(当前章节)
- 响应、流式与错误处理
工具调用生命周期
在 Anthropic Messages API 中,Agent 借助工具调用的标准循环包含以下阶段:
- 客户端发起请求:在
tools中声明可用工具,并提交用户指令; - 模型决定调用:模型分析后暂停生成,返回
stop_reason: "tool_use",并在content中输出包含tool_use_id与参数 JSON 的type: "tool_use"块; - 客户端本地执行:客户端根据工具名称与参数执行真实业务逻辑(如查询数据库、调用三方 API、截取屏幕等);
- 回传执行结果:客户端将执行结果封装为
type: "tool_result"块以role: "user"消息回传给模型; - 模型综合回答:模型接收执行结果,生成最终自然语言答复或发起下一轮工具调用。
工具定义(tools)
在请求体中传入 tools 数组以注册工具。支持客户端自定义函数工具与官方内置能力:
1. 自定义客户端工具
使用标准的 JSON Schema 声明工具的入参约束:
{
"name": "get_stock_quote",
"description": "获取指定股票代码的实时行情与成交量",
"input_schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string",
"description": "股票代码,如 AAPL, TSLA, 600519.SH"
},
"include_dividends": {
"type": "boolean",
"description": "是否包含分红除权信息"
}
},
"required": ["ticker"]
}
}
2. Computer Use 工具代际对照表
Claude 模型原生支持直接控制操作系统屏幕、键盘与鼠标。随着模型迭代,官方的 Computer Use 工具定义版本也在不断演进:
| 模型系列 | 官方规范要求的 Computer 工具类型 | UniGateway 跨平台适配规则 |
|---|---|---|
| Sonnet / Haiku 4.5 | computer_20250124 | 保持原生透传;若上游仅支持新版工具集,网关自动迁移结构。 |
| Opus 4.5 / Claude 4.6 | computer_20251124 | 标准支持。 |
| Claude 4.7 – 4.8 系列 | Opus 4.7: computer_20251124<br>Opus 4.8: computer_toolset_20260801 与 computer_20251124 | 双格式支持;出站时对齐至目标平台最高可用版本。 |
| Claude 5.0 – 5.1 系列 | computer_toolset_20260801(GA)与 computer_20251124 | 生产级正式版本支持。 |
| Claude 5.5 及同档系列 | computer_toolset_20260801(全平台 GA);AWS Bedrock 额外支持 computer_20251124 | 网关根据具体上游通道类型(Direct / Bedrock / Vertex)自动选择最匹配的工具声明。 |
工具选择策略(tool_choice)
开发者可通过 tool_choice 参数显式控制模型的工具调用偏好:
tool_choice 取值 | 行为说明 |
|---|---|
{"type": "auto"} | 默认行为。模型根据对话上下文自主决定是调用工具还是直接回复文本。 |
{"type": "any"} | 强制模型必须调用 tools 列表中的至少一个工具,不可直接回复纯文本。 |
{"type": "tool", "name": "get_stock_quote"} | 强制模型必须调用指定名称的工具。 |
{"type": "none"} | 显式禁止模型调用任何工具,必须直接返回自然语言文本。 |
工具选择与 Extended Thinking 的交互冲突与解决
在 Anthropic 官方规范中,推理模型对强制工具选择存在严格的代际约束:
- Claude 4.5 手动思考模式:当启用手动
thinking(type: "enabled")时,官方规范禁止使用any或tool强制工具选择,否则返回 400; - Claude 5.5 前沿模型约束:在 Claude Opus 5.5 与 Claude Sonnet 5.5 上,官方设计理念强调由模型的内部自适应思考自主推断是否需要调用工具,因此仅允许
auto与none,不支持强行传入any或tool(而 Haiku 5.5 则保留了强选支持); - UniGateway 自动规范化:当客户端向不支持强制工具调用的模型发送了
any或tool时,网关在出站时安全降级为auto并引导模型优先调用目标工具,在响应头x-gateway-modified-tool-choice: forced_to_auto中进行审计记录,防止调用直接报错。
多轮工具结果回传与多模态
当模型返回工具调用请求时,响应结构如下:
{
"id": "msg_01A...",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "正在为您查询苹果公司(AAPL)的最新股价..."
},
{
"type": "tool_use",
"id": "toolu_01B...",
"name": "get_stock_quote",
"input": {
"ticker": "AAPL"
}
}
],
"stop_reason": "tool_use"
}
客户端执行完成后,在下一轮请求中回传 tool_result 块:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01B...",
"content": "{\"price\": 235.50, \"currency\": \"USD\", \"change_pct\": \"+1.2%\"}"
}
]
}
错误处理与多模态返回
- 执行出错:若工具调用遇到异常,可在
tool_result中设置"is_error": true,模型将感知执行失败并尝试修正参数或向用户解释原因; - 多模态结果(如截图):在 Computer Use 或图表工具中,
content可传入图片块(type: "image"),模型将直接分析回传的图片数据; - 思考签名全流程保持(Thought Signature Preservation):在启用 Extended Thinking 的模型上,模型生成
tool_use块时会附带思考签名(signature);客户端在后续轮次回传assistant的tool_use与thinking块时必须完整保留该签名。在跨云桥接或跨协议转换场景下,网关双向保障签名的透传与还原,避免上游因签名缺失或篡改报错。
代码示例
Python SDK(完整工具调用循环)
import os
import json
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ.get("UNIGATEWAY_API_KEY"),
base_url="https://api.unigateway.ai",
)
# 1. 声明工具
tools = [
{
"name": "get_weather",
"description": "获取指定城市的实时天气",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称,如北京、上海"}
},
"required": ["city"],
},
}
]
messages = [{"role": "user", "content": "今天北京天气怎么样?"}]
# 2. 发起请求
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
# 3. 判断是否需要执行工具
if response.stop_reason == "tool_use":
tool_use_block = next(b for b in response.content if b.type == "tool_use")
print(f"模型发起工具调用: {tool_use_block.name}, 参数: {tool_use_block.input}")
# 模拟本地执行
tool_result_data = {"city": "北京", "weather": "晴朗", "temp": "22°C"}
# 4. 组装下一轮消息回传
messages.append({"role": "assistant", "content": response.content})
messages.append({
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use_block.id,
"content": json.dumps(tool_result_data, ensure_ascii=False),
}
],
})
# 5. 获取最终回答
final_response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
print("最终回答:\n", final_response.content[0].text)
下一步
- 掌握 SSE 流式事件推送与响应头审计:响应、流式与错误处理
- 为长工具列表配置缓存以降低开销:提示词缓存 Prompt Caching
- 探索模型的深度思维链推理:扩展推理 Thinking