Controles del lado del servidor

Controla una sesión de GPT-Live desde tu servidor

Conecta el servidor de tu aplicación a una sesión existente de GPT-Live que use WebRTC o SIP cuando el servidor necesite recibir eventos de conversación, ejecutar herramientas privadas o actualizar la conversación. Esta segunda conexión se denomina WebSocket auxiliar. Ambas conexiones comparten una sesión, y WebRTC o SIP se encarga del transporte principal de audio.

El canal auxiliar transmite eventos y comandos. Tu aplicación se encarga de ejecutar las herramientas, verificar la autorización y aplicar las reglas de negocio. Guarda las claves de API y las credenciales de las herramientas en tu servidor.

Decide si necesitas un canal auxiliar

En aplicaciones de navegador, usa el canal de datos de WebRTC para mostrar subtítulos y actualizar la interfaz local. Usa un canal auxiliar cuando proceses la transcripción en tu servidor, por ejemplo, para aplicar controles de seguridad, analizar el sentimiento o hacer llamadas especulativas a herramientas. Tu servidor puede recibir eventos y controlar directamente esa misma sesión mientras el navegador sigue transmitiendo el audio por WebRTC. Consulta los ejemplos en Cómo reaccionar a los fragmentos de transcripción.

Si tu backend transmite audio por la conexión WebSocket principal, usa esa conexión para recibir eventos y enviar comandos.

La delegación en Responses también funciona sin un canal auxiliar. El navegador puede reenviar los eventos de llamada a función desde su canal de datos a un backend autenticado para que ejecute las funciones. Las herramientas alojadas por OpenAI se ejecutan a través del backend delegado sin necesidad de que la aplicación implemente un ejecutor de herramientas.

Conéctate a la sesión existente

1. Guarda el ID de la sesión que controlará tu backend. Para WebRTC o una llamada SIP saliente, usa session.id de la respuesta JSON a POST /v1/live/sessions. Para llamadas SIP entrantes, primero acepta la llamada entrante y luego usa data.session_id de su webhook. Guarda el ID junto con el registro del usuario y de la conversación en tu aplicación.

2. Abre una conexión WebSocket desde tu servidor con la siguiente URL. Sustituye el marcador por el ID guardado, sin modificarlo. Autentícate con Authorization: Bearer $OPENAI_API_KEY usando las credenciales del proyecto que creó o aceptó la sesión. Incluye los mismos encabezados de conexión que se requieren al crear la sesión.

   wss://api.openai.com/v1/live/sessions/{session_id}/attach

3. Recibe eventos y envía comandos por el socket conectado a la sesión. La sesión ya está en curso. No vuelvas a enviar session.start.

Usa el ID de sesión sin modificarlo, incluido el prefijo, y verifica que tu aplicación tenga autorización para acceder a esa sesión.

Observa eventos y envía comandos

Los comandos siguen las mismas reglas de validación y delegación que en la conexión principal. Al agregar contexto general a la sesión, usa delegation_id: null. Si el ID no es nulo, debe identificar una delegación existente del cliente. Consulta Delegación y herramientas para ver cómo configurar la delegación y ejecutar funciones, así como ejemplos de cómo agregar contexto.

En las sesiones de navegador, mantén la entrada del micrófono y la salida de los altavoces en la pista multimedia negociada mediante WebRTC. Usa el canal auxiliar para recibir eventos de conversación y controlar la sesión, y haz el seguimiento de la reproducción en tu reproductor de audio.

Recibe copias del audio

Una vez conectado, el canal auxiliar también recibe copias del audio de entrada y salida que se transmite a partir de ese momento. La conexión principal sigue transportando el audio en vivo.

Ambas cargas útiles contienen audio PCM16LE mono sin procesar a 24 kHz, codificado en base64, independientemente del formato de audio del transporte principal. Ninguno de los eventos tiene un event_id. La copia del audio de entrada contiene el audio recibido antes de silenciar la entrada. Recibirla no confirma que el modelo haya procesado esas muestras. Los intervalos del audio de salida copiado pueden presentar discontinuidades si se descartan tramas y no indican cuándo escuchó el audio la persona que llamó.

Envía el audio del micrófono únicamente por la conexión principal. Usa el canal auxiliar para recibir las copias del audio.

Asigna un solo responsable a cada acción

Decide si el navegador o el backend se encargará de cada acción. Si ambas conexiones reciben un evento de llamada a función, ejecuta la función una sola vez. Aplica la misma regla a las actualizaciones de contexto y a las solicitudes para continuar el trabajo en el backend.

Conecta el backend lo antes posible si necesita observar la conversación desde el inicio. Guarda las transcripciones y el estado de las herramientas en tu aplicación, incluido el historial recopilado antes de la conexión.

El navegador puede seguir recibiendo eventos de sesión mientras el canal auxiliar está conectado. Mantén las credenciales sensibles de las herramientas y las decisiones de autorización en tu backend, y devuelve solo el contexto necesario para la conversación.

Aplica controles de seguridad a la conversación

Usa la conexión WebSocket principal de tu servidor o el canal auxiliar para monitorear la conversación y verificar que las solicitudes cumplan las políticas de tu aplicación. Tu aplicación realiza las verificaciones, bloquea las acciones afectadas y envía instrucciones correctivas cuando detecta un problema.

Ejecuta las verificaciones mientras continúa la conversación

Al procesar los fragmentos de transcripción a medida que llegan, puedes aplicar controles de seguridad. Con el mismo flujo puedes iniciar una consulta especulativa o actualizar la interfaz mientras se ejecutan las verificaciones.

1. Monitorea las transcripciones. Acumula los fragmentos de session.input_transcript.delta para detectar intentos de jailbreak, información sensible o infracciones de las políticas en las solicitudes del usuario. Usa session.output_transcript.delta para detectar afirmaciones sin fundamento o respuestas fuera del alcance de tu aplicación en lo que dice el asistente. Mantén cada verificación asociada con la transcripción y la solicitud de la aplicación que evaluó.
2. Ejecuta las verificaciones en paralelo. Un modelo rápido y ligero puede evaluar las solicitudes mientras continúa la conversación. Devuelve un resultado estructurado breve, como {"triggered": true}, que tu aplicación pueda usar para decidir cómo actuar. Ejecuta las acciones que requieren aprobación solo después de que superen las verificaciones. Mantenlas bloqueadas si alguna verificación falla o excede el tiempo de espera.
3. Bloquea las acciones afectadas. Cuando se active un control de seguridad, marca la solicitud como bloqueada en el estado de la aplicación. Consulta ese estado antes de ejecutar una herramienta o confirmar un cambio, incluso si el trabajo ya está en cola.
4. Detén el trabajo relacionado. Cancela las tareas que gestiona tu aplicación si el backend admite su cancelación, y descarta los resultados tardíos de las solicitudes bloqueadas o reemplazadas. Si usas la delegación en Responses, deja de ejecutar las funciones personalizadas afectadas y no envíes response.create para continuar el trabajo bloqueado. Esto no cancela una respuesta alojada que ya esté en curso ni detiene la voz del frontend.
5. Registra la decisión y reorienta la conversación. Registra la decisión junto con los ID de la solicitud y de la delegación afectadas, y luego envía una instrucción correctiva.

Consulta Deltas de transcripción para recopilar fragmentos y Delegación y herramientas para que los resultados del backend correspondan a la tarea actual.

Reorienta la conversación

Usa session.instructions.append para reorientar la conversación cuando se active un control de seguridad. Este comando puede interrumpir al asistente mientras habla y aplicar una nueva instrucción. Por ejemplo, después de que tu aplicación bloquee una solicitud, envía lo siguiente:

1
2
3
4
5
6
7
8
9export function sendUpdate(connection) {
  connection.send({
    type: "session.instructions.append",
    event_id: "guardrail_block_17",
    delegation_id: null,
    content:
      "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.",
  });
}

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


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    await connection.session.instructions.append(
        event_id="guardrail_block_17",
        delegation_id=None,
        content=(
            "Stop speaking immediately. Do not continue or act on the last request. "
            "Refuse briefly, then wait."
        ),
    )

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import (
	"context"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/live"
	"github.com/openai/openai-go/v3/packages/param"
)

// SendSidebandUpdate uses the server connection attached to an existing session.
func SendSidebandUpdate(ctx context.Context, connection *live.SidebandConnection) error {
	return connection.Send(ctx, live.ConnectClientEventUnionParam{OfSessionInstructionsAppend: &live.InstructionsAppendEventParam{
		EventID:      openai.String("guardrail_block_17"),
		DelegationID: param.Null[string](),
		Content:      "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.",
	}})
}

// SendUpdate requires a started Live session.
func SendUpdate(ctx context.Context, connection *live.LiveConnection) error {
	return connection.Send(ctx, live.ClientEventUnionParam{OfSessionInstructionsAppend: &live.InstructionsAppendEventParam{
		EventID:      openai.String("guardrail_block_17"),
		DelegationID: param.Null[string](),
		Content:      "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.",
	}})
}

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
27import com.openai.core.JsonField;
import com.openai.helpers.LiveConnection;
import com.openai.helpers.LiveSidebandConnection;
import com.openai.models.live.*;

// Use the server connection attached to an existing session.
public static void sendUpdate(LiveSidebandConnection connection) {
  connection.send(
      InstructionsAppendEvent.builder()
          .eventId("guardrail_block_17")
          .delegationId(JsonField.<String>ofNullable(null))
          .content(
              "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.")
          .build());
}

// Use a primary connection after its session has started.
public static void sendUpdate(LiveConnection connection) {
  connection.send(
      ClientEvent.ofSessionInstructionsAppend(
          InstructionsAppendEvent.builder()
              .eventId("guardrail_block_17")
              .delegationId(JsonField.<String>ofNullable(null))
              .content(
                  "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.")
              .build()));
}

1
2
3def send_update(connection)
  connection.send_event(type: "session.instructions.append", event_id: "guardrail_block_17", delegation_id: nil, content: "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.")
end

Asegúrate de que tu aplicación redacte la instrucción. No copies en ella texto no confiable del usuario como si fuera una instrucción. Usa delegation_id: null para aplicar esta corrección a toda la sesión y limita content a un máximo de 500 tokens.

Asocia el evento session.instructions.appended con tu comando mediante client_event_id. La confirmación llega después del momento estimado de incorporación del contexto. Para impedir que el audio llegue a la persona que llamó, usa los controles de reproducción que se describen a continuación.

Usa instrucciones también para los avisos que deban comunicarse en voz alta con una formulación específica. Consulta Cómo comunicar un aviso para ver un ejemplo y algunas consideraciones sobre la reproducción.

Controla la reproducción cuando sea necesario

Si tu aplicación necesita bloquear el audio del modelo, controla la reproducción en el cliente o en el retransmisor multimedia. Silencia o descarta temporalmente la salida, descarta el audio en la cola local y envía la instrucción correctiva. Después de eliminar el audio que ya no corresponde, reanuda la reproducción según la política de recuperación de tu aplicación. La confirmación de la instrucción no indica que debas reanudarla. El canal auxiliar por sí solo no controla la reproducción, y las instrucciones correctivas no pueden retirar el audio que la persona que llamó ya escuchó.

session.input_audio.mute controla la entrada del micrófono de la persona que llamó. No silencia la salida del modelo ni cancela el trabajo delegado.

Verifica lo que dice el asistente antes de reproducirlo

En la mayoría de las aplicaciones, monitorea las transcripciones del usuario y del asistente mientras continúa la conversación. Cuando se active un control de seguridad, tu aplicación podrá bloquear las acciones afectadas o enviar instrucciones correctivas.

Si tu aplicación necesita verificar lo que dice el asistente antes de reproducirlo, almacena temporalmente el audio en el búfer del reproductor o del puente multimedia antes de enviarlo a la persona que llamó. Sigue recibiendo eventos de audio y de transcripción mientras se ejecuta la verificación, y lee las transcripciones independientemente de la reproducción.

1. Recopila el audio y su transcripción. Implementa la detección de actividad de voz (VAD) en la salida de tu aplicación o usa una puerta de ruido que ofrezca tu framework multimedia para identificar posibles segmentos de voz. GPT-Live no proporciona un detector de actividad de voz ni una puerta de ruido en la salida para este flujo de trabajo. Espera a recibir la transcripción necesaria para verificar cada segmento.
2. Habilita la reproducción del audio aprobado. Cuando un segmento supere la verificación, agrega el audio original de ese segmento, almacenado en el búfer, a la cola de reproducción. Si la verificación falla, falta la transcripción o se excede el tiempo de espera, descarta el segmento y usa una alternativa segura definida por tu aplicación.
3. Gestiona las interrupciones. Asocia el audio, la transcripción, el resultado de la verificación y el estado de reproducción con un ID generado por tu aplicación. Si una interrupción cancela ese segmento de voz, elimina su audio del búfer y de la cola, e ignora cualquier aprobación posterior del segmento.

Una pausa puede delimitar un posible segmento de voz aunque el modelo aún esté formulando la respuesta. Si tu política exige verificar la respuesta completa, define cómo determinará tu aplicación que la respuesta ha terminado. La detección de actividad de voz por sí sola no basta para determinarlo.

El almacenamiento en búfer agrega latencia. Lo que el asistente dijo permanece en el contexto de conversación del modelo aunque descartes el audio. Por eso, prueba cómo continúa la conversación después de omitir un segmento de audio o de usar una alternativa segura.

Prueba la intervención

Prueba solicitudes permitidas y bloqueadas, falsos positivos, verificaciones lentas o fallidas y resultados tardíos de tareas canceladas. Prueba también qué ocurre si se activa un control mientras el asistente habla o mientras se ejecuta una herramienta. Verifica por separado el bloqueo de acciones, el estado de la aplicación, lo que dice el asistente para corregir la situación y el audio que se reproduce. Si controlas la salida, incluye en la prueba el audio en cola y la recuperación. Usa la guía del Cookbook para evaluar agentes de voz para comparar el éxito de las tareas y el tiempo de respuesta por voz.

Cierra la sesión de forma ordenada

Sigue recibiendo eventos mientras las herramientas terminan de ejecutarse y la sesión informa del uso final. Registra el manejador de session.closed antes de enviar session.close, y mantén abiertos la conexión WebRTC, el canal de datos y el canal auxiliar hasta que termine el trabajo pendiente. Antes de liberar los recursos, guarda los datos de uso finales de la sesión y los datos de uso del backend que hayas recibido en eventos de Responses. Si la conexión falla antes de que llegue el evento final, registra el cierre como incompleto. Consulta la secuencia de cierre en Gestión de sesiones.

La Realtime API permite que los clientes se conecten directamente al servidor de la API mediante WebRTC o SIP. Sin embargo, lo más probable es que quieras gestionar el uso de herramientas y el resto de la lógica de negocio en el servidor de tu aplicación para que esa lógica sea privada e independiente del cliente.

Protege el uso de herramientas, la lógica de negocio y otros detalles en el servidor mediante un canal de control “auxiliar”. Ya puedes usar un canal auxiliar tanto con conexiones SIP como con conexiones WebRTC.

Al usar un canal auxiliar, hay dos conexiones activas a la misma sesión de Realtime: una desde el cliente del usuario y otra desde el servidor de tu aplicación. Puedes usar la conexión del servidor para monitorear la sesión, actualizar las instrucciones y responder a llamadas a herramientas.

Con WebRTC

1. Al establecer una conexión entre pares, envías una solicitud a la Realtime API y recibes una respuesta SDP para configurar la conexión. Si usaste el código de ejemplo de la guía de WebRTC, verás algo similar a esto:

1
2
3
4
5
6
7
8
9const baseUrl = "https://api.openai.com/v1/realtime/calls";
const sdpResponse = await fetch(baseUrl, {
  method: "POST",
  body: offer.sdp,
  headers: {
    Authorization: `Bearer ${EPHEMERAL_KEY}`,
    "Content-Type": "application/sdp",
  },
});

2. La respuesta a la solicitud incluirá un encabezado Location con un ID de llamada único que puedes usar en el servidor para establecer una conexión WebSocket con esa misma sesión de Realtime.

1
2
3
4// Location: /v1/realtime/calls/rtc_123456
const location = sdpResponse.headers.get("Location");
const callId = location?.split("/").pop();
console.log(callId);

3. Desde el servidor, puedes escuchar eventos y configurar la sesión tal como lo harías con una conexión WebSocket habitual a la Realtime API. Usa ese ID de llamada en la URL wss://api.openai.com/v1/realtime?call_id=rtc_xxxxx, como en el siguiente ejemplo:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30import WebSocket from "ws";
const callId = "rtc_u1_9c6574da8b8a41a18da9308f4ad974ce";

// Connect to a WebSocket for the in-progress call
const url = "wss://api.openai.com/v1/realtime?call_id=" + callId;
const ws = new WebSocket(url, {
  headers: {
    Authorization: "Bearer " + process.env.OPENAI_API_KEY,
  },
});

ws.on("open", function open() {
  console.log("Connected to server.");

  // Send client events over the WebSocket once connected
  ws.send(
    JSON.stringify({
      type: "session.update",
      session: {
        type: "realtime",
        instructions: "Be extra nice today!",
      },
    })
  );
});

// Listen for and parse server events
ws.on("message", function incoming(message) {
  console.log(JSON.parse(message.toString()));
});

En Go, pasa el ID de llamada a la función que actualiza la sesión en el servidor:

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
28func updateSession(ctx context.Context, client openai.Client, callID string) error {
	conn, err := client.Realtime.Connect(ctx, realtime.RealtimeConnectionOptions{}, option.WithQuery("call_id", callID))
	if err != nil {
		return err
	}
	defer conn.Close()
	if err := conn.Send(ctx, realtime.RealtimeClientEventParamOfSessionUpdate(realtime.RealtimeSessionCreateRequestParam{
		Instructions: openai.String("Be extra nice today!"),
	})); err != nil {
		return err
	}
	for {
		event, err := conn.Recv(ctx)
		if err != nil {
			return err
		}
		if event.Type == "error" {
			return fmt.Errorf("Realtime API error: %s", event.OfRealtimeErrorEvent.Error.Message)
		}
		if event.Type == "session.updated" {
			if event.OfSessionUpdatedEvent.Session.OfRealtimeSessionCreateRequest.Instructions != "Be extra nice today!" {
				return fmt.Errorf("session update was not applied")
			}
			fmt.Println("session.updated")
			return nil
		}
	}
}

Así puedes agregar herramientas, monitorear sesiones y ejecutar la lógica de negocio en el servidor sin tener que configurar esas acciones en el cliente.

Con SIP

1. Un usuario se conecta a OpenAI por teléfono mediante SIP.
2. OpenAI envía un webhook a la URL de webhooks del servidor de tu aplicación para informarle del estado de la sesión. El webhook tendrá un aspecto similar al siguiente:

123456789101112131415161718192021POST https://my_website.com/webhook_endpoint
user-agent: OpenAI/1.0 (+https://platform.openai.com/docs/webhooks)
content-type: application/json
webhook-id: wh_685342e6c53c8190a1be43f081506c52 # unique id for idempotency
webhook-timestamp: 1750287078 # timestamp of delivery attempt
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= # signature to verify authenticity from OpenAI

{
  "object": "event",
  "id": "evt_685343a1381c819085d44c354e1b330e",
  "type": "realtime.call.incoming",
  "created_at": 1750287018, // Unix timestamp
  "data": {
    "call_id": "some_unique_id",
    "sip_headers": [
      { "name": "From", "value": "sip:+142555512112@sip.example.com" },
      { "name": "To", "value": "sip:+18005551212@sip.example.com" },
      { "name": "Call-ID", "value": "03782086-4ce9-44bf-8b0d-4e303d2cc590"}
    ]
  }
}

3. El servidor de la aplicación abre una conexión WebSocket con la Realtime API usando el valor de call_id recibido en el webhook y una URL como esta: wss://api.openai.com/v1/realtime?call_id={callId}. La conexión WebSocket permanecerá abierta durante toda la llamada SIP.

Puedes usar la conexión WebSocket para enviar y recibir eventos que controlen la llamada, tal como lo harías si la sesión se hubiera iniciado con una conexión WebSocket. Esto incluye monitorear la llamada, actualizar las instrucciones de forma dinámica y responder a llamadas a herramientas.