Bouw een volledige voice-agent
Op deze pagina
Bijgewerkt op 2 november 2026 — Audiomodellen. Verschillende modellen in deze cursus zijn verouderd:
tts-1,tts-1-hdengpt-4o-mini-ttsstoppen 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-realtimeen legacy audiomodellen op 20 januari 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeen/v1/audio/translationsop 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 nochserver_vadnochsemantic_vadondersteunt. In een conversatiesessie zoals deze, waarbij VAD elke beurt valideert, specificeert de documentatiegpt-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.
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.gathermaakt 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