Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Construir um agente de voz completo

Aula 14 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Construir um agente de voz completo
  2. Arquitetura do agente
  3. A classe VoiceAgent
  4. Módulo de captação de áudio
  5. Módulo de processamento de eventos
  6. Módulo de gestão de ferramentas
  7. Iniciar o agente
  8. Pontos-chave

Atualizado em 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos: tts-1, tts-1-hd e gpt-4o-mini-tts deixarã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-realtime e 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-transcribe e /v1/audio/translations a 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 nem server_vad nem semantic_vad. Numa sessão de conversação como esta, onde o VAD valida cada turno, a documentação especifica gpt-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.

Áudio
Captação e reprodução
Sessão
WebSocket e configuração
Ferramentas
Ações de negócio
Estado
Gestão da conversação

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 VoiceAgent encapsula toda a lógica numa interface simples
  • asyncio.gather permite 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