Orientación durante el turno

La orientación durante el turno permite a los usuarios agregar requisitos o cambiar de rumbo sin esperar a que termine una respuesta.

La orientación no reescribe la salida ya enviada a tu aplicación, no deshace acciones anteriores ni cancela herramientas que ya se hayan iniciado.

Para conocer la configuración de la conexión y el comportamiento general del transporte, consulta Modo WebSocket. Para ver las definiciones exactas de los eventos, consulta la referencia de eventos WebSocket de Responses.

Enviar un mensaje de orientación

Inicia una respuesta con response.create. Después de recibir su evento response.created, envía response.steer por la misma conexión, usando el ID de esa respuesta como 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."
}

El evento solo acepta type, previous_response_id y input. Establece input en una cadena o un arreglo no vacío de mensajes de usuario con tipos de contenido compatibles.

La API confirma que la entrada está en cola con response.steer.accepted:

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

La aceptación significa que la entrada está en cola, no que el modelo haya actuado en función de ella. La API crea automáticamente una nueva respuesta con tu actualización, a menos que necesite un resultado de herramienta o una aprobación de tu aplicación.

Antes de crear esta continuación automática, el servidor termina el elemento de salida actual y cualquier trabajo de herramientas alojadas que ya esté en ejecución. Sigue leyendo eventos para recibir la respuesta con tu actualización; no envíes otro response.create.

Si la orientación interrumpe la respuesta original, esta termina con response.incomplete y incomplete_details.reason: "steered". Si la respuesta original termina normalmente antes, conserva su estado de completada y aun así puede tener una continuación de orientación.

Las continuaciones automáticas heredan la configuración de la solicitud original. Los límites de tokens y de llamadas a herramientas se aplican por separado a cada respuesta.

Ejecutar un ejemplo completo

El SDK de .NET no proporciona un cliente WebSocket de Responses, por lo que no hay una variante con el SDK de C# para este ejemplo.

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

El ejemplo envía la actualización después del primer evento response.created. En tu aplicación, envíala cuando un usuario proporcione una actualización. Usa el ID de la continuación para enviar nueva orientación una vez que llegue su evento response.created.

Devolver resultados de herramientas o una aprobación

Si la respuesta necesita un resultado de una herramienta del cliente o una aprobación, la API mantiene la orientación en cola. Continúa tu flujo habitual de herramientas o aprobación en la misma conexión.

Por ejemplo, la respuesta original puede completarse con una llamada a get_project_status. Las siguientes cargas útiles muestran solo los campos pertinentes:

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

Después de que se completa la respuesta original, la API envía response.steer.pending para la orientación aceptada que aún necesita datos de entrada. Su campo required_input identifica los resultados de herramientas o las aprobaciones que la API necesita antes de poder aplicar la actualización:

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

Devuelve los datos de entrada requeridos con response.create por la misma conexión, estableciendo previous_response_id en resp_1. No repitas la orientación aceptada. Un response.create explícito usa sus propias herramientas, instrucciones y demás ajustes.

Los comentarios de este ejemplo JSONC muestran dónde agrega el servidor la actualización en cola:

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

No necesitas esperar a response.steer.pending para devolver los resultados de herramientas. Si el servidor ya recibió un response.create correspondiente, puede continuar sin enviar primero esta notificación.

Gestionar fallas y desconexiones

response.steer.failed significa que la API no aplicó la entrada mediante la orientación y no la aplicará automáticamente más adelante. El evento devuelve los valores originales de input y previous_response_id dentro de steer, junto con un objeto error que describe la falla.

Haz un seguimiento de los envíos aceptados mediante steer.id. Una falla posterior usa el mismo ID.

Códigos de error comunes:

• invalid_input: usa solo los campos de evento compatibles y mensajes de usuario como entrada.
• steering_not_supported: el modelo, los parámetros de la solicitud o ambos pueden ser incompatibles con la orientación.
• response_not_found: la respuesta de destino debe seguir disponible en la misma conexión WebSocket.
• too_many_pending_steers: hay demasiadas entradas de orientación pendientes. Devuelve los resultados de herramientas o las aprobaciones que se requieran mediante response.create; de lo contrario, espera a la continuación automática antes de enviar más. No reenvíes orientación ya aceptada.

Las entradas de orientación en cola existen solo en la conexión actual; no se almacenan con la respuesta original. Registra las entradas de orientación que envíes y compáralas con los eventos y el historial de respuestas antes de volver a enviarlas. No supongas que la orientación pendiente se conservó tras la desconexión. Consulta la guía de recuperación de WebSocket.