open-responses

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Open Responses

Open Responses is an open-source specification defining a unified HTTP protocol for multi-provider LLM interactions. It standardizes how clients and servers communicate — messages, tool calls, streaming, multimodal inputs, reasoning — so that code written against one provider works with any compliant provider.

This is the protocol standard itself, not any specific SDK. Open Responses is provider-agnostic. Any LLM provider (OpenAI, Anthropic, Gemini, Databricks, Hugging Face, Ollama, etc.) can implement a compliant API.

Stateless by default, stateful where needed. The core protocol does not require server-side session persistence. Multi-turn conversations can be threaded via
previous_response_id
, which instructs the server to reconstruct context from prior responses. However, providers may offer stateful features (e.g., server-side storage, conversation objects) as extensions. The spec notes that item states "do not necessarily mean they are stateful in the sense of being persisted to disk or stored long-term."

Open Responses是一个开源规范，定义了用于多提供商LLM交互的统一HTTP协议。它标准化了客户端与服务器之间的通信方式——包括消息、工具调用、流式传输、多模态输入、推理等——使得针对某一提供商编写的代码可以兼容任何符合该标准的提供商。

注意：这是协议标准本身，而非特定SDK。 Open Responses是提供商无关的。任何LLM提供商（OpenAI、Anthropic、Gemini、Databricks、Hugging Face、Ollama等）都可以实现符合该标准的API。

默认无状态，按需支持有状态。 核心协议不需要服务器端会话持久化。多轮对话可通过
previous_response_id
进行串联，该参数指示服务器从先前的响应中重建上下文。不过，提供商可作为扩展提供有状态功能（如服务器端存储、对话对象）。规范指出，项的状态“不一定意味着它们会被持久化到磁盘或长期存储”。

Design Principles

设计原则

Multi-provider compatibility — one schema, any provider
Stateless-first protocol — context reconstruction via
```
previous_response_id
```
; providers may optionally offer persistence
Polymorphic items — all model outputs share a common item structure discriminated by
```
type
```
Semantic streaming — SSE events map directly to state machine transitions
Extensible without fragmentation — vendor-prefixed extensions prevent namespace collisions

Specification: https://www.openresponses.org/specification

多提供商兼容性 —— 一套 schema，适配所有提供商
无状态优先协议 —— 通过
```
previous_response_id
```
重建上下文；提供商可选择性提供持久化功能
多态项 —— 所有模型输出共享一个通用的项结构，通过
```
type
```
字段区分类型
语义流式传输 —— SSE事件直接映射到状态机转换
可扩展且无碎片化 —— 厂商前缀的扩展可避免命名空间冲突

规范地址： https://www.openresponses.org/specification

Reference Files

参考文件

For detailed schemas, JSON examples, and complete event catalogs, load the appropriate reference file:

File	Contents	When to Load
`references/protocol-and-items.md`	HTTP protocol, item types, content types, control parameters, error handling	Implementing or debugging request/response structure
`references/state-machines-and-streaming.md`	State machine diagrams, streaming event catalog, complete SSE sequences for text and tool use	Implementing or debugging streaming, state transitions
`references/extensions.md`	Custom items, custom events, schema extensions, governance path	Extending the spec with provider-specific features

To search references for specific topics: grep for

function_call

streaming

tool_choice

previous_response_id

vendor:

, or other keywords.

如需详细的schema、JSON示例和完整事件目录，请加载相应的参考文件：

文件	内容	加载场景
`references/protocol-and-items.md`	HTTP协议、项类型、内容类型、控制参数、错误处理	实现或调试请求/响应结构
`references/state-machines-and-streaming.md`	状态机图、流式事件目录、文本和工具使用的完整SSE序列	实现或调试流式传输、状态转换
`references/extensions.md`	自定义项、自定义事件、schema扩展、治理路径	通过提供商特定功能扩展规范

如需在参考文件中搜索特定主题：可使用grep查找

function_call

、

streaming

、

tool_choice

、

previous_response_id

、

vendor:

或其他关键词。

Core Concepts

核心概念

Endpoint and Transport

端点与传输

All requests go to

POST /v1/responses

with

Authorization: Bearer <token>

and

Content-Type: application/json

. Non-streaming responses return JSON. Streaming responses use SSE (

text/event-stream

) terminated by

data: [DONE]

所有请求都发送至

POST /v1/responses

，需携带

Authorization: Bearer <token>

和

Content-Type: application/json

头。非流式响应返回JSON格式。流式响应使用SSE（

text/event-stream

），并以

data: [DONE]

结束。

Items

项

Items are polymorphic atomic units discriminated by

type

. Output items (those emitted by the model in a response) must include

id

type

, and

status

fields. Core output types:

message

function_call

reasoning

. Providers extend with vendor-prefixed types (e.g.,

acme:web_search_call

Input items (those sent by the client in a request) have different requirements per type. Content types like

input_text

input_image

, and

input_file

do not carry

id

status

function_call_output

items require

call_id

and

output

but treat

id

and

status

as optional.

Message roles:

user

assistant

system

developer

. The

system

role is distinct from the

instructions

parameter — it is an inline message item in the input array. The

developer

role is a separate role that providers may handle differently from

system

项是通过

type

字段区分类型的多态原子单元。输出项（模型在响应中生成的项）必须包含

id

、

type

和

status

字段。核心输出类型包括：

message

、

function_call

、

reasoning

。提供商可使用厂商前缀扩展类型（如

acme:web_search_call

）。

输入项（客户端在请求中发送的项）的要求因类型而异。

input_text

、

input_image

、

input_file

等内容类型不需要携带

id

或

status

。

function_call_output

项需要

call_id

和

output

字段，但

id

和

status

为可选。

消息角色：

user

、

assistant

、

system

、

developer

。

system

角色与

instructions

参数不同——它是输入数组中的内联消息项。

developer

角色是一个独立角色，提供商可能会以不同于

system

的方式处理它。

State Machines and Event Emission

状态机与事件触发

The response and item lifecycles are both finite state machines. Each state constrains which events can be emitted.

响应和项的生命周期均为有限状态机。每个状态会限制可触发的事件类型。

Response Lifecycle — Events Emitted Per State

响应生命周期——各状态下触发的事件

mermaid

stateDiagram-v2
    [*] --> created : response.created
    created --> queued : response.queued
    queued --> in_progress : response.in_progress

    state in_progress {
        direction LR
        note right of in_progress
            Events emittable while in_progress:
            ─────────────────────────────────
            response.output_item.added
            response.content_part.added
            response.output_text.delta
            response.output_text.done
            response.function_call_arguments.delta
            response.function_call_arguments.done
            response.reasoning_summary_text.delta
            response.reasoning_summary_text.done
            response.content_part.done
            response.output_item.done
            vendor:custom_event

            All delta events carry: sequence_number,
            output_index, item_id
            Content-level events also carry: content_index
        end note
    }

    in_progress --> completed : response.completed
    in_progress --> incomplete : response.incomplete\n(item hit token budget)
    in_progress --> failed : response.failed
    completed --> [*]
    incomplete --> [*]
    failed --> [*]

Note: If any item ends in
incomplete
status, the containing response MUST also be
incomplete
.

mermaid

stateDiagram-v2
    [*] --> created : response.created
    created --> queued : response.queued
    queued --> in_progress : response.in_progress

    state in_progress {
        direction LR
        note right of in_progress
            Events emittable while in_progress:
            ─────────────────────────────────
            response.output_item.added
            response.content_part.added
            response.output_text.delta
            response.output_text.done
            response.function_call_arguments.delta
            response.function_call_arguments.done
            response.reasoning_summary_text.delta
            response.reasoning_summary_text.done
            response.content_part.done
            response.output_item.done
            vendor:custom_event

            All delta events carry: sequence_number,
            output_index, item_id
            Content-level events also carry: content_index
        end note
    }

    in_progress --> completed : response.completed
    in_progress --> incomplete : response.incomplete\n(item hit token budget)
    in_progress --> failed : response.failed
    completed --> [*]
    incomplete --> [*]
    failed --> [*]

注意： 如果任何项的状态为
incomplete
，则包含该项的响应也必须为
incomplete
状态。

Item Lifecycle — Events Emitted Per State

项生命周期——各状态下触发的事件

mermaid

stateDiagram-v2
    [*] --> in_progress : response.output_item.added

    state in_progress {
        direction LR
        note right of in_progress
            Events emittable while item is in_progress:
            ──────────────────────────────────────────
            Message items:
              response.content_part.added
              response.output_text.delta  (repeated)
              response.output_text.done
              response.content_part.done

            Function call items:
              response.function_call_arguments.delta  (repeated)
              response.function_call_arguments.done

            Reasoning items:
              response.reasoning_summary_text.delta  (repeated)
              response.reasoning_summary_text.done
        end note
    }

    in_progress --> completed : response.output_item.done
    in_progress --> incomplete : response.output_item.done
    completed --> [*]
    incomplete --> [*]

    note right of completed : Terminal — no further deltas
    note right of incomplete : Terminal — token budget exhausted

mermaid

stateDiagram-v2
    [*] --> in_progress : response.output_item.added

    state in_progress {
        direction LR
        note right of in_progress
            Events emittable while item is in_progress:
            ──────────────────────────────────────────
            Message items:
              response.content_part.added
              response.output_text.delta  (repeated)
              response.output_text.done
              response.content_part.done

            Function call items:
              response.function_call_arguments.delta  (repeated)
              response.function_call_arguments.done

            Reasoning items:
              response.reasoning_summary_text.delta  (repeated)
              response.reasoning_summary_text.done
        end note
    }

    in_progress --> completed : response.output_item.done
    in_progress --> incomplete : response.output_item.done
    completed --> [*]
    incomplete --> [*]

    note right of completed : Terminal — no further deltas
    note right of incomplete : Terminal — token budget exhausted

Event Validity Summary

事件有效性汇总

Response State	Valid Events
`created`	(transient — response object just created)
`queued`	(waiting for model availability)
`in_progress`	All delta events, all custom events, item lifecycle events
`completed`	(terminal — no more events except `[DONE]` )
`incomplete`	(terminal — no more events except `[DONE]` )
`failed`	(terminal — no more events except `[DONE]` )

Item State	Valid Events
`in_progress`	Content deltas ( `.delta` ), content completion ( `.done` ), part lifecycle
`completed`	(terminal — no further deltas for this item)
`incomplete`	(terminal — no further deltas for this item)

All delta and item events carry

sequence_number

(monotonically increasing),

output_index

(position in response output array), and

item_id

. Content-level events (text, reasoning summary) additionally carry

content_index

(position within a content part). Servers SHOULD NOT use the SSE

id

field.

响应状态	有效事件
`created`	（临时状态——响应对象刚创建）
`queued`	（等待模型可用）
`in_progress`	所有delta事件、所有自定义事件、项生命周期事件
`completed`	（终端状态——除 `[DONE]` 外无其他事件）
`incomplete`	（终端状态——除 `[DONE]` 外无其他事件）
`failed`	（终端状态——除 `[DONE]` 外无其他事件）

项状态	有效事件
`in_progress`	内容增量（ `.delta` ）、内容完成（ `.done` ）、部分生命周期事件
`completed`	（终端状态——该项无后续增量）
`incomplete`	（终端状态——该项无后续增量）

所有delta和项事件都携带

sequence_number

（单调递增）、

output_index

（响应输出数组中的位置）和

item_id

。内容级事件（文本、推理摘要）还额外携带

content_index

（内容部分中的位置）。服务器不应使用SSE的

id

字段。

Streaming Events

流式事件

Two categories of SSE events:

Delta events — incremental content:

response.output_text.delta

response.function_call_arguments.delta

response.output_item.added

response.output_item.done

, etc.

Lifecycle events — state transitions:

response.created

response.queued

response.in_progress

response.completed

response.incomplete

response.failed

Rule: the

event

SSE header must match the

type

field inside the JSON body.

SSE事件分为两类：

Delta事件 —— 增量内容：

response.output_text.delta

、

response.function_call_arguments.delta

、

response.output_item.added

、

response.output_item.done

等

生命周期事件 —— 状态转换：

response.created

、

response.queued

、

response.in_progress

、

response.completed

、

response.incomplete

、

response.failed

规则：SSE的

event

头必须与JSON体中的

type

字段匹配。

Tools

工具

Open Responses defines two tool categories based on execution location.

Externally-hosted tools — implementation lives outside the provider's system. The model requests invocation via

function_call

items, and the developer must supply results as

function_call_output

items in a follow-up request. Note that "externally hosted" does not always mean the developer executes the tool locally — MCP tools are externally hosted (the implementation lives on external servers), but control is not necessarily yielded back to the developer first. Examples: function tools, MCP server tools.

Internally-hosted tools — implementation lives inside the provider's system. The provider executes without yielding control and returns results as provider-specific item types within the same response. These items must be losslessly round-trippable in follow-up requests. Examples: file search, code interpreter, web search.

Open Responses根据执行位置定义了两类工具。

外部托管工具 —— 实现逻辑位于提供商系统之外。模型通过

function_call

项请求调用，开发者必须在后续请求中以

function_call_output

项的形式提供结果。注意，“外部托管”并不总是意味着开发者在本地执行工具——MCP工具是外部托管的（实现逻辑位于外部服务器），但控制权不一定会先交还给开发者。示例：函数工具、MCP服务器工具。

内部托管工具 —— 实现逻辑位于提供商系统之内。提供商无需交出控制权即可执行，并在同一响应中以提供商特定的项类型返回结果。这些项必须能够在后续请求中无损往返传输。示例：文件搜索、代码解释器、网页搜索。

Tool Definition

工具定义

json

{
  "type": "function",
  "name": "get_weather",
  "description": "Get current weather for a location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {"type": "string", "description": "City name"},
      "units": {"type": "string", "enum": ["celsius", "fahrenheit"]}
    },
    "required": ["location"]
  }
}

json

{
  "type": "function",
  "name": "get_weather",
  "description": "Get current weather for a location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {"type": "string", "description": "City name"},
      "units": {"type": "string", "enum": ["celsius", "fahrenheit"]}
    },
    "required": ["location"]
  }
}

Tool Control

工具控制

The

tool_choice

parameter controls whether and how the model uses tools:

`tool_choice` value	Purpose
`"auto"`	Model decides whether to call tools (default)
`"required"`	Model must invoke at least one tool
`"none"`	No tool calls permitted
`{"type": "function", "name": "..."}`	Force a specific tool
`{"type": "allowed_tools", "tools": [...]}`	Restrict which tools the model may invoke

The

allowed_tools

form is nested inside

tool_choice

, not a separate top-level parameter:

json

{
  "tool_choice": {
    "type": "allowed_tools",
    "tools": [
      {"type": "function", "name": "get_weather"}
    ]
  }
}

The model MUST restrict its tool calls to the subset named in

allowed_tools

. Servers MUST enforce this as a hard constraint. Tool definitions remain in the model's context, preserving prompt cache.

tool_choice

参数控制模型是否以及如何使用工具：

`tool_choice` 值	用途
`"auto"`	模型决定是否调用工具（默认值）
`"required"`	模型必须至少调用一个工具
`"none"`	不允许调用任何工具
`{"type": "function", "name": "..."}`	强制调用特定工具
`{"type": "allowed_tools", "tools": [...]}`	限制模型可调用的工具范围

allowed_tools

形式嵌套在

tool_choice

内部，而非单独的顶层参数：

json

{
  "tool_choice": {
    "type": "allowed_tools",
    "tools": [
      {"type": "function", "name": "get_weather"}
    ]
  }
}

模型必须将工具调用限制在

allowed_tools

中指定的子集。服务器必须将此作为硬约束强制执行。工具定义保留在模型上下文中，以保留提示缓存。

Agentic Loop Pattern

Agentic Loop模式

The agentic loop is the core pattern for multi-step, tool-augmented workflows.

Agentic Loop是多步骤、工具增强型工作流的核心模式。

Flow

流程

  Client                     Provider                    Model
    |                           |                          |
    |-- POST /v1/responses ---->|                          |
    |                           |--- prompt to model ----->|
    |                           |<-- output items ---------|
    |                           |                          |
    |            [external tool calls needing               |
    |             client-supplied results?]                 |
    |                           |                          |
    |              YES                                     |
    |<-- response with --------|                          |
    |   function_call items     |                          |
    |                           |                          |
    |   [client satisfies       |                          |
    |    tool calls]            |                          |
    |                           |                          |
    |-- POST /v1/responses ---->|                          |
    |   previous_response_id +  |                          |
    |   function_call_output    |--- prompt + context ---->|
    |   items in input          |<-- output items ---------|
    |                           |                          |
    |              NO: no client-satisfied calls remain     |
    |<-- completed response ----|                          |
    |   (may contain message,   |                          |
    |    reasoning, hosted-tool |                          |
    |    items, etc.)           |                          |

  Client                     Provider                    Model
    |                           |                          |
    |-- POST /v1/responses ---->|                          |
    |                           |--- prompt to model ----->|
    |                           |<-- output items ---------|
    |                           |                          |
    |            [external tool calls needing               |
    |             client-supplied results?]                 |
    |                           |                          |
    |              YES                                     |
    |<-- response with --------|                          |
    |   function_call items     |                          |
    |                           |                          |
    |   [client satisfies       |                          |
    |    tool calls]            |                          |
    |                           |                          |
    |-- POST /v1/responses ---->|                          |
    |   previous_response_id +  |                          |
    |   function_call_output    |--- prompt + context ---->|
    |   items in input          |<-- output items ---------|
    |                           |                          |
    |              NO: no client-satisfied calls remain     |
    |<-- completed response ----|                          |
    |   (may contain message,   |                          |
    |    reasoning, hosted-tool |                          |
    |    items, etc.)           |                          |

Key Principles

核心原则

Stateless-first iteration — Each loop iteration is a new HTTP request. The server reconstructs context from
```
previous_response_id
```
. Providers may optionally persist state, but the protocol does not require it.
Developer controls external tool execution — For externally-hosted function tools, the developer decides when to execute, what results to return, and whether to continue. For MCP tools (also externally hosted), execution may happen without first yielding control to the developer.
Parallel tool calls — The model may emit multiple
```
function_call
```
items in a single response. Execute all of them and return all results in one follow-up request.
Loop termination — The loop ends when no client-satisfied external tool calls remain in the response. The final response may contain not just
```
message
```
items but also
```
reasoning
```
items, internally-hosted tool items, and other non-message output items.
Provider handles internal tools — For internally-hosted tools, the provider executes within the same request and returns provider-specific item types. No developer loop required.

无状态优先迭代 —— 每个循环迭代都是一个新的HTTP请求。服务器通过
```
previous_response_id
```
重建上下文。提供商可选择性持久化状态，但协议不强制要求。
开发者控制外部工具执行 —— 对于外部托管的函数工具，开发者决定何时执行、返回什么结果以及是否继续。对于MCP工具（同样是外部托管），执行可能无需先将控制权交还给开发者。
并行工具调用 —— 模型可在单个响应中生成多个
```
function_call
```
项。执行所有这些调用，并在一个后续请求中返回所有结果。
循环终止 —— 当响应中不再需要客户端处理的外部工具调用时，循环结束。最终响应可能不仅包含
```
message
```
项，还可能包含
```
reasoning
```
项、内部托管工具项以及其他非消息输出项。
提供商处理内部工具 —— 对于内部托管工具，提供商在同一请求中执行，并返回提供商特定的项类型。无需开发者参与循环。

Example: Multi-Tool Agent

示例：多工具智能体

Turn 1 — Request with tools:

json

{
  "model": "provider/model-name",
  "input": [{"type": "message", "role": "user", "content": "Compare the weather in Paris and Tokyo."}],
  "tools": [{"type": "function", "name": "get_weather", "description": "Get current weather for a city", "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}]
}

Turn 1 — Model emits two parallel function_call items:

json

{
  "id": "resp_100",
  "status": "completed",
  "output": [
    {"id": "item_101", "type": "function_call", "name": "get_weather", "call_id": "call_paris", "arguments": "{\"location\":\"Paris\"}", "status": "completed"},
    {"id": "item_102", "type": "function_call", "name": "get_weather", "call_id": "call_tokyo", "arguments": "{\"location\":\"Tokyo\"}", "status": "completed"}
  ]
}

Turn 2 — Developer returns tool results:

json

{
  "model": "provider/model-name",
  "previous_response_id": "resp_100",
  "input": [
    {"type": "function_call_output", "call_id": "call_paris", "output": "{\"temperature\":18,\"condition\":\"partly cloudy\"}"},
    {"type": "function_call_output", "call_id": "call_tokyo", "output": "{\"temperature\":24,\"condition\":\"sunny\"}"}
  ],
  "tools": [...]
}

Turn 2 — Model synthesizes final answer (no function_call items = loop ends):

json

{
  "id": "resp_101",
  "status": "completed",
  "output": [
    {"id": "item_200", "type": "message", "role": "assistant", "status": "completed", "content": [{"type": "output_text", "text": "Paris is currently 18°C and partly cloudy. Tokyo is warmer at 24°C with sunny skies."}]}
  ]
}

第1轮——带工具的请求：

json

{
  "model": "provider/model-name",
  "input": [{"type": "message", "role": "user", "content": "Compare the weather in Paris and Tokyo."}],
  "tools": [{"type": "function", "name": "get_weather", "description": "Get current weather for a city", "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}]
}

第1轮——模型生成两个并行的function_call项：

json

{
  "id": "resp_100",
  "status": "completed",
  "output": [
    {"id": "item_101", "type": "function_call", "name": "get_weather", "call_id": "call_paris", "arguments": "{\"location\":\"Paris\"}", "status": "completed"},
    {"id": "item_102", "type": "function_call", "name": "get_weather", "call_id": "call_tokyo", "arguments": "{\"location\":\"Tokyo\"}", "status": "completed"}
  ]
}

第2轮——开发者返回工具结果：

json

{
  "model": "provider/model-name",
  "previous_response_id": "resp_100",
  "input": [
    {"type": "function_call_output", "call_id": "call_paris", "output": "{\"temperature\":18,\"condition\":\"partly cloudy\"}"},
    {"type": "function_call_output", "call_id": "call_tokyo", "output": "{\"temperature\":24,\"condition\":\"sunny\"}"}
  ],
  "tools": [...]
}

第2轮——模型合成最终答案（无function_call项=循环结束）：

json

{
  "id": "resp_101",
  "status": "completed",
  "output": [
    {"id": "item_200", "type": "message", "role": "assistant", "status": "completed", "content": [{"type": "output_text", "text": "Paris is currently 18°C and partly cloudy. Tokyo is warmer at 24°C with sunny skies."}]}
  ]
}

Multi-Turn Conversations

多轮对话

Multi-turn conversations use

previous_response_id

to chain context. The server reconstructs the full conversation by walking the response chain (providers may also support server-side persistence as an extension):

Server loads: previous_response.input + previous_response.output + new_input

json

// Turn 1
{"model": "provider/model-name", "input": [{"type": "message", "role": "user", "content": "What is the population of France?"}]}
// Response: {"id": "resp_200", ...}

// Turn 2 — references Turn 1
{"model": "provider/model-name", "previous_response_id": "resp_200", "input": [{"type": "message", "role": "user", "content": "And what about Germany?"}]}

多轮对话使用

previous_response_id

串联上下文。服务器通过遍历响应链重建完整对话（提供商也可作为扩展支持服务器端持久化）：

Server loads: previous_response.input + previous_response.output + new_input

json

// Turn 1
{"model": "provider/model-name", "input": [{"type": "message", "role": "user", "content": "What is the population of France?"}]}
// Response: {"id": "resp_200", ...}

// Turn 2 — references Turn 1
{"model": "provider/model-name", "previous_response_id": "resp_200", "input": [{"type": "message", "role": "user", "content": "And what about Germany?"}]}

Extensions

扩展

Open Responses supports four extension mechanisms, all using vendor-prefixed names to prevent collisions. For full details with examples, load

references/extensions.md

Mechanism	Naming Pattern	Required Fields	Constraint
Custom Items	`vendor:type_name`	`id` , `type` , `status`	Must follow item state machine, must round-trip
Custom Events	`vendor:event_name`	`type` , `sequence_number`	Must not alter core semantics or token order
Schema Extensions	vendor-prefixed fields	N/A (optional fields)	Must not break clients ignoring unknown fields
Governance Path	N/A	N/A	Broad adoption -> TSC proposal -> core spec

Clients must silently ignore unknown item types and event types — this is the forward-compatibility contract.

Open Responses支持四种扩展机制，均使用厂商前缀名称以避免冲突。如需详细示例，请加载

references/extensions.md

。

机制	命名模式	必填字段	约束
自定义项	`vendor:type_name`	`id` , `type` , `status`	必须遵循项状态机，必须支持往返传输
自定义事件	`vendor:event_name`	`type` , `sequence_number`	不得改变核心语义或令牌顺序
Schema扩展	厂商前缀字段	无（可选字段）	不得破坏忽略未知字段的客户端
治理路径	无	无	广泛采用 -> TSC提案 -> 核心规范

客户端必须静默忽略未知的项类型和事件类型——这是向前兼容的约定。

Compliance

合规性

An API is Open Responses-compliant if it implements the spec directly or is a proper superset. The published acceptance test suite is available at https://www.openresponses.org/.

如果API直接实现了该规范或为其正确超集，则该API符合Open Responses标准。已发布的验收测试套件可在https://www.openresponses.org/获取。

Core Compliance Tests

核心合规测试

Test	Validates
Basic Text Response	ResponseResource schema, item structure, usage
Streaming Response	SSE events, correct ordering, final structure
System Prompt	`instructions` parameter, system role handling
Tool Calling	Function tool definition, function_call output, round-tripping
Image Input	Image URL in user content
Multi-turn Conversation	Message history, assistant + user turns

测试	验证内容
基础文本响应	ResponseResource schema、项结构、用法
流式响应	SSE事件、正确排序、最终结构
系统提示	`instructions` 参数、system角色处理
工具调用	函数工具定义、function_call输出、往返传输
图片输入	用户内容中的图片URL
多轮对话	消息历史、助手+用户轮次

Server Implementation Checklist

服务器实现检查清单

```
POST /v1/responses
```
endpoint with
```
Authorization
```
header
Valid output items with
```
id
```
,
```
type
```
,
```
status
```
; input items per their type requirements
Item state machine:
```
in_progress
```
->
```
completed
```
/
```
incomplete
```

Response state machine:

created

queued

in_progress

completed

incomplete

failed

Emit all 6 lifecycle events:

response.created

.queued

.in_progress

.completed

.incomplete

.failed

Response
```
incomplete
```
when any item ends
```
incomplete
```
Non-streaming JSON and streaming SSE with
```
event
```
/
```
type
```
matching
```
data: [DONE]
```
terminal marker
Function tools:
```
function_call
```
items,
```
function_call_output
```
round-tripping
```
previous_response_id
```
for conversation continuation
Error objects:
```
type
```
,
```
code
```
,
```
param
```
,
```
message
```
with correct HTTP status codes
Vendor-prefixed extensions (if applicable)

带
```
Authorization
```
头的
```
POST /v1/responses
```
端点
包含
```
id
```
、
```
type
```
、
```
status
```
的有效输出项；输入项符合其类型要求
项状态机：
```
in_progress
```
->
```
completed
```
/
```
incomplete
```

响应状态机：

created

queued

in_progress

completed

incomplete

failed

触发所有6种生命周期事件：

response.created

、

.queued

、

.in_progress

、

.completed

、

.incomplete

、

.failed

当任何项状态为
```
incomplete
```
时，响应状态也为
```
incomplete
```
非流式JSON和流式SSE的
```
event
```
/
```
type
```
匹配
```
data: [DONE]
```
终端标记
函数工具：
```
function_call
```
项、
```
function_call_output
```
往返传输
用于对话延续的
```
previous_response_id
```
错误对象：包含
```
type
```
、
```
code
```
、
```
param
```
、
```
message
```
字段，并使用正确的HTTP状态码
厂商前缀扩展（如适用）

Client Implementation Checklist

客户端实现检查清单

Send
```
Authorization
```
and
```
Content-Type
```
headers
Parse polymorphic items by
```
type
```
field
Track item and response state machines
Process SSE: parse
```
event:
```
+
```
data:
```
lines, handle
```
[DONE]
```
Implement agentic loop for externally-hosted tools
Silently ignore unknown item types and event types
Support
```
previous_response_id
```
for multi-turn conversations
Handle parallel tool calls in a single response

发送
```
Authorization
```
和
```
Content-Type
```
头
通过
```
type
```
字段解析多态项
跟踪项和响应状态机
处理SSE：解析
```
event:
```
+
```
data:
```
行，处理
```
[DONE]
```
为外部托管工具实现Agentic Loop
静默忽略未知的项类型和事件类型
支持使用
```
previous_response_id
```
进行多轮对话
处理单个响应中的并行工具调用

Quick Reference

快速参考

Streaming Event Types

流式事件类型

Event	Category
`response.created`	Lifecycle
`response.queued`	Lifecycle
`response.in_progress`	Lifecycle
`response.completed`	Lifecycle
`response.incomplete`	Lifecycle
`response.failed`	Lifecycle
`response.output_item.added` / `.done`	Delta
`response.content_part.added` / `.done`	Delta
`response.output_text.delta` / `.done`	Delta
`response.function_call_arguments.delta` / `.done`	Delta
`response.reasoning_summary_text.delta` / `.done`	Delta
`vendor:custom_event`	Custom

事件	类别
`response.created`	生命周期
`response.queued`	生命周期
`response.in_progress`	生命周期
`response.completed`	生命周期
`response.incomplete`	生命周期
`response.failed`	生命周期
`response.output_item.added` / `.done`	Delta
`response.content_part.added` / `.done`	Delta
`response.output_text.delta` / `.done`	Delta
`response.function_call_arguments.delta` / `.done`	Delta
`response.reasoning_summary_text.delta` / `.done`	Delta
`vendor:custom_event`	自定义

Item Types

项类型

Type	Category
`message`	Core
`function_call`	Core
`function_call_output`	Core
`reasoning`	Core
`vendor:custom_type`	Extension

类型	类别
`message`	核心
`function_call`	核心
`function_call_output`	核心
`reasoning`	核心
`vendor:custom_type`	扩展

State Summary

状态汇总

Object	States	Terminal
Response	created -> queued -> in_progress -> completed / incomplete / failed	completed, incomplete, failed
Item	in_progress -> completed / incomplete	completed, incomplete

If any item ends

incomplete

, the containing response MUST also be

incomplete

对象	状态	终端状态
响应	created -> queued -> in_progress -> completed / incomplete / failed	completed, incomplete, failed
项	in_progress -> completed / incomplete	completed, incomplete

如果任何项状态为

incomplete

，则包含该项的响应也必须为

incomplete

。

Error Types

错误类型

Type	HTTP	Retry
`invalid_request`	400	No
`not_found`	404	No
`too_many_requests`	429	Yes
`server_error`	500	Yes
`model_error`	500	Maybe

类型	HTTP状态码	是否可重试
`invalid_request`	400	否
`not_found`	404	否
`too_many_requests`	429	是
`server_error`	500	是
`model_error`	500	可能