Responses API 支持 WebSocket 模式,适用于长时间运行且频繁调用工具的工作流。除了降低延迟,您还可以通过 stream_id 实现 WebSocket 多路复用:在一条连接到 /v1/responses 的持久连接上并行运行多个对话,并从现有对话派生分支,在新流上继续运行。接续每一轮对话时,只需发送新增的输入项和 previous_response_id。
WebSocket 模式兼容零数据保留(ZDR)和 store=false。
当工作流需要模型与工具之间进行多次往返交互时,WebSocket 模式尤其适用,例如智能体编程或反复调用工具的编排循环。
由于连接保持打开,且每轮只发送增量输入,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.104.0。
对于 Java,请添加 Maven 依赖 com.openai:openai-java:4.105.0,并使用 Java 17 或更高版本运行这些示例。
这些版本的 Go 和 Java SDK 原生支持 Responses API 的 WebSocket 模式。
在 WebSocket 模式下,客户端通过发送 response.create 事件开始每一轮对话。事件载荷与常规的创建响应请求体 一致,但不使用 stream 和 background 等特定于传输方式的字段。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43 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.2-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 ();
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26 from openai import OpenAI
client = OpenAI()
with client.responses.connect() as connection:
connection.response.create(
stream_id="main",
model="gpt-6.2-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.") 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27 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.2-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()) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28 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.2-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();
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31 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.2-astra", store: false,
input: [
{
role: "user",
content: "Find fizz_buzz()"
}
], tools: []
)
puts(wait_for_response(connection).output_text)
end
end
end
客户端可以发送 response.create 并设置 generate: false,提前准备请求状态。如果您已经确定接下来某一轮要发送的工具、指令或自定义消息,就可以使用这种方式。generate: false 不会返回模型输出,但会预先准备好请求状态,让下一轮生成更快开始。预热请求会返回一个响应 ID,您可以通过 previous_response_id 从该响应接续,也可以在响应链的后续轮次中使用这个 ID。下一节介绍如何使用 previous_response_id 和增量输入继续会话。
要在响应仍在生成时添加用户指令,请使用轮次内引导 。这样可以保留已完成的工作,并在接续时纳入新指令。要在两轮之间接续对话或提交工具结果,请按以下方式发送 response.create 事件。
要继续运行,请再发送一个 response.create 事件,并按如下方式设置字段:
将 previous_response_id 设为上一条响应的 ID。
在 input 中仅包含新增项,例如工具输出和下一条用户消息。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79 import OpenAI from "openai" ;
import { ResponsesWS } from "openai/resources/responses/ws" ;
const client = new OpenAI ();
const model = "gpt-6.2-astra" ;
const tools : OpenAI . Responses . Tool [] = [
{
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 : ResponsesWS ) {
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 ();
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74 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.2-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) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91 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.2-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.2-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()) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78 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.2-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.2-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();
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73 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.2-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.2-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
WebSocket 模式与 HTTP 模式使用相同的 previous_response_id 规则来串联响应,同时支持在当前打开的套接字上以更低的延迟接续对话。
在活动的 WebSocket 连接上,服务会将近期响应的状态保存在该连接专属的内存缓存中。使用 stream_id 时,每个通道都会缓存其最新响应。从该通道的最新响应接续时,服务可以复用当前连接中缓存的状态,因此接续速度很快。由于服务仅在内存中保留先前响应的状态,不将其写入磁盘,因此您可以在使用 store=false 或启用零数据保留(ZDR)的情况下使用 WebSocket 模式。
如果在内存缓存中找不到 previous_response_id,服务的行为取决于您是否存储响应:
使用 store=true 时,如果有可用的持久化状态,服务可以根据较早的响应 ID 从中恢复相应状态。对话仍有可能接续,但无法享受内存缓存带来的低延迟。
使用 store=false 时(包括启用 ZDR 的情况),没有可用于恢复的持久化状态。如果缓存中找不到该 ID,请求会返回 previous_response_not_found。
如果同一通道内的接续请求返回 4xx 或 5xx,服务会从当前连接的缓存中移除 previous_response_id 所引用的响应。如果跨通道派生分支时返回错误,服务会保留共享的父响应,以便源通道继续运行。
如果您使用上下文压缩,接续方式有以下两种:
服务端压缩(context_management)
启用服务端压缩(在 context_management 中设置 compact_threshold)后,压缩会在 /responses 正常生成响应时进行。在 WebSocket 模式下,按常规方式接续即可:发送下一个 response.create 事件,携带最新的 previous_response_id,并且只包含新增的输入项。
独立的 /responses/compact 端点 会返回一个新的压缩后输入窗口,而不是响应 ID。压缩完成后,在 WebSocket 连接上创建新响应,将压缩后的窗口用作 input,并追加接下来的用户消息或工具项。
省略 previous_response_id 或将其设为 null,即可开始新的响应链。请原样传入压缩输出,不要删减返回的窗口内容。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47 import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems" ;
// Compact your current window with an HTTP request.
const compacted = await client.responses. compact ({
model: "gpt-6.2-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.2-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 ();
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39 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.2-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.2-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.") 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46 package main
import (
"context"
"encoding/json"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
"log"
"time"
)
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
compacted, err := client.Responses.Compact(ctx, responses.ResponseCompactParams{Model: "gpt-6.2-astra", Input: responses.ResponseCompactParamsInputUnion{OfResponseInputItemArray: responses.ResponseInputParam{responses.ResponseInputItemParamOfMessage("Find the failing test.", responses.EasyInputMessageRoleUser)}}})
if err != nil {
log.Fatal(err)
}
input := responses.ResponseInputParam{}
for _, item := range compacted.Output {
var converted responses.ResponseInputItemUnion
if err := json.Unmarshal([]byte(item.RawJSON()), &converted); err != nil {
log.Fatal(err)
}
input = append(input, converted.ToParam())
}
input = append(input, responses.ResponseInputItemParamOfMessage("Continue from here.", responses.EasyInputMessageRoleUser))
conn, err := client.Responses.Connect(ctx, responses.ResponseConnectionOptions{})
if err != nil {
log.Fatal(err)
}
defer conn.Close()
if err := conn.Create(ctx, responses.ResponsesClientEventResponseCreateParam{StreamID: openai.String("main"), Model: "gpt-6.2-astra", Store: openai.Bool(false), Input: responses.ResponsesClientEventResponseCreateInputUnionParam{OfResponse: &input}, 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())
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41 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.2-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.2-astra", store: false,
input: next_input, tools: []
)
puts(wait_for_response(connection).output_text)
end
end
end
您可以使用 stream_id 参数,在同一连接上同时维持多个对话。连续发送多个独立的 response.create 事件,并为它们指定不同的 stream_id 值。服务器可以在同一连接上并发处理这些请求。不同请求的事件可能交错到达,因此请使用一个读取循环,并根据 stream_id 分发每个事件。
stream_id 用于标识一条 WebSocket 连接上的一个有序通道。请区分 stream_id 和 previous_response_id 的作用:
stream_id 决定事件发往哪个通道,以及哪些请求按先进先出的顺序运行。
previous_response_id 决定当前对话从哪条响应接续。
这两个参数各司其职,因此可以支持两种用法。
一条 WebSocket 连接
├─ stream_id="planner" 起草部署计划
└─ stream_id="research" 列出部署风险
具有相同 stream_id 的请求按先进先出的顺序运行,执行时间不会重叠。具有不同 stream_id 值的请求可以并发运行。
一条连接上的所有命名通道和默认通道合计最多可以有 16 个正在处理的响应。连接可以继续接受 response.create 事件,并将其排队,直到有正在处理的响应完成。
一条连接最多接受 32 个不同的命名 stream_id 值。隐式默认通道不计入这一命名流数量上限。达到上限后,请复用现有的 stream_id 或打开新连接。
要从已完成的响应派生分支,请将该响应的 ID 作为 previous_response_id,与新的 stream_id 一起发送。只要该响应仍然可用,新流就能继承其上下文,原来的流也可以继续运行。派生的分支启动后,两个分支可以并发运行,因为它们使用不同的流 ID。
使用 store=false 时(包括启用 ZDR 的情况),跨通道派生分支要求父响应仍在当前连接的缓存中。如果派生请求正在排队,而源通道已进入下一轮或运行失败,父响应可能会在分支启动前被移出缓存,此时派生请求会返回 previous_response_not_found。请等待分支所在的通道发出 response.in_progress 事件后,再让源通道进入下一轮。您也可以将 previous_response_id 设为 null,重新发送完整的输入上下文以重试。
main: resp_1 ──▶ resp_2 ──▶ resp_3
╲
critic: resp_4 ──▶ resp_5
复用 stream_id 时,如果未指定 previous_response_id,就会开始一个新响应,不会接续原来的对话。
关键调用如下:
# 在同一套接字上运行两个独立对话。
send_create(connection, "planner", "起草一份部署计划。")
send_create(connection, "research", "列出部署风险。")
# 从 planner 的响应派生分支,然后让原分支与新分支并行运行。
send_create(
connection,
"critic",
"找出这份计划中的疏漏。",
previous_response_id=planner_response_id,
)
wait_for_in_progress(connection, "critic")
send_create(
connection,
"planner",
"补充回滚步骤。",
previous_response_id=planner_response_id,
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120 import OpenAI from "openai" ;
import type { ResponsesStreamMessage } from "openai/resources/responses/internal-base.mjs" ;
import { ResponsesWS } from "openai/resources/responses/ws" ;
const client = new OpenAI ();
const latestResponseIdByLane = new Map ();
function sendCreate (
ws : ResponsesWS ,
streamId : string ,
text : string ,
previousResponseId = latestResponseIdByLane. get (streamId)
) {
ws. send ({
type: "response.create" ,
stream_id: streamId,
model: "gpt-6.2-astra" ,
store: false ,
input: [
{
type: "message" ,
role: "user" ,
content: [{ type: "input_text" , text }],
},
],
previous_response_id: previousResponseId,
});
}
async function readMessage (
events : AsyncIterableIterator < ResponsesStreamMessage >
) {
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 : AsyncIterableIterator < ResponsesStreamMessage >,
expectedStreamIds : Iterable < unknown > | null | undefined
) {
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 : AsyncIterableIterator < ResponsesStreamMessage >,
streamId : string
) {
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 ();
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93 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.2-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"}) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97 package main
import (
"context"
"encoding/json"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
"log"
"os"
"time"
)
func sendCreate(ctx context.Context, conn *responses.ResponseConnection, lane, text, parent string) error {
input := responses.ResponseInputParam{responses.ResponseInputItemParamOfMessage(text, responses.EasyInputMessageRoleUser)}
command := responses.ResponsesClientEventResponseCreateParam{StreamID: openai.String(lane), Model: "gpt-6.2-astra", Store: openai.Bool(false), Input: responses.ResponsesClientEventResponseCreateInputUnionParam{OfResponse: &input}}
if parent != "" {
command.PreviousResponseID = openai.String(parent)
}
return conn.Create(ctx, command)
}
func readEvent(ctx context.Context, conn *responses.ResponseConnection) (responses.ResponsesServerEventUnion, error) {
event, err := conn.Recv(ctx)
if err != nil {
return event, err
}
switch event.Type {
case "error", "response.failed", "response.incomplete":
return event, fmt.Errorf("response failed: %s", event.RawJSON())
}
return event, nil
}
func drainResponses(ctx context.Context, conn *responses.ResponseConnection, latest map[string]string, lanes ...string) error {
remaining := map[string]bool{}
for _, lane := range lanes {
remaining[lane] = true
}
for len(remaining) > 0 {
event, err := readEvent(ctx, conn)
if err != nil {
return err
}
if event.Type != "response.completed" {
continue
}
completed := event.AsResponseCompleted()
if !remaining[completed.StreamID] {
continue
}
latest[completed.StreamID] = completed.Response.ID
delete(remaining, completed.StreamID)
}
return nil
}
func main() {
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()
latest := map[string]string{}
if err := sendCreate(ctx, conn, "planner", "Draft a deployment plan for a stateless API service.", ""); err != nil {
log.Fatal(err)
}
if err := sendCreate(ctx, conn, "research", "List common deployment risks for a stateless API service.", ""); err != nil {
log.Fatal(err)
}
if err := drainResponses(ctx, conn, latest, "planner", "research"); err != nil {
log.Fatal(err)
}
parent := latest["planner"]
if err := sendCreate(ctx, conn, "critic", "Find gaps in this deployment plan.", parent); err != nil {
log.Fatal(err)
}
// Let the fork load its parent before advancing the original lane's cache.
for {
event, err := readEvent(ctx, conn)
if err != nil {
log.Fatal(err)
}
if event.Type == "response.in_progress" && event.AsResponseInProgress().StreamID == "critic" {
break
}
}
if err := sendCreate(ctx, conn, "planner", "Add rollback and monitoring steps.", parent); err != nil {
log.Fatal(err)
}
if err := drainResponses(ctx, conn, latest, "critic", "planner"); err != nil {
log.Fatal(err)
}
if err := json.NewEncoder(os.Stdout).Encode(latest); err != nil {
log.Fatal(err)
}
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64 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.2-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,请求会使用隐式默认通道,其事件中不包含 stream_id。除此之外,默认通道遵循与命名流相同的排序和并发规则。空字符串不是有效的 stream_id。要选择默认通道,请省略该字段。
每个响应内的事件遵循现有的 Responses 流式事件模型。不同通道的事件可能交错到达。
具有相同 stream_id 的请求按先进先出的顺序运行,执行时间不会重叠。不同通道上的请求可以并发运行。
每条连接最多持续 60 分钟。达到时限后,请重新连接。
当连接关闭或达到 60 分钟的时限时,该连接上所有通道的缓存都会随之清除。请打开新的 WebSocket 连接,并根据各通道的情况选择以下方式恢复:
如果您已存储先前的响应(store=true)且持有有效的响应 ID,请使用 previous_response_id 和新增的输入项接续该通道上的对话。
如果无法接续某个通道上的对话(例如,使用了 store=false 或 ZDR,或收到了 previous_response_not_found 错误),请将 previous_response_id 设为 null(或省略该字段)以开始新响应,并发送该通道下一轮所需的完整输入上下文。
如果您使用 /responses/compact 压缩了上下文,请将返回的压缩后窗口用作新响应的基础 input,然后追加最新的用户消息或工具项。
如果服务器能确定错误属于哪个命名通道,错误事件中就会包含 stream_id。单个请求出错后,其他通道仍可继续运行。
previous_response_not_found
1 2 3 4 5 6 7 8 9 10 11 {
"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
1 2 3 4 5 6 7 8 9 10 {
"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
1 2 3 4 5 6 7 8 9 10 11 {
"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
1 2 3 4 5 6 7 8 9 {
"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
}