Migre para o GPT-Live

Da Realtime API

Comece pelo guia de criação de prompts do GPT-Live. Divida seu prompt existente entre o modelo de voz e o backend, em vez de copiá-lo integralmente para session.instructions. Mantenha o estilo da conversa e as orientações de delegação no prompt de voz; mova os fluxos de trabalho detalhados e as instruções de uso de ferramentas para o backend.

Antes: o modelo Realtime cuida da fala e seleciona funções como check_availability e book_appointment. Sua aplicação executa as funções e retorna seus resultados.

Depois: o GPT-Live cuida da fala e delega a execução das tarefas. O backend seleciona as mesmas funções; sua aplicação continua a validá-las e executá-las. As etapas aqui usam a delegação via Responses. Se você mantiver um agente externo, use o adaptador de cliente.

Como funciona a delegação via Responses

Configure o modelo de backend, as instruções e as ferramentas em delegation.responses. Quando o GPT-Live decide que uma solicitação precisa de processamento no backend, o serviço Live chama esse modelo da Responses e fornece o contexto relevante da conversa. O backend raciocina sobre a tarefa e seleciona ferramentas. Sua aplicação continua a executar funções personalizadas, aplicar permissões e retornar os resultados dessas funções.

No caso do assistente de agendamento:

1. O usuário pergunta quais horários estão disponíveis na sexta-feira, e o GPT-Live delega a solicitação.
2. O backend da Responses solicita check_availability.
3. Sua aplicação executa a função, retorna seu resultado e dá continuidade à resposta do backend.
4. O GPT-Live usa a resposta do backend para conversar com o usuário sobre os horários disponíveis.

O GPT-Live pode manter a conversa enquanto o processamento no backend está em andamento. Concluir esse processamento não significa que o assistente terminou de falar. Consulte Delegação e ferramentas para ver a configuração e o fluxo completo de eventos.

Preserve as decisões que dependem de áudio

Verifique se as decisões existentes sobre ferramentas dependem de evidências acústicas, como o bipe de uma caixa postal ou a cadência de uma saudação gravada. O GPT-Live ouve o áudio de entrada, mas seu frontend de voz delega tarefas em vez de emitir chamadas de função estruturadas comuns. No modo cliente, session.delegation.created contém metadados e informações de tempo, sem áudio bruto, texto da tarefa ou argumentos de ferramentas já interpretados. Um backend que recebe tarefas delegadas não recebe automaticamente a forma de onda.

Para detectar secretárias eletrônicas, encaminhe explicitamente o áudio de entrada a um detector capaz de processar áudio. Uma arquitetura gerenciada pela aplicação que você pode avaliar executa uma sessão Realtime separada em paralelo com o GPT-Live durante parte da chamada:

1. Envie uma cópia do áudio de entrada da chamada para as duas sessões.
2. Faça o detector informar sua classificação por meio de uma chamada de função estruturada. Valide cada resultado em relação ao seu esquema, rejeite resultados desatualizados e mantenha um estado desconhecido quando as evidências forem insuficientes. Permita que evidências posteriores revisem a decisão.
3. Envie contexto relevante e confiável ao GPT-Live e aplique a política da sua aplicação à reprodução do áudio de saída.

Mantenha a classificação como humano ou máquina separada da avaliação de prontidão para gravação. Reconhecer uma caixa postal não comprova que a saudação e o bipe terminaram ou que a gravação pode começar. Um resultado do classificador ou uma confirmação de recebimento de contexto também não concede permissão para reproduzir áudio. Use Adapte seus mecanismos de proteção e os controles de reprodução para aplicar essa decisão no fluxo de áudio controlado pela sua aplicação.

Teste um breve “alô” que continua como uma saudação de caixa postal, mensagens de triagem de chamadas e uma pessoa atendendo durante a caixa postal. Se você interromper o detector antes do fim da chamada, teste o atendimento por uma pessoa depois dessa interrupção. Escolha quando interromper o detector com base nesses testes e no custo adicional dele. A primeira classificação como humano, por si só, não comprova que continuar a detecção seja desnecessário.

Adapte a conexão e o ciclo de vida do áudio

Substitua a configuração de sessão do Realtime pelo procedimento de conexão do GPT-Live. Verifique novamente a inicialização e o formato de áudio do seu transporte. O WebRTC transporta áudio em trilhas de mídia e eventos JSON no canal de dados. Um WebSocket primário transporta áudio em eventos JSON.

Se sua aplicação Realtime usa uma conexão de servidor para monitorar a chamada ou aplicar mecanismos de proteção, adapte-a à conexão de canal lateral do GPT-Live. Siga Adapte seus mecanismos de proteção para ajustar as verificações da conversa e a reprodução.

Geração e reprodução: No Realtime, response.output_audio.done marca o fim da geração de áudio, enquanto response.done marca o fim do fluxo de resposta. Esses eventos também podem ocorrer quando uma resposta é interrompida ou malsucedida; verifique response.status em response.done. Nenhum deles confirma que o áudio armazenado em buffer terminou de ser reproduzido. Por exemplo, o servidor pode terminar a geração enquanto o cliente ainda tem um segundo de áudio para reproduzir. Atualize um indicador de "falando" com base no estado da reprodução.

Legendas: A transcrição de entrada representa a fala do usuário; a transcrição de saída representa a fala gerada pelo assistente. Quando a transcrição de entrada está ativada, o Realtime envia atualizações por meio de conversation.item.input_audio_transcription.delta e uma transcrição final por meio de conversation.item.input_audio_transcription.completed. Um delta é um novo fragmento de texto. No GPT-Live, acrescente cada fragmento às legendas de quem está falando de forma independente, pois a escuta e a fala podem ocorrer ao mesmo tempo. Um fragmento não é um turno completo nem uma confirmação de reprodução. Consulte Exiba legendas para ver um exemplo de implementação.

No GPT-Live, response.create inicia ou continua o trabalho delegado à Responses. Ele não concede permissão para o modelo de voz falar. Para inicialização, saudações, interrupções e encerramento de sessões, siga as orientações em Gerenciamento de sessões.

Separe as instruções de conversa das instruções do backend

Mova o estilo de conversa e as orientações de delegação para session.instructions. Mova as regras de negócio e as instruções de uso de ferramentas para delegation.responses.instructions. Se você executa o backend por conta própria, mantenha essas regras no prompt existente dele.

Antes: um único prompt do 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.

Depois: instruções de conversa do 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.

Depois: instruções do 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.

Aplique verificações de confirmação e permissão no seu aplicativo antes de executar uma ferramenta. As instruções do prompt orientam os modelos; elas não garantem a aplicação dessas verificações. Consulte Criação de prompts para modelos de voz para saber como elaborar os prompts.

Adapte suas rotinas de tratamento de funções

Mantenha a implementação de check_availability e book_appointment. Mova as definições delas de session.tools ou response.tools do Realtime para delegation.responses.tools, usando o esquema de funções da Responses. Mova as configurações de seleção de ferramentas para delegation.responses.tool_choice e delegation.responses.parallel_tool_calls. Consulte Configure a delegação via Responses.

A função continua retornando um resultado para o call_id original. O que muda é onde sua rotina de tratamento recebe a chamada e envia o resultado:

Por exemplo, depois que check_availability retorna um horário verificado, seu resultado muda da seguinte forma. Estas são mensagens em uma sessão já conectada; call_availability representa o ID real da chamada que você recebeu.

Antes: resultado do 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}"
  }
}

Depois: resultado do 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,
    )

Depois de enviar todos os resultados de função necessários, continue a execução do 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",
    )

Na migração inicial, definir parallel_tool_calls como false simplifica o tratamento dos resultados. Colete as chamadas dos eventos de conclusão de itens de saída, mesmo que um retrato do estado final do ciclo de vida contenha output: []. Um evento de conclusão dos argumentos, por si só, não fornece o nome da função nem o call_id. Siga o procedimento completo para resultados de funções, que abrange coleta, envio de saídas e erros.

Preserve o contexto e aplique correções

A delegação via Responses fornece ao backend o contexto relevante da conversa por voz. Mantenha no seu aplicativo o estado oficial do agendamento: horário selecionado, horário confirmado, permissões, operação ativa e resultado. O histórico de conversas do Live pode ser compactado; ele não é seu registro de agendamentos.

Se o usuário disser “Na verdade, prefiro sexta-feira” enquanto uma consulta para quinta-feira estiver pendente, atualize a versão da tarefa e invalide a confirmação anterior de horário. Antes de executar um agendamento, verifique se os argumentos ainda correspondem à tarefa e à confirmação atuais. Para qualquer chamada de função pendente que seu aplicativo recusar, retorne um resultado que indique corretamente se ela foi substituída ou cancelada e, em seguida, complete o lote de saídas necessário antes de continuar. Se um agendamento já tiver sido concluído com sucesso, concilie esse resultado com a alteração solicitada antes de realizar outra ação.

Fragmentos de transcrição podem chegar com atraso ou se sobrepor à fala do assistente. Acrescente cada delta exatamente como recebido e use start_ms e end_ms para agrupar o conteúdo exibido. Esses marcadores de tempo não delimitam os turnos de forma definitiva nem indicam o momento de reprodução de cada palavra. Esclareça datas, nomes e números importantes quando a intenção não estiver clara. Consulte Gerenciamento de sessões para saber como lidar com transcrições e contexto.

Imagens e contexto da tela: se seu aplicativo Realtime aceita imagens, encaminhe-as a um backend com recursos de visão e retorne o texto relevante ao GPT-Live. Tanto a delegação ao cliente quanto a delegação via Responses oferecem suporte a esse padrão. Consulte Adicione imagens e contexto visual.

A partir de um agente de texto ou pipeline encadeado

Antes: um agente de texto recebe solicitações por escrito e usa suas ferramentas e seu estado salvo. Um pipeline de voz encadeado, ou em cascata, adiciona a conversão de fala em texto antes desse agente e a conversão de texto em fala depois dele.

Depois: o GPT-Live fornece a interface de voz e delega a execução das tarefas ao seu agente existente. No caso de um pipeline encadeado, ele substitui as etapas separadas de conversão de fala em texto e de texto em fala. Mantenha os modelos, as instruções, as ferramentas, o fluxo de trabalho e o estado persistente no seu backend quando ainda forem adequados à tarefa.

Conecte seu agente existente

Defina delegation como {"type":"client"} durante a configuração da sessão. Seu aplicativo recebe uma notificação como esta:

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

A notificação contém metadados, não o texto da solicitação, os argumentos das ferramentas ou uma transcrição completa. Mantenha o valor real de delegation.id inalterado. Monte a entrada do agente a partir de fragmentos recentes da transcrição identificados por papel e do estado verificado do aplicativo, incluindo a tarefa ativa e a correção mais recente. Uma delegação pode chegar antes que uma frase completa apareça na transcrição. Se o contexto disponível não deixar clara a solicitação, reúna mais contexto ou peça esclarecimentos antes de agir.

Em um aplicativo de texto, você pode passar a mensagem mais recente do usuário diretamente ao agente. Com o GPT-Live, adicione um adaptador que forneça esse contexto e retorne um resultado conciso e 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,
    )

O adaptador usa funções de retorno de chamada do aplicativo para ler o contexto, executar seu agente e verificar a versão atual da tarefa; elas não são métodos do SDK. A função de retorno de chamada de contexto retorna um retrato do estado pronto para uso, contendo a conversa recente e a tarefa atual, ou não retorna nenhum retrato quando a solicitação continua pouco clara. A função de retorno de chamada do agente invoca seu agente existente e retorna um resumo verificado de no máximo 500 tokens. Em JavaScript, a função de retorno de chamada send, fornecida pelo aplicativo, envia o evento JSON pela sua conexão Live. Em Python, o adaptador envia a atualização diretamente por meio de connection do SDK.

Se o contexto não estiver pronto, retenha a notificação e invoque o adaptador novamente depois de esclarecer a solicitação. Antes de invocar esse adaptador, registre no seu aplicativo que a delegação está sob seu processamento, para que uma entrega duplicada não inicie a mesma operação duas vezes. Mantenha a autorização, a confirmação, os IDs de operação e as decisões sobre novas tentativas no seu backend. A verificação de versão impede que esse adaptador anuncie um resultado desatualizado; o backend também deve verificar a versão atual antes de produzir um efeito colateral, como um agendamento.

Para o assistente de agendamentos, o contexto deve estabelecer a data e o fuso horário solicitados, os horários oferecidos anteriormente, qualquer horário confirmado e a correção mais recente. Um resultado de disponibilidade deve informar que um horário está disponível e que nenhum agendamento foi feito. Só retorne uma confirmação de agendamento depois que ele for concluído com sucesso. Consulte Delegação ao cliente para ver a configuração completa e o fluxo de resultados.

Encaminhe atualizações e correções

Mantenha as saídas estruturadas das ferramentas e os detalhes do fluxo de trabalho no seu backend. Retorne ao GPT-Live atualizações breves e factuais:

• Use session.thinking.append para informar o progresso em segundo plano, como uma consulta que ainda está em execução.
• Use session.commentary.append para um resultado verificado que o usuário deve ouvir.
• Use session.instructions.append para orientações de comportamento definidas pelo aplicativo.

Os três recebem content como uma string simples de no máximo 500 tokens e exigem delegation_id. Use o ID original da delegação ao cliente para o trabalho relacionado ou null para o contexto geral da sessão. Correlacione as confirmações de acréscimo por meio de client_event_id. A aceitação não comprova que houve fala ou reprodução de áudio. Consulte Envie o tipo certo de atualização.

Quando o usuário disser “Na verdade, prefiro sexta-feira”, atualize a tarefa ativa e sua versão, invalide qualquer confirmação para quinta-feira e direcione o agente existente à solicitação corrigida. Decida se deve cancelar, alterar ou deixar a consulta pendente terminar. Descarte resultados desatualizados antes de retorná-los ao GPT-Live. Uma interrupção na fala não cancela uma operação do backend, e uma solicitação de cancelamento não comprova que uma ação foi cancelada.

O trabalho do backend pode continuar após o fim da sessão de voz. Persista seu status no aplicativo. Em uma interação por voz posterior, inicie uma nova sessão com o contexto relevante salvo; consulte Gerenciamento de sessões.

Adapte as proteções de texto e fala

Um agente de texto pode concluir e validar uma resposta antes de exibi-la. Um pipeline encadeado pode validar a resposta completa antes de enviá-la para a conversão de texto em fala. O GPT-Live pode falar enquanto o trabalho do backend ainda está em execução, portanto, reter o resultado de uma ferramenta ou a continuação do backend não impede toda a fala.

Siga as orientações em Adapte seus mecanismos de proteção para manter suas verificações e levar em conta a fala contínua.

Mantenha a entrada digitada conectada ao seu backend existente. Trate uma correção digitada como uma atualização da mesma tarefa e envie o contexto relevante verificado à sessão de voz. Consulte Aceite entradas digitadas e Mantenha as atualizações precisas e úteis.