Migra a GPT-Live

Desde Realtime API

Empieza por la guía de prompts para GPT-Live. Divide el prompt existente entre el modelo de voz y el backend en lugar de copiarlo íntegro en session.instructions. Conserva el estilo de conversación y las pautas de delegación en el prompt de voz. Traslada al backend los flujos de trabajo detallados y las instrucciones de uso de las herramientas.

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 las tareas. El backend selecciona las mismas funciones y tu aplicación sigue validándolas y ejecutándolas. Los pasos de esta sección usan la delegación a Responses. Si conservas un agente externo, usa el adaptador de cliente.

Cómo funciona la delegación a Responses

Configura el modelo de backend, las instrucciones y las herramientas en delegation.responses. Cuando GPT-Live determina que una solicitud requiere la intervención 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 las herramientas. Tu aplicación sigue ejecutando las funciones personalizadas, comprobando los permisos y devolviendo los 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 el resultado e indica al backend que continúe con su respuesta.
4. GPT-Live usa la respuesta del backend para conversar con el usuario sobre los horarios disponibles.

GPT-Live puede seguir hablando mientras el backend trabaja. Haz un seguimiento por separado de la tarea del backend y de la reproducción de audio. Usa los resultados de las herramientas para actualizar el estado de la tarea y el estado del reproductor para actualizar el indicador que muestra si el asistente está hablando. Consulta Delegación y herramientas para ver la configuración y el flujo completo de eventos.

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

Reemplaza la configuración de la sesión de Realtime por el procedimiento de conexión de GPT-Live. Vuelve a comprobar cómo se inicia el transporte y qué formato de audio usa. WebRTC transmite el audio por pistas multimedia y los eventos JSON por el canal de datos. Un WebSocket principal transmite el audio dentro de eventos JSON.

Si tu aplicación de Realtime usa una conexión de servidor para supervisar la llamada o aplicar medidas de protección, adáptala a la conexión de banda lateral de GPT-Live. Sigue los pasos de Adapta tus medidas de protección para modificar las comprobaciones de la conversación y la reproducción.

Generación y reproducción: usa el estado del reproductor de audio para indicar si el asistente está hablando. El servidor puede terminar de generar audio cuando al reproductor todavía le queda un segundo de audio en la cola. En Realtime, response.output_audio.done marca el final de la generación y response.done cierra el flujo de la respuesta. Consulta response.status para detectar interrupciones o fallas. GPT-Live no tiene un evento equivalente que indique el final de cada respuesta de voz.

Subtítulos: cuando la transcripción de entrada está habilitada, Realtime envía fragmentos de texto mediante conversation.item.input_audio_transcription.delta y una transcripción final mediante conversation.item.input_audio_transcription.completed. En GPT-Live, agrega cada fragmento al final de los subtítulos de quien llama o del asistente. Ambos conjuntos de subtítulos pueden cambiar al mismo tiempo. Tu aplicación decide cómo agrupar el texto y hace un seguimiento de la reproducción mediante el reproductor de audio. Consulta Muestra subtítulos.

Usa response.create para iniciar o continuar el trabajo delegado a Responses. GPT-Live decide cuándo hablar mientras escucha la conversación. Para gestionar el inicio de la sesión, los saludos, las interrupciones y el cierre, consulta Administración de sesiones.

Separa las instrucciones de conversación de las del backend

Al migrar un asistente de Realtime a GPT-Live, parte de tu prompt actual. Traslada al prompt de Live las instrucciones sobre el estilo de voz y los turnos de conversación, y agrega reglas que indiquen cuándo delegar. Conserva en el prompt del backend las instrucciones de las tareas y los procedimientos de uso de las herramientas.

Si vas a agregar voz a un agente de texto, reutiliza su prompt de backend actual y escribe un prompt de Live para la interacción por voz.

Mantén la coherencia de la experiencia

Conserva el rol, el público y el propósito de tu asistente, así como los detalles que dan forma a la conversación:

• Los saludos, las presentaciones y los avisos que deben comunicarse de viva voz, incluidos el texto o el orden exigidos.
• Los requisitos de idioma y pronunciación, como “Habla en inglés”.
• La personalidad, la calidez, la empatía, la formalidad y el ritmo.
• El nivel de detalle de las respuestas de voz y los ejemplos que ilustran el estilo deseado.
• La manera en que el asistente le indica al usuario que lo escucha, hace pausas para escuchar y responde a las interrupciones.

Un prompt de Live breve también puede pedir respuestas de voz detalladas.

Escribe el prompt de Live

Usa la estructura de prompt recomendada para definir la identidad del asistente, su estilo al hablar y su comportamiento durante la conversación. Conserva Backchannel policy e Interruption policy para describir cómo indica que está escuchando y cómo responde cuando alguien empieza a hablar mientras él habla.

Live necesita saber qué puede hacer el backend para delegar correctamente. Describe esas capacidades en lenguaje sencillo. Los nombres de las funciones y los esquemas de las herramientas corresponden al backend, que gestiona las llamadas a herramientas.

En Delegation policy, adapta estas secciones a tu aplicación:

• Backend tools: enumera las capacidades que admite tu aplicación con los mismos términos que usas en el prompt actual. Por ejemplo: “Consulta la disponibilidad de citas y programa devoluciones de llamada”.
• Delegate to the backend when: indica cuándo usar esas capacidades, por ejemplo: “Delega cuando el usuario pida programar una devolución de llamada”. Incluye las correcciones, las confirmaciones y los datos nuevos que se necesiten para el trabajo en curso.
• Do not delegate to the backend when: describe lo que Live puede resolver directamente, como saludar, pedir una aclaración breve o repetir información de la conversación o de un resultado del backend que siga vigente.

Describe cómo debe comunicar Live los avances, formular la siguiente pregunta del backend o transmitir un resultado verificado.

Si tu asistente finaliza llamadas, dale a Live instrucciones para despedirse y delegar la solicitud de finalización. Coloca en el backend la herramienta que finaliza la llamada y la secuencia de pasos correspondiente. Por ejemplo, un procedimiento podría exigir que la aplicación termine de reproducir la despedida, se desconecte, cancele los cálculos pendientes y bloquee cualquier intento posterior de guardar datos. Live se encarga de la despedida y la delegación. El backend y la aplicación ejecutan los pasos restantes.

Adapta el prompt de tu backend

Parte de tu prompt original. Conserva su redacción, orden, ejemplos y estructura donde sigan siendo pertinentes. Si describe principalmente tareas, puedes dejar la mayor parte tal como está.

Conserva aquí las instrucciones para:

• Interpretar la solicitud del usuario, aplicar correcciones, recopilar la información faltante y seguir el progreso de la tarea.
• Usar datos propios del dominio, comprobar si se cumplen los requisitos y consultar los registros o servicios que permiten determinar la respuesta.
• Seguir los procedimientos para búsquedas, actualizaciones, confirmaciones, enrutamiento, transferencias, devoluciones de llamada y otras acciones admitidas.
• Aplicar reglas de seguridad, privacidad y autorización, gestionar fallas y restringir acciones después de una transferencia o del fin de una llamada.
• Preparar datos precisos, el estado de la tarea y la siguiente pregunta para que Live los comunique.

Traslada al prompt de Live las instrucciones de voz, saludos, turnos de conversación y delegación. Adapta las instrucciones que dan por hecho que el backend habla directamente con el usuario para que el backend devuelva la información a Live. Conserva en ambos prompts los límites de seguridad y privacidad que afecten lo que el modelo correspondiente puede decir, preguntar o hacer.

Conserva los nombres de funciones, los requisitos de los argumentos y los procedimientos de uso de las herramientas en las instrucciones del backend. Incluye las definiciones de las herramientas en la configuración de herramientas de tu backend. Tu aplicación ejecuta sus herramientas y comprueba los permisos, la validez de los argumentos y las confirmaciones requeridas según el estado actual de la tarea.

Usa el modelo de backend para interpretar las solicitudes, correcciones y confirmaciones de la conversación. Las expresiones regulares, las listas de palabras clave y las reglas que buscan frases exactas no captan los significados que dependen de lo dicho antes o de una corrección. Por ejemplo, un “sí” puede confirmar un horario, indicar que se escuchó una pregunta o hacer referencia a una sugerencia anterior.

Conserva las reglas que se aplican al trabajo en curso cuando la persona que llama interrumpe al asistente o cuando se transfiere o finaliza la llamada. Aunque el asistente deje de hablar, el backend sigue trabajando. Si la persona pide cancelar la operación, el backend y la aplicación deben gestionar la cancelación e informar a Live del resultado.

Resuelve las contradicciones entre instrucciones

Revisa el prompt original y los dos prompts nuevos para detectar instrucciones contradictorias. Combina las instrucciones repetidas y mantén las condiciones específicas y las excepciones junto a las reglas correspondientes. Revisa los permisos, los límites de preguntas, las confirmaciones y las acciones permitidas después de que finalice una llamada.

Distingue entre lo que quiere el usuario y lo que ya ocurrió. Si la persona cambia el viernes por el jueves, la solicitud más reciente le indica al backend que debe trabajar con el jueves. El registro de la reserva le indica si ya se había reservado el viernes. Tus reglas de confirmación y autorización determinan qué cambios puede hacer a continuación.

Antes de usar los prompts, acuerda las decisiones de producto con las personas responsables. Por ejemplo, si una instrucción indica que se debe continuar con una reserva y otra exige detener todo el trabajo cuando la persona que llama interrumpe al asistente, decide cómo debe comportarse la aplicación. Documenta el comportamiento acordado en los prompts y en la lógica de la aplicación que lo hace cumplir.

Comprueba que cada acción requerida esté implementada. Para finalizar una llamada, necesitas una función que la termine. Si el asistente solo se despide, la conexión queda abierta. Si falta una capacidad, decide si la implementarás o si acordarás una alternativa compatible con el equipo responsable del flujo de trabajo.

Revisa ambos prompts

Compara los dos prompts con el original y comprueba que contemplen todos los comportamientos requeridos:

• El prompt de Live conserva la identidad, el vocabulario, el estilo de voz y los avisos del asistente, así como su forma de responder a las interrupciones.
• El prompt del backend conserva los procedimientos de las tareas, los datos, las condiciones, los ejemplos, los permisos y la gestión de fallas.
• La delegación abarca solicitudes nuevas, correcciones, confirmaciones y solicitudes que combinan la conversación con información de la tarea.
• Los dos prompts coinciden en los límites de preguntas, en cuándo se considera confirmada una acción y en cómo gestionar el trabajo en curso, la cancelación, las transferencias y la finalización de llamadas.

Coloca el prompt de Live en session.instructions. Para la delegación a Responses, coloca el prompt del backend en session.delegation.responses.instructions. Para la delegación al cliente, consérvalo en la configuración de tu agente actual. Mantén las definiciones de las herramientas en el backend. Consulta Delegación y herramientas para ver cómo configurar la delegación y gestionar los resultados.

Eres Rowan, el asistente de citas de Northstar Repairs.
Habla en inglés, con calma y brevedad. Saluda a quien llama una sola vez con estas palabras:
“Hello, this is Rowan from Northstar Repairs. How can I help?”
Usa frases breves para indicar que estás escuchando. Si te interrumpen, deja de hablar.

Ayuda a quienes llaman a encontrar y reservar citas. Si no conoces la fecha que prefiere
la persona o su zona horaria, pide los datos que falten. Luego usa check_availability.
Ofrece únicamente los horarios que devuelva la herramienta. Pide a la persona que confirme
el horario exacto. Llama a book_appointment solo después de recibir esa confirmación.
Si la persona cambia la fecha, la zona horaria o el horario, descarta la confirmación anterior
y vuelve a consultar la disponibilidad.
Comunica que la cita quedó reservada solo cuando la herramienta confirme que la reserva se completó.
Si el resultado no está claro, di que la reserva sigue sin confirmarse y no vuelvas a intentarlo automáticamente.

Eres Rowan, el asistente de citas de Northstar Repairs.
Habla en inglés, con calma y brevedad. Saluda a quien llama una sola vez con estas palabras:
“Hello, this is Rowan from Northstar Repairs. How can I help?”

Backchannel policy: usa frases breves para indicar que estás escuchando.

Interruption policy: si te interrumpen, deja de hablar y escucha.

Delegation policy:
Backend tools:
- Citas: consulta de horarios disponibles y reserva de citas.

Delegate to the backend when:
- La persona que llama quiere encontrar o reservar una cita.
- La persona indica o corrige una fecha, una zona horaria o un horario, o responde
  a una pregunta sobre la reserva, por ejemplo, al confirmar un horario.

Do not delegate to the backend when:
- La persona te saluda o te pide que repitas un resultado que sigue vigente.
- Necesitas una breve aclaración para entender qué te pide.

Transmite las preguntas y los resultados del backend. Ofrece únicamente los horarios que devuelva.
Espera a que el backend confirme que la reserva se completó antes de decir que la cita quedó reservada.
Si el backend indica que el resultado no está claro, di que la reserva sigue sin confirmarse.

Ayuda a quienes llaman a encontrar y reservar citas en Northstar Repairs.
Si no conoces la fecha que prefiere la persona o su zona horaria, pide los datos que falten.
Luego usa check_availability. Ofrece únicamente los horarios que devuelva la herramienta.
Pide a la persona que confirme el horario exacto. Llama a book_appointment solo después de recibir esa confirmación.
Si la persona cambia la fecha, la zona horaria o el horario, descarta la confirmación anterior
y vuelve a consultar la disponibilidad.
Informa que la cita quedó reservada solo cuando la herramienta confirme que la reserva se completó.
Si el resultado no está claro, indica que la reserva sigue sin confirmarse y no vuelvas a intentarlo automáticamente.

Devuelve los horarios disponibles, el resultado de la reserva o la siguiente pregunta
para que el asistente de voz los comunique. Usa la conversación y el estado actual de la tarea
para interpretar las respuestas y correcciones más recientes de quien llama.

Adapta tus manejadores de funciones

Conserva la implementación de check_availability y book_appointment. Traslada sus definiciones de session.tools o response.tools de Realtime a delegation.responses.tools y usa el esquema de funciones de Responses. Traslada 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 el manejador y adónde envía el resultado:

Por ejemplo, después de que check_availability devuelva un horario verificado, envía lo siguiente en tu sesión conectada. Reemplaza call_availability por el ID de 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,
    )

1
2
3
4
5
6
7
8
9
10
11
12
13
14import (
	"context"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/live"
	"github.com/openai/openai-go/v3/responses"
)

// SendUpdate requires a started Live session.
func SendUpdate(ctx context.Context, connection *live.LiveConnection) error {
	return connection.Send(ctx, live.ClientEventUnionParam{OfResponseItemCreate: &live.ResponseItemCreateEventParam{
		EventID: openai.String("availability_result_1"),
		Item:    responses.ResponseInputItemUnionParam{OfFunctionCallOutput: &responses.ResponseInputItemFunctionCallOutputParam{CallID: openai.String("call_availability"), Output: responses.ResponseInputItemFunctionCallOutputOutputUnionParam{OfString: openai.String("{\"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
17import com.openai.helpers.LiveConnection;
import com.openai.models.live.*;
import com.openai.models.responses.*;

public static void sendUpdate(LiveConnection connection) {
  connection.send(
      ClientEvent.ofResponseItemCreate(
          ResponseItemCreateEvent.builder()
              .eventId("availability_result_1")
              .item(
                  ResponseInputItem.FunctionCallOutput.builder()
                      .callId("call_availability")
                      .output(
                          "{\"available\":true,\"slot_id\":\"slot_friday_14\",\"booked\":false}")
                      .build())
              .build()));
}

1
2
3
4
5
6
7
8
9def send_update(connection)
  connection.send_event(
    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}"
    }
  )
end

Después de enviar todos los resultados de funciones requeridos, indica al backend que continúe:

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",
    )

1
2
3
4
5
6
7
8
9
10
11
12import (
	"context"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/live"
)

// SendUpdate requires a started Live session.
func SendUpdate(ctx context.Context, connection *live.LiveConnection) error {
	return connection.Send(ctx, live.ClientEventUnionParam{OfResponseCreate: &live.ResponseCreateEventParam{
		EventID: openai.String("continue_availability_1"),
	}})
}

1
2
3
4
5
6
7
8import com.openai.helpers.LiveConnection;
import com.openai.models.live.*;

public static void sendUpdate(LiveConnection connection) {
  connection.send(
      ClientEvent.ofResponseCreate(
          ResponseCreateEvent.builder().eventId("continue_availability_1").build()));
}

1
2
3def send_update(connection)
  connection.send_event(type: "response.create", event_id: "continue_availability_1")
end

Para la migración inicial, configura parallel_tool_calls en false para procesar una llamada a herramienta a la vez. Obtén cada llamada a función del evento interno response.output_item.done y conserva su nombre, sus argumentos y su call_id. Conserva ese registro incluso si un evento de finalización posterior contiene output: []. Espera a recibir el elemento completo antes de ejecutar el manejador. El evento que indica que los argumentos están completos no incluye por sí solo el nombre de la función ni el call_id. Sigue el procedimiento completo para los resultados de funciones para recopilar las llamadas, enviar los resultados y gestionar los errores.

Conserva el contexto y aplica las correcciones

La delegación a Responses proporciona al backend el contexto pertinente de la conversación de voz. Mantén en tu aplicación el registro de referencia del estado de la cita: el horario seleccionado, el horario confirmado, los permisos, la operación activa y el resultado. El historial de conversación de Live puede compactarse y no sustituye al registro de reservas.

Cuando el usuario diga “Mejor el viernes”, registra el viernes como la solicitud actual y elimina cualquier confirmación del jueves. Asigna un nuevo número de versión a la tarea, como la revisión 2, para que tu aplicación pueda reconocer los resultados de la solicitud anterior.

Antes de reservar, comprueba que la fecha, el horario y la confirmación sigan coincidiendo con la solicitud actual. Si rechazas una llamada a función pendiente porque el usuario cambió la solicitud, devuelve un resultado que indique si se omitió o se canceló, según lo que haya ocurrido. Envía un resultado por cada llamada requerida antes de indicar al backend que continúe.

Si la reserva del jueves ya se completó, comprueba su estado actual y gestiona el cambio solicitado antes de intentar otra reserva.

Conserva cada fragmento de transcripción tal como lo recibes, junto con la identidad de quien habla, start_ms y end_ms. Usa esa información para actualizar el subtítulo o la burbuja de chat que corresponda a quien llama o al asistente, incluso si el fragmento llega tarde o si ambos hablan a la vez. Define en tu aplicación dónde empieza y termina cada mensaje y haz un seguimiento de la reproducción de audio en el reproductor. Las marcas de tiempo de la transcripción no indican el momento exacto en que se reproduce cada palabra. Aclara las fechas, los nombres y los números importantes si la intención del usuario no está clara. Consulta Administración de sesiones para ver cómo gestionar las transcripciones y el contexto.

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

Conserva las decisiones que dependen del audio

Algunas decisiones requieren el sonido en sí, como detectar el tono del buzón de voz o reconocer un saludo grabado por su cadencia. GPT-Live escucha la llamada, pero la delegación no envía automáticamente el audio a tu backend. En el modo de cliente, session.delegation.created contiene un ID e información temporal. Tu aplicación proporciona el contexto de la solicitud y el audio que necesite el backend.

Para detectar contestadores automáticos, envía explícitamente el audio entrante a un detector que pueda procesarlo. Una arquitectura que puedes evaluar consiste en que tu aplicación ejecute una sesión independiente de Realtime 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 comunique su clasificación mediante una llamada a función estructurada. Valida cada resultado con tu esquema, descarta los resultados desactualizados y conserva el estado como desconocido si no hay evidencia suficiente. Permite que la decisión cambie si aparecen nuevos indicios.
3. Envía a GPT-Live el contexto pertinente que provenga de fuentes confiables y aplica la política de tu aplicación a la reproducción de audio saliente.

Haz un seguimiento de dos decisiones: si estás hablando con una persona o con un sistema automático y si el destinatario está listo para grabar tu mensaje. Un detector puede reconocer el buzón de voz mientras aún se reproduce el saludo. Espera a tener la evidencia que exige tu aplicación antes de permitir la salida de audio. El acuse de recibo del contexto indica que se aceptó la actualización. La decisión de reproducir el audio sigue correspondiendo a tu aplicación. Usa Adapta 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 luego resulta ser parte de un saludo del buzón de voz, los mensajes de un sistema de filtrado de llamadas y el caso de una persona que contesta mientras está activo el buzón de voz. Si planeas detener el detector antes de que termine la llamada, prueba qué ocurre si una persona contesta después. Usa esos resultados y el costo adicional del detector para decidir cuánto tiempo debe estar activo. Incluye casos en los que la clasificación inicial de “persona” cambie al recibir más audio.

Desde un agente de texto o un pipeline en cadena

Antes: un agente de texto recibe solicitudes escritas y usa sus herramientas y el estado guardado. Un pipeline de voz en cadena, o en cascada, agrega una etapa de conversión de voz a texto antes del agente y otra de texto a voz después.

Después: GPT-Live proporciona la interfaz de voz y delega las tareas a tu agente actual. En un pipeline en cadena, reemplaza las etapas independientes 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 actual

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

Usa esta notificación para iniciar el manejador de delegación de tu aplicación. Conserva delegation.id para que puedas asociar el resultado con la misma solicitud. El manejador prepara la entrada del agente a partir de las transcripciones de quien llama y del asistente, junto con los registros de tareas que conserva tu aplicación. La notificación en sí no contiene el texto de la solicitud ni los argumentos de las herramientas.

Por ejemplo, el agente de citas podría recibir lo siguiente:

Persona que llama: “Mejor el viernes”.

Solicitud actual: buscar una cita para el viernes en la zona horaria de la persona que llama.

Resultado anterior: se ofreció el jueves a las 2 p. m.

Confirmación: no se ha confirmado ningún horario para el viernes.

Revisión de la tarea: 2.

La notificación puede llegar antes de que se transcriba la oración completa. Consérvala hasta que tengas suficiente contexto o pide una aclaración a la persona que llama antes de actuar.

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

Antes de llamar al adaptador, registra el ID de delegación para que solo un manejador empiece a trabajar en esa solicitud. Si la solicitud no está clara, vuelve a llamar al adaptador cuando el contexto esté listo.

Tu backend sigue siendo responsable de la autorización, la confirmación, los ID de las operaciones y los reintentos. Comprueba la revisión actual de la tarea antes de cambiar una reserva. La comprobación de revisión que realiza el adaptador más adelante solo evita que se anuncie un resultado desactualizado. No puede deshacer una reserva ya realizada.

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,
    )

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
34import (
	"context"
	"crypto/rand"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/live"
)

type Context struct {
	Revision           int
	RecentConversation string
	Task               string
}

func handleDelegation(ctx context.Context, event live.ServerEventUnion, connection *live.LiveConnection,
	readContext func() *Context, runAgent func(context.Context, Context) (string, error), currentRevision func() int) error {
	if event.Type != "session.delegation.created" || event.AsDelegationCreatedEvent().Delegation.Target != "client" {
		return nil
	}
	snapshot := readContext()
	if snapshot == nil {
		return nil
	} // Retain the notice; resolve the request before acting.
	saved := *snapshot
	summary, err := runAgent(ctx, saved)
	if err != nil {
		return err
	}
	if currentRevision() != saved.Revision {
		return nil
	}
	return connection.Send(ctx, live.ClientEventUnionParam{OfSessionCommentaryAppend: &live.CommentaryAppendEventParam{
		EventID: openai.String(rand.Text()), DelegationID: openai.String(event.AsDelegationCreatedEvent().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
34import com.openai.helpers.LiveConnection;
import com.openai.models.live.*;
import java.util.UUID;
import java.util.concurrent.CompletionStage;
import java.util.function.*;

public record Context(int revision, String recentConversation, String task) {}

public static CompletionStage<Void> handleDelegation(
    ServerEvent event,
    LiveConnection connection,
    Supplier<Context> readContext,
    Function<Context, CompletionStage<String>> runAgent,
    IntSupplier currentRevision) {
  if (!event.isSessionDelegationCreated()
      || !event.asSessionDelegationCreated().delegation().target().toString().equals("client"))
    return java.util.concurrent.CompletableFuture.completedFuture(null);
  var snapshot = readContext.get();
  // Retain the notice; resolve the request before acting.
  if (snapshot == null) return java.util.concurrent.CompletableFuture.completedFuture(null);
  return runAgent
      .apply(snapshot)
      .thenAccept(
          summary -> {
            if (currentRevision.getAsInt() != snapshot.revision()) return;
            connection.send(
                ClientEvent.ofSessionCommentaryAppend(
                    CommentaryAppendEvent.builder()
                        .eventId(UUID.randomUUID().toString())
                        .delegationId(event.asSessionDelegationCreated().delegation().id())
                        .content(summary)
                        .build()));
          });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18require "openai"
require "securerandom"
Context = Data.define(:revision, :recent_conversation, :task)

def handle_delegation(event, connection, read_context:, run_agent:, current_revision:)
  return unless event.type == :"session.delegation.created" && event.delegation.target == :client

  context = read_context.call
  return if context.nil? # Retain the notice; resolve the request before acting.

  summary = run_agent.call(context)
  return unless current_revision.call == context.revision

  connection.send_event(
    type: :"session.commentary.append", event_id: SecureRandom.uuid,
    delegation_id: event.delegation.id, content: summary
  )
end

Implementa en tu aplicación los callbacks de contexto y del agente. El callback de contexto devuelve la conversación reciente y la tarea actual, o no devuelve ningún valor mientras la solicitud siga sin estar clara. El callback del agente ejecuta tu backend actual y devuelve un resumen verificado de hasta 500 tokens. En JavaScript, el callback send que proporciona tu aplicación envía el evento JSON por tu conexión de Live. En Python, el adaptador envía la actualización directamente mediante connection del SDK.

En el caso del asistente de citas, el contexto debe indicar la fecha y la zona horaria solicitadas, 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 aún no se ha realizado ninguna reserva. Devuelve una confirmación de reserva solo después de que se complete la reserva. Consulta Delegación al cliente para ver la configuración y el flujo completo de resultados.

Dirige las actualizaciones y las correcciones

Conserva en tu backend los resultados estructurados de las herramientas y los detalles del flujo de trabajo. Envía a GPT-Live actualizaciones breves que comuniquen hechos:

• Usa session.thinking.append para comunicar el progreso en segundo plano, como una consulta que sigue en curso.
• Usa session.commentary.append para un resultado verificado que el usuario deba escuchar.
• Usa session.instructions.append para las pautas de comportamiento que proporcione la aplicación.

Los tres comandos aceptan content como una cadena de texto simple de hasta 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 cada acuse de recibo con el comando que enviaste mediante client_event_id. Esto confirma que se aceptó la actualización. Usa los eventos de transcripción del asistente para saber qué contenido de voz se generó y el estado del reproductor para seguir la reproducción. Consulta Envía el tipo de actualización adecuado.

Cuando el usuario diga “Mejor el viernes”, guarda el viernes como la solicitud actual, incrementa su número de versión y elimina cualquier confirmación del jueves. Envía la corrección a tu agente actual. Decide si solicitarás la cancelación de la consulta del jueves, si la modificarás o si dejarás que termine y descartarás el resultado.

Comprueba el estado de la consulta antes de comunicar que se canceló. Gestiona esa decisión en el backend incluso si la interrupción del usuario ya hizo que el asistente dejara de hablar.

El backend puede seguir trabajando después de que termine la sesión de voz. Guarda el estado de ese trabajo en tu aplicación. En una interacción de voz posterior, inicia una sesión nueva con el contexto guardado que corresponda. Consulta Administración de sesiones.

Mantén la entrada de texto conectada a tu agente

Mantén la entrada de texto conectada a tu backend actual. Trata las correcciones escritas como actualizaciones de la misma tarea y envía a la sesión de voz el contexto pertinente que hayas verificado. Consulta Acepta entradas de texto y Mantén las actualizaciones precisas y útiles.

Adapta las medidas de protección para texto y voz

Un agente de texto o un pipeline en cadena puede validar una respuesta completa antes de mostrarla o leerla en voz alta. Con GPT-Live, la conversación y el trabajo del backend ocurren al mismo tiempo. Si cada respuesta de voz debe pasar una comprobación antes de que la escuche el usuario, incorpora esa comprobación a la ruta de reproducción de audio que controla tu aplicación. Retener un resultado del backend no basta para pausar toda la salida de voz.

Sigue los pasos de Adapta tus medidas de protección para conservar tus comprobaciones y tener en cuenta que el asistente puede seguir hablando.