OpenAI Responses API怎么用？从请求结构到工具调用与结果回传的入门指南

使用 Responses API 时，可以把一次请求拆成三层：模型输入、模型输出，以及由业务服务执行的外部操作。模型负责理解问题和决定是否需要工具；你的服务端负责鉴权、参数校验、调用天气或数据库服务，再把执行结果交给模型继续生成最终答复。模型不会因为声明了一个工具，就自动访问任意外部系统。

一、基本请求结构

服务端通常向 Responses API 发送一个 POST 请求，请求体至少包含 model 和 input。input 可以是简单文本，也可以是包含角色和内容的消息数组；还可以使用 instructions 放置稳定的行为要求。例如，消息内容可以表达为“查询北京今天的天气”，模型据此判断是否需要调用已声明的天气工具。

除输入外，还可以按需要设置温度等模型参数，或通过 tools 声明可用工具。实际项目中不要把请求密钥放在浏览器、移动端或前端代码里，而应由服务端读取环境变量或密钥管理系统中的配置，并限制日志中对密钥、用户隐私和业务数据的输出。

二、三种常见返回结果

普通文本响应

如果问题不需要外部数据，响应中通常会包含模型生成的文本内容。业务代码应从响应对象中读取输出内容，而不是假定所有结果都只有一个固定字段。对展示给用户的文本，还应根据应用场景处理空结果、敏感内容和长度限制。

结构化输出

当程序需要稳定读取结果时，可以在请求的 text 配置中声明 JSON Schema，要求模型按照指定字段和类型返回。例如订单摘要可以定义 order_id、items、total 和 status 等字段。收到结果后，服务端仍应执行 JSON 解析、Schema 校验和业务规则校验，不能只因为模型返回了 JSON 就认为数据一定正确。

工具调用结果

启用工具后，响应可能先返回一个 function_call 项，其中包含工具名称、调用标识和参数字符串。这个结果不是天气答案，而是模型给服务端的执行请求。服务端解析参数并完成工具调用后，再提交一个与调用标识对应的 function_call_output，让模型结合工具结果生成最终文本。

三、工具调用的完整闭环

1. 定义工具：在 tools 中声明工具类型、名称、用途和 parameters Schema。参数应尽量少而明确，例如 weather 工具只接收 city 和 date。
2. 发起请求：把用户问题和工具定义一同发送给 Responses API。模型可以直接回答，也可以选择提出工具调用。
3. 校验参数：服务端解析 arguments，检查字段类型、必填项、长度和允许范围。不要直接把模型生成的字符串拼接进 SQL 或命令行。
4. 执行操作：通过服务端权限调用天气 API 或查询数据库，并设置连接超时、访问范围和结果大小限制。
5. 回传结果：将执行成功的数据序列化为清晰的字符串或 JSON，作为 function_call_output，并带上原来的 call_id，再发起后续请求。
6. 生成答复：模型根据工具结果组织面向用户的回答；如果工具失败，则回传明确的错误状态或可用替代信息，而不是伪造查询结果。

四、天气查询示例的调用顺序

用户问“北京今天会下雨吗？”第一轮请求中，服务端提供 weather 工具及其参数规则。若模型返回对 weather 的调用请求，业务代码先确认 city 为北京、date 为合法日期，再请求天气服务。成功后，服务端把“北京，降水概率 60%，最高温度……”作为工具输出回传，模型据此回答用户。

如果天气服务超时，服务端可以把失败原因整理为工具错误消息，并根据业务规则让模型说明暂时无法获取数据，或建议稍后重试。工具失败不应被包装成成功数据。数据库查询也是同样流程：模型只提出查询意图，真正的 SQL、权限、分页和脱敏规则必须由业务代码控制。

五、超时、错误与重试

API 请求和外部工具请求都应设置超时，并区分参数错误、鉴权失败、限流、网络暂时不可用和服务端错误。对于具有暂时性的网络错误，可以采用有限次数、逐步延迟的重试；参数错误不适合盲目重试。为避免重复写入，涉及订单或支付等操作时要设计幂等标识，并记录 response、call_id、工具状态和业务请求编号。

最后，建议把模型输出视为不可信输入：严格校验结构化结果，限制工具权限，过滤敏感信息，并对每一步保留可审计日志。这样，Responses API 就能被清晰地放在“模型决策”和“服务端执行”的边界上，既发挥自然语言理解能力，也保持业务系统的可控性。