Agentes de voz

Com agentes de voz, os usuários podem fazer perguntas e concluir tarefas conversando com seu aplicativo. A principal decisão de arquitetura é como conectar a fala ao raciocínio e ao uso de ferramentas. Você pode usar uma conversa contínua com um backend separado, um único modelo de voz ou um pipeline em que você controla cada etapa.

Escolha a arquitetura adequada

Crie um agente de voz full duplex

O GPT-Live consegue ouvir e falar ao mesmo tempo. Essa capacidade é chamada de full duplex. O modelo de voz conduz a conversa e delega o raciocínio e o uso de ferramentas a um backend separado. Os usuários podem continuar falando enquanto o backend executa as tarefas.

Você pode manter seu fluxo de trabalho de texto, com a lógica de negócio e as ferramentas que já usa, e adicionar o GPT-Live como interface de voz. O modo de delegação determina quem executa as tarefas no backend e quem fornece o contexto da conversa:

• Delegação pelo cliente: Conecte seu próprio agente ou fluxo de trabalho usando o modelo de backend e o provedor de sua escolha. Seu aplicativo executa as tarefas e devolve os resultados ao GPT-Live.
• Delegação via Responses: Escolha um modelo da Responses hospedado pela OpenAI para o raciocínio e o uso de ferramentas no backend. O GPT-Live fornece o contexto da conversa e gerencia as chamadas ao modelo. Seu aplicativo continua responsável por executar as funções personalizadas.

Nos dois modos, seu aplicativo controla as permissões e os registros de negócio. Defina como o agente deve falar no prompt do modelo de voz e mantenha as regras de negócio no prompt do backend.

Comece pelo guia Primeiros passos com o GPT-Live. Consulte Delegação e ferramentas para configurar o backend e Prompts para modelos de voz para definir como o modelo deve falar.

Crie um agente de voz com arquitetura de fala para fala

Para começar a usar a Realtime API no navegador, use RealtimeAgent e RealtimeSession. A sessão gerencia os turnos de fala, as ferramentas, as interrupções e as transferências entre agentes. O exemplo inicial completo agora está em Primeiros passos com a Realtime API.

Crie um fluxo de trabalho de voz encadeado

Use um pipeline encadeado quando quiser inspecionar ou transformar o texto entre as etapas de reconhecimento de fala, execução do agente e geração de fala. Seu aplicativo gerencia três etapas:

1. Conversão de fala em texto
2. Fluxo de trabalho do próprio agente
3. Conversão de texto em fala

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
32import asyncio
import numpy as np

from agents import Agent, function_tool
from agents.voice import AudioInput, SingleAgentVoiceWorkflow, VoicePipeline


@function_tool
def get_weather(city: str) -> str:
    """Get the weather for a given city."""
    return f"The weather in {city} is sunny."


agent = Agent(
    name="Assistant",
    instructions="You are a helpful voice assistant.",
    model="gpt-6-astra",
    tools=[get_weather],
)


async def main() -> None:
    pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
    audio_input = AudioInput(buffer=np.zeros(24000 * 3, dtype=np.int16))
    result = await pipeline.run(audio_input)
    async for event in result.stream():
        if event.type == "voice_stream_event_audio":
            print("Received audio bytes", event.data.nbytes)


if __name__ == "__main__":
    asyncio.run(main())

Use essa arquitetura quando precisar observar ou substituir cada etapa. Por exemplo, você pode armazenar a transcrição, verificar a conformidade com as políticas antes que o agente de texto responda, chamar sistemas internos e gerar a fala somente depois que o fluxo de trabalho chegar a uma resposta aprovada.

Avalie seu agente de voz

Teste tanto a conversa quanto o resultado da tarefa. No caso de um assistente de agendamento, ouça a confirmação e verifique se o compromisso correto foi salvo.

1. Escolha cenários representativos e defina os resultados, as chamadas de ferramentas e as permissões esperadas.
2. Salve o áudio, os eventos, os resultados das ferramentas e o estado do aplicativo necessários para verificar cada resultado. Diferencie uma falha na execução da avaliação de uma execução válida em que o agente não consegue concluir a tarefa.
3. Repita os cenários e compare a conclusão das tarefas, a latência até que a resposta seja ouvida, as interrupções e os períodos de silêncio indesejados. Ao comparar alterações, mantenha o mesmo interlocutor, a mesma configuração do modelo, as mesmas ferramentas e o mesmo transporte.

Para o GPT-Live, avalie cada uma destas dimensões separadamente:

• Resultados das tarefas e das ferramentas: Verifique se o agente preservou a intenção do usuário. Confira as tarefas delegadas, os argumentos das ferramentas, as permissões e o estado final do aplicativo. Verifique se as confirmações por voz correspondem às ações concluídas.
• Ritmo da conversa: Meça o tempo até que a resposta seja ouvida, os períodos de silêncio indesejados e a sobreposição de falas. Avalie se o agente cede a vez quando é interrompido, inclusive quando o usuário faz uma correção enquanto o backend executa uma tarefa.
• Fala e idioma: Teste o reconhecimento de fala com diferentes sotaques, ruído de fundo, mudanças de idioma, nomes e números. Avalie a clareza da fala gerada e a escolha do idioma da resposta separadamente do reconhecimento da entrada.
• Confiabilidade da sessão: Acompanhe falhas de conexão, perdas de áudio, tempos limite excedidos e sessões incompletas separadamente das pontuações das tarefas.

Aumente a complexidade em três etapas: engatinhar, caminhar e correr.

1. Engatinhar: Use fala sintética para fazer solicitações controladas de um único turno. Mantenha o áudio gerado, o contexto do aplicativo e o resultado esperado fixos para poder repetir as comparações.
2. Caminhar: Reproduza gravações representativas de pessoas fazendo solicitações de um único turno para testar como as vozes, os microfones, as pausas e as condições acústicas afetam o comportamento do agente.
3. Correr: Use um interlocutor simulado independente em conversas contínuas de vários turnos. Teste como o agente esclarece dúvidas, lida com mudanças nos requisitos e interrupções e retoma a conversa enquanto o backend executa tarefas em paralelo.

Complemente as pontuações automatizadas com avaliações de pessoas que ouçam as conversas e analisem a pronúncia, a naturalidade da fala e a adequação do ritmo da conversa.

Para obter um harness de avaliação do GPT-Live, consulte o exemplo de avaliação de agentes de voz no Cookbook.

Para obter um harness de avaliação do Realtime e ver exemplos passo a passo, consulte o guia de avaliação do Realtime no OpenAI Cookbook.

Meça a latência

Meça quanto tempo o interlocutor espera até ouvir uma resposta útil. Acompanhe separadamente o tempo gasto no backend para identificar atrasos. Compare a mediana e o percentil 95 entre chamadas semelhantes.

Ao comparar modelos de frontend, use o mesmo interlocutor, a mesma gravação, o mesmo modelo de backend, o mesmo prompt, o mesmo transporte, a mesma cadência de áudio e o mesmo avaliador.

No GPT-Live, registre os momentos que seu aplicativo consegue observar: o recebimento da delegação, o início da solicitação ao backend, o primeiro resultado útil, o início e o fim da execução da ferramenta, o envio do resultado, a chegada do áudio e sua reprodução no cliente. Com a delegação pelo cliente, seu aplicativo pode observar diretamente as próprias solicitações ao backend. A delegação via Responses expõe os eventos de resposta aninhados e as ferramentas personalizadas que seu aplicativo executa.

Use essas medições para identificar atrasos no estabelecimento da conexão, no processamento pelo modelo, na execução das ferramentas, no armazenamento em buffer ou na reprodução. Meça o tempo até ouvir mensagens como “Estou verificando” separadamente do tempo até ouvir a resposta de que o interlocutor precisa.

Altere um fator por vez e repita os mesmos cenários. Verifique se respostas mais rápidas também afetam o sucesso das tarefas, o uso correto das ferramentas ou as interrupções. Consulte Como reduzir a latência do backend.

Agentes de voz usam os mesmos componentes básicos dos demais agentes

A interface de voz muda o transporte e o ciclo de entrada e saída de áudio, mas as decisões centrais sobre o fluxo de trabalho continuam as mesmas:

• Consulte Como usar ferramentas quando o agente de voz precisar de recursos externos.
• Consulte Execução de agentes quando os fluxos de trabalho por voz precisarem de streaming, continuidade da execução ou estado persistente.
• Consulte Orquestração e transferências entre agentes quando os fluxos de trabalho por voz seguirem caminhos diferentes conforme o especialista necessário.
• Consulte Mecanismos de proteção e revisão humana quando os fluxos de trabalho por voz exigirem verificações de segurança ou aprovações.
• Consulte Integrações e observabilidade quando precisar de recursos baseados em MCP ou quiser examinar o comportamento do fluxo de trabalho por voz.

Na prática, escolha primeiro a arquitetura de áudio. Depois, projete o restante do fluxo de trabalho do agente como faria para texto.

Próximos passos