Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Bouw een volledige voice-agent

Les 14 van 18 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Bouw een volledige voice-agent
  2. Architectuur van de agent
  3. De VoiceAgent-klasse
  4. Module voor audio-opname
  5. Module voor evenementverwerking
  6. Module voor toolbeheer
  7. Start de agent
  8. Belangrijkste punten

Bijgewerkt op 2 november 2026 — Audiomodellen. Verschillende modellen in deze cursus zijn verouderd: tts-1, tts-1-hd en gpt-4o-mini-tts stoppen op 6 januari 2027 (opvolger: gpt-realtime-2.1-mini, waarvan de OpenAI TTS-gids aangeeft dat deze niet wordt ondersteund door /v1/audio/speech: migratie van spraaksynthese gaat naar de Realtime API); gpt-realtime, gpt-4o-realtime en legacy audiomodellen op 20 januari 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe en /v1/audio/translations op 26 februari 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Voor full-duplex spraak is GPT-Live 1 beschikbaar in de API sinds 10 september 2026.

Gecorrigeerd op 3 november 2026. Invoertranscriptie gebruikte gpt-live-transcribe, wat alleen werkt in een transcriptie-sessie en noch server_vad noch semantic_vad ondersteunt. In een conversatiesessie zoals deze, waarbij VAD elke beurt valideert, specificeert de documentatie gpt-transcribe, dat gevalideerde beurten transcribeert en eerdere beurten als context gebruikt. Bronnen: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Bouw een volledige voice-agent

Deze les brengt alle tot nu toe behandelde concepten samen om een volledig functionele end-to-end voice-agent te bouwen. U creëert een assistent die naar de gebruiker luistert, diens verzoek begrijpt, acties uitvoert en met spraak antwoordt – allemaal in real time via de Realtime API.

Architectuur van de agent

Vier modules, en bovenal één beperking die de hele architectuur stuurt: alles moet tegelijkertijd gebeuren. De microfoon neemt op terwijl het model antwoordt, evenementen komen binnen terwijl audio wordt afgespeeld, en de gebruiker kan op elk moment onderbreken. Een voice-agent is geen vraag-en-antwoord-lus; het is een systeem waarin meerdere streams parallel lopen – daarom maken we in het vervolg intensief gebruik van asyncio.

Audio
Opname en weergave
Sessie
WebSocket en configuratie
Tools
Bedrijfsacties
State
Conversatiebeheer

De VoiceAgent-klasse

De klasse bundelt de state die deze parallelle streams moeten delen: de verbinding, de huidige sessie en het antwoord dat momenteel wordt afgespeeld. Juist omdat meerdere taken gelijktijdig toegang hebben tot deze state, heeft een object de voorkeur boven een reeks globale variabelen – wanneer u een lopend antwoord moet annuleren, moet u weten dat er een bestaat.

import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio

class VoiceAgent:
    """Volledige voice-agent gebaseerd op de 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):
        """Legt de verbinding vast en configureert de sessie."""
        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)

        # Wacht op session.created
        event = json.loads(await self.ws.recv())
        print(f"Sessie: {event['session']['id']}")

        # Configureer
        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("Voice-agent klaar.")

    async def start(self):
        """Start de voice-agent."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Module voor audio-opname

    async def _capture_audio(self):
        """Neemt microfooninvoer op en stuurt deze naar de 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
                }))

Module voor evenementverwerking

    async def _process_events(self):
        """Verwerkt alle evenementen van de server."""
        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"\nFout: {event['error']['message']}")

        finally:
            player.close()
            pa.terminate()

Module voor toolbeheer

Deze module transformeert de agent van een simpele voice-chatbot in een assistent die actie kan ondernemen. Het verschil met klassieke function calling zit in de timingbeperking: de gebruiker staat aan de lijn zonder visuele voortgangsindicator. Als de uitvoering langer dan een seconde of twee duurt, laat de agent dan spreken terwijl hij werkt – “Ik controleer dat direct voor u” – want stilte in een spraakgesprek klinkt als een storing.

    async def _handle_response_done(self, event):
        """Verwerkt functieaanroepen in het antwoord."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Nieuwe regel na transcriptie
            return

        for call in function_calls:
            name = call["name"]
            args = json.loads(call["arguments"])
            call_id = call["call_id"]

            print(f"\n→ {name}({args})")

            # Voer de functie uit (pas aan uw bedrijfslogica aan)
            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)
                }
            }))

        # Vraag het model om door te gaan
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Dispatcht de functieaanroep."""
        # Implementeer volgens uw bedrijfslogica
        return {"error": f"Functie {name} niet geïmplementeerd"}

Start de agent

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "Je bent een voice-assistent voor Corsen AI. "
            "Je helpt gebruikers bij het beheren van hun afspraken "
            "en het verkrijgen van informatie over onze diensten. "
            "Antwoord in het Frans, beknopt en professioneel."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Controleert beschikbaarheid voor een tijdslot",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Belangrijkste punten

  • Een volledige voice-agent combineert vier modules: audio, sessie, tools en state-beheer
  • De VoiceAgent-klasse kapselt alle logica achter een eenvoudige interface
  • asyncio.gather maakt gelijktijdige microfoonopname en evenementverwerking mogelijk
  • Het afhandelen van onderbrekingen (een antwoord annuleren wanneer de gebruiker spreekt) is essentieel
  • Tools transformeren de agent van een simpele voice-chatbot in een assistent die actie kan ondernemen