Responses tools 怎样串联工具结果

如果一个模型先查订单，再根据订单结果计算运费，Responses tools 的关键不是把两个函数写在同一个请求里，而是把每次工具调用都当成一条需要回传的上下文数据。模型返回 function_call 后，由应用执行本地函数，再用相同的 call_id 发送 function_call_output；模型拿到结果后，才有机会决定是否继续调用下一个工具。

官方地址：https://developers.openai.com/api/docs/guides/function-calling

下面的示例只围绕自定义函数工具展开。它不讨论 MCP、Agents SDK 或 Chat Completions，重点是把“模型决定调用什么”和“应用真正执行什么”分开。

先分清三种数据：工具声明、工具调用和工具结果

我第一次接工具链时，最容易混淆的是 tools、function_call 和 function_call_output。三者职责不同：

• tools 是请求里交给模型看的能力说明，包含函数名、用途和参数模式。
• function_call 是模型返回的调用意图，至少要关注 call_id、name 和 JSON 字符串形式的 arguments。
• function_call_output 是应用执行后的回传项，必须用对应的 call_id 让模型知道这份结果属于哪个调用。

因此，工具声明不是执行器，模型返回调用也不是函数返回值。应用需要在两者之间放一个本地分发器，负责白名单、参数解析、异常转换和结果序列化。

把 function_call 交给本地分发器

工具函数可以是查数据库、读取业务服务或计算规则，但分发器只应调用明确注册过的名称。下面用两个普通函数表示“查订单”和“计算运费”，代码展示的是 Responses API 的回路形状，函数内部数据可以替换成自己的业务实现。

import json
from openai import OpenAI

client = OpenAI()

def get_order(order_id: str) -> dict:
    # 示例只返回可序列化的订单摘要，真实项目应在这里访问受控的数据层。
    return {"order_id": order_id, "weight_kg": 2.4, "destination": "杭州"}

def quote_shipping(weight_kg: float, destination: str) -> dict:
    # 把业务计算结果整理成稳定字段，便于模型继续理解或展示。
    price = 12.0 if destination == "杭州" else 18.0
    return {"destination": destination, "weight_kg": weight_kg, "price": price}

tool_registry = {
    "get_order": get_order,
    "quote_shipping": quote_shipping,
}

tools = [
    {
        "type": "function",
        "name": "get_order",
        "description": "读取订单摘要，返回重量和目的地。",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
            "additionalProperties": False,
        },
        "strict": True,
    },
    {
        "type": "function",
        "name": "quote_shipping",
        "description": "根据重量和目的地估算运费。",
        "parameters": {
            "type": "object",
            "properties": {
                "weight_kg": {"type": "number"},
                "destination": {"type": "string"},
            },
            "required": ["weight_kg", "destination"],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

response = client.responses.create(
    model="gpt-5",
    tools=tools,
    input="查询订单 A100 的运费，并说明计算依据。",
)

for item in response.output:
    if item.type != "function_call":
        continue
    # 只允许注册表中的函数，避免把模型生成的名字当成任意代码执行。
    handler = tool_registry.get(item.name)
    if handler is None:
        raise ValueError(f"未知工具：{item.name}")
    arguments = json.loads(item.arguments)
    result = handler(**arguments)
    print(item.call_id, item.name, result)

这段代码的重点不是两个业务函数，而是 item.name 只从注册表取处理器，item.arguments 先解析再传参。生产代码还应按自己的权限边界校验参数，并将内部异常转换成可供模型理解的错误对象。

用 function_call_output 接回同一轮上下文

上一个循环只完成了“拿到调用并执行”。要让模型继续思考，必须把原始输出项和工具结果一起放回下一次 Responses 请求。最容易出错的地方是只发送文本结果，却丢掉调用项；这样模型无法把结果和原调用对应起来。

# 继续上面的 response，收集每个调用对应的回传项。
tool_outputs = []
for item in response.output:
    if item.type != "function_call":
        continue
    try:
        # 用 call_id 建立稳定映射，输出保持为 JSON 字符串。
        handler = tool_registry[item.name]
        result = handler(**json.loads(item.arguments))
        output = json.dumps(result, ensure_ascii=False)
    except Exception as exc:
        # 把失败变成结构化文本，避免整个工具循环静默中断。
        output = json.dumps({"error": str(exc)}, ensure_ascii=False)
    tool_outputs.append({
        "type": "function_call_output",
        "call_id": item.call_id,
        "output": output,
    })

next_response = client.responses.create(
    model="gpt-5",
    tools=tools,
    # 把模型刚才的输出和应用产生的工具结果放在同一轮输入中。
    input=[*response.output, *tool_outputs],
)
print(next_response.output_text)

如果第一个工具的结果已经包含第二个工具所需字段，模型就可能在 next_response.output 中再次返回 function_call。应用重复“读取调用—执行—回传”的小循环，直到输出中出现普通消息，或达到自己设置的最大轮数。

多工具、错误和终止条件怎么处理

串联并不等于所有工具都必须按顺序执行。判断依据是参数是否依赖前一个结果：

• 两个工具互不依赖时，可以按返回的多个 function_call 分别执行，再一次性回传多个 function_call_output。
• 第二个工具需要第一个工具的字段时，先回传第一个结果，再让模型生成下一次调用，避免应用自行猜测参数。
• 任何失败都要回传对应 call_id 的错误信息，并限制最大循环轮数；不要让模型在错误工具上无限重试。

我会额外记录每轮的 call_id、工具名、耗时和结果状态，但不会把访问令牌、数据库连接串或内部堆栈直接放进 output。对用户展示时，再把模型的最终消息和内部执行日志分开。

一张表记住这条回路

一句话概括：Responses tools 负责提出调用意图，应用负责执行和回传，模型再依据回传结果决定下一步。只要保留调用项、结果项和 call_id 的对应关系，多个工具就能在同一个上下文中自然串起来。

相关问题

工具结果一定要是字符串吗？回传项的 output 可以按接口要求组织为文本或内容数组；工程上常把结构化对象序列化为 JSON 字符串，字段更稳定。

为什么不直接在应用里调用第二个工具？如果第二个工具参数必须由模型根据第一份结果选择，交给模型生成下一次 function_call 更清晰，也保留了工具选择的上下文。

工具循环什么时候停止？通常在没有新的 function_call、得到普通消息、达到最大轮数或发生不可恢复错误时停止。