Controles no servidor

Controle uma sessão do GPT-Live pelo servidor

Conecte o servidor do aplicativo a uma sessão WebRTC ou SIP do GPT-Live já em andamento quando o servidor precisar receber eventos da conversa, executar ferramentas privadas ou atualizar a conversa. Essa segunda conexão é chamada de WebSocket auxiliar. As duas conexões compartilham a mesma sessão, enquanto o WebRTC ou o SIP transporta o áudio principal.

O canal auxiliar transmite eventos e comandos. Cabe ao aplicativo executar as ferramentas, verificar as autorizações e aplicar as regras de negócio. Mantenha as chaves de API e as credenciais das ferramentas no servidor.

Avalie se você precisa de um canal auxiliar

Em aplicativos que rodam no navegador, use o canal de dados WebRTC para exibir legendas e atualizar a interface localmente. Use um canal auxiliar quando o servidor processar a transcrição, por exemplo, para fazer verificações de segurança, analisar sentimentos ou chamar ferramentas de forma especulativa. O servidor pode receber eventos e controlar diretamente a mesma sessão enquanto o navegador continua transmitindo áudio por WebRTC. Consulte Reaja a fragmentos da transcrição para ver exemplos.

Se o backend transmite áudio pela conexão WebSocket principal, use essa conexão para receber eventos e enviar comandos.

A delegação com a API Responses também funciona sem um canal auxiliar. O navegador pode encaminhar eventos de chamada de função do canal de dados para que um backend autenticado execute as funções. As ferramentas hospedadas pela OpenAI são executadas por meio do backend que recebe a delegação, sem exigir que o aplicativo implemente um executor de ferramentas.

Conecte o servidor à sessão existente

1. Salve o ID da sessão que o backend vai controlar. Para WebRTC ou uma chamada SIP de saída, use session.id da resposta JSON a POST /v1/live/sessions. Para SIP de entrada, primeiro aceite a chamada recebida e depois use data.session_id do webhook correspondente. Armazene o ID junto ao registro do usuário e da conversa no aplicativo.

2. No servidor, abra uma conexão WebSocket com a URL abaixo, usando o ID exatamente como foi salvo. Autentique-se com Authorization: Bearer $OPENAI_API_KEY usando as credenciais do projeto que criou ou aceitou a sessão. Inclua os mesmos cabeçalhos de conexão exigidos na criação da sessão.

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

3. Receba eventos e envie comandos pelo socket conectado à sessão. A sessão já está em andamento. Não envie session.start novamente.

Use o ID da sessão sem alterações, inclusive o prefixo, e verifique se o aplicativo tem autorização para acessar essa sessão.

Monitore eventos e envie comandos

Os comandos seguem as mesmas regras de validação e delegação da conexão principal. Ao acrescentar contexto geral à sessão, use delegation_id: null. Um ID não nulo deve identificar uma delegação existente do cliente. Consulte Delegação e ferramentas para saber como configurar a delegação e executar funções e para ver exemplos de como acrescentar contexto.

Em sessões no navegador, mantenha a entrada do microfone e a saída para os alto-falantes na faixa de mídia negociada pelo WebRTC. Use o canal auxiliar para receber eventos e controlar a conversa. Acompanhe a reprodução no player de áudio.

Receba cópias do áudio

O canal auxiliar também recebe cópias do áudio de entrada e de saída transmitido após a conexão, enquanto a conexão principal transporta a mídia ao vivo.

Ambos os eventos contêm áudio bruto mono em PCM16LE a 24 kHz, codificado em base64, independentemente do formato de áudio usado no transporte principal. Nenhum dos eventos tem um event_id. A cópia da entrada contém o áudio recebido antes da aplicação do controle que silencia a entrada. Receber essa cópia não confirma que o modelo processou as amostras. Os intervalos de áudio copiados da saída podem apresentar lacunas quando há descarte de quadros e não indicam quando a pessoa na chamada ouviu o áudio.

Envie o áudio do microfone somente pela conexão principal. Use o canal auxiliar para receber cópias do áudio.

Defina um único responsável por cada ação

Para cada ação, decida se a responsabilidade é do navegador ou do backend. Se as duas conexões receberem um evento de chamada de função, execute a função apenas uma vez. Aplique a mesma regra às atualizações de contexto e às solicitações para que o backend continue o trabalho.

Conecte o canal auxiliar logo no início se o backend precisar acompanhar toda a conversa. Armazene as transcrições e o estado das ferramentas no aplicativo, inclusive o histórico coletado antes da conexão do canal auxiliar.

O navegador continua podendo receber eventos da sessão quando o canal auxiliar está conectado. Mantenha as credenciais confidenciais das ferramentas e as decisões de autorização no backend. Retorne apenas o contexto necessário para a conversa.

Aplique medidas de proteção à conversa

Use o WebSocket principal ou o canal auxiliar do servidor para monitorar a conversa e verificar se as solicitações atendem às políticas do aplicativo. O aplicativo executa as verificações, bloqueia as ações afetadas e envia instruções corretivas quando uma verificação detecta um problema.

Execute as verificações durante a conversa

Uma das aplicações do processamento de fragmentos da transcrição à medida que chegam é verificar se a conversa respeita as políticas do aplicativo. Enquanto essas verificações são executadas, o mesmo fluxo de eventos pode iniciar uma consulta especulativa ou atualizar a interface.

1. Monitore as transcrições. Acumule fragmentos de session.input_transcript.delta para identificar tentativas de jailbreak, informações confidenciais ou violações de políticas nas solicitações do usuário. Use session.output_transcript.delta para identificar afirmações sem fundamento ou respostas fora do escopo do aplicativo na fala do assistente. Mantenha cada verificação associada à transcrição e à solicitação do aplicativo que ela avaliou.
2. Execute as verificações em paralelo. Um modelo rápido e leve pode avaliar as solicitações enquanto a conversa continua. Retorne um resultado estruturado e conciso, como {"triggered": true}, com base no qual o aplicativo possa agir. Só execute ações que exigem aprovação depois que elas passarem pelas verificações. Mantenha essas ações bloqueadas se uma verificação falhar ou exceder o tempo limite.
3. Bloqueie as ações afetadas. Quando uma verificação detectar um problema, marque a solicitação como bloqueada no estado do aplicativo. Consulte esse estado antes de executar uma ferramenta ou efetivar uma alteração, inclusive para tarefas que já estão na fila.
4. Interrompa as tarefas relacionadas. Cancele as tarefas sob controle do aplicativo quando o backend permitir o cancelamento. Descarte resultados que chegarem tarde para solicitações bloqueadas ou substituídas. Se usar delegação pela API Responses, interrompa a execução das funções personalizadas afetadas e não envie response.create para dar continuidade a tarefas bloqueadas. Isso não cancela uma resposta hospedada já em andamento nem interrompe a fala no frontend.
5. Registre a decisão e redirecione a conversa. Registre a decisão junto com os IDs da solicitação e da delegação afetadas. Em seguida, envie uma instrução corretiva.

Consulte Trechos incrementais da transcrição para saber como coletar fragmentos e Delegação e ferramentas para manter os resultados do backend alinhados à tarefa atual.

Redirecione a conversa

Use session.instructions.append para orientar a conversa quando uma verificação detectar um problema. Esse comando pode interromper a fala em andamento e aplicar uma nova instrução. Por exemplo, depois que o aplicativo bloquear uma solicitação, envie o comando a seguir.

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

Use uma instrução escrita pelo próprio aplicativo. Não copie texto não confiável do usuário para a instrução como se fosse uma orientação. Use delegation_id: null para aplicar a correção à sessão inteira e limite content a 500 tokens.

Associe session.instructions.appended ao comando por meio de client_event_id. A confirmação chega após o momento estimado da inserção da instrução no contexto. Para impedir que o áudio chegue à pessoa na chamada, use os controles de reprodução descritos a seguir.

Use instruções também para comunicados que precisam ser lidos em voz alta com uma redação específica. Consulte Transmita um comunicado para ver um exemplo e saber o que considerar na reprodução.

Controle a reprodução quando necessário

Se o aplicativo precisar bloquear o áudio do modelo, controle a reprodução no cliente ou no retransmissor de mídia. Silencie ou descarte temporariamente a saída, descarte o áudio na fila local e envie a instrução corretiva. Depois de limpar o áudio desatualizado, retome a reprodução de acordo com a política de recuperação do aplicativo. A confirmação de recebimento da instrução não é um sinal para retomar a reprodução. O canal auxiliar, por si só, não controla a reprodução, e as instruções corretivas não podem desfazer o que a pessoa na chamada já ouviu.

session.input_audio.mute controla a entrada do microfone da pessoa na chamada. Esse comando não silencia a saída do modelo nem cancela tarefas delegadas.

Verifique a fala antes da reprodução

Na maioria dos aplicativos, monitore as transcrições do usuário e do assistente enquanto a conversa continua. Quando uma verificação detectar um problema, o aplicativo pode bloquear as ações afetadas ou enviar instruções corretivas.

Se o aplicativo precisar verificar a fala do assistente antes de reproduzi-la, armazene o áudio em um buffer no player ou na ponte de mídia antes de enviá-lo à pessoa na chamada. Continue recebendo eventos de áudio e transcrição durante a verificação e leia as transcrições independentemente da reprodução.

1. Colete o áudio e a transcrição correspondente. Para identificar possíveis segmentos de fala, implemente a detecção de atividade de voz (VAD) na saída do aplicativo ou use um filtro de ruído por limiar fornecido pelo framework de mídia. O GPT-Live não fornece VAD de saída nem filtro de ruído por limiar para esse fluxo. Aguarde a transcrição necessária para verificar cada segmento.
2. Libere o áudio aprovado. Quando um segmento passar na verificação, coloque o áudio original armazenado no buffer na fila de reprodução. Se a verificação falhar ou exceder o tempo limite, ou se a transcrição estiver ausente, descarte o segmento e use uma alternativa segura definida pelo aplicativo.
3. Trate as interrupções. Associe o áudio, a transcrição, o resultado da verificação e o estado da reprodução a um ID gerado pelo aplicativo. Se uma interrupção cancelar essa fala, remova o áudio correspondente do buffer e da fila e ignore qualquer aprovação posterior desse trecho.

Uma pausa pode delimitar um possível segmento de fala enquanto o modelo ainda está formulando a resposta. Se a política exigir a verificação de uma resposta completa, defina como o aplicativo vai determinar que a resposta terminou. A detecção de atividade de voz, por si só, não permite concluir que a resposta terminou por completo.

O uso do buffer aumenta a latência. A fala descartada permanece no contexto da conversa do modelo. Por isso, teste como a conversa prossegue quando um trecho de áudio não é reproduzido ou quando o aplicativo recorre à alternativa segura.

Teste a intervenção

Teste solicitações permitidas e bloqueadas, falsos positivos, verificações lentas ou com falha, acionamentos das medidas de proteção durante a fala ou a execução de uma ferramenta e resultados tardios de tarefas canceladas. Verifique separadamente o bloqueio das ações, o estado do aplicativo, a fala corretiva e o áudio efetivamente reproduzido. Se você controla a saída, inclua no teste o áudio na fila e a retomada da reprodução. Use o guia do Cookbook sobre avaliação de agentes de voz para comparar o sucesso na execução das tarefas e o tempo de resposta por voz.

Encerre a sessão de forma ordenada

Continue recebendo eventos enquanto as ferramentas concluem a execução e a sessão informa os dados finais de uso. Registre o manipulador de session.closed antes de enviar session.close e mantenha a conexão WebRTC, o canal de dados e o canal auxiliar abertos até a conclusão das tarefas pendentes. Antes de liberar os recursos, salve os dados finais de uso da sessão e todos os dados de uso do backend recebidos nos eventos da API Responses. Se a conexão falhar antes da chegada do evento final, registre o encerramento como incompleto. Consulte Gerenciamento de sessões para ver a sequência de encerramento.

A Realtime API permite que os clientes se conectem diretamente ao servidor da API por WebRTC ou SIP. Em geral, é preferível manter o uso de ferramentas e as demais regras de negócio no servidor do aplicativo, para que essa lógica permaneça privada e independente do cliente.

Conecte o servidor por um canal de controle “auxiliar” para proteger o uso de ferramentas, as regras de negócio e outros detalhes de implementação. O canal auxiliar já está disponível tanto para conexões SIP quanto para WebRTC.

Com um canal auxiliar, há duas conexões ativas com a mesma sessão da Realtime API. Uma delas é estabelecida pelo cliente do usuário e a outra, pelo servidor do aplicativo. A conexão do servidor permite monitorar a sessão, atualizar as instruções e responder a chamadas de ferramentas.

Com WebRTC

1. Ao estabelecer uma conexão entre pares, você faz uma requisição à Realtime API e recebe uma resposta SDP para configurar a conexão. Se você usou o código de exemplo do guia de WebRTC, a requisição será parecida com a seguinte.

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. A resposta à requisição contém um cabeçalho Location com um ID exclusivo da chamada. No servidor, você pode usar esse ID para abrir uma conexão WebSocket com a mesma sessão da Realtime API.

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. No servidor, você pode então receber eventos e configurar a sessão como faria em uma conexão WebSocket comum da Realtime API. Para isso, use o ID da chamada na URL wss://api.openai.com/v1/realtime?call_id=rtc_xxxxx, como no exemplo abaixo.

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()));
});

Em Go, passe o ID da chamada para a função que atualiza a sessão no 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
		}
	}
}

Assim, você pode adicionar ferramentas, monitorar sessões e aplicar as regras de negócio no servidor sem precisar configurar essas ações no cliente.

Com SIP

1. O usuário se conecta à OpenAI por telefone em uma chamada SIP.
2. A OpenAI envia um webhook à URL de webhooks do servidor do aplicativo para informar o estado da sessão. O webhook será parecido com o seguinte.

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. O servidor do aplicativo abre uma conexão WebSocket com a Realtime API usando o valor de call_id recebido no webhook em uma URL como wss://api.openai.com/v1/realtime?call_id={callId}. A conexão WebSocket permanece ativa enquanto durar a chamada SIP.

Use a conexão WebSocket para enviar e receber eventos de controle da chamada, como faria em uma sessão iniciada por WebSocket. Isso inclui monitorar a chamada, atualizar as instruções dinamicamente e responder a chamadas de ferramentas.