WebSocket 模式

该模式同时支持 Zero Data Retention（ZDR）和 store=false，因为延续对话不需要访问 Persistent Storage。

适用场景

WebSocket 模式面向包含大量连续 Tool Call 的 Agent workload，例如 Coding Agent、Orchestration Loop，以及任何需要与模型往返数十次的任务。

每个轮次都会跳过 Connection Setup，并且只重新发送新的 input，而不是完整对话；在长时间 rollout 中，这会带来显著收益。在包含大量 Tool Call 的 Agent workload 内部 benchmark 中，与使用相同 previous_response_id 串联的重复 HTTP Request 相比，我们测得 end-to-end latency 最多降低约 20%。

建立连接并发送首个轮次

WebSocket Upgrade 成功后，每个轮次都由 Client 发送 response.create message 发起。Body 结构与Responses Create Body相同，但不包含 stream 和 background 等仅用于 transport 的字段（response 始终以 event 形式在 Socket 上流式返回）。

import json
import os
from websocket import create_connection

ws = create_connection(
    "wss://api.x.ai/v1/responses",
    header=[
        f"Authorization: Bearer {os.environ['XAI_API_KEY']}",
    ],
)

ws.send(
    json.dumps(
        {
            "type": "response.create",
            "model": "grok-4.5",
            "store": False,
            "input": [
                {
                    "type": "message",
                    "role": "user",
                    "content": [{"type": "input_text", "text": "Find fizz_buzz()"}],
                }
            ],
            "tools": [],
        }
    )
)

import WebSocket from "ws";

const ws = new WebSocket("wss://api.x.ai/v1/responses", {
  headers: {
    Authorization: \`Bearer \${process.env.XAI_API_KEY}\`,
  },
});

ws.on("open", () => {
  ws.send(
    JSON.stringify({
      type: "response.create",
      model: "grok-4.5",
      store: false,
      input: [
        {
          type: "message",
          role: "user",
          content: [{ type: "input_text", text: "Find fizz_buzz()" }],
        },
      ],
      tools: [],
    })
  );
});

ws.on("message", (data) => {
  console.log(JSON.parse(data.toString()));
});

使用预热参数 generate: false

如果已经知道后续轮次需要的 Tool、instruction 或 system message，可以发送 response.create 并设置 generate: false 来预热连接。Server 会准备 Request State，但不会运行模型，也不会返回 output。Warmup 仍会生成 response ID，之后可以通过 previous_response_id 从该 ID 继续，让实际生成轮次更快启动。

继续运行

每个后续轮次都发送新的 response.create，并包含：

• previous_response_id — 当前 chain 中上一个 response 的 ID。

• input — 仅包含当前轮次的新 item（通常是 Tool Output 和下一条 user message）。不要重新发送先前历史，Server 已经保存。

ws.send(
    json.dumps(
        {
            "type": "response.create",
            "model": "grok-4.5",
            "store": False,
            "previous_response_id": "resp_123",
            "input": [
                {
                    "type": "function_call_output",
                    "call_id": "call_123",
                    "output": "tool result",
                },
                {
                    "type": "message",
                    "role": "user",
                    "content": [{"type": "input_text", "text": "Now optimize it."}],
                },
            ],
            "tools": [],
        }
    )
)

ws.send(
  JSON.stringify({
    type: "response.create",
    model: "grok-4.5",
    store: false,
    previous_response_id: "resp_123",
    input: [
      {
        type: "function_call_output",
        call_id: "call_123",
        output: "tool result",
      },
      {
        type: "message",
        role: "user",
        content: [{ type: "input_text", text: "Now optimize it." }],
      },
    ],
    tools: [],
  })
);

Socket 上的 Chaining 工作原理

previous_response_id 的行为与 HTTP 相同，但 WebSocket Path 还有额外的 in-memory shortcut。每个已打开连接都会在 per-connection cache 中保存最近一次 response 的状态。从该 response 继续时完全无需访问 Storage，因此 WebSocket 模式可以安全地与 store=false 和 ZDR 一起使用。

如果引用的旧 previous_response_id 已不在 Connection Cache 中：

• 使用 store=true 时，Server 可以从 Persisted State 恢复，但会失去 in-memory latency 优势。

• 使用 store=false 或 ZDR 时，没有 Fallback Storage 可供读取，该轮次会以 previous_response_not_found 失败。

失败的轮次（4xx 或 5xx）会从 Connection Cache 中清除对应的 previous_response_id，避免重试从损坏状态继续。

连接限制与行为

• Event 类型和顺序与现有 Responses Streaming 格式完全相同。

• 单个连接会串行处理轮次；在一个 response.create 正在进行时发送第二个，只会排队，不会 multiplex。

• 需要并行轮次时，请打开多个连接。

• 单个连接最多保持打开 25 分钟。之后 Server 会关闭连接，需要重新连接。

重新连接

Socket 中断（网络波动、部署或达到 25 分钟上限）时，打开新连接并选择适用的恢复路径：

1. 如果使用了 store=true 且仍有有效 response ID，直接在新 Socket 上使用 previous_response_id 和新的 input item 继续。

2. 否则（例如 store=false 或遇到 previous_response_not_found），完全移除 previous_response_id，并通过发送下一轮的完整 input context 开始新的 chain。

错误

部分 Error Response 是 WebSocket 模式特有的，值得显式处理。

previous_response_not_found

当请求的 previous_response_id 不在 Connection Cache 中，且无法从 Storage 恢复时返回（例如 ZDR、store=false，或因先前失败被清除）。

{
  "type": "error",
  "status": 400,
  "error": {
    "code": "previous_response_not_found",
    "message": "Previous response with id 'resp_abc' not found.",
    "param": "previous_response_id"
  }
}

websocket_connection_limit_reached

Server 即将关闭已达到最长 25 分钟的连接时发送。请打开新的 WebSocket，并使用上述任一模式重新连接。

{
  "type": "error",
  "status": 400,
  "error": {
    "type": "invalid_request_error",
    "code": "websocket_connection_limit_reached",
    "message": "Responses websocket connection limit reached (25 minutes). Create a new websocket connection to continue."
  }
}

相关指南

• Streaming

• Function Calling

• Responses API Reference