OpenAI Responses API 如何让工具调用返回结构化结果

如果你希望 OpenAI Responses API 的工具调用稳定落到业务代码里，关键不是把模型输出强行截成 JSON，而是把边界分成两层：工具定义中的 strict: true 约束模型传入的参数；应用执行完工具后，再通过 function_call_output 回传自己生成的 JSON 字符串。strict 不会替你校验本地函数的返回值。

一、先把工具参数约束在 JSON Schema 内

先以订单查询为例。工具只接受 order_id 和可选的 include_items，不要把数据库连接、鉴权令牌或内部字段暴露给模型。Responses API 的 function 工具使用顶层 name、description、parameters 和 strict，不要直接照搬旧版 Chat Completions 的嵌套 function 外壳。

严格模式下，每个对象都应设置 additionalProperties: false，properties 里的字段都列入 required。真正的“可选”可以把类型写成包含 null 的联合类型，让字段存在但值允许为空。

import OpenAI from "openai";

const openai = new OpenAI();

const tools = [{
  type: "function",
  name: "lookup_order",
  description: "按订单号查询订单摘要",
  parameters: {
    type: "object",
    properties: {
      order_id: { type: "string", description: "业务订单号" },
      include_items: {
        type: ["boolean", "null"],
        description: "是否带上商品明细"
      }
    },
    required: ["order_id", "include_items"],
    additionalProperties: false
  },
  strict: true
}];

// 先让模型根据 schema 生成可路由的工具参数。
const response = await openai.responses.create({
  model: "gpt-6-astra",
  input: "查询订单 A-10086，并带上商品明细",
  tools
});

二、从 response.output 中找到真正的 function_call

不要假设 response.output[0] 一定是文本，也不要只读取一个固定下标。Responses API 的输出是多个项目组成的数组，工具调用项目的 type 是 function_call，参数位于 JSON 字符串 arguments 中。先保存整组 response.output，下一轮还要把它和工具结果一起传回。

下面的本地函数只模拟业务查询，生产环境应在函数内部做订单权限校验、超时控制和错误映射。模型生成的参数符合 schema，并不意味着它已经获得了访问数据库的权限。

function lookupOrder(orderId, includeItems) {
  // 真实项目中在这里访问服务层，不把数据库细节交给模型。
  return {
    order_id: orderId,
    status: "paid",
    items: includeItems ? [{ sku: "SKU-01", quantity: 2 }] : null
  };
}

const input = [{ role: "user", content: "查询订单 A-10086，并带上商品明细" }];
let response = await openai.responses.create({ model: "gpt-6-astra", input, tools });

// 保留模型产生的 function_call，形成下一轮输入的一部分。
input.push(...response.output);
for (const item of response.output) {
  if (item.type !== "function_call") continue;

  // strict 约束参数形状，但路由仍由应用自己负责。
  const args = JSON.parse(item.arguments);
  if (item.name !== "lookup_order") throw new Error("未知工具");

  const result = lookupOrder(args.order_id, args.include_items);
  input.push({
    type: "function_call_output",
    call_id: item.call_id,
    // 工具结果由应用序列化，避免传入不可预测的对象表示。
    output: JSON.stringify(result)
  });
}

response = await openai.responses.create({
  model: "gpt-6-astra",
  instructions: "根据工具结果回答订单状态，不要编造未返回的字段。",
  input,
  tools
});

console.log(response.output_text);

三、用 function_call_output 把结果送回模型

工具闭环里最容易漏掉的是 call_id。它把模型发出的某次 function_call 和应用回传的 function_call_output 绑定起来。回传值可以是文本，但如果下游要继续做解析，建议由应用明确生成 JSON，再用 JSON.stringify 放入 output 字段。

这层 JSON 只代表你的工具结果，不代表模型最终回答已经通过 JSON Schema 校验。订单状态、商品列表等字段应由服务端决定；如果本地函数失败，可以回传可识别的错误对象，让模型向用户解释“暂时无法查询”，而不是让它猜一个状态。

四、工具参数结构化不等于最终回复结构化

可以把需要稳定的字段分成三类：

如果只关心工具参数，前面的写法已经足够。若前端还要求最终响应固定为 {"summary":"...","next_action":"..."}，则在最后一次 Responses 请求中另外配置文本格式 schema。不要把这个要求塞进工具的 parameters，否则模型得到的是“调用工具的参数协议”，不是“回答用户的协议”。

还有两个实用开关：默认让模型自行决定是否调用工具时使用 tool_choice: "auto"；只允许零次或一次调用时把 parallel_tool_calls 设为 false。涉及扣款、发货、写入等副作用操作时，应用仍应在工具函数内做幂等和权限保护。

最小检查清单

• 工具对象是否使用 Responses API 当前的顶层 function 形状？
• 每个对象是否关闭了 additionalProperties，每个属性是否出现在 required？
• 是否遍历 response.output 并按 item.type 识别调用？
• 是否原样关联 call_id，并对工具结果执行 JSON.stringify？
• 最终回复需要固定 JSON 时，是否单独配置 text.format？

相关问题

strict 为 true 后为什么请求会被拒绝？

通常是对象没有设置 additionalProperties: false，或某个属性没有进入 required。把可选字段改为允许 null，而不是从 required 删除。

function_call_output 可以直接放 JavaScript 对象吗？

建议先用 JSON.stringify 转成明确的字符串。这样工具输出的字段、数组和错误结构更容易记录、重放和继续交给模型。

工具调用成功后还要校验最终回答吗？

要。工具参数 schema 只管入参；涉及前端协议或自动化动作时，再为最终文本配置 JSON Schema，并在应用侧处理拒绝、缺字段和业务错误。