Responses API 的结构化输出如何保留工具错误字段

Responses API 里，结构化输出并不会自动替工具结果“保留错误字段”。真正可靠的做法是分两层处理：工具执行器先返回固定的 JSON 错误信封，再通过 function_call_output 回传；最后一轮响应再用 text.format 的 JSON Schema 约束模型输出。这样，error.code、error.message 和 error.retryable 才有稳定的位置。

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

如果只在最终响应上配置 Structured Outputs，却让工具失败时返回一段自然语言，模型可以理解这段话，但应用无法保证错误字段完整、可解析、可审计。工具信封和最终 schema 必须同时存在。

症状：工具失败了，最终 JSON 却没有错误字段

这类问题通常出现在一个看似合理的链路里：函数调用成功时返回订单或库存对象，失败时直接抛异常；应用捕获异常后只把“查询失败”拼成字符串，再让模型继续生成结构化结果。最后的 JSON 可能仍然合法，但 error.code 为空，甚至把失败说成了“没有数据”。

影响不只是展示问题。前端无法区分“订单不存在”和“上游超时”，重试策略、告警分级和客服提示都会失去依据。排查时先把时间线拆开：模型发出 function_call，应用执行函数，应用提交 function_call_output，模型生成最终 message。错误字段是在工具执行阶段丢的，还是在最终映射阶段丢的，结论完全不同。

根因：两个 schema 管的是两段不同的数据

Responses API 的函数调用项目包含两份容易混淆的约束。函数工具的参数 schema 约束模型发给应用的调用参数；text.format 的 JSON Schema 约束模型最后返回给用户的文本。工具执行器返回的内容由应用自己决定，API 不会替你把它校验成最终 schema。

因此，工具错误必须先有自己的信封。成功和失败都保留同一层级，失败时不要只返回字符串：

修复：先回传稳定的工具错误信封

下面的示例用订单查询模拟工具失败场景。关键点有两个：用 call_id 把结果对应到本次调用；用 JSON 字符串承载结构化错误。代码中的异常也被转换成可识别的 TOOL_EXECUTION_FAILED，不会把堆栈直接交给模型。

import OpenAI from "openai";

const client = new OpenAI();

function lookupOrder(orderId) {
  // 业务层统一返回信封，避免失败时只剩一段自然语言。
  if (orderId === "missing") {
    return {
      ok: false,
      data: null,
      error: { code: "ORDER_NOT_FOUND", message: "订单不存在", retryable: false }
    };
  }
  return {
    ok: true,
    data: { order_id: orderId, status: "ready" },
    error: { code: null, message: null, retryable: false }
  };
}

const tool = {
  type: "function",
  name: "lookup_order",
  description: "查询订单状态，失败也返回结构化错误信封",
  strict: true,
  parameters: {
    type: "object",
    properties: { order_id: { type: "string" } },
    required: ["order_id"],
    additionalProperties: false
  }
};

const response = await client.responses.create({
  model: "gpt-5",
  input: "查询订单 missing，并说明是否可以重试",
  tools: [tool]
});

const originalResults = new Map();
const nextInput = [...response.output];
for (const call of response.output) {
  if (call.type !== "function_call") continue;
  let result;
  try {
    const args = JSON.parse(call.arguments);
    result = lookupOrder(args.order_id);
  } catch (error) {
    // 不回传堆栈；用稳定错误码让最终 schema 能继续工作。
    result = { ok: false, data: null, error: {
      code: "TOOL_EXECUTION_FAILED", message: "工具执行失败", retryable: true
    }};
  }
  originalResults.set(call.call_id, result);
  nextInput.push({
    type: "function_call_output",
    call_id: call.call_id,
    output: JSON.stringify(result)
  });
}

让最终结构化输出保留错误字段

第二轮请求把工具结果送回模型，同时给最终消息设置严格 schema。成功和失败都要求出现 status、data、error 和 call_id；其中 data 和错误字段根据状态允许为空。这样，业务层只需要解析一个固定形状，不必猜测模型会不会省略失败分支。

const finalResponse = await client.responses.create({
  model: "gpt-5",
  input: nextInput,
  text: {
    format: {
      type: "json_schema",
      name: "tool_result",
      strict: true,
      schema: {
        type: "object",
        properties: {
          call_id: { type: "string" },
          status: { type: "string", enum: ["ok", "error"] },
          data: { type: ["object", "null"] },
          error: {
            type: ["object", "null"],
            properties: {
              code: { type: ["string", "null"] },
              message: { type: ["string", "null"] },
              retryable: { type: "boolean" }
            },
            required: ["code", "message", "retryable"],
            additionalProperties: false
          }
        },
        required: ["call_id", "status", "data", "error"],
        additionalProperties: false
      }
    }
  }
});

const structured = JSON.parse(finalResponse.output_text);
const original = originalResults.get(structured.call_id);
// 业务决定是否采用模型解释；原始错误用于审计和重试判断。
if (original?.error?.code !== structured.error?.code) {
  throw new Error("工具错误字段在模型映射后发生变化");
}

复查：不要只看 JSON 能否解析

JSON.parse 成功只能证明格式合法，不能证明错误字段没有被改写。至少保存 call_id、原始信封和最终响应三份关联数据，再做下面的复查：错误码必须一致；retryable 必须来自工具策略，而不是模型自行推断；工具失败时 data 应为空，避免旧数据和新错误混在一起。

• 字段缺失：检查最终 schema 的 required，严格模式下不要把失败字段设计成可省略。
• 字段被改写：以工具保存的原始信封为准，模型只负责解释和组织展示。
• 多工具并行：遍历全部 function_call，每一条结果都必须用自己的 call_id 回传，不能只处理第一条。

常见问题

工具失败时能直接抛异常让 Responses API 处理吗？

不建议。异常应在应用侧转换成可序列化的错误信封，再作为 function_call_output 传回；否则模型和业务层都拿不到稳定错误码。

开启 strict 后，工具返回值也会自动符合 schema 吗？

不会。strict 主要约束函数调用参数；工具返回值仍由应用生成，最终消息的 text.format 只约束模型输出。

为什么还要保存原始工具结果？

因为最终响应可能是模型对工具结果的解释。保留原始信封，才能审计字段是否丢失，并在重试或回放时避免依赖模型记忆。