Agentes de voz

Agentes de voz permitem que os usuários façam perguntas e concluam tarefas falando com seu aplicativo. A principal decisão de projeto é como conectar a fala ao raciocínio e às ferramentas: uma conversa contínua com um backend separado, um único modelo de voz ou um pipeline que você controla etapa por etapa.

Escolha a arquitetura adequada

Crie um agente de voz com comunicação bidirecional simultânea

O GPT-Live pode ouvir e falar ao mesmo tempo, uma capacidade chamada comunicação bidirecional simultânea. O modelo de voz ao vivo cuida da interação falada e delega o raciocínio e o uso de ferramentas a um backend separado. Os usuários podem continuar falando enquanto o backend executa o trabalho.

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

• Delegação ao cliente: Conecte seu próprio agente ou fluxo de trabalho, usando o modelo e o provedor de backend de sua escolha. Seu aplicativo executa o trabalho e retorna os resultados ao GPT-Live.
• Delegação via Responses: Escolha um modelo 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 a esse modelo; seu aplicativo continua executando as funções personalizadas.

Nos dois modos, seu aplicativo controla as permissões e os registros de negócios. Mantenha o comportamento de fala no prompt do modelo de voz ao vivo e as regras de negócios no prompt do backend.

Comece por Primeiros passos com GPT-Live. Consulte Delegação e ferramentas para configurar o backend e Criação de prompts para modelos de voz para definir o comportamento de fala.

Crie um agente de voz de fala para fala

Para a Realtime API, um RealtimeAgent e uma RealtimeSession oferecem um ponto de partida voltado ao navegador. A sessão gerencia turnos de áudio, ferramentas, interrupções e transferências de controle. O exemplo inicial completo agora está em Primeiros passos com a Realtime API.

Crie um fluxo de trabalho de voz encadeado

Use a abordagem encadeada quando quiser inspecionar ou transformar o texto entre o reconhecimento de fala, seu agente e a geração de fala. Seu aplicativo gerencia três etapas:

1. Conversão de fala em texto
2. O fluxo de trabalho do agente em si
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", len(event.data))


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

Use essa abordagem quando cada etapa precisar ser visível ou substituível. Por exemplo, você pode armazenar a transcrição, executar verificações de políticas antes que o agente de texto responda, chamar sistemas internos e, depois, gerar a fala somente quando o fluxo de trabalho chegar a uma resposta aprovada.

Avalie seu agente de voz

Teste a qualidade da conversa e os resultados das tarefas separadamente. Uma resposta que soa natural não comprova que uma ferramenta foi executada nem que o estado do aplicativo mudou.

1. Escolha cenários representativos com resultados, chamadas de ferramentas e permissões esperados.
2. Salve o áudio, os eventos, os resultados das ferramentas e o estado do aplicativo necessários para verificar cada resultado. Diferencie uma execução de avaliação que falhou de uma execução válida em que o agente não conseguiu concluir a tarefa.
3. Repita os cenários e compare a conclusão das tarefas, a latência da resposta audível, as interrupções e o silêncio indesejado. Mantenha o interlocutor, a configuração do modelo, as ferramentas e o transporte constantes ao comparar alterações.

Para o GPT-Live, meça estas dimensões de forma independente:

• Resultados das tarefas e ferramentas: Verifique a preservação da intenção, o trabalho delegado, os argumentos das ferramentas, as permissões e o estado final do aplicativo. Confira se as confirmações faladas correspondem às ações concluídas.
• Ritmo da conversa: Meça o tempo de resposta audível, o silêncio indesejado, a sobreposição de falas e a cessão da vez diante de interrupções, incluindo correções enquanto o backend executa o trabalho.
• Fala e idioma: Teste o reconhecimento da entrada com diferentes sotaques, ruídos de fundo, mudanças de idioma, nomes e números. Avalie a inteligibilidade da saída e a escolha do idioma separadamente do reconhecimento.
• 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.

Use as etapas Engatinhar, andar e correr para aumentar a complexidade gradualmente:

1. Engatinhar: Use fala sintética para solicitações controladas de um único turno. Mantenha o áudio gerado, o contexto do aplicativo e o resultado esperado fixos para permitir comparações repetíveis.
2. Andar: Reproduza gravações representativas de pessoas fazendo solicitações de um único turno para testar como vozes, microfones, pausas e condições acústicas afetam o comportamento.
3. Correr: Use um interlocutor simulado independente para conversas contínuas com vários turnos. Teste esclarecimentos, mudanças de requisitos, interrupções e recuperação enquanto a conversa e o trabalho no backend ocorrem simultaneamente.

Complemente as pontuações automatizadas com a escuta humana para avaliar a pronúncia, a naturalidade e se a conversa parece ter um ritmo adequado.

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

Para um harness de avaliação do Realtime e exemplos detalhados, use o guia de avaliação do Realtime no OpenAI Cookbook. O Cookbook reúne os exemplos executáveis de avaliação; esta página fornece a lista de verificação de testes comum às arquiteturas.

Meça a latência

Defina um evento observado de início e outro de término para cada métrica de latência. O tempo até a primeira resposta audível, até a delegação, até a cessão da vez diante de uma interrupção, até a conclusão do trabalho no backend e até a conclusão verificada da tarefa mede intervalos distintos. Use uma única linha do tempo monotônica e informe a população elegível, a mediana e a latência de cauda. Não substitua o tempo de resposta de ponta a ponta por uma medição restrita ao backend.

Mantenha o interlocutor, a gravação, o modelo de backend, o prompt, o transporte, a cadência do áudio e o avaliador fixos ao comparar modelos de frontend.

Para o GPT-Live, registre as etapas que seu aplicativo pode observar: recebimento da delegação, início da solicitação ao backend, primeiro resultado útil, início e término da execução de ferramentas, envio do resultado, chegada do áudio e reprodução no cliente. A delegação ao cliente dá ao seu aplicativo visibilidade direta das solicitações ao backend; a delegação via Responses expõe eventos de respostas aninhadas e as ferramentas personalizadas que seu aplicativo executa.

Use os intervalos para localizar atrasos no estabelecimento da conexão, no processamento do modelo, nas ferramentas, no armazenamento em buffer do aplicativo e na reprodução. Meça a primeira resposta falada útil separadamente de uma confirmação de recebimento como “Estou verificando”. Uma confirmação mais rápida não demonstra que o resultado solicitado chegou mais cedo.

Altere um fator por vez e repita os mesmos cenários. Compare a mediana e a latência de cauda das respostas faladas úteis, juntamente com o sucesso das tarefas, a correção do uso das ferramentas e as interrupções. Consulte Reduza a latência do backend para obter orientações de implementação.

Agentes de voz continuam usando os mesmos componentes fundamentais dos agentes

A interface de voz muda o transporte e o ciclo de áudio, mas as decisões centrais do fluxo de trabalho continuam as mesmas:

• Consulte Como usar ferramentas quando o agente de voz precisar de capacidades externas.
• Consulte Execução de agentes quando os fluxos de trabalho de voz precisarem de streaming, continuação ou estado persistente.
• Consulte Orquestração e transferências quando os fluxos de trabalho de voz se ramificarem entre especialistas.
• Consulte Mecanismos de proteção e revisão humana quando os fluxos de trabalho de voz precisarem de verificações de segurança ou aprovações.
• Consulte Integrações e observabilidade quando precisar de capacidades baseadas em MCP ou quiser examinar como o fluxo de trabalho de voz se comportou.

A regra prática é: escolha primeiro a arquitetura de áudio e depois projete o restante do fluxo de trabalho do agente da mesma forma que faria para texto.

Próximos passos