Construir um agente de voz completo
Nesta página
Atualizado em 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos:
tts-1,tts-1-hdegpt-4o-mini-ttsdeixarão de funcionar a 6 de janeiro de 2027 (sucessor:gpt-realtime-2.1-mini, que o guia TTS da OpenAI indica não ser suportado por/v1/audio/speech: a migração da síntese de fala passa para a Realtime API);gpt-realtime,gpt-4o-realtimee modelos de áudio legados a 20 de janeiro de 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsa 26 de fevereiro de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para voz full-duplex, o GPT-Live 1 está disponível na API desde 10 de setembro de 2026.
Corrigido em 3 de novembro de 2026. A transcrição de entrada utilizava
gpt-live-transcribe, que só funciona numa sessão de transcrição e não suporta nemserver_vadnemsemantic_vad. Numa sessão de conversação como esta, onde o VAD valida cada turno, a documentação especificagpt-transcribe, que transcreve turnos validados e utiliza os turnos anteriores como contexto. Fontes: Transcrição em tempo real · GPT-Transcribe · GPT-Live-Transcribe.
Construir um agente de voz completo
Esta lição reúne todos os conceitos abordados até agora para construir um agente de voz funcional de ponta a ponta. Vai criar um assistente que ouve o utilizador, compreende o seu pedido, executa ações e responde por voz — tudo em tempo real através da Realtime API.
Arquitetura do agente
Quatro módulos e, acima de tudo, uma restrição que conduz toda a arquitetura: tudo deve acontecer simultaneamente. O microfone capta enquanto o modelo responde, os eventos chegam enquanto o áudio é reproduzido e o utilizador pode interromper a qualquer momento. Um agente de voz não é um ciclo de pergunta e resposta; é um sistema onde múltiplos fluxos avançam em paralelo — é por isso que dependemos fortemente de asyncio no que se segue.
A classe VoiceAgent
A classe agrega o estado que estes fluxos paralelos devem partilhar: a ligação, a sessão atual e a resposta que está a ser reproduzida. Precisamente porque múltiplas tarefas acedem a este estado simultaneamente, um objeto é preferível a um conjunto de variáveis globais — quando precisa de cancelar uma resposta em curso, tem de saber que ela existe.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Agente de voz completo baseado na Realtime API."""
def __init__(self, api_key: str, instructions: str, tools: list = None):
self.api_key = api_key
self.instructions = instructions
self.tools = tools or []
self.ws = None
self.is_playing = False
self.sample_rate = 24000
self.chunk_size = 2400 # 100ms
async def connect(self):
"""Estabelece a ligação e configura a sessão."""
url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"
headers = {
"Authorization": f"Bearer {self.api_key}"
}
self.ws = await websockets.connect(url, additional_headers=headers)
# Aguardar session.created
event = json.loads(await self.ws.recv())
print(f"Sessão: {event['session']['id']}")
# Configurar
await self.ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": self.instructions,
"audio": {
"input": {
"format": {"type": "audio/pcm", "rate": 24000},
"transcription": {"model": "gpt-transcribe", "languages": ["fr"]},
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"silence_duration_ms": 600
}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000},
"voice": "marin"
}
},
"tools": self.tools,
"tool_choice": "auto"
}
}))
await self.ws.recv() # session.updated
print("Agente de voz pronto.")
async def start(self):
"""Inicia o agente de voz."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Módulo de captação de áudio
async def _capture_audio(self):
"""Capta a entrada do microfone e envia-a para a Realtime API."""
loop = asyncio.get_event_loop()
queue = asyncio.Queue()
def callback(indata, frames, time_info, status):
pcm = (indata[:, 0] * 32767).astype(np.int16)
loop.call_soon_threadsafe(queue.put_nowait, pcm)
stream = sd.InputStream(
samplerate=self.sample_rate,
channels=1,
dtype="float32",
blocksize=self.chunk_size,
callback=callback
)
with stream:
while True:
pcm_data = await queue.get()
audio_b64 = base64.b64encode(pcm_data.tobytes()).decode()
await self.ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": audio_b64
}))
Módulo de processamento de eventos
async def _process_events(self):
"""Processa todos os eventos provenientes do servidor."""
pa = pyaudio.PyAudio()
player = pa.open(
format=pyaudio.paInt16, channels=1,
rate=self.sample_rate, output=True
)
try:
async for raw in self.ws:
event = json.loads(raw)
t = event["type"]
if t == "response.output_audio.delta":
audio = base64.b64decode(event["delta"])
player.write(audio)
self.is_playing = True
elif t == "response.output_audio.done":
self.is_playing = False
elif t == "response.output_audio_transcript.delta":
print(event["delta"], end="", flush=True)
elif t == "input_audio_buffer.speech_started":
if self.is_playing:
await self.ws.send(json.dumps({
"type": "response.cancel"
}))
self.is_playing = False
elif t == "response.done":
await self._handle_response_done(event)
elif t == "error":
print(f"\nErro: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Módulo de gestão de ferramentas
Este módulo transforma o agente de um simples chatbot de voz num assistente capaz de tomar iniciativas. A diferença em relação à chamada de funções clássica reside na restrição de tempo: o utilizador está na linha sem qualquer indicador visual de progresso. Se a execução demorar mais de um ou dois segundos, faça o agente falar enquanto trabalha — «Deixe-me verificar isso para si agora mesmo» — porque o silêncio numa conversação por voz soa a uma avaria.
async def _handle_response_done(self, event):
"""Gera as chamadas de função na resposta."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # Nova linha após transcrição
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Executar a função (adaptar à sua lógica de negócio)
result = await self._execute_function(name, args)
await self.ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps(result)
}
}))
# Pedir ao modelo para continuar
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Despacha a chamada de função."""
# Implementar de acordo com a sua lógica de negócio
return {"error": f"Função {name} não implementada"}
Iniciar o agente
async def main():
agent = VoiceAgent(
api_key="sk-...",
instructions=(
"É um assistente de voz para a Corsen AI. "
"Ajuda os utilizadores a gerir as suas marcações "
"e a obter informações sobre os nossos serviços. "
"Responda em francês, de forma concisa e profissional."
),
tools=[
{
"type": "function",
"name": "check_availability",
"description": "Verifica a disponibilidade para um intervalo de tempo",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string"},
"service": {"type": "string"}
},
"required": ["date"]
}
}
]
)
await agent.start()
asyncio.run(main())
Pontos-chave
- Um agente de voz completo combina quatro módulos: áudio, sessão, ferramentas e gestão de estado
- A classe
VoiceAgentencapsula toda a lógica numa interface simples asyncio.gatherpermite a captação do microfone e o processamento de eventos em paralelo- O tratamento de interrupções (cancelar uma resposta quando o utilizador fala) é essencial
- As ferramentas transformam o agente de um simples chatbot de voz num assistente capaz de agir