responses api的格式

A
Admin

如果你已经在研究 Codex 架构，那么 Responses API 可以理解为 OpenAI 新一代的 Agent API。

它的设计目标就是：

让模型、工具调用、推理过程、多轮上下文管理统一到一个接口里。

相比以前的 Chat Completions：

messages
   ↓
model
   ↓
text

Responses API 更像：

input
   ↓
model
   ↓
reasoning
   ↓
tool call
   ↓
tool result
   ↓
reasoning
   ↓
final answer

这其实就是 Codex 内部 Agent Loop 所依赖的能力。

传统 Chat Completion

以前调用大概是：

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "北京天气"
    }
  ]
}

返回：

{
  "choices": [
    {
      "message": {
        "content": "..."
      }
    }
  ]
}

模型主要负责生成文本。

Responses API

结构变成：

{
  "model": "gpt-5",
  "input": "北京天气"
}

返回内容不再只有文本。

而是一个 Output 数组：

{
  "output": [
    {
      "type": "reasoning",
      ...
    },
    {
      "type": "function_call",
      ...
    }
  ]
}

概念上类似：

Response
 ├─ reasoning
 ├─ function_call
 ├─ message
 └─ ...

Tool 调用示例

假设注册了：

{
  "name": "get_weather",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string"
      }
    }
  }
}

用户：

东京天气

模型可能返回：

{
  "type": "function_call",
  "name": "get_weather",
  "arguments": {
    "city": "Tokyo"
  }
}

你的程序执行：

get_weather("Tokyo")

得到：

{
  "temperature": 27
}

再把结果送回模型。

Agent Loop 长什么样

这是最关键的部分。

Codex、Claude Code、OpenHands 本质上都在干类似事情：

while True:

    response = client.responses.create(...)

    if response.contains_tool_call():

        result = execute_tool()

        response = client.responses.create(
            previous_response_id=response.id,
            input=result
        )

    else:
        break

流程：

User
 ↓
Response API
 ↓
Tool Call
 ↓
Tool Result
 ↓
Response API
 ↓
Final Answer

previous_response_id

这是 Responses API 非常重要的设计。

以前：

messages = [
  ...
]

每轮都要传整个历史。

现在：

response = client.responses.create(...)

返回：

{
  "id": "resp_abc123"
}

下一轮：

client.responses.create(
    previous_response_id="resp_abc123",
    input=tool_result
)

OpenAI 后端自动关联上下文。

所以：

response1
      ↓
response2
      ↓
response3

形成一棵执行链。

这也是 Codex 能长时间执行任务的重要基础。

对你做数据分析 Agent意味着什么

假设你有：

query_db(sql)

Tool Schema：

{
  "name": "query_db"
}

用户：

上个月收入多少？

Responses API 返回：

{
  "type": "function_call",
  "name": "query_db",
  "arguments": {
    "sql": "..."
  }
}

执行后：

{
  "rows": [
    {
      "revenue": 1000000
    }
  ]
}

再送回：

client.responses.create(
    previous_response_id=response.id,
    input=tool_result
)

模型最终输出：

上个月收入为100万元。

从 Agent 架构角度理解

可以把 Responses API 看成：

Chat Completion
+
Function Calling
+
Conversation State
+
Reasoning Items
+
Tool Loop Support

即：

Responses API
    =
    Agent Runtime API

这也是为什么你看 Codex 源码时，会发现很多逻辑不再围绕：

messages[]

展开，而是围绕：

response
tool_call
tool_result
previous_response_id

展开。

因为 OpenAI 近两年的方向就是把 Agent 所需的基础能力下沉到 Responses API，而不是让每个开发者自己拼装一个 ReAct 框架。

← Back to all posts
responses api的格式 | JBLOG