Delegación y herramientas en GPT-Live

Configurar la delegación a Responses

Agrega esta configuración de delegación al crear tu sesión de Live. Elige el modelo de Responses de forma independiente del modelo de voz:

1
2
3
4
5
6
7
8
9
10export const session = {
  model: "gpt-live-1",
  delegation: {
    type: "responses",
    responses: {
      model: "gpt-5.6-terra",
      instructions: "[Your backend prompt]",
    },
  },
};

1
2
3
4
5
6
7
8
9
10
11
12from openai.types.live.session_config_param import SessionConfigParam

session: SessionConfigParam = {
    "model": "gpt-live-1",
    "delegation": {
        "type": "responses",
        "responses": {
            "model": "gpt-5.6-terra",
            "instructions": "[Your backend prompt]",
        },
    },
}

Empieza con GPT-5.6 Terra o prueba GPT-5.6 Luna para cargas de trabajo en las que el costo sea un factor clave. Compara la calidad de las respuestas y la latencia en tus tareas antes de elegir un modelo para el backend.

Registra las herramientas compatibles en delegation.responses.tools. Usa delegation.responses.tool_choice para controlar qué herramientas puede usar el backend: "auto" le permite elegir, "required" exige una llamada a una herramienta y "none" la impide. También puedes seleccionar una función por su nombre. Establece delegation.responses.parallel_tool_calls en true para permitir consultas independientes simultáneas, o en false cuando las llamadas deban ejecutarse de forma secuencial. Tu aplicación sigue ejecutando sus funciones personalizadas y haciendo cumplir las dependencias y las aprobaciones. Estas opciones no obligan al modelo en vivo a delegar.

La configuración de Responses requiere un model para el backend al momento de la creación. Admite definiciones de function y entradas de web_search en tools. También ofrece max_output_tokens (al menos 16 si se establece), service_tier y las opciones de reasoning y text compatibles con el modelo de backend seleccionado. Consulta Reducir la latencia del backend para conocer las opciones que puedes ajustar.

Si el Modo rápido está disponible para tu modelo y proyecto, considera usarlo para llamadas sensibles a la latencia. En GPT-Live, selecciónalo con delegation.responses.service_tier: "priority".

A medida que cambie la conversación, envía session.update con cambios en session.delegation.responses para actualizar el modelo del backend, las instrucciones, las herramientas disponibles, tool_choice u otras opciones compatibles sin iniciar una nueva sesión de Live. Las opciones omitidas conservan sus valores. Establecer delegation en null selecciona el modo de cliente y no permite restablecer una sesión de Responses en ejecución; cambiar de modo falla con immutable_field_update.

Estas opciones usan conceptos conocidos de Responses, pero Live admite solo un subconjunto de la API Responses independiente. Live proporciona el contexto de la conversación e inicia el trabajo delegado. Configura el backend a través de la sesión; el comando response.create de Live usa esa configuración y no acepta el cuerpo de una solicitud independiente de Responses.

Dirigir la conversación en vivo desde tu aplicación

La delegación a Responses gestiona el flujo de trabajo del backend, pero tu aplicación puede seguir enviando contexto directamente al modelo GPT-Live. Si supervisas la llamada mediante un WebSocket de canal auxiliar o la conexión principal de eventos, puedes usar session.instructions.append, session.thinking.append o session.commentary.append con delegation_id: null. Por ejemplo, una medida de protección basada en la transcripción puede agregar una instrucción para redirigir la conversación. Esto orienta al modelo en vivo; no cambia el prompt del backend de Responses ni cancela el trabajo que ya está en curso.

Gestionar la delegación a Responses

Para el trabajo que usa Responses como backend, session.delegation.created contiene target: "responses" y un response_id. Los eventos posteriores de Responses llegan dentro de una envoltura response.event:

1234567891011121314{
  "type": "response.event",
  "event_id": "event_response_1",
  "delegation_id": "item_9tA2cB6n2V8c4X1z7Q5r9",
  "event": {
    "type": "response.output_text.delta",
    "sequence_number": 4,
    "item_id": "msg_123",
    "output_index": 0,
    "content_index": 0,
    "delta": "The forecast is",
    "logprobs": []
  }
}

Dirige cada evento al controlador correspondiente según envelope.event.type y conserva el delegation_id externo. No trates todos los valores response.* de nivel superior como eventos de Responses sin envoltura. Admite eventos anidados adicionales del ciclo de vida de Responses.

El habla en vivo y el trabajo delegado continúan de forma independiente. Una respuesta completada del backend no significa por sí sola que el usuario haya escuchado la respuesta. Usa la transcripción y el audio de salida de Live para la parte hablada de la interacción.

Completar una llamada a una función que el cliente puede ejecutar

Lee las llamadas a funciones completadas en los eventos anidados response.output_item.done. El elemento de función finalizado contiene call_id, name y arguments; un evento de finalización de argumentos por sí solo no basta para identificar la llamada.

Registra el ID de respuesta del evento anidado response.created junto con el delegation_id externo y recopila las llamadas a funciones de esa respuesta a partir de response.output_item.done. Las instantáneas reenviadas del ciclo de vida contienen deliberadamente response.output: [], incluso en response.completed; su arreglo tools está vacío, instructions es null y se omite input. Una lista de salida vacía al finalizar no significa que no haya llamadas a funciones pendientes. Usa las llamadas recopiladas para determinar qué resultados deben enviarse antes de continuar.

Después de ejecutar la operación autorizada, agrega el resultado como un elemento de Responses:

1
2
3
4
5
6
7
8
9
10
11export function sendUpdate(connection) {
  connection.send({
    type: "response.item.create",
    event_id: "tool_result_1",
    item: {
      type: "function_call_output",
      call_id: "call_123",
      output: '{"status":"confirmed","order_id":"order_123"}',
    },
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection
from openai.types.responses.response_input_item_param import ResponseInputItemParam


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    item: ResponseInputItemParam = {
        "type": "function_call_output",
        "call_id": "call_123",
        "output": '{"status":"confirmed","order_id":"order_123"}',
    }
    await connection.response.item.create(
        event_id="tool_result_1",
        item=item,
    )

Luego, continúa la respuesta de forma explícita:

1
2
3
4
5
6export function sendUpdate(connection) {
  connection.send({
    type: "response.create",
    event_id: "continue_1",
  });
}

1
2
3
4
5
6
7
8
9
10from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    await connection.response.create(
        event_id="continue_1",
    )

Envía todos los resultados requeridos para las llamadas a herramientas pendientes antes de continuar. Agregar el resultado de una función no continúa la respuesta automáticamente. response.item.create no tiene una confirmación de éxito independiente; sigue procesando los errores y los eventos anidados posteriores del ciclo de vida de la respuesta.

response.create es un comando de Live para crear o continuar trabajo delegado a Responses mediante el backend configurado en la sesión. No adjuntes a este evento un cuerpo de creación de la API Responses, una anulación del modelo del backend ni delegation_id. Ambos comandos requieren delegación a Responses.

Configurar la delegación al cliente

Establece delegation al crear tu sesión de Live:

1
2
3
4
5
6export const session = {
  model: "gpt-live-1",
  delegation: {
    type: "client",
  },
};

1
2
3from openai.types.live.session_config_param import SessionConfigParam

session: SessionConfigParam = {"model": "gpt-live-1", "delegation": {"type": "client"}}

Esto selecciona la delegación al cliente para la sesión. Configura el backend por separado: tu aplicación elige su modelo o servicio, sus instrucciones, sus herramientas y cómo dirigir el trabajo. Si usas la API Responses para ese backend, establece su modelo y sus herramientas en tus propias solicitudes a Responses. La sesión de Live no configura ni ejecuta esas herramientas del backend.

Cuando GPT-Live solicita ayuda, tu aplicación construye la solicitud al backend a partir del contexto de la conversación y de la aplicación, ejecuta el trabajo y decide qué resultados devolver. Aplica los permisos y exige las confirmaciones requeridas antes de ejecutar tus herramientas. Conserva el historial completo de la conversación en tu aplicación para poder proporcionar el contexto pertinente en cada solicitud al backend.

Conservar el contexto de la conversación en tu aplicación

Para la delegación al cliente, recopila las transcripciones y mantén tú mismo el estado actual de la tarea.

Escucha los eventos session.input_transcript.delta y session.output_transcript.delta. Estos eventos contienen el texto de la transcripción en delta, junto con las marcas de tiempo start_ms y end_ms. Conserva suficiente historial para entender respuestas breves como “sí”, correcciones como “jueves, no viernes” y detalles proporcionados antes. Un fragmento de transcripción no es un turno completo del usuario, y las transcripciones pueden contener errores.

El evento independiente session.delegation.created contiene una marca de tiempo offset_ms y metadatos de delegación, incluidos delegation.id y delegation.target. No contiene lo que dijo el usuario ni el texto de la tarea. Usa los eventos de transcripción y el estado de la aplicación para determinar qué quiere el usuario. Guarda delegation.id para poder asociar las actualizaciones con esa solicitud.

Conserva los registros extensos y la salida completa de las herramientas en el backend. Si creas una sesión de reemplazo, restaura el contexto pertinente desde tu aplicación y verifica qué acciones ya se ejecutaron antes de repetir cualquier trabajo.

Recibir una delegación al cliente

session.delegation.created identifica una delegación:

12345678910{
  "type": "session.delegation.created",
  "event_id": "event_delegation",
  "offset_ms": 1000,
  "delegation": {
    "id": "item_9tA2bF3h7K9m2P5q8R1s4",
    "type": "delegation",
    "target": "client"
  }
}

Lee event.delegation.id. El objeto de delegación contiene metadatos, no el texto de la tarea. Mantén la transcripción y el contexto de la aplicación que necesita tu propio controlador de trabajo delegado. Los ID actuales tienen el prefijo item_, como se muestra aquí; trata el ID completo como un valor opaco y devuélvelo sin cambios, en lugar de construirlo o analizar su estructura.

Devuelve un resultado con ese ID:

1
2
3
4
5
6
7
8export function sendUpdate(connection) {
  connection.send({
    type: "session.commentary.append",
    event_id: "result_123",
    delegation_id: "item_9tA2bF3h7K9m2P5q8R1s4",
    content: "The order shipped today and should arrive tomorrow.",
  });
}

1
2
3
4
5
6
7
8
9
10
11
12from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    await connection.session.commentary.append(
        event_id="result_123",
        delegation_id="item_9tA2bF3h7K9m2P5q8R1s4",
        content="The order shipped today and should arrive tomorrow.",
    )

Usa session.thinking.append para agregar información al razonamiento interno del modelo sin que la diga en voz alta al incorporarla. Usa session.commentary.append para un resultado que el modelo deba decir en voz alta; el modelo está entrenado para parafrasear el texto agregado. Todas las operaciones de adición contienen una cadena simple y requieren delegation_id, incluso cuando su valor es null. Un ID no nulo debe identificar una delegación al cliente conocida.

Agregar resultados de forma sucesiva permite continuar la misma delegación al cliente. El acuse de recibo de la adición llega después del momento estimado de incorporación del contexto; no demuestra que el modelo haya procesado o dicho el resultado, ni que una acción externa se haya completado correctamente.

Con la delegación a Responses, pon en cola un mensaje del usuario para el backend:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16export function sendUpdate(connection) {
  connection.send({
    type: "response.item.create",
    event_id: "typed_order_number",
    item: {
      type: "message",
      role: "user",
      content: [
        {
          type: "input_text",
          text: "My order number is A0042.",
        },
      ],
    },
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection
from openai.types.responses.response_input_item_param import ResponseInputItemParam


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    item: ResponseInputItemParam = {
        "type": "message",
        "role": "user",
        "content": [{"type": "input_text", "text": "My order number is A0042."}],
    }
    await connection.response.item.create(
        event_id="typed_order_number",
        item=item,
    )

Envía response.create cuando estés listo para ejecutar o continuar el trabajo del backend. Si está esperando resultados de funciones, devuelve primero todos los resultados requeridos. Poner texto en cola no cancela por sí solo el trabajo que ya está en ejecución.

Con la delegación al cliente, envía el valor escrito directamente al backend que gestiona la conversación. Si corrige una tarea en ejecución, actualiza esa tarea en lugar de volver a iniciar el mismo trabajo. Puedes enviar una copia de un breve resumen factual a la sesión en vivo con session.thinking.append, o usar session.commentary.append para un resultado que el usuario deba escuchar.

Con la delegación a Responses, configura un modelo de backend con capacidad de visión. Pon en cola un elemento de entrada de imagen compatible con Responses mediante response.item.create y luego envía response.create para ejecutar o reanudar el trabajo del backend. Devuelve todos los resultados de funciones pendientes requeridos antes de continuar. Consulta Gestiona la delegación a Responses.

Con la delegación al cliente, envía la entrada visual al backend que gestiona las solicitudes delegadas, junto con la conversación relevante y el estado de la aplicación. Devuelve conclusiones concisas mediante el flujo de resultados del cliente.

Delegación a Responses

Live gestiona conexiones WebSocket persistentes con Responses, prepara de antemano la conexión y la configuración conocida de la solicitud, y reutiliza el estado de respuestas anteriores cuando está disponible. No necesitas implementar esos pasos para el backend alojado. La reutilización depende de la conexión activa y de que el estado sea compatible; no garantiza un acierto de caché ni una latencia específica.

Ajusta el backend mediante delegation.responses:

• model: elige el modelo que se encarga del razonamiento y la selección de herramientas de forma independiente del modelo de voz.
• reasoning.effort: equilibra el tiempo de razonamiento y la calidad de la tarea con valores compatibles con ese modelo.
• service_tier: usa auto, default, flex o priority, según la compatibilidad del modelo y el acceso del proyecto. auto sigue la configuración del proyecto. Evalúa el rendimiento y el costo del nivel que elijas.

Actualiza los ajustes compatibles durante la sesión con session.update. Tus herramientas personalizadas siguen ejecutándose en tu aplicación, por lo que las llamadas lentas a servicios, las colas y el almacenamiento en búfer de los resultados de herramientas pueden retrasar la respuesta incluso cuando Live gestiona la conexión con Responses. Devuelve cada resultado de herramienta requerido sin demora y continúa la respuesta del backend.

Delegación al cliente

Tu aplicación se encarga de todo el flujo, desde la recepción de la delegación hasta la devolución de un resultado. Prepara ese flujo mientras la sesión de voz está activa:

• Reutiliza las conexiones del backend. Mantén activos el cliente de la API y su grupo de conexiones entre delegaciones. Para llamadas repetidas a Responses, considera usar una conexión WebSocket de Responses persistente.
• Prepara la configuración conocida. Inicializa las instrucciones, las herramientas y las conexiones antes de que la primera solicitud las necesite. El modo WebSocket de Responses también permite preparar el estado conocido de la solicitud antes de la generación; sigue sus indicaciones de configuración.
• Transmite resultados útiles de forma incremental. Devuelve fragmentos coherentes y verificados con session.commentary.append. Usa session.thinking.append para informar del progreso sin hablar en voz alta. Conserva el ID de delegación al cliente y respeta el límite de 500 tokens por adición. Mantén el razonamiento privado en el backend y confirma las acciones antes de anunciar que se completaron correctamente.
• Mantén estable la entrada reutilizable. Conserva las instrucciones, las definiciones de herramientas y su orden, y los prefijos del historial que no hayan cambiado. Agrega la información nueva después del contenido reutilizable cuando tu backend admita el almacenamiento en caché y la continuación.
• Evita el almacenamiento innecesario en búfer. Envía un resultado útil en cuanto esté listo. Almacena en búfer solo lo suficiente para clasificar la salida y formar un fragmento coherente. Da preferencia a los metadatos estructurados de fase; si usas prefijos de texto para distinguir el progreso de los resultados, espera a tener el prefijo completo antes de enviar el texto.

Mide el tiempo hasta la primera respuesta hablada útil al comparar este flujo con la delegación a Responses.