Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

WebSocket-Modus

Nutze eine dauerhafte WebSocket-Verbindung für parallele Unterhaltungen, Forks von Antwortketten und inkrementelle Eingaben, um die Latenz in agentischen Workflows zu senken.

Die Responses API unterstützt einen WebSocket-Modus für lang laufende Workflows mit vielen Tool-Aufrufen. Der Modus senkt die Latenz und ermöglicht mit stream_id auch WebSocket-Multiplexing. Über eine dauerhafte Verbindung zu /v1/responses kannst du mehrere Unterhaltungen parallel führen und eine bestehende Unterhaltung auf einen neuen Stream forken. Sende für jede weitere Runde nur die neuen Eingabeelemente zusammen mit previous_response_id.

Der WebSocket-Modus ist sowohl mit der Einstellung „Keine Datenaufbewahrung“ (ZDR) als auch mit store=false kompatibel.

Wann sich der WebSocket-Modus lohnt

Der WebSocket-Modus ist besonders nützlich, wenn ein Workflow viele Aufrufe und Rückgaben zwischen Modell und Tools erfordert, etwa beim agentischen Programmieren oder in Orchestrierungsschleifen mit wiederholten Tool-Aufrufen.

Die Verbindung bleibt offen, und pro Runde werden nur neue Eingaben übertragen. Dadurch sinkt der Aufwand für jede Fortsetzung, und die Ende-zu-Ende-Latenz bei langen Antwortketten nimmt ab. Bei Durchläufen mit mindestens 20 Tool-Aufrufen haben wir beobachtet, dass die gesamte Ausführung bis zu rund 40 % schneller war.

Verbindung herstellen und Antworten erstellen

Installiere die WebSocket-Abhängigkeiten für Python mit pip install "openai[realtime]>=3.8.0", für JavaScript mit npm install openai@^7.10.0 ws oder für Ruby mit gem install openai async-websocket.

Führe für Go go get github.com/openai/openai-go/v3@v3.98.0 aus. Füge für Java die Maven-Abhängigkeit com.openai:openai-java:4.101.0 hinzu und verwende für diese Beispiele Java 17 oder höher. Diese Versionen der SDKs für Go und Java unterstützen WebSocket-Verbindungen zur Responses API nativ.

Starte im WebSocket-Modus jede Runde, indem du vom Client aus ein response.create-Ereignis sendest. Die Nutzdaten entsprechen dem üblichen Anfragetext zum Erstellen einer Antwort. Transportspezifische Felder wie stream und background entfallen.

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();
}

Clients können den Anfragezustand vorbereiten, indem sie response.create mit generate: false senden. Das ist nützlich, wenn du bereits weißt, welche Tools, Anweisungen oder benutzerdefinierten Nachrichten du in einer der nächsten Runden senden möchtest. Mit generate: false erhältst du keine Modellausgabe. Stattdessen bereitet der Dienst den Anfragezustand vor, damit die nächste Runde mit Modellgenerierung schneller starten kann. Die vorbereitende Anfrage liefert eine Antwort-ID, an die du mit previous_response_id anknüpfen kannst, auch in späteren Runden einer Antwortkette. Im nächsten Abschnitt erfährst du, wie du eine Sitzung mit previous_response_id und inkrementellen Eingaben fortsetzt.

Mit inkrementellen Eingaben fortfahren

Wenn du zusätzliche Nutzeranweisungen senden möchtest, während das Modell noch eine Antwort generiert, nutze die Steuerung während einer laufenden Runde. Dabei bleiben bereits erzielte Ergebnisse erhalten, und die Fortsetzung berücksichtigt die neuen Anweisungen. Um nach einer abgeschlossenen Runde fortzufahren oder Tool-Ergebnisse zu übermitteln, verwende das folgende Muster mit response.create.

Sende zur Fortsetzung eines Durchlaufs ein weiteres response.create-Ereignis mit diesen Feldern:

  • Setze previous_response_id auf die ID der vorherigen Antwort.
  • Übergib in input nur neue Elemente, etwa Tool-Ausgaben und die nächste Nutzernachricht.
import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/responses/ws";

const client = new OpenAI();
const model = "gpt-6-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();
}

So funktioniert die Fortsetzung

Im WebSocket-Modus verknüpfst du Antworten über previous_response_id nach denselben Regeln wie im HTTP-Modus. Über den aktiven Socket lässt sich die Antwortkette jedoch mit geringerer Latenz fortsetzen.

Solange eine WebSocket-Verbindung aktiv ist, hält der Dienst den Zustand kürzlich erstellter Antworten in einem Cache im Arbeitsspeicher dieser Verbindung vor. Wenn du stream_id verwendest, bleibt für jeden Stream dessen jüngste Antwort im Cache. An diese Antwort kannst du schnell anknüpfen, weil der Dienst den Zustand aus dem Cache der Verbindung wiederverwenden kann. Der Dienst hält den Zustand vorheriger Antworten ausschließlich im Arbeitsspeicher und schreibt ihn nicht auf die Festplatte. Deshalb kannst du den WebSocket-Modus mit store=false und der Einstellung „Keine Datenaufbewahrung“ (ZDR) nutzen.

Wenn der Cache im Arbeitsspeicher keinen Eintrag für previous_response_id enthält, hängt das Verhalten davon ab, ob du Antworten speicherst:

  • Mit store=true kann der Dienst den Zustand zu älteren Antwort-IDs nachladen, sofern er dauerhaft gespeichert wurde. Eine Fortsetzung ist dann weiterhin möglich, allerdings ohne den Latenzvorteil des Arbeitsspeichers.
  • Mit store=false (auch bei ZDR) gibt es keinen dauerhaft gespeicherten Zustand, auf den der Dienst zurückgreifen kann. Fehlt die ID im Cache, liefert die Anfrage previous_response_not_found.

Liefert eine Fortsetzung im selben Stream einen 4xx- oder 5xx-Fehler, entfernt der Dienst den Eintrag für die angegebene previous_response_id aus dem Cache der Verbindung. Schlägt ein Fork auf einen anderen Stream fehl, bleibt die gemeinsame Ausgangsantwort erhalten, sodass der ursprüngliche Stream fortgesetzt werden kann.

Kontextverdichtung und Erstellen neuer Antworten

Wenn du die Kontextverdichtung nutzt, gibt es zwei Möglichkeiten zur Fortsetzung:

Serverseitige Kontextverdichtung (context_management)

Wenn du die serverseitige Kontextverdichtung aktivierst (context_management mit compact_threshold), verdichtet der Dienst den Kontext während der regulären Antwortgenerierung über /responses. Im WebSocket-Modus fährst du wie gewohnt fort. Sende das nächste response.create-Ereignis mit der aktuellen previous_response_id und nur den neuen Eingabeelementen.

Eigenständiger Aufruf von /responses/compact

Der eigenständige Endpunkt /responses/compact gibt ein neues, verdichtetes Eingabefenster zurück. Eine Antwort-ID erhältst du dabei nicht. Erstelle nach der Kontextverdichtung über deine WebSocket-Verbindung eine neue Antwort. Übergib das verdichtete Fenster als input und füge die nächsten Nutzernachrichten oder Tool-Ergebnisse hinzu.

Starte eine neue Kette, indem du previous_response_id weglässt oder auf null setzt. Übergib die verdichtete Ausgabe unverändert und kürze das zurückgegebene Fenster nicht.

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();
}

Unterhaltungen parallel führen

Mit dem Parameter stream_id kannst du mehrere Unterhaltungen parallel über dieselbe Verbindung führen. Sende unabhängige response.create-Ereignisse mit unterschiedlichen Werten für stream_id direkt hintereinander. Der Server kann die Anfragen über eine einzige Verbindung gleichzeitig verarbeiten. Die Ereignisse verschiedener Streams können abwechselnd eintreffen. Verwende deshalb eine einzige Leseschleife und ordne jedes Ereignis anhand von stream_id dem jeweiligen Stream zu.

Eine stream_id bezeichnet einen Stream, dessen Anfragen innerhalb einer WebSocket-Verbindung in fester Reihenfolge verarbeitet werden. Unterscheide zwischen stream_id und previous_response_id:

  • stream_id bestimmt, welchem Stream Ereignisse zugeordnet werden und welche Anfragen der Dienst in der Reihenfolge ihres Eingangs verarbeitet.
  • previous_response_id bestimmt, an welche Antwort die Unterhaltung anknüpft.

Damit kannst du unabhängige Unterhaltungen parallel führen und bestehende Unterhaltungen forken.

eine WebSocket-Verbindung
├─ stream_id="planner"   Entwirf einen Bereitstellungsplan.
└─ stream_id="research"  Liste die Risiken der Bereitstellung auf.

Anfragen mit derselben stream_id werden nacheinander in der Reihenfolge ihres Eingangs verarbeitet. Anfragen mit unterschiedlichen Werten für stream_id können gleichzeitig laufen.

Limits pro Verbindung

  • Pro Verbindung können über alle benannten Streams und den Standardstream hinweg bis zu 16 Antworten gleichzeitig generiert werden. Die Verbindung nimmt weitere response.create-Ereignisse an und stellt sie in eine Warteschlange, bis eine der laufenden Antworten abgeschlossen ist.
  • Eine Verbindung akzeptiert bis zu 32 verschiedene Werte für stream_id, mit denen du Streams benennst. Der implizite Standardstream zählt nicht zu diesem Limit. Wenn du das Limit erreicht hast, verwende eine vorhandene stream_id erneut oder öffne eine neue Verbindung.

Eine Unterhaltung auf einen neuen Stream forken

Um eine Unterhaltung ausgehend von einer abgeschlossenen Antwort zu forken, sende deren ID als previous_response_id zusammen mit einer neuen stream_id. Solange die Antwort verfügbar ist, übernimmt der neue Stream ihren Kontext, und du kannst den ursprünglichen Stream weiterführen. Sobald der Fork gestartet ist, können beide Zweige gleichzeitig laufen, da sie unterschiedliche Stream-IDs verwenden.

Bei store=false (auch bei ZDR) kann ein Fork auf einen anderen Stream nur starten, solange die Ausgangsantwort noch im Cache der Verbindung liegt. Wird der ursprüngliche Stream fortgesetzt oder tritt dort ein Fehler auf, während der Fork in der Warteschlange steht, kann der Dienst die Ausgangsantwort aus dem Cache entfernen, bevor der Fork startet. Der Fork liefert dann previous_response_not_found. Warte, bis der neue Stream response.in_progress ausgibt, bevor du den ursprünglichen Stream fortsetzt. Alternativ kannst du die Anfrage wiederholen. Setze dabei previous_response_id auf null und sende den vollständigen Eingabekontext erneut.

main:   resp_1 ──▶ resp_2 ──▶ resp_3
                       ╲
critic:                 resp_4 ──▶ resp_5

Wenn du eine stream_id ohne previous_response_id erneut verwendest, startest du eine neue Antwort. Die bisherige Unterhaltung wird dabei nicht fortgesetzt.

So sehen die einzelnen Aufrufe aus:

# Ein Socket, zwei unabhängige Unterhaltungen.
send_create(connection, "planner", "Entwirf einen Bereitstellungsplan.")
send_create(connection, "research", "Liste die Risiken der Bereitstellung auf.")

# Forke die Antwort aus dem Stream „planner“ und setze dann den ursprünglichen Zweig parallel fort.
send_create(
    connection,
    "critic",
    "Finde Lücken in diesem Plan.",
    previous_response_id=planner_response_id,
)
wait_for_in_progress(connection, "critic")
send_create(
    connection,
    "planner",
    "Ergänze Schritte für ein Rollback.",
    previous_response_id=planner_response_id,
)

Vollständiges Beispiel

Unterhaltungen parallel führen und anschließend eine davon forken
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-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();
}

Eine stream_id muss 1 bis 256 Zeichen lang sein und darf nur Buchstaben, Ziffern, Unterstriche (_), Bindestriche (-) und Punkte (.) enthalten. Verwende sie ausschließlich in WebSocket-Ereignissen vom Typ response.create. Lass sie bei HTTP-Anfragen an POST /v1/responses weg.

Bei benannten Streams enthalten die Serverereignisse die zugehörige stream_id. Das gilt auch für Abschlussereignisse und Fehler, die eine einzelne Anfrage betreffen.

Wenn du stream_id weglässt, verwendet die Anfrage den impliziten Standardstream. Die zugehörigen Ereignisse enthalten keine stream_id. Ansonsten gelten für den Standardstream dieselben Regeln für Reihenfolge und Parallelität wie für benannte Streams. Ein leerer String ist keine gültige stream_id. Lass das Feld weg, um den Standardstream auszuwählen.

Verhalten und Limits der Verbindung

  • Die Ereignisse innerhalb jeder Antwort folgen dem bestehenden Ereignismodell der Responses API für das Streaming. Ereignisse verschiedener Streams können abwechselnd eintreffen.
  • Anfragen mit derselben stream_id laufen nacheinander in der Reihenfolge ihres Eingangs. Anfragen auf unterschiedlichen Streams können gleichzeitig laufen.
  • Verbindungen bleiben bis zu 60 Minuten offen. Stelle danach eine neue Verbindung her.

Verbindung erneut herstellen und Streams wiederaufnehmen

Wenn die Verbindung geschlossen wird oder das Limit von 60 Minuten erreicht, geht der Cache dieser Verbindung für alle Streams verloren. Öffne eine neue WebSocket-Verbindung. Je nach Ausgangslage kannst du jeden Stream wie folgt wiederaufnehmen:

  1. Wenn du eine frühere Antwort gespeichert hast (store=true) und eine gültige Antwort-ID hast, setze den Stream mit previous_response_id und den neuen Eingabeelementen fort.
  2. Wenn du einen Stream nicht fortsetzen kannst (etwa bei store=false/ZDR oder previous_response_not_found), starte eine neue Antwort. Setze dazu previous_response_id auf null oder lass das Feld weg. Sende den vollständigen Eingabekontext für die nächste Runde dieses Streams.
  3. Wenn du den Kontext mit /responses/compact verdichtet hast, verwende das zurückgegebene Fenster als Grundlage für input in der neuen Anfrage. Hänge die neuesten Nutzernachrichten oder Tool-Ergebnisse an.

Fehlerbehandlung

Wenn der Server einen Fehler einem benannten Stream zuordnen kann, enthält das Fehlerereignis die zugehörige stream_id. Nach einem Fehler, der nur eine einzelne Anfrage betrifft, können die anderen Streams weiterlaufen.

previous_response_not_found

{
  "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

{
  "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

{
  "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

{
  "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
}

Weiterführende Leitfäden