Während der Ausführung nachsteuern

Durch Nachsteuern während der Ausführung können Nutzende Anforderungen ergänzen oder die Richtung ändern, ohne auf den Abschluss einer Antwort zu warten.

Nachsteuern verändert keine Ausgaben, die bereits an deine Anwendung gesendet wurden, macht keine früheren Aktionen rückgängig und bricht keine bereits gestarteten Tools ab.

Informationen zum Verbindungsaufbau und zum allgemeinen Übertragungsverhalten findest du unter WebSocket-Modus. Die genauen Ereignisdefinitionen findest du in der Referenz zu den WebSocket-Ereignissen der Responses API.

Eine Nachricht zum Nachsteuern senden

Starte eine Antwort mit response.create. Sobald du das zugehörige Ereignis response.created empfangen hast, sende response.steer über dieselbe Verbindung und verwende die ID dieser Antwort als previous_response_id:

12345{
  "type": "response.steer",
  "previous_response_id": "resp_1",
  "input": "Keep the scope small enough for one developer to finish in two weeks."
}

Das Ereignis akzeptiert nur type, previous_response_id und input. Setze input auf einen String oder ein nicht leeres Array aus Nutzernachrichten mit unterstützten Inhaltstypen.

Die API bestätigt mit response.steer.accepted, dass die Eingabe in die Warteschlange aufgenommen wurde:

12345678{
  "type": "response.steer.accepted",
  "sequence_number": 4,
  "steer": {
    "id": "steer_0123456789abcdef0123456789abcdef",
    "previous_response_id": "resp_1"
  }
}

Die Annahme bedeutet, dass sich die Eingabe in der Warteschlange befindet, nicht, dass das Modell sie bereits umgesetzt hat. Die API erstellt automatisch eine neue Antwort mit deinen neuen Angaben, sofern sie kein Tool-Ergebnis oder eine Genehmigung von deiner Anwendung benötigt.

Bevor der Server diese automatische Fortsetzung erstellt, schließt er das aktuelle Ausgabeelement sowie alle bereits laufenden Arbeiten gehosteter Tools ab. Lies weiterhin Ereignisse, um die Antwort mit deinen neuen Angaben zu empfangen. Sende kein weiteres response.create.

Wenn das Nachsteuern die ursprüngliche Antwort unterbricht, endet sie mit response.incomplete und incomplete_details.reason: "steered". Wenn die ursprüngliche Antwort vorher regulär abgeschlossen wird, behält sie ihren Status als abgeschlossen und kann dennoch eine Fortsetzung mit den neuen Angaben erhalten.

Automatische Fortsetzungen übernehmen die Einstellungen der ursprünglichen Anfrage. Limits für Token und Tool-Aufrufe gelten für jede Antwort separat.

Ein vollständiges Beispiel ausführen

Das .NET SDK bietet keinen WebSocket-Client für Responses. Daher ist für dieses Beispiel keine Variante mit dem C# SDK verfügbar.

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// Set OPENAI_API_KEY before running this example.
// Install the SDK and WebSocket transport: npm install openai ws

import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/responses/ws";

const client = new OpenAI();
const ws = new ResponsesWS(client, {
  handshakeTimeout: 10_000,
});
let initialResponseId = "";
let successorResponseId = "";
let timeout;

try {
  const output = await new Promise((resolve, reject) => {
    timeout = setTimeout(() => {
      reject(new Error("Timed out waiting for the steered response."));
      ws.close();
    }, 120_000);
    ws.once("error", reject);
    ws.once("close", () => {
      reject(
        new Error("Connection closed before the steered response finished.")
      );
    });
    ws.on("event", (event) => {
      try {
        if (event.type === "response.created") {
          if (!initialResponseId) {
            initialResponseId = event.response.id;
            // Simulate a user adding instructions while the response runs.
            ws.send({
              type: "response.steer",
              previous_response_id: initialResponseId,
              input:
                "Keep the scope small enough for one developer to finish in two weeks.",
            });
          } else {
            successorResponseId = event.response.id;
          }
        } else if (
          ["response.steer.failed", "response.failed", "error"].includes(
            event.type
          )
        ) {
          reject(new Error(JSON.stringify(event)));
        } else if (
          event.type === "response.incomplete" &&
          (event.response.id !== initialResponseId ||
            event.response.incomplete_details?.reason !== "steered")
        ) {
          reject(new Error(JSON.stringify(event)));
        } else if (
          event.type === "response.completed" &&
          event.response.id === successorResponseId
        ) {
          let text = "";
          for (const item of event.response.output) {
            if (item.type !== "message") continue;
            for (const part of item.content) {
              if (part.type === "output_text") text += part.text;
            }
          }
          resolve(text);
        }
        // Acceptance only queues the input. Keep reading past the first response.
      } catch (error) {
        reject(error);
      }
    });
    ws.send({
      type: "response.create",
      model: "gpt-6-astra",
      reasoning: { effort: "medium" },
      input: "Draft a project plan for building a task-tracking app.",
    });
  });
  console.log(output);
} finally {
  clearTimeout(timeout);
  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
48import asyncio

from openai import AsyncOpenAI


async def main():
    client = AsyncOpenAI()
    initial_response_id = None
    successor_response_id = None

    async with client.responses.connect() as connection, asyncio.timeout(120):
        await connection.response.create(
            model="gpt-6-astra",
            reasoning={"effort": "medium"},
            input="Draft a project plan for building a task-tracking app.",
        )
        async for event in connection:
            if event.type == "response.created":
                if initial_response_id is None:
                    initial_response_id = event.response.id
                    # Simulate a user adding instructions while the response runs.
                    await connection.response.steer(
                        previous_response_id=initial_response_id,
                        input="Keep the scope small enough for one developer to finish in two weeks.",
                    )
                else:
                    successor_response_id = event.response.id
            elif event.type in {"response.steer.failed", "response.failed", "error"}:
                raise RuntimeError(event.to_json())
            elif event.type == "response.incomplete":
                response = event.response
                if (
                    response.id != initial_response_id
                    or response.incomplete_details is None
                    or response.incomplete_details.reason != "steered"
                ):
                    raise RuntimeError(event.to_json())
            elif (
                event.type == "response.completed"
                and event.response.id == successor_response_id
            ):
                print(event.response.output_text)
                return
            # Acceptance only queues the input. Keep reading past the first response.
        raise RuntimeError("Connection closed before the steered response finished.")


asyncio.run(main())

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
45require "async"
require "openai"

client = OpenAI::Client.new
Sync do |task|
  task.with_timeout(120) do
    client.responses.connect(request_options: { timeout: 10 }) do |connection|
      connection.response.create(
        model: "gpt-6-astra", reasoning: { effort: "medium" },
        input: "Draft a project plan for building a task-tracking app."
      )
      state = {}
      while (event = connection.receive)
        case event
        when OpenAI::Responses::ResponseCreatedEvent
          response = event.response
          if !state[:initial_id]
            state[:initial_id] = response.id
            connection.send_event(
              type: "response.steer", previous_response_id: state[:initial_id],
              input: "Keep the scope small enough for one developer to finish in two weeks."
            )
          else
            state[:successor_id] = response.id
          end
        when OpenAI::Responses::ResponseSteerFailedEvent, OpenAI::Responses::ResponseFailedEvent, OpenAI::Responses::ResponsesServerEvent::ResponseWsError
          raise "Steering failed: #{event.to_json}"
        when OpenAI::Responses::ResponseIncompleteEvent
          response = event.response
          unless response.id == state[:initial_id] && response.incomplete_details&.reason.to_s == "steered"
            raise "Response incomplete: #{event.to_json}"
          end
        when OpenAI::Responses::ResponseCompletedEvent
          response = event.response
          next unless state[:successor_id] && response.id == state[:successor_id]

          puts(response.output_text)
          state[:completed] = true
          break
        end
      end
      raise "Connection closed before the steered response finished" unless state[:completed]
    end
  end
end

Das Beispiel sendet die neuen Angaben nach dem ersten Ereignis response.created. Sende sie in deiner Anwendung, sobald Nutzende neue Angaben machen. Verwende zum weiteren Nachsteuern die ID der Fortsetzung, sobald deren Ereignis response.created eintrifft.

Tool-Ergebnisse oder eine Genehmigung zurückgeben

Wenn die Antwort ein Ergebnis eines clientseitigen Tools oder eine Genehmigung benötigt, lässt die API die Eingabe zum Nachsteuern in der Warteschlange. Setze deinen üblichen Tool- oder Genehmigungsablauf über dieselbe Verbindung fort.

Die ursprüngliche Antwort kann beispielsweise mit einem Aufruf von get_project_status enden. Die folgenden Payloads zeigen nur die relevanten Felder:

123456789101112131415{
  "type": "response.completed",
  "response": {
    "id": "resp_1",
    "status": "completed",
    "output": [
      {
        "type": "function_call",
        "call_id": "call_project",
        "name": "get_project_status",
        "arguments": "{\"project\":\"task-tracker\"}"
      }
    ]
  }
}

Nach Abschluss der ursprünglichen Antwort sendet die API response.steer.pending für angenommene Eingaben zum Nachsteuern, für die noch weitere Eingaben benötigt werden. Das Feld required_input gibt an, welche Tool-Ergebnisse oder Genehmigungen die API benötigt, bevor sie die neuen Angaben anwenden kann:

12345678910111213141516{
  "type": "response.steer.pending",
  "sequence_number": 12,
  "steer": {
    "id": "steer_0123456789abcdef0123456789abcdef",
    "previous_response_id": "resp_1"
  },
  "reason": "waiting_for_required_input",
  "required_input": [
    {
      "type": "function_call_output",
      "call_id": "call_project",
      "name": "get_project_status"
    }
  ]
}

Gib die erforderliche Eingabe mit response.create über dieselbe Verbindung zurück und setze dabei previous_response_id auf resp_1. Wiederhole die bereits angenommene Eingabe zum Nachsteuern nicht. Ein explizites response.create verwendet eigene Tools, Anweisungen und sonstige Einstellungen.

Die Kommentare in diesem JSONC-Beispiel zeigen, wo der Server die neuen Angaben aus der Warteschlange einfügt:

123456789101112131415161718{
  "type": "response.create",
  "model": "gpt-6-astra",
  "previous_response_id": "resp_1",
  "input": [
    // The server implicitly prepends your accepted steer here:
    // "Keep the scope small enough for one developer to finish in two weeks."
    {
      "type": "function_call_output",
      "call_id": "call_project",
      "output": "Design is complete. Development has not started.",
    },
    {
      "role": "user",
      "content": "Show me the updated plan before starting any work.",
    },
  ],
}

Du musst nicht auf response.steer.pending warten, bevor du Tool-Ergebnisse zurückgibst. Wenn der Server bereits ein passendes response.create empfangen hat, kann er fortfahren, ohne zuvor diese Benachrichtigung zu senden.

Fehler und Verbindungsabbrüche behandeln

response.steer.failed bedeutet, dass die API die Eingabe nicht zum Nachsteuern angewendet hat und dies auch später nicht automatisch tun wird. Das Ereignis gibt die ursprünglichen Werte von input und previous_response_id unter steer zurück, zusammen mit einem error-Objekt, das den Fehler beschreibt.

Verfolge angenommene Eingaben anhand von steer.id. Ein späterer Fehler verwendet dieselbe ID.

Häufige Fehlercodes:

• invalid_input: Verwende nur die unterstützten Ereignisfelder und Nutzernachrichten als Eingabe.
• steering_not_supported: Das Modell, die Anfrageparameter oder beides sind möglicherweise nicht mit dem Nachsteuern kompatibel.
• response_not_found: Die Zielantwort muss noch über dieselbe WebSocket-Verbindung verfügbar sein.
• too_many_pending_steers: Es sind zu viele Eingaben zum Nachsteuern ausstehend. Gib alle erforderlichen Tool-Ergebnisse oder Genehmigungen mit response.create zurück. Andernfalls warte auf die automatische Fortsetzung, bevor du weitere Eingaben sendest. Sende bereits angenommene Eingaben zum Nachsteuern nicht erneut.

Eingaben zum Nachsteuern in der Warteschlange existieren nur auf der aktuellen Verbindung. Sie werden nicht zusammen mit der ursprünglichen Antwort gespeichert. Protokolliere die gesendeten Eingaben zum Nachsteuern und gleiche sie mit den Antwortereignissen und dem Verlauf ab, bevor du sie erneut sendest. Gehe nicht davon aus, dass ausstehende Eingaben zum Nachsteuern nach einem Verbindungsabbruch erhalten geblieben sind. Siehe die Hinweise zur Wiederherstellung bei WebSockets.