Migrar a GPT-Live

Desde Realtime API

Comienza con la guía de diseño de prompts de GPT-Live. Divide tu prompt existente entre el modelo de voz y el backend en lugar de copiarlo completo en session.instructions. Mantén el estilo de conversación y las pautas de delegación en el prompt de voz; traslada los flujos de trabajo detallados y las instrucciones de uso de herramientas al backend.

Antes: el modelo de Realtime se encarga de la voz y selecciona funciones como check_availability y book_appointment. Tu aplicación ejecuta las funciones y devuelve sus resultados.

Después: GPT-Live se encarga de la voz y delega el trabajo de las tareas. El backend selecciona las mismas funciones; tu aplicación sigue validándolas y ejecutándolas. Los pasos que se muestran aquí usan la delegación a Responses. Si conservas un agente externo, usa el adaptador del cliente.

Cómo funciona la delegación a Responses

Configura el modelo del backend, las instrucciones y las herramientas en delegation.responses. Cuando GPT-Live decide que una solicitud necesita trabajo del backend, el servicio Live llama a ese modelo de Responses y le proporciona el contexto pertinente de la conversación. El backend razona sobre la tarea y selecciona herramientas. Tu aplicación sigue ejecutando funciones personalizadas, aplicando los permisos y devolviendo sus resultados.

En el caso del asistente de citas:

1. El usuario pregunta qué citas hay disponibles el viernes y GPT-Live delega la solicitud.
2. El backend de Responses solicita check_availability.
3. Tu aplicación ejecuta la función, devuelve su resultado y continúa la respuesta del backend.
4. GPT-Live usa la respuesta del backend para conversar con el usuario sobre los horarios disponibles.

GPT-Live puede mantener la conversación mientras se ejecuta el trabajo del backend. Que ese trabajo termine no significa que el asistente haya terminado de hablar. Consulta Delegación y herramientas para ver la configuración y el flujo completo de eventos.

Conservar las decisiones que dependen del audio

Verifica si las decisiones actuales sobre herramientas dependen de indicios acústicos, como el tono del buzón de voz o la cadencia de un saludo grabado. GPT-Live escucha el audio entrante, pero su frontend de voz delega el trabajo en lugar de emitir llamadas a funciones estructuradas convencionales. En el modo de cliente, session.delegation.created contiene metadatos e información temporal, sin audio sin procesar, texto de la tarea ni argumentos de herramientas analizados. El backend al que se delega el trabajo no recibe automáticamente la forma de onda.

Para detectar contestadores automáticos, dirige explícitamente el audio entrante a un detector capaz de procesar audio. Una arquitectura administrada por la aplicación que puedes evaluar consiste en ejecutar una sesión de Realtime independiente junto con GPT-Live durante parte de la llamada:

1. Envía una copia del audio entrante de la llamada a ambas sesiones.
2. Haz que el detector informe su clasificación mediante una llamada a función estructurada. Valida cada resultado según tu esquema, rechaza los resultados desactualizados y mantén un estado desconocido cuando los indicios sean insuficientes. Permite que los indicios posteriores modifiquen la decisión.
3. Envía contexto pertinente y confiable a GPT-Live, y aplica la política de tu aplicación a la reproducción del audio saliente.

Mantén separadas la clasificación como persona o máquina y la determinación de si se puede empezar a grabar. Reconocer un buzón de voz no establece que el saludo y el tono hayan terminado ni que se pueda comenzar a grabar. El resultado de un clasificador o una confirmación de recepción del contexto tampoco establece el permiso para reproducir audio. Usa Adaptar tus medidas de protección y los controles de reproducción para hacer cumplir esa decisión en la ruta de audio que controla tu aplicación.

Prueba un “hola” breve que continúe como un saludo de buzón de voz, mensajes de filtrado de llamadas y una persona que conteste mientras está activo el buzón de voz. Si detienes el detector antes de que termine la llamada, prueba el caso en que una persona conteste después de detenerlo. Elige cuándo detener el detector según estas pruebas y su costo adicional. La primera clasificación como persona no basta para establecer que ya no es necesario seguir detectando.

Adapta la conexión y el ciclo de vida del audio

Reemplaza la configuración de sesiones de Realtime por el procedimiento de conexión de GPT-Live. Vuelve a verificar el inicio y el formato de audio de tu transporte. WebRTC transmite audio en pistas multimedia y eventos JSON en el canal de datos. Un WebSocket principal transmite audio en eventos JSON.

Si tu aplicación de Realtime usa una conexión de servidor para monitorear la llamada o aplicar medidas de protección, adáptala a la conexión de banda lateral de GPT-Live. Sigue Adaptar tus medidas de protección para realizar los cambios en las verificaciones de la conversación y la reproducción.

Generación y reproducción: en Realtime, response.output_audio.done marca el final de la generación de audio, mientras que response.done marca el final del flujo de respuesta. Estos eventos también pueden ocurrir cuando una respuesta se interrumpe o no se completa correctamente; verifica response.status en response.done. Ninguno confirma que el audio almacenado en el búfer haya terminado de reproducirse. Por ejemplo, el servidor puede terminar de generar audio mientras al cliente aún le queda un segundo de audio por reproducir. Controla el indicador de “hablando” a partir del estado de reproducción.

Subtítulos: la transcripción de entrada representa lo que dice el usuario; la transcripción de salida representa la voz generada por el asistente. Cuando la transcripción de entrada está habilitada, Realtime envía actualizaciones mediante conversation.item.input_audio_transcription.delta y una transcripción final mediante conversation.item.input_audio_transcription.completed. Un delta es un nuevo fragmento de texto. En GPT-Live, agrega cada fragmento al final de los subtítulos de quien habla, de forma independiente, ya que la escucha y el habla pueden superponerse. Un fragmento no es un turno completo ni una confirmación de reproducción. Consulta Mostrar subtítulos para ver un ejemplo de implementación.

En GPT-Live, response.create inicia o continúa el trabajo delegado a Responses. No otorga permiso al modelo de voz para hablar. Para el inicio, los saludos, las interrupciones y el cierre de una sesión, consulta Administración de sesiones.

Separa las instrucciones de conversación y del backend

Mueve el estilo de conversación y las indicaciones de delegación a session.instructions. Mueve las reglas de negocio y las instrucciones de uso de herramientas a delegation.responses.instructions. Si ejecutas tu propio backend, conserva esas reglas en su prompt existente.

Antes: un único prompt de Realtime

Help callers book appointments. Speak briefly. Check availability with the tool,
ask the caller to confirm a slot, then book it. Never claim an unverified booking.

Después: instrucciones de conversación de GPT-Live

Help callers book appointments. Keep spoken replies brief. Delegate availability
checks and booking requests. Ask the caller to confirm the proposed slot.
Only announce a booking when the backend reports that it succeeded.

Después: instrucciones del backend

Use the appointment tools to check current availability. Before booking, verify
that the caller confirmed the exact slot and still has permission to book it.
Apply the latest correction. Return verified availability, booking, or failure
status with the date, time, and time zone.

Aplica las verificaciones de confirmación y permisos en tu aplicación antes de ejecutar una herramienta. Las instrucciones del prompt orientan a los modelos; no aplican esas verificaciones. Consulta Diseño de prompts para modelos de voz para diseñar tus prompts.

Adapta tus manejadores de funciones

Conserva la implementación de check_availability y book_appointment. Mueve sus definiciones de session.tools o response.tools de Realtime a delegation.responses.tools, usando el esquema de funciones de Responses. Mueve la configuración de selección de herramientas a delegation.responses.tool_choice y delegation.responses.parallel_tool_calls. Consulta Configura la delegación a Responses.

La función sigue devolviendo un resultado para su call_id original. Lo que cambia es dónde recibe la llamada y envía el resultado tu manejador:

Por ejemplo, después de que check_availability devuelve un horario verificado, tu resultado cambia de la siguiente manera. Estos son mensajes de una sesión que ya está conectada; call_availability representa el ID real de la llamada que recibiste.

Antes: resultado de Realtime

12345678{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_availability",
    "output": "{\"available\":true,\"slot_id\":\"slot_friday_14\",\"booked\":false}"
  }
}

Después: resultado de GPT-Live

1
2
3
4
5
6
7
8
9
10
11export function sendUpdate(connection) {
  connection.send({
    type: "response.item.create",
    event_id: "availability_result_1",
    item: {
      type: "function_call_output",
      call_id: "call_availability",
      output: '{"available":true,"slot_id":"slot_friday_14","booked":false}',
    },
  });
}

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_availability",
        "output": '{"available":true,"slot_id":"slot_friday_14","booked":false}',
    }
    await connection.response.item.create(
        event_id="availability_result_1",
        item=item,
    )

Después de enviar todos los resultados de funciones requeridos, continúa la ejecución del backend:

1
2
3
4
5
6export function sendUpdate(connection) {
  connection.send({
    type: "response.create",
    event_id: "continue_availability_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_availability_1",
    )

Para la migración inicial, establecer parallel_tool_calls en false simplifica el manejo de resultados. Recopila las llamadas a partir de los eventos que indican que un elemento de salida está completo, incluso si una instantánea del estado final del ciclo de vida contiene output: []. Un evento que indica que los argumentos están completos no proporciona por sí solo el nombre de la función y el call_id. Sigue el procedimiento completo para los resultados de funciones para la recopilación, el envío de resultados y el manejo de errores.

Conserva el contexto y aplica correcciones

La delegación a Responses proporciona al backend el contexto relevante de la conversación de voz. Mantén en tu aplicación el estado de la cita que sirve como fuente de verdad: horario seleccionado, horario confirmado, permisos, operación activa y resultado. El historial de conversación de Live se puede compactar; no es tu registro de reservas.

Si el usuario dice “Mejor el viernes” mientras hay una consulta pendiente para el jueves, actualiza la versión de la tarea e invalida la confirmación del horario anterior. Antes de realizar una reserva, verifica que sus argumentos sigan coincidiendo con la tarea y la confirmación actuales. Para cualquier llamada a función pendiente que tu aplicación rechace, devuelve un resultado que indique correctamente si quedó reemplazada o cancelada; luego completa el lote de resultados requerido antes de continuar. Si una reserva ya se realizó correctamente, concilia ese resultado con el cambio solicitado antes de realizar otra acción.

Los fragmentos de transcripción pueden llegar tarde o superponerse con la voz del asistente. Agrega cada delta al final exactamente como lo recibes y usa start_ms y end_ms para agrupar el contenido mostrado. Estas marcas de tiempo no son límites definitivos de los turnos ni marcas de tiempo de reproducción a nivel de palabra. Aclara las fechas, los nombres y los números importantes cuando la intención no esté clara. Consulta Administración de sesiones para el manejo de transcripciones y contexto.

Imágenes y contexto de pantalla: si tu aplicación de Realtime acepta imágenes, envíalas a un backend con capacidad de visión y devuelve el texto relevante a GPT-Live. Tanto la delegación al cliente como la delegación a Responses admiten este patrón. Consulta Agrega imágenes y contexto visual.

Desde un agente de texto o un flujo de procesamiento encadenado

Antes: un agente de texto recibe solicitudes escritas y usa sus herramientas y su estado guardado. Un flujo de procesamiento de voz encadenado, o en cascada, agrega una etapa de conversión de voz a texto antes de ese agente y otra de texto a voz después.

Después: GPT-Live proporciona la interfaz de voz y delega el trabajo de las tareas a tu agente existente. En un flujo de procesamiento encadenado, reemplaza las etapas separadas de conversión de voz a texto y de texto a voz. Conserva en tu backend los modelos, las instrucciones, las herramientas, el flujo de trabajo y el estado persistente que sigan siendo adecuados para la tarea.

Conecta tu agente existente

Configura delegation como {"type":"client"} durante la configuración de la sesión. Tu aplicación recibe una notificación como esta:

123456789{
  "type": "session.delegation.created",
  "offset_ms": 1000,
  "delegation": {
    "id": "item_appointment_1",
    "type": "delegation",
    "target": "client"
  }
}

La notificación contiene metadatos, no el texto de la solicitud, los argumentos de las herramientas ni una transcripción completa. Mantén el delegation.id real sin cambios. Prepara la entrada del agente a partir de fragmentos recientes de transcripción etiquetados por rol y del estado verificado de la aplicación, incluida la tarea activa y la última corrección. Una delegación puede llegar antes de que aparezca una oración completa en la transcripción. Si el contexto disponible no permite determinar la solicitud, reúne más contexto o pide una aclaración antes de actuar.

En una aplicación de texto, podrías pasar el último mensaje del usuario directamente a tu agente. Con GPT-Live, agrega un adaptador que proporcione ese contexto y devuelva un resultado conciso y verificado:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25async function handleDelegation(event, app) {
  if (
    event.type !== "session.delegation.created" ||
    event.delegation?.target !== "client"
  )
    return;

  const context = app.readContext();
  if (!context) return; // Retain the notice; resolve the request before acting.

  const summary = await app.runAgent({
    revision: context.revision,
    recentConversation: context.recentConversation,
    task: context.task,
  });

  if (app.currentRevision() !== context.revision) return;

  app.send({
    type: "session.commentary.append",
    event_id: crypto.randomUUID(),
    delegation_id: event.delegation.id,
    content: summary,
  });
}

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
40from collections.abc import Awaitable, Callable
from dataclasses import dataclass
from uuid import uuid4

from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection
from openai.types.live.server_event import ServerEvent


@dataclass(frozen=True)
class Context:
    revision: int
    recent_conversation: str
    task: str


async def handle_delegation(
    event: ServerEvent,
    connection: AsyncLiveConnection | AsyncSidebandConnection,
    *,
    read_context: Callable[[], Context | None],
    run_agent: Callable[[Context], Awaitable[str]],
    current_revision: Callable[[], int],
) -> None:
    if (
        event.type != "session.delegation.created"
        or event.delegation.target != "client"
    ):
        return
    context = read_context()
    if context is None:
        return  # Retain the notice; resolve the request before acting.
    summary = await run_agent(context)
    if current_revision() != context.revision:
        return
    await connection.session.commentary.append(
        event_id=str(uuid4()),
        delegation_id=event.delegation.id,
        content=summary,
    )

El adaptador usa callbacks de la aplicación para leer el contexto, ejecutar tu agente y verificar la versión actual de la tarea; no son métodos del SDK. El callback de contexto devuelve una instantánea lista para usar que contiene la conversación reciente y la tarea actual, o no devuelve ninguna instantánea si la solicitud sigue sin estar clara. El callback del agente invoca tu agente existente y devuelve un resumen verificado de un máximo de 500 tokens. En JavaScript, el callback send proporcionado por la aplicación envía el evento JSON a través de tu conexión de Live. En Python, el adaptador envía la actualización directamente a través de connection del SDK.

Si el contexto no está listo, conserva la notificación y vuelve a invocar el adaptador después de aclarar la solicitud. Antes de invocar este adaptador, marca la delegación en tu aplicación como asignada para su procesamiento, de modo que una entrega duplicada no pueda iniciar la misma operación dos veces. Mantén la autorización, la confirmación, los ID de operación y las decisiones de reintento en tu backend. La verificación de la versión impide que este adaptador anuncie un resultado desactualizado; el backend también debe verificar la versión actual antes de realizar una acción con efectos secundarios, como una reserva.

Para el asistente de citas, el contexto debe establecer la fecha solicitada y la zona horaria, los horarios ofrecidos anteriormente, cualquier horario confirmado y la última corrección. Un resultado de disponibilidad debe indicar que un horario está disponible y que no se ha realizado ninguna reserva. Devuelve una confirmación de reserva solo después de que la reserva se haya realizado correctamente. Consulta Delegación al cliente para ver la configuración y el flujo de resultados completos.

Dirige las actualizaciones y correcciones

Mantén los resultados estructurados de las herramientas y los detalles del flujo de trabajo en tu backend. Devuelve a GPT-Live actualizaciones breves basadas en hechos:

• Usa session.thinking.append para informar sobre el progreso en segundo plano, como una consulta que sigue en ejecución.
• Usa session.commentary.append para un resultado verificado que el usuario deba escuchar.
• Usa session.instructions.append para las indicaciones de comportamiento redactadas por la aplicación.

Los tres aceptan content como una cadena de texto simple de un máximo de 500 tokens y requieren delegation_id. Usa el ID original de la delegación al cliente para el trabajo relacionado o null para el contexto general de la sesión. Asocia los acuses de recibo de las operaciones de adición mediante client_event_id. La aceptación no confirma que se haya generado voz ni reproducido audio. Consulta Envía el tipo de actualización adecuado.

Cuando el usuario diga “Mejor el viernes”, actualiza la tarea activa y su versión, invalida cualquier confirmación del jueves y dirige al agente existente a la solicitud corregida. Decide si cancelas o modificas la consulta pendiente, o si dejas que termine. Descarta cualquier resultado desactualizado antes de devolverlo a GPT-Live. Una interrupción de la voz no cancela una operación del backend, y una solicitud de cancelación no demuestra que una acción se haya cancelado.

El trabajo del backend puede continuar después de que termine la sesión de voz. Guarda su estado de forma persistente en tu aplicación. En una interacción de voz posterior, inicia una nueva sesión con el contexto guardado relevante; consulta Administración de sesiones.

Adapta las medidas de protección de texto y voz

Un agente de texto puede terminar y validar una respuesta antes de mostrarla. Un flujo de procesamiento encadenado puede validar la respuesta completa antes de enviarla a la etapa de conversión de texto a voz. GPT-Live puede hablar mientras el trabajo del backend sigue en ejecución, por lo que retener el resultado de una herramienta o impedir que el backend continúe no detiene toda la voz.

Sigue las indicaciones de Adapta tus medidas de protección para conservar tus verificaciones y tener en cuenta la voz continua.

Mantén la entrada de texto conectada a tu backend existente. Trata una corrección escrita como una actualización de la misma tarea y envía el contexto verificado relevante a la sesión de voz. Consulta Acepta entradas de texto y Mantén las actualizaciones precisas y útiles.