Ajustar el rumbo de una respuesta en curso

Los usuarios pueden agregar requisitos o cambiar de rumbo sin esperar a que termine la respuesta.

Puedes ajustar el rumbo de una respuesta con los modelos de la familia GPT-6 mediante una conexión WebSocket a la API de Responses. GPT-5.6 y los modelos anteriores no admiten esta función.

Al ajustar el rumbo de una respuesta, no se modifica la salida que ya se envió a tu aplicación, no se deshacen las acciones anteriores ni se cancelan las herramientas que ya están en ejecución.

El ejemplo en Java requiere Java 17 o una versión posterior. Para obtener información sobre cómo configurar la conexión y cómo funciona el transporte en general, consulta Modo WebSocket. Para conocer la definición exacta de cada evento, consulta la referencia de eventos WebSocket de Responses.

Enviar un mensaje para ajustar el rumbo

Inicia una respuesta con response.create. Cuando recibas el evento response.created de esa respuesta, envía response.steer por la misma conexión y usa el ID de la respuesta como valor 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."
}

El evento solo acepta los campos type, previous_response_id e input. Asigna a input una cadena de texto o un arreglo no vacío de mensajes de usuario con tipos de contenido admitidos.

La API confirma que puso la entrada en cola mediante response.steer.accepted:

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

La confirmación solo indica que la entrada está en cola. El modelo podría no haberla aplicado todavía. La API crea automáticamente una nueva respuesta con tu actualización, salvo que necesite que tu aplicación le envíe el resultado de una herramienta o una aprobación.

Antes de crear esta continuación automática, el servidor termina el elemento de salida actual y espera a que las herramientas alojadas terminen las tareas que ya están en curso. Sigue leyendo los eventos para recibir la respuesta que incorpora tu actualización. No envíes otro response.create.

Si la actualización interrumpe la respuesta original, esta termina con response.incomplete e incomplete_details.reason: "steered". Si la respuesta original termina normalmente antes de que se aplique la actualización, conserva su estado de respuesta completada y aún puede tener una continuación que incorpore la actualizació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 incluye un cliente WebSocket para la API de Responses, por lo que este ejemplo no tiene una variante que use el SDK de C#.

Actualiza un plan de proyecto mientras se genera

Python

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
84// 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",
      store: false,
      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
48
49
50
51
52
53import 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:
        await connection.response.create(
            model="gpt-6-astra",
            store=False,
            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.")


async def run():
    await asyncio.wait_for(main(), timeout=120)


asyncio.run(run())

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
61ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
conn, err := client.Responses.Connect(ctx, responses.ResponseConnectionOptions{})
if err != nil {
	log.Fatal(err)
}
defer conn.Close()
if err := conn.Create(ctx, responses.ResponsesClientEventResponseCreateParam{
	Model: "gpt-6-astra",
	Reasoning: shared.ReasoningParam{
		Effort: shared.ReasoningEffortMedium,
	},
	Store: openai.Bool(false),
	Input: responses.ResponsesClientEventResponseCreateInputUnionParam{
		OfString: openai.String("Draft a project plan for building a task-tracking app."),
	},
}); err != nil {
	log.Fatal(err)
}
initialID, successorID := "", ""
for {
	event, err := conn.Recv(ctx)
	if err != nil {
		log.Fatal(err)
	}
	switch event.Type {
	case "response.created":
		id := event.OfResponsesServerEventResponseWsCreated.Response.ID
		if initialID == "" {
			initialID = id
			err := conn.Send(ctx, responses.ResponsesClientEventUnionParam{
				OfResponseSteer: &responses.ResponseSteerEventParam{
					PreviousResponseID: id,
					Input: responses.ResponseSteerInputUnionParam{
						OfString: openai.String("Keep the scope small enough for one developer to finish in two weeks."),
					},
				},
			})
			if err != nil {
				log.Fatal(err)
			}
		} else {
			successorID = id
		}
	case "response.steer.failed", "response.failed", "error":
		log.Fatal(event.RawJSON())
	case "response.incomplete":
		r := event.OfResponsesServerEventResponseWsIncomplete.Response
		if r.ID != initialID || r.IncompleteDetails.Reason != "steered" {
			log.Fatal(event.RawJSON())
		}
	case "response.completed":
		r := event.OfResponsesServerEventResponseWsCompleted.Response
		if successorID != "" && r.ID == successorID {
			fmt.Println(r.OutputText())
			return
		}
	}
	// Steering acceptance only queues input. Wait for the successor to complete.
}

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
67import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.*;
import java.util.*;

var client = OpenAIOkHttpClient.fromEnv();

long deadline = System.nanoTime() + java.util.concurrent.TimeUnit.SECONDS.toNanos(120);
try (var conn =
    client.async().responses().connect().get(10, java.util.concurrent.TimeUnit.SECONDS)) {
  conn.send(
      ResponsesClientEvent.ofResponseCreate(
          ResponsesClientEvent.ResponseCreate.builder()
              .model("gpt-6-astra")
              .reasoning(
                  com.openai.models.Reasoning.builder()
                      .effort(com.openai.models.ReasoningEffort.MEDIUM)
                      .build())
              .store(false)
              .input("Draft a project plan for building a task-tracking app.")
              .build()));
  String initialId = null, successorId = null;
  while (true) {
    var event =
        conn.receive()
            .get(
                Math.max(1, deadline - System.nanoTime()),
                java.util.concurrent.TimeUnit.NANOSECONDS);
    if (event.responseCreated().isPresent()) {
      var id = event.responseCreated().orElseThrow().response().id();
      if (initialId == null) {
        initialId = id;
        conn.send(
            ResponsesClientEvent.ofResponseSteer(
                ResponseSteerEvent.builder()
                    .previousResponseId(id)
                    .input(
                        "Keep the scope small enough for one developer to finish in two weeks.")
                    .build()));
      } else {
        successorId = id;
      }
    } else if (event.responseSteerFailed().isPresent()
        || event.responseFailed().isPresent()
        || event.error().isPresent()) {
      throw new IllegalStateException(event.toString());
    } else if (event.responseIncomplete().isPresent()) {
      var response = event.responseIncomplete().orElseThrow().response();
      if (!response.id().equals(initialId)
          || !response
              .incompleteDetails()
              .flatMap(Response.IncompleteDetails::reason)
              .map(r -> r.toString().equals("steered"))
              .orElse(false)) throw new IllegalStateException(event.toString());
    } else if (event.responseCompleted().isPresent()
        && event.responseCompleted().orElseThrow().response().id().equals(successorId)) {
      event.responseCompleted().orElseThrow().response().output().stream()
          .flatMap(item -> item.message().stream())
          .flatMap(message -> message.content().stream())
          .flatMap(content -> content.outputText().stream())
          .forEach(text -> System.out.println(text.text()));
      break;
    }
    // Acceptance only queues input; follow the successor through completion.
  }
} finally {
  client.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
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", store: false, 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 el usuario la proporcione. Una vez que recibas el evento response.created de la continuación, usa el ID de esa continuación para enviar nuevas actualizaciones.

Devolver resultados de herramientas o una aprobación

Si la respuesta requiere el resultado de una herramienta del cliente o una aprobación, la API mantiene la actualización en cola. Continúa con el flujo habitual de ejecución de herramientas o de aprobación en la misma conexión.

Por ejemplo, la respuesta original puede completarse con una llamada a get_project_status. En los siguientes mensajes se 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\"}"
      }
    ]
  }
}

Cuando se completa la respuesta original, la API envía response.steer.pending si aún necesita datos para aplicar una actualización aceptada. El campo required_input indica qué resultados de herramientas o aprobaciones necesita la API para 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"
    }
  ]
}

Envía los datos requeridos con response.create por la misma conexión y asigna a previous_response_id el valor resp_1. No repitas la actualización aceptada. Si envías response.create de forma explícita, la solicitud usa sus propias herramientas, instrucciones y demás parámetros de configuración.

Los comentarios de este ejemplo en 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.",
    },
  ],
}

Puedes devolver los resultados de las herramientas sin esperar a recibir response.steer.pending. Si el servidor ya recibió el evento response.create correspondiente, puede continuar sin enviar antes esta notificación.

Gestionar errores y desconexiones

response.steer.failed indica que la API no aplicó la entrada como actualización de la respuesta en curso ni 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 el fallo.

Usa steer.id para hacer un seguimiento de las actualizaciones aceptadas. Si una actualización falla más adelante, el evento de error usa el mismo ID.

Códigos de error comunes:

invalid_input: usa solo los campos admitidos del evento y envía únicamente mensajes de usuario como entrada.
steering_not_supported: es posible que el modelo, los parámetros de la solicitud o ambos sean incompatibles con las actualizaciones durante la generación de una respuesta.
response_not_found: la respuesta que quieres actualizar debe seguir disponible en la misma conexión WebSocket.
too_many_pending_steers: hay demasiadas actualizaciones pendientes. Si se requieren resultados de herramientas o aprobaciones, envíalos con response.create. De lo contrario, espera a que se genere la continuación automática antes de enviar más actualizaciones. No vuelvas a enviar las que ya se aceptaron.

Las actualizaciones en cola solo existen en la conexión actual. No se guardan con la respuesta original. Registra las actualizaciones que envíes y compáralas con los eventos y el historial de respuestas antes de volver a enviarlas. No des por hecho que las actualizaciones pendientes se conservaron tras la desconexión. Consulta la guía de recuperación de conexiones WebSocket.

Sugerencias

Primeros pasos

Conceptos fundamentales

SDK y CLI

Proveedores de servicios en la nube

Recursos

API heredadas

Elige un modelo

Texto y código

Redacción de prompts

Razonamiento

Imágenes

Tiempo real y audio

Modelos especializados

API de agentes

Agents SDK

ChatKit

Búsqueda y recuperación de información

Conecta herramientas y datos

Crea flujos de trabajo con herramientas

Computadora y código

Multimedia

GPT-Live

Realtime API

Desarrollar aplicaciones de voz

Conexiones

Procesamiento de audio

Pasa a producción

Rendimiento y calidad

Evaluación

Costo y rendimiento

Seguridad y gobernanza

Infraestructura y acceso

Operaciones

Conceptos básicos

Planificación

Desarrollo

Pruebas y publicación

Especificaciones de conversión

Guías

Recursos

Identidad

Uso del plan de ChatGPT

Guías

Carga de archivos

API

Medición

API para anunciantes

Referencia de la API

Primeros pasos

Primeros pasos

Fundamentos

Explorar

Disponible en

Versiones

Flujos de trabajo

Capacidades

Sites

dots

ChatGPT Espacio

Referencia

Personalización

Archivo de configuración

Configuración de agentes

Ampliar las funciones de ChatGPT y Codex

Linux

Windows

Flujos de trabajo de desarrollo

Ampliar funciones y automatizar

Entornos

Codex Cloud

Desarrollar con Codex

Integraciones de terceros

Referencia

Permisos

Codex Security

Ciberseguridad

Primeros pasos

Configuración de funciones

Identidad y acceso