Réorientation en cours de tour

La réorientation en cours de tour permet aux utilisateurs d’ajouter des exigences ou de changer de direction sans attendre la fin d’une réponse.

La réorientation ne réécrit pas les sorties déjà envoyées à votre application, n’annule pas les actions précédentes et n’interrompt pas les outils dont l’exécution a déjà commencé.

Pour la configuration de la connexion et le fonctionnement général du transport, consultez Mode WebSocket. Pour les définitions exactes des événements, consultez la référence des événements WebSocket de l’API Responses.

Envoyez un message de réorientation

Démarrez une réponse avec response.create. Après réception de son événement response.created, envoyez response.steer sur la même connexion, en utilisant l’ID de cette réponse comme valeur de 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."
}

L’événement accepte uniquement type, previous_response_id et input. Définissez input sur une chaîne de caractères ou un tableau non vide de messages utilisateur dont les types de contenu sont pris en charge.

L’API confirme la mise en attente des entrées avec response.steer.accepted :

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

L’acceptation signifie que les entrées sont en attente, et non que le modèle en a tenu compte. L’API crée automatiquement une nouvelle réponse intégrant vos nouvelles instructions, sauf si elle attend un résultat d’outil ou une approbation de votre application.

Avant de créer cette continuation automatique, le serveur termine l’élément de sortie en cours et toute opération déjà lancée par un outil hébergé. Continuez à lire les événements pour recevoir la réponse intégrant vos nouvelles instructions ; n’envoyez pas d’autre response.create.

Si la réorientation interrompt la réponse initiale, celle-ci se termine avec response.incomplete et incomplete_details.reason: "steered". Si la réponse initiale se termine normalement avant cela, elle conserve son statut terminé et peut tout de même être suivie d’une continuation intégrant la réorientation.

Les continuations automatiques héritent des paramètres de la requête initiale. Les limites de tokens et d’appels d’outils s’appliquent séparément à chaque réponse.

Exécutez un exemple complet

Le SDK .NET ne fournit pas de client WebSocket pour Responses ; aucune variante utilisant le SDK C# n’est donc disponible pour cet exemple.

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

L’exemple envoie les nouvelles instructions après le premier événement response.created. Dans votre application, envoyez-les lorsqu’un utilisateur les fournit. Pour toute nouvelle réorientation, utilisez l’ID de la continuation dès réception de son événement response.created.

Renvoyez des résultats d’outils ou une approbation

Si la réponse nécessite un résultat d’outil côté client ou une approbation, l’API garde la réorientation en attente. Poursuivez votre workflow habituel de gestion des outils ou des approbations sur la même connexion.

Par exemple, la réponse initiale peut se terminer par un appel à get_project_status. Les charges utiles suivantes montrent uniquement les champs pertinents :

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\"}"
      }
    ]
  }
}

Une fois la réponse initiale terminée, l’API envoie response.steer.pending pour toute réorientation acceptée qui nécessite encore des entrées. Son champ required_input indique les résultats d’outils ou les approbations dont l’API a besoin avant de pouvoir appliquer les nouvelles instructions :

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

Renvoyez les entrées requises avec response.create sur la même connexion, en définissant previous_response_id sur resp_1. Ne répétez pas la réorientation acceptée. Un response.create explicite utilise ses propres outils, instructions et autres paramètres.

Les commentaires de cet exemple JSONC indiquent où le serveur ajoute les nouvelles instructions en attente :

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.",
    },
  ],
}

Vous n’avez pas besoin d’attendre response.steer.pending avant de renvoyer les résultats d’outils. Si le serveur a déjà reçu un response.create correspondant, il peut poursuivre sans envoyer cette notification au préalable.

Gérez les échecs et les déconnexions

response.steer.failed signifie que l’API n’a pas appliqué les entrées par réorientation et ne les appliquera pas automatiquement par la suite. L’événement renvoie les valeurs initiales de input et de previous_response_id sous steer, avec un objet error décrivant l’échec.

Suivez les envois acceptés à l’aide de steer.id. Un échec ultérieur utilise le même ID.

Codes d’erreur courants :

• invalid_input : Utilisez uniquement les champs d’événement pris en charge et des messages utilisateur en entrée.
• steering_not_supported : Le modèle, les paramètres de la requête ou les deux peuvent être incompatibles avec la réorientation.
• response_not_found : La réponse ciblée doit toujours être disponible sur la même connexion WebSocket.
• too_many_pending_steers : Trop d’entrées de réorientation sont en attente. Renvoyez les éventuels résultats d’outils ou approbations requis avec response.create ; sinon, attendez la continuation automatique avant d’envoyer d’autres entrées. Ne renvoyez pas de réorientation déjà acceptée.

Les entrées de réorientation en attente existent uniquement sur la connexion actuelle ; elles ne sont pas enregistrées avec la réponse initiale. Consignez les entrées de réorientation que vous envoyez et comparez-les aux événements de réponse et à l’historique avant de les renvoyer. Ne supposez pas que les réorientations en attente ont été conservées après la déconnexion. Consultez les consignes de reprise WebSocket.