OpenAI Responses WebSocket 模式
Responses API 的 WebSocket 模式适合运行时间长、工具调用频繁的工作流。除降低延迟外,stream_id 支持多路复用:一条连接到 /v1/responses 的持久连接,可运行并行对话,也可把既有对话分叉到新流。每轮只发送新输入项和 previous_response_id 即可继续。
此模式兼容零数据保留(ZDR)与 store=false。
为什么使用 WebSocket 模式
多次模型与工具往返的工作流最有收益,例如智能体编程或反复工具调用的编排循环。
连接保持打开,每轮仅发增量输入,可减少逐轮续接开销,降低长链端到端延迟。官方报告在超过 20 次工具调用的运行中,观察到最高约 40% 的端到端执行提速;这是观察结果,并非所有工作负载的保证。
连接并创建响应
安装 WebSocket 依赖:Python 为 pip install "openai[realtime]>=3.8.0",JavaScript 为 npm install openai@^7.10.0 ws,Ruby 为 gem install openai async-websocket。
Go 执行 go get github.com/openai/openai-go/v3@v3.94.0,Java 添加 Maven 依赖 com.openai:openai-java:4.98.0。这些 Go、Java 版本原生支持 Responses WebSocket。
每轮从客户端发送 response.create。载荷与普通 Responses 创建请求体相同,但不使用 stream、background 等传输相关字段。
来源示例 1(javascript):
程序文字译释265:查找fizz_buzz()函数。
程序文字译释266:响应完成前连接已关闭。
// [中文] 示例 1:连接并创建响应;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 本段构造的事件类型:response.create;不要将构造载荷等同于收到成功确认。
// [中文] 沿原示例执行这些方法:ws.send、ws.close;异步调用及事件接收顺序保留。
import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/responses/ws";
const client = new OpenAI();
const ws = new ResponsesWS(client);
try {
ws.send({
type: "response.create",
stream_id: "main",
model: "gpt-6-astra",
store: false,
input: [
{
type: "message",
role: "user",
content: [{ type: "input_text", text: "Find fizz_buzz()" }],
},
],
tools: [],
});
let completed = false;
for await (const event of ws) {
if (event.type === "error") throw event.error;
if (event.type !== "message") continue;
const message = event.message;
if (message.type === "response.output_text.delta") {
process.stdout.write(message.delta);
} else if (message.type === "response.completed") {
completed = true;
break;
} else if (
message.type === "response.failed" ||
message.type === "response.incomplete"
) {
throw new Error(JSON.stringify(message));
}
}
if (!completed)
throw new Error("Connection closed before the response finished.");
} finally {
ws.close();
}
来源示例 2(python):
沿用程序文字译释265。
## [中文] 显式请求创建或继续响应,使用本段实际设置的模态、上下文与工具字段;发送请求不等同于收到完成事件。
from openai import OpenAI
client = OpenAI()
with client.responses.connect() as connection:
connection.response.create(
stream_id="main",
model="gpt-6-astra",
store=False,
input=[
{
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "Find fizz_buzz()"}],
}
],
tools=[],
)
for event in connection:
if event.type == "response.completed":
print(event.response.output_text)
break
if event.type in {"response.failed", "response.incomplete", "error"}:
raise RuntimeError(event.to_json())
else:
raise RuntimeError("Connection closed before the response finished.")
来源示例 3(go):
沿用程序文字译释265。
程序文字译释267:响应以指定状态结束。
// [中文] 示例 3:连接并创建响应;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 沿原示例执行这些方法:client.Responses.Connect;异步调用及事件接收顺序保留。
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
conn, err := client.Responses.Connect(ctx, responses.ResponseConnectionOptions{})
if err != nil {
log.Fatal(err)
}
defer conn.Close()
if err := conn.Create(ctx, responses.ResponsesClientEventResponseCreateParam{
Model: "gpt-6-astra",
Store: openai.Bool(false),
Input: responses.ResponsesClientEventResponseCreateInputUnionParam{
OfString: openai.String("Find fizz_buzz()"),
},
StreamID: openai.String("main"),
Tools: []responses.ToolUnionParam{},
}); err != nil {
log.Fatal(err)
}
response, err := conn.FinalResponse(ctx)
if err != nil {
log.Fatal(err)
}
if response.Status != responses.ResponseStatusCompleted {
log.Fatalf("Response ended with status %s", response.Status)
}
fmt.Println(response.OutputText())
来源示例 4(java):
程序文字译释55:响应以所示状态结束。
沿用程序文字译释265。
// [中文] 显式请求创建或继续响应,使用本段实际设置的模态、上下文与工具字段;发送请求不等同于收到完成事件。
// [中文] 本段为配置或调用片段,需结合外层程序与已建立连接使用;不作为独立完整程序宣称编译通过。
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.*;
import java.util.*;
var client = OpenAIOkHttpClient.fromEnv();
try (var conn = client.responses().connect()) {
conn.send(
ResponsesClientEvent.ofResponseCreate(
ResponsesClientEvent.ResponseCreate.builder()
.model("gpt-6-astra")
.store(false)
.input("Find fizz_buzz()")
.streamId("main")
.tools(List.of())
.build()));
var response = conn.finalResponse();
if (response.status().filter(ResponseStatus.COMPLETED::equals).isEmpty())
throw new IllegalStateException(
"Response ended with status " + response.status().orElse(null));
response.output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text()));
} finally {
client.close();
}
来源示例 5(ruby):
沿用程序文字译释265。
程序文字译释268:响应失败,后接事件JSON。
程序文字译释269:响应结束前连接已关闭。
## [中文] 示例 5:连接并创建响应;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:client.responses.connect、connection.response.create;异步调用及事件接收顺序保留。
require "async"
require "openai"
def wait_for_response(connection)
while (event = connection.receive)
case event.type.to_s
when "response.completed" then return event.response
when "response.failed", "response.incomplete", "error"
raise "Response failed: #{event.to_json}"
end
end
raise "Connection closed before the response finished"
end
client = OpenAI::Client.new
Sync do |task|
task.with_timeout(120) do
client.responses.connect(request_options: { timeout: 10 }) do |connection|
connection.response.create(
stream_id: "main", model: "gpt-6-astra", store: false,
input: [
{
role: "user",
content: "Find fizz_buzz()"
}
], tools: []
)
puts(wait_for_response(connection).output_text)
end
end
end
可选发送 generate: false 的 response.create 预热请求状态,适合预先知道下一轮工具、指令或消息的情况。它不返回模型输出,而是准备状态,让后续生成更快。预热返回响应 ID,可用 previous_response_id 链接,包括链中较后的轮次。增量续接见下文。
用增量输入继续
响应仍在运行时要追加用户指令,使用轮次中途引导,保留已完成工作并在续接中纳入新指令。普通轮次间续接与工具结果采用以下模式:
previous_response_id设为上一响应 ID。input只包含新增项,例如工具输出和下一条用户消息。
来源示例 6(javascript):
沿用程序文字译释266。
程序文字译释270:返回本地演示测试结果。
程序文字译释271:找到失败的测试并建议修复。
程序文字译释272:预期get_test_results函数调用。
程序文字译释273:现在优化它。
// [中文] 示例 6:用增量输入继续;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 本段构造的事件类型:response.create;不要将构造载荷等同于收到成功确认。
// [中文] 沿原示例执行这些方法:ws.send、ws.close;异步调用及事件接收顺序保留。
// [中文] 返回函数结果时保留对应 call_id;响应继续事件与结果项目是两个独立步骤。
import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/responses/ws";
const client = new OpenAI();
const model = "gpt-6-astra";
const tools = [
{
type: "function",
name: "get_test_results",
description: "Return a local demo test result.",
parameters: { type: "object", properties: {}, additionalProperties: false },
strict: true,
},
];
async function waitForResponse(ws) {
for await (const event of ws) {
if (event.type === "error") throw event.error;
if (event.type !== "message") continue;
const message = event.message;
if (message.type === "response.output_text.delta") {
process.stdout.write(message.delta);
} else if (message.type === "response.completed") {
return message.response;
} else if (
message.type === "response.failed" ||
message.type === "response.incomplete"
) {
throw new Error(JSON.stringify(message));
}
}
throw new Error("Connection closed before the response finished.");
}
const ws = new ResponsesWS(client);
try {
ws.send({
type: "response.create",
stream_id: "main",
model,
store: false,
input: "Find the failing test and suggest a fix.",
tools,
tool_choice: { type: "function", name: "get_test_results" },
parallel_tool_calls: false,
});
const first = await waitForResponse(ws);
const call = first.output.find((item) => item.type === "function_call");
if (!call || call.name !== "get_test_results") {
throw new Error("Expected a get_test_results function call.");
}
const result = {
test: "test_fizz_buzz",
failure: 'Expected "FizzBuzz" for 15, got "Fizz".',
};
// Continue on the same socket with the actual response and tool-call IDs.
ws.send({
type: "response.create",
stream_id: "main",
model,
store: false,
previous_response_id: first.id,
input: [
{
type: "function_call_output",
call_id: call.call_id,
output: JSON.stringify(result),
},
{ role: "user", content: "Now optimize it." },
],
tools,
tool_choice: "none",
});
await waitForResponse(ws);
} finally {
ws.close();
}
来源示例 7(python):
沿用程序文字译释266。
沿用程序文字译释271。
沿用程序文字译释273。
程序文字译释274:读取演示测试结果。
程序文字译释275:预期无参数get_test_results调用。
## [中文] 示例 7:用增量输入继续;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:client.responses.connect、connection.response.create;异步调用及事件接收顺序保留。
## [中文] 返回函数结果时保留对应 call_id;响应继续事件与结果项目是两个独立步骤。
import json
from openai import OpenAI
from openai.resources.responses.responses import ResponsesConnection
from openai.types.responses import FunctionToolParam, Response
client = OpenAI()
model = "gpt-6-astra"
tools: list[FunctionToolParam] = [
{
"type": "function",
"name": "get_test_results",
"description": "Read the demo test results.",
"parameters": {
"type": "object",
"properties": {},
"required": [],
"additionalProperties": False,
},
"strict": True,
}
]
def get_test_results():
# Demo data. Replace this function with your test runner.
return {
"test": "test_fizz_buzz",
"failure": 'Expected "FizzBuzz" for 15, got "Fizz".',
}
def wait_for_response(connection: ResponsesConnection) -> Response:
for event in connection:
if event.type == "response.completed":
return event.response
if event.type in {"response.failed", "response.incomplete", "error"}:
raise RuntimeError(event.to_json())
raise RuntimeError("Connection closed before the response finished.")
with client.responses.connect() as connection:
connection.response.create(
stream_id="main",
model=model,
store=False,
input="Find the failing test and suggest a fix.",
tools=tools,
tool_choice={"type": "function", "name": "get_test_results"},
parallel_tool_calls=False,
)
response = wait_for_response(connection)
call = next(item for item in response.output if item.type == "function_call")
if call.name != "get_test_results" or json.loads(call.arguments) != {}:
raise ValueError("Expected a get_test_results call with no arguments")
# Continue on the same connection using the actual response and tool-call IDs.
connection.response.create(
stream_id="main",
model=model,
store=False,
previous_response_id=response.id,
input=[
{
"type": "function_call_output",
"call_id": call.call_id,
"output": json.dumps(get_test_results()),
},
{"role": "user", "content": "Now optimize it."},
],
tools=tools,
tool_choice="none",
)
print(wait_for_response(connection).output_text)
来源示例 8(go):
沿用程序文字译释267。
沿用程序文字译释270。
沿用程序文字译释271。
沿用程序文字译释273。
程序文字译释276:预期get_test_results函数调用。
// [中文] 示例 8:用增量输入继续;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 沿原示例执行这些方法:client.Responses.Connect;异步调用及事件接收顺序保留。
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
tools := []responses.ToolUnionParam{
{
OfFunction: &responses.FunctionToolParam{
Name: "get_test_results",
Description: openai.String("Return a local demo test result."),
Parameters: map[string]any{
"type": "object",
"properties": map[string]any{},
"additionalProperties": false,
},
Strict: openai.Bool(true),
},
},
}
conn, err := client.Responses.Connect(ctx, responses.ResponseConnectionOptions{})
if err != nil {
log.Fatal(err)
}
defer conn.Close()
if err := conn.Create(ctx, responses.ResponsesClientEventResponseCreateParam{
Model: "gpt-6-astra",
Store: openai.Bool(false),
Input: responses.ResponsesClientEventResponseCreateInputUnionParam{
OfString: openai.String("Find the failing test and suggest a fix."),
},
StreamID: openai.String("main"),
Tools: tools,
ParallelToolCalls: openai.Bool(false),
ToolChoice: responses.ResponsesClientEventResponseCreateToolChoiceUnionParam{
OfFunctionTool: &responses.ToolChoiceFunctionParam{
Name: "get_test_results",
},
},
}); err != nil {
log.Fatal(err)
}
first, err := conn.FinalResponse(ctx)
if err != nil {
log.Fatal(err)
}
if first.Status != responses.ResponseStatusCompleted {
log.Fatalf("Response ended with status %s", first.Status)
}
var callID string
for _, item := range first.Output {
if item.Type == "function_call" && item.Name == "get_test_results" {
callID = item.CallID
break
}
}
if callID == "" {
log.Fatal("Expected a get_test_results function call")
}
// The result is a local demo fixture; carry the real response and call IDs.
result := `{"test":"test_fizz_buzz","failure":"Expected FizzBuzz for 15, got Fizz."}`
if err := conn.Create(ctx, responses.ResponsesClientEventResponseCreateParam{
Model: "gpt-6-astra",
StreamID: openai.String("main"),
Store: openai.Bool(false),
PreviousResponseID: openai.String(first.ID),
Tools: tools,
ToolChoice: responses.ResponsesClientEventResponseCreateToolChoiceUnionParam{
OfToolChoiceMode: openai.Opt(responses.ToolChoiceOptionsNone),
},
Input: responses.ResponsesClientEventResponseCreateInputUnionParam{
OfResponse: &responses.ResponseInputParam{
{
OfFunctionCallOutput: &responses.ResponseInputItemFunctionCallOutputParam{
CallID: openai.String(callID),
Output: responses.ResponseInputItemFunctionCallOutputOutputUnionParam{
OfString: openai.String(result),
},
},
},
responses.ResponseInputItemParamOfMessage("Now optimize it.", responses.EasyInputMessageRoleUser),
},
},
}); err != nil {
log.Fatal(err)
}
response, err := conn.FinalResponse(ctx)
if err != nil {
log.Fatal(err)
}
if response.Status != responses.ResponseStatusCompleted {
log.Fatalf("Response ended with status %s", response.Status)
}
fmt.Println(response.OutputText())
来源示例 9(java):
沿用程序文字译释55。
沿用程序文字译释270。
沿用程序文字译释271。
沿用程序文字译释273。
程序文字译释277:预期get_test_results调用。
程序文字译释278:测试test_fizz_buzz失败:输入15预期FizzBuzz,实际得到Fizz。
// [中文] 显式请求创建或继续响应,使用本段实际设置的模态、上下文与工具字段;发送请求不等同于收到完成事件。
// [中文] 本段为配置或调用片段,需结合外层程序与已建立连接使用;不作为独立完整程序宣称编译通过。
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.*;
import java.util.*;
var client = OpenAIOkHttpClient.fromEnv();
var tool =
FunctionTool.builder()
.name("get_test_results")
.description("Return a local demo test result.")
.strict(true)
.parameters(
FunctionTool.Parameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty("properties", JsonValue.from(Map.of()))
.putAdditionalProperty("additionalProperties", JsonValue.from(false))
.build())
.build();
try (var conn = client.responses().connect()) {
conn.send(
ResponsesClientEvent.ofResponseCreate(
ResponsesClientEvent.ResponseCreate.builder()
.model("gpt-6-astra")
.store(false)
.input("Find the failing test and suggest a fix.")
.streamId("main")
.addTool(tool)
.parallelToolCalls(false)
.toolChoice(ToolChoiceFunction.builder().name("get_test_results").build())
.build()));
var first = conn.finalResponse();
if (first.status().filter(ResponseStatus.COMPLETED::equals).isEmpty())
throw new IllegalStateException(
"Response ended with status " + first.status().orElse(null));
var call =
first.output().stream()
.flatMap(item -> item.functionCall().stream())
.filter(item -> item.name().equals("get_test_results"))
.findFirst()
.orElseThrow(() -> new IllegalStateException("Expected get_test_results call"));
// Use the real response and call IDs with a local demo result.
var result =
"{\"test\":\"test_fizz_buzz\",\"failure\":\"Expected FizzBuzz for 15, got Fizz.\"}";
conn.send(
ResponsesClientEvent.ofResponseCreate(
ResponsesClientEvent.ResponseCreate.builder()
.model("gpt-6-astra")
.streamId("main")
.store(false)
.previousResponseId(first.id())
.addTool(tool)
.toolChoice(ToolChoiceOptions.NONE)
.inputOfResponse(
List.of(
ResponseInputItem.ofFunctionCallOutput(
ResponseInputItem.FunctionCallOutput.builder()
.callId(call.callId())
.output(result)
.build()),
ResponseInputItem.ofEasyInputMessage(
EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content("Now optimize it.")
.build())))
.build()));
var response = conn.finalResponse();
if (response.status().filter(ResponseStatus.COMPLETED::equals).isEmpty())
throw new IllegalStateException(
"Response ended with status " + response.status().orElse(null));
response.output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text()));
} finally {
client.close();
}
来源示例 10(ruby):
沿用程序文字译释268。
沿用程序文字译释269。
沿用程序文字译释271。
沿用程序文字译释273。
沿用程序文字译释274。
沿用程序文字译释275。
## [中文] 示例 10:用增量输入继续;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:client.responses.connect、connection.response.create;异步调用及事件接收顺序保留。
## [中文] 返回函数结果时保留对应 call_id;响应继续事件与结果项目是两个独立步骤。
require "async"
require "openai"
require "json"
def wait_for_response(connection)
while (event = connection.receive)
case event.type.to_s
when "response.completed" then return event.response
when "response.failed", "response.incomplete", "error"
raise "Response failed: #{event.to_json}"
end
end
raise "Connection closed before the response finished"
end
tools = [
{
type: "function",
name: "get_test_results",
description: "Read the demo test results.",
parameters: {
type: "object",
properties: {},
required: [],
additionalProperties: false
},
strict: true
}
]
client = OpenAI::Client.new
Sync do |task|
task.with_timeout(120) do
client.responses.connect(request_options: { timeout: 10 }) do |connection|
connection.response.create(
stream_id: "main", model: "gpt-6-astra", store: false,
input: "Find the failing test and suggest a fix.", tools: tools,
tool_choice: {
type: "function",
name: "get_test_results"
}, parallel_tool_calls: false
)
response = wait_for_response(connection)
call = response.output.grep(OpenAI::Responses::ResponseFunctionToolCall).first
unless call && call.name == "get_test_results" && JSON.parse(call.arguments) == {}
raise "Expected a get_test_results call with no arguments"
end
# Demo data. Replace this with your test runner.
result = {
test: "test_fizz_buzz",
failure: 'Expected "FizzBuzz" for 15, got "Fizz".'
}
connection.response.create(
stream_id: "main", model: "gpt-6-astra", store: false,
previous_response_id: response.id,
input: [
{
type: "function_call_output",
call_id: call.call_id,
output: JSON.generate(result)
},
{
role: "user",
content: "Now optimize it."
}
],
tools: tools, tool_choice: "none"
)
puts(wait_for_response(connection).output_text)
end
end
end
续接如何工作
链式语义与 HTTP 相同,但在活动套接字上增加低延迟路径。
活动连接以连接本地的内存缓存保存近期响应状态。使用 stream_id 时,每个通道保留最近缓存的响应,从该通道最新响应继续可复用状态,因此较快。状态只留内存、不写磁盘,可兼容 store=false 和 ZDR。
previous_response_id 不在内存缓存时:
store=true:如有持久状态,可恢复较旧 ID,续接仍可能成功,但失去内存延迟收益。store=false,包括 ZDR:没有持久化回退,返回previous_response_not_found。
同一通道续接返回 4xx 或 5xx 时,会从连接缓存移除引用的响应。跨通道分叉失败则保留共享父响应,源通道仍可继续。
压缩与创建新响应
使用压缩时,两种续接模式不同。
服务端压缩(context_management)
启用含 compact_threshold 的 context_management 后,压缩发生在正常 /responses 生成中。WebSocket 仍发送最新 previous_response_id 和新增输入项即可。
独立 /responses/compact
独立 /responses/compact 返回新的压缩输入窗口,不返回响应 ID。压缩后,在 WebSocket 上以压缩窗口和下一个用户或工具项作为 input 创建新响应。
省略 previous_response_id 或设为 null 开始新链。压缩输出原样传入,不要裁剪返回窗口。
来源示例 11(javascript):
沿用程序文字译释266。
程序文字译释279:从这里继续。
// [中文] 示例 11:独立 /responses/compact;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 本段构造的事件类型:response.create;不要将构造载荷等同于收到成功确认。
// [中文] 沿原示例执行这些方法:client.responses.compact、ws.send、ws.close;异步调用及事件接收顺序保留。
import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";
// Compact your current window with an HTTP request.
const compacted = await client.responses.compact({
model: "gpt-6-astra",
input: longInputItems,
});
const nextInput = toResponseInputItems(compacted.output);
nextInput.push({
type: "message",
role: "user",
content: [{ type: "input_text", text: "Continue from here." }],
});
// Start a new response on the WebSocket using the compacted window.
const ws = new ResponsesWS(client);
try {
ws.send({
type: "response.create",
stream_id: "main",
model: "gpt-6-astra",
store: false,
input: nextInput,
tools: [],
});
let completed = false;
for await (const event of ws) {
if (event.type === "error") throw event.error;
if (event.type !== "message") continue;
const message = event.message;
if (message.type === "response.output_text.delta") {
process.stdout.write(message.delta);
} else if (message.type === "response.completed") {
completed = true;
break;
} else if (
message.type === "response.failed" ||
message.type === "response.incomplete"
) {
throw new Error(JSON.stringify(message));
}
}
if (!completed)
throw new Error("Connection closed before the response finished.");
} finally {
ws.close();
}
来源示例 12(python):
沿用程序文字译释279。
## [中文] 显式请求创建或继续响应,使用本段实际设置的模态、上下文与工具字段;发送请求不等同于收到完成事件。
from typing import cast
from openai import OpenAI
from openai.types.responses import ResponseInputParam
## Compact your current window (HTTP call).
compacted = client.responses.compact(
model="gpt-6-astra",
input=long_input_items_array,
)
next_input = cast(
ResponseInputParam,
[item.to_dict() for item in compacted.output],
)
next_input.append(
{
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "Continue from here."}],
}
)
## Start a new response on the WebSocket using the compacted window.
with client.responses.connect() as connection:
connection.response.create(
stream_id="main",
model="gpt-6-astra",
store=False,
input=next_input,
tools=[],
)
for event in connection:
if event.type == "response.completed":
print(event.response.output_text)
break
if event.type in {"response.failed", "response.incomplete", "error"}:
raise RuntimeError(event.to_json())
else:
raise RuntimeError("Connection closed before the response finished.")
来源示例 13(ruby):
沿用程序文字译释268。
沿用程序文字译释269。
沿用程序文字译释279。
程序文字译释280:寻找失败的测试。
## [中文] 示例 13:独立 /responses/compact;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:client.responses.compact、client.responses.connect、connection.response.create;异步调用及事件接收顺序保留。
require "async"
require "openai"
def wait_for_response(connection)
while (event = connection.receive)
case event.type.to_s
when "response.completed" then return event.response
when "response.failed", "response.incomplete", "error"
raise "Response failed: #{event.to_json}"
end
end
raise "Connection closed before the response finished"
end
client = OpenAI::Client.new
compacted = client.responses.compact(
model: "gpt-6-astra",
input: [
{
role: :user,
content: "Find the failing test."
}
]
)
next_input = compacted.output.map(&:to_h)
next_input << {
role: :user,
content: "Continue from here."
}
Sync do |task|
task.with_timeout(120) do
client.responses.connect(request_options: { timeout: 10 }) do |connection|
connection.response.create(
stream_id: "main", model: "gpt-6-astra", store: false,
input: next_input, tools: []
)
puts(wait_for_response(connection).output_text)
end
end
end
并行运行对话
通过 stream_id 在同一连接维持并行对话。连续发送不同 stream_id 的独立 response.create,服务器可并发运行。事件可能交错,保持单一读取循环并按 ID 路由。
stream_id 是一条连接上有序通道的名称,应与 previous_response_id 区分:
stream_id控制事件去向,以及哪些请求先进先出。previous_response_id控制对话继承关系。
这种分离支持以下两种用法:
来源示例 14(text):
本例中文译文与说明:
一条 WebSocket 连接:planner 流起草部署计划,researcher 流列出部署风险。
one WebSocket connection
├─ stream_id="planner" draft a deployment plan
└─ stream_id="research" list deployment risks
同 ID 请求先进先出、不重叠;不同 ID 可并发。
每连接限制
- 命名与默认通道合计最多 16 个活动中的响应。更多
response.create仍可接受,排队等活动响应结束。 - 最多接受 32 个不同的命名
stream_id,隐式默认通道不计入。达到限制后复用 ID 或新建连接。
将对话分叉到新流
把已完成响应 ID 作为 previous_response_id,配合新 stream_id。父响应仍可用时,新流继承上下文,原流可继续;分叉启动后,两条不同 ID 分支可并发。
store=false,包括 ZDR,要求父响应仍在连接缓存。如果分叉排队时源通道已推进或失败,父响应可能在分叉启动前被移除,导致 previous_response_not_found。应等分叉通道发出 response.in_progress 再推进源通道,或将 ID 设为 null 并重放完整上下文重试。
来源示例 15(text):
本例中文译文与说明:
主分支按resp_1、resp_2、resp_3推进,critic分支从既有父响应分叉,按resp_4、resp_5继续,展示对话继承关系。
main: resp_1 ──▶ resp_2 ──▶ resp_3
╲
critic: resp_4 ──▶ resp_5
仅复用 stream_id、不提供 previous_response_id,会开始新响应,不会自动继续对话。
关键调用:
来源示例 16(text):
本例中文译文与说明:
同一连接的四项任务提示分别为:起草部署计划、列出部署风险、寻找计划缺口、补充回滚步骤。前两次send_create启动planner与researcher独立对话,之后通过新stream_id与已完成响应的previous_response_id分叉或续接。stream_id决定通道,previous_response_id决定对话继承。
## One socket, two independent conversations.
send_create(connection, "planner", "Draft a deployment plan.")
send_create(connection, "research", "List deployment risks.")
## Fork the planner response, then continue the original branch in parallel.
send_create(
connection,
"critic",
"Find gaps in this plan.",
previous_response_id=planner_response_id,
)
wait_for_in_progress(connection, "critic")
send_create(
connection,
"planner",
"Add rollback steps.",
previous_response_id=planner_response_id,
)
完整示例
并行运行多个对话,再分叉其中一个:
来源示例 17(javascript):
程序文字译释285:全部响应完成前连接已关闭。
程序文字译释286:为无状态API服务起草部署计划。
程序文字译释287:列出无状态API服务常见部署风险。
程序文字译释288:寻找此部署计划中的缺口。
程序文字译释289:为计划添加回滚和监控步骤。
// [中文] 示例 17:完整示例;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 本段构造的事件类型:response.create;不要将构造载荷等同于收到成功确认。
// [中文] 沿原示例执行这些方法:ws.send、ws.stream、ws.close;异步调用及事件接收顺序保留。
import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/responses/ws";
const client = new OpenAI();
const latestResponseIdByLane = new Map();
function sendCreate(
ws,
streamId,
text,
previousResponseId = latestResponseIdByLane.get(streamId)
) {
ws.send({
type: "response.create",
stream_id: streamId,
model: "gpt-6-astra",
store: false,
input: [
{
type: "message",
role: "user",
content: [{ type: "input_text", text }],
},
],
previous_response_id: previousResponseId,
});
}
async function readMessage(events) {
while (true) {
const { value: event, done } = await events.next();
if (done)
throw new Error("Connection closed before all responses finished.");
if (event.type === "error") throw event.error;
if (event.type !== "message") continue;
const message = event.message;
if (
message.type === "response.failed" ||
message.type === "response.incomplete"
) {
throw new Error(
`Lane ${message.stream_id} failed: ${JSON.stringify(message)}`
);
}
return message;
}
}
async function drainUntilComplete(events, expectedStreamIds) {
const remaining = new Set(expectedStreamIds);
while (remaining.size > 0) {
const message = await readMessage(events);
const streamId = message.stream_id;
if (!streamId || !remaining.has(streamId)) continue;
if (message.type === "response.completed") {
latestResponseIdByLane.set(streamId, message.response.id);
remaining.delete(streamId);
}
}
}
async function waitForInProgress(events, streamId) {
while (true) {
const message = await readMessage(events);
if (
message.type === "response.in_progress" &&
message.stream_id === streamId
)
return;
}
}
const ws = new ResponsesWS(client);
// Keep one iterator so events stay queued while moving between phases.
const events = ws.stream();
try {
// Run two independent conversations in parallel.
sendCreate(
ws,
"planner",
"Draft a deployment plan for a stateless API service."
);
sendCreate(
ws,
"research",
"List common deployment risks for a stateless API service."
);
await drainUntilComplete(events, new Set(["planner", "research"]));
// Fork the planner conversation and continue its original branch in parallel.
const plannerResponseId = latestResponseIdByLane.get("planner");
sendCreate(
ws,
"critic",
"Find gaps in this deployment plan.",
plannerResponseId
);
// Let the fork load its parent before advancing the original lane's cache.
await waitForInProgress(events, "critic");
sendCreate(
ws,
"planner",
"Add rollback and monitoring steps to the plan.",
plannerResponseId
);
await drainUntilComplete(events, new Set(["critic", "planner"]));
} finally {
await events.return?.();
ws.close();
}
来源示例 18(python):
沿用程序文字译释285。
沿用程序文字译释286。
沿用程序文字译释287。
沿用程序文字译释288。
沿用程序文字译释289。
程序文字译释290:连接错误,后接事件JSON。
程序文字译释291:分叉启动前连接已关闭。
## [中文] 示例 18:完整示例;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:connection.response.create、client.responses.connect;异步调用及事件接收顺序保留。
from openai import OpenAI
from openai.resources.responses.responses import ResponsesConnection
client = OpenAI()
latest_response_id_by_lane: dict[str, str] = {}
def send_create(
connection: ResponsesConnection,
stream_id: str,
text: str,
previous_response_id: str | None = None,
):
if previous_response_id is None:
previous_response_id = latest_response_id_by_lane.get(stream_id)
connection.response.create(
stream_id=stream_id,
model="gpt-6-astra",
store=False,
input=[
{
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": text}],
}
],
previous_response_id=previous_response_id,
)
def drain_until_complete(
connection: ResponsesConnection, expected_stream_ids: set[str]
):
completed: set[str] = set()
for event in connection:
stream_id = event.stream_id
if event.type == "error" and stream_id is None:
raise RuntimeError(f"Connection error: {event.to_json()}")
if stream_id is None or stream_id not in expected_stream_ids:
continue
if event.type == "response.completed":
latest_response_id_by_lane[stream_id] = event.response.id
completed.add(stream_id)
if completed == expected_stream_ids:
return
elif event.type in {"response.failed", "response.incomplete", "error"}:
raise RuntimeError(f"Lane {stream_id} failed: {event.to_json()}")
raise RuntimeError("Connection closed before all responses finished.")
def wait_for_in_progress(connection: ResponsesConnection, expected_stream_id: str):
for event in connection:
if event.type == "error" and event.stream_id is None:
raise RuntimeError(f"Connection error: {event.to_json()}")
if event.stream_id != expected_stream_id:
continue
if event.type == "response.in_progress":
return
if event.type in {"response.failed", "response.incomplete", "error"}:
raise RuntimeError(f"Lane {expected_stream_id} failed: {event.to_json()}")
raise RuntimeError("Connection closed before the fork started.")
with client.responses.connect() as connection:
# 1. Run two independent conversations in parallel.
send_create(
connection, "planner", "Draft a deployment plan for a stateless API service."
)
send_create(
connection,
"research",
"List common deployment risks for a stateless API service.",
)
drain_until_complete(connection, {"planner", "research"})
# 2. Fork the planner conversation and continue the original branch in parallel.
planner_response_id = latest_response_id_by_lane["planner"]
send_create(
connection,
"critic",
"Find gaps in this deployment plan.",
previous_response_id=planner_response_id,
)
# Let the fork bind its parent before advancing the original lane.
wait_for_in_progress(connection, "critic")
send_create(
connection,
"planner",
"Add rollback and monitoring steps to the plan.",
previous_response_id=planner_response_id,
)
drain_until_complete(connection, {"critic", "planner"})
来源示例 19(ruby):
沿用程序文字译释268。
沿用程序文字译释286。
沿用程序文字译释287。
沿用程序文字译释288。
程序文字译释292:所有响应完成前连接已关闭。
程序文字译释293:补充回滚与监控步骤。
## [中文] 示例 19:完整示例;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:connection.response.create、client.responses.connect;异步调用及事件接收顺序保留。
require "async"
require "openai"
require "json"
def send_create(connection, stream_id, text, previous_response_id = nil)
payload = {
stream_id: stream_id,
model: "gpt-6-astra",
store: false,
input: [
{
role: "user",
content: text
}
]
}
payload[:previous_response_id] = previous_response_id if previous_response_id
connection.response.create(**payload)
end
def read_event(connection)
event = connection.receive or raise "Connection closed before all responses finished"
if ["response.failed", "response.incomplete", "error"].include?(event.type.to_s)
raise "Response failed: #{event.to_json}"
end
event
end
def drain_responses(connection, lanes, latest_ids)
remaining = lanes.dup
until remaining.empty?
event = read_event(connection)
next unless event.type.to_s == "response.completed"
lane = event.stream_id
next unless remaining.include?(lane)
latest_ids[lane] = event.response.id
remaining.delete(lane)
end
end
client = OpenAI::Client.new
Sync do |task|
task.with_timeout(120) do
client.responses.connect(request_options: { timeout: 10 }) do |connection|
latest_ids = {}
send_create(connection, "planner", "Draft a deployment plan for a stateless API service.")
send_create(connection, "research", "List common deployment risks for a stateless API service.")
drain_responses(connection, ["planner", "research"], latest_ids)
parent_id = latest_ids.fetch("planner")
send_create(connection, "critic", "Find gaps in this deployment plan.", parent_id)
# Let the fork load its parent before advancing the original lane's cache.
loop do
event = read_event(connection)
break if event.type.to_s == "response.in_progress" && event.stream_id == "critic"
end
send_create(connection, "planner", "Add rollback and monitoring steps.", parent_id)
drain_responses(connection, ["critic", "planner"], latest_ids)
puts(JSON.generate(latest_ids))
end
end
end
stream_id 必须为 1–256 个字符,只能包含字母、数字、下划线 _、连字符 - 和句点 .。仅在 WebSocket response.create 使用,不放入 HTTP POST /v1/responses。
命名流的服务端事件会带相同 stream_id,包括终结事件与请求级错误。
省略时使用隐式默认通道,其事件不带 stream_id,但排序和并发规则相同。空字符串无效,选择默认通道应省略字段。
连接行为与限制
- 单个响应内部沿用 Responses 流式事件模型,不同通道事件可交错。
- 同
stream_id请求先进先出、不重叠;不同 ID 可并发。 - 连接最长 60 分钟,到限后重新连接。
重连与恢复
连接关闭或达到 60 分钟后,所有通道的连接本地缓存都消失。新建 WebSocket,再逐通道恢复:
- 先前响应已
store=true保存且有有效 ID,使用previous_response_id加新增输入继续。 - 无法继续,例如
store=false、ZDR 或previous_response_not_found,将 ID 设为null或省略,发送该通道下一轮需要的完整上下文。 - 如经
/responses/compact压缩,以返回窗口为基础input,再追加最新用户或工具项。
需要处理的错误
服务器能关联命名通道时,错误事件包含 stream_id。请求级错误后,其他通道可继续。
previous_response_not_found:
来源示例 20(json):
程序文字译释294:找不到ID为resp_abc的先前响应。
{
"type": "error",
"status": 400,
"stream_id": "main",
"error": {
"type": "invalid_request_error",
"code": "previous_response_not_found",
"message": "Previous response with id 'resp_abc' not found.",
"param": "previous_response_id"
}
}
invalid_stream_id:
来源示例 21(json):
程序文字译释295:stream_id必须是非空字符串,最多256字符,只含字母、数字、下划线、连字符与句点。
{
"type": "error",
"status": 400,
"error": {
"type": "invalid_request_error",
"code": "invalid_stream_id",
"message": "The 'stream_id' field must be a non-empty string with at most 256 characters and may only contain letters, numbers, underscores, hyphens, and periods.",
"param": "stream_id"
}
}
websocket_stream_limit_reached:
来源示例 22(json):
程序文字译释296:连接已达到32个不同命名流的上限,请复用现有stream_id或新建WebSocket连接。
{
"type": "error",
"status": 400,
"stream_id": "agent_33",
"error": {
"type": "invalid_request_error",
"code": "websocket_stream_limit_reached",
"message": "This WebSocket connection has reached its maximum number of distinct stream IDs (32). Reuse an existing stream_id or open a new WebSocket connection.",
"param": "stream_id"
}
}
websocket_connection_limit_reached:
来源示例 23(json):
程序文字译释297:Responses WebSocket连接达到60分钟上限,请新建连接继续。
{
"type": "error",
"error": {
"type": "invalid_request_error",
"code": "websocket_connection_limit_reached",
"message": "Responses websocket connection limit reached (60 minutes). Create a new websocket connection to continue."
},
"status": 400
}