⚠️ 待更新·2026-08-29核验 · 更新时间待核验 · 本文信息可能已过期，请以官方文档为准
更新时间：2026-08-29 · 核验状态：待更新 · 官方溯源待补
背景
OpenAI 用 tools + tool_calls + function 三层;Anthropic 用 tools + tool_use block + tool_result 配对;Gemini 用 function_declarations + functionCall + functionResponse。同一段 Agent 代码要跑在不同模型上,网关必须把这三套协议翻译成同一形状。
统一抽象
- 入参统一:客户端发 OpenAI 形状的
tools 描述,网关翻译成各家原生格式。
- 输出统一:把 Anthropic 的
tool_use block、Gemini 的 functionCall 都转成 OpenAI 的 tool_calls 数组。
- 多轮统一:无论哪家,第二轮的
tool 角色消息都被翻译成对应家的"工具结果"格式(Anthropic 的 tool_result,Gemini 的 functionResponse)。
- 不支持 tools 的模型降级:对
llama-3.1-8b 这类不原生支持 tools 的模型,网关可以用 prompt 注入 + JSON 解析的方式"模拟"tools 协议,代价是准确率降低。
代码示例
def openai_tools_to_anthropic(tools):
return [{
"name": t["function"]["name"],
"description": t["function"]["description"],
"input_schema": t["function"]["parameters"],
} for t in tools]
def anthropic_response_to_openai(resp):
tool_calls = []
for i, block in enumerate(resp["content"]):
if block["type"] == "tool_use":
tool_calls.append({
"id": block["id"],
"type": "function",
"function": {
"name": block["name"],
"arguments": json.dumps(block["input"]),
},
})
return {
"role": "assistant",
"content": None,
"tool_calls": tool_calls,
}
def openai_tool_result_to_anthropic(tool_call_id, output):
return {
"role": "user",
"content": [{"type": "tool_result",
"tool_use_id": tool_call_id,
"content": output}],
}
Schema 演进与版本控制
tools 协议会演进:某个工具的参数从 {"url": string} 变成 {"url": string, "method": string}。客户端 SDK 升级了,但模型可能还在用旧 schema 描述。网关要做schema 版本协商:每个 tool 带 schema_version,网关在请求里看到客户端声明的版本,自动选择对应版本的 schema 注入到 tools 字段。同时维护版本兼容表,旧版本工具调用在新 schema 下仍能执行,通过默认值填充新增字段。
最佳实践
- Schema 校验:用 JSON Schema 在网关入口校验
tools 定义,避免坏 schema 浪费上游调用。
- parallel tool calls:OpenAI 与 Anthropic 都支持并行调用,但 Gemini 单次只一个,网关要按最严格语义限制。
- 错误透传:工具执行失败要回
{"error": "..."} 给模型,而不是直接 raise,让模型有机会自己重试或换工具。
- 回退提示词模板:对不支持 tools 的模型,prompt 模板要把工具列表序列化进 system message,并把模型回复解析成 JSON。
- 工具黑名单:为每个 client_id 维护禁用工具列表,防止用户调危险工具(如删除文件)。
统一 tools 协议让 Agent 框架写一次跑遍所有模型。
⚠️ Pending Update · 2026-08-29 Verification · Content may be outdated, please refer to official docs
Updated: 2026-08-29 · Status: Pending Verification
Background
OpenAI uses tools + tool_calls + function as three layers; Anthropic uses tools + tool_use block + tool_result pairing; Gemini uses function_declarations + functionCall + functionResponse. For the same agent code to run across models, the gateway must translate all three into one shape.
Unified Abstraction
- Input normalization: the client sends
tools in OpenAI shape; the gateway translates to each vendor's native format.
- Output normalization: Anthropic's
tool_use block and Gemini's functionCall both become OpenAI's tool_calls array.
- Multi-turn normalization: regardless of vendor, the second-turn
tool role message is translated into the corresponding vendor's "tool result" format (Anthropic tool_result, Gemini functionResponse).
- Degradation for tool-less models: models like
llama-3.1-8b that lack native tools can be "simulated" by the gateway via prompt injection + JSON parsing, at the cost of lower accuracy.
Code Example
def openai_tools_to_anthropic(tools):
return [{
"name": t["function"]["name"],
"description": t["function"]["description"],
"input_schema": t["function"]["parameters"],
} for t in tools]
def anthropic_response_to_openai(resp):
tool_calls = []
for i, block in enumerate(resp["content"]):
if block["type"] == "tool_use":
tool_calls.append({
"id": block["id"],
"type": "function",
"function": {
"name": block["name"],
"arguments": json.dumps(block["input"]),
},
})
return {
"role": "assistant",
"content": None,
"tool_calls": tool_calls,
}
def openai_tool_result_to_anthropic(tool_call_id, output):
return {
"role": "user",
"content": [{"type": "tool_result",
"tool_use_id": tool_call_id,
"content": output}],
}
Schema Evolution and Versioning
The tools protocol evolves: a tool's parameters shift from {"url": string} to {"url": string, "method": string}. The client SDK upgrades, but the model may still describe the old schema. The gateway needs schema version negotiation: each tool carries a schema_version, and when the gateway sees the client-declared version in the request, it auto-selects the matching schema to inject into the tools field. It also maintains a version compatibility table so old-version tool calls still execute under the new schema by filling new fields with defaults.
Best Practices
- Schema validation: validate
tools definitions at the gateway ingress with JSON Schema so bad schemas never waste an upstream call.
- Parallel tool calls: both OpenAI and Anthropic support parallel calls, but Gemini allows only one at a time — the gateway must cap to the strictest semantics.
- Error pass-through: when a tool execution fails, return
{"error": "..."} to the model rather than raising; the model then gets a chance to retry or pick another tool.
- Fallback prompt template: for models without tools support, serialize the tool list into the system message and parse the model's reply as JSON.
- Tool blocklist: maintain a per-
client_id disabled-tool list to block dangerous tools (e.g. file deletion).
Unifying the tools protocol lets an agent framework be written once and run across every model.