Bygg en komplett röstagent
På denna sida
Uppdaterad 2 november 2026 — Ljudmodeller. Flera modeller i denna kurs är avvecklade:
tts-1,tts-1-hdochgpt-4o-mini-ttsupphör den 6 januari 2027 (efträdare:gpt-realtime-2.1-mini, vilket OpenAI:s TTS-guide anger inte stöds av/v1/audio/speech: migreringen av talgenerering flyttas till Realtime API);gpt-realtime,gpt-4o-realtimeoch äldre ljudmodeller den 20 januari 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeoch/v1/audio/translationsden 26 februari 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). För full duplex-röst har GPT-Live 1 funnits tillgänglig i API:t sedan den 10 september 2026.
Korrigerad 3 november 2026. Inmatningstranskribering använde
gpt-live-transcribe, vilket endast fungerar i en transkriberingssession och varken stöderserver_vadellersemantic_vad. I en konversationssession som denna, där VAD validerar varje tur, specificerar dokumentationengpt-transcribe, som transkriberar validerade turer och använder tidigare turer som kontext. Källor: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.
Bygg en komplett röstagent
Den här lektionen sammanför alla begrepp som behandlats hittills för att bygga en fullt fungerande röstagent från början till slut. Du kommer att skapa en assistent som lyssnar på användaren, förstår deras begäran, utför åtgärder och svarar med röst – allt i realtid via Realtime API.
Agentarkitektur
Fyra moduler, och framför allt en begränsning som driver hela arkitekturen: allt måste ske samtidigt. Mikrofonen fångar ljud medan modellen svarar, händelser anländer medan ljud spelas upp, och användaren kan avbryta när som helst. En röstagent är inte en fråga-och-svar-loop; det är ett system där flera strömmar avancerar parallellt – vilket är anledningen till att vi förlitar oss kraftigt på asyncio i det följande.
Klassen VoiceAgent
Klassen samlar det tillstånd som dessa parallella strömmar måste dela: anslutningen, den aktuella sessionen och svaret som för närvarande spelas upp. Just eftersom flera uppgifter kommer åt detta tillstånd samtidigt är ett objekt att föredra framför en uppsättning globala variabler – när du behöver avbryta ett pågående svar måste du veta att ett existerar.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Komplett röstagent baserad på 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):
"""Upprättar anslutningen och konfigurerar sessionen."""
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)
# Vänta på session.created
event = json.loads(await self.ws.recv())
print(f"Session: {event['session']['id']}")
# Konfigurera
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("Röstagent redo.")
async def start(self):
"""Startar röstagenten."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Modul för ljudinspelning
async def _capture_audio(self):
"""Fångar mikrofoninmatning och skickar den till 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
}))
Modul för händelsebearbetning
async def _process_events(self):
"""Bearbetar alla händelser från servern."""
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"\nFel: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Modul för verktygshantering
Denna modul omvandlar agenten från en enkel röstchattbot till en assistent som kan vidta åtgärder. Skillnaden från klassisk funktionsanrop ligger i tidsbegränsningen: användaren är uppkopplad utan någon visuell framstegsindikator. Om exekveringen tar mer än en sekund eller två, låt agenten prata medan den arbetar – »Låt mig kolla upp det åt dig direkt« – eftersom tystnad i en röstkonversation låter som ett avbrott.
async def _handle_response_done(self, event):
"""Hanterar funktionsanrop i svaret."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # Ny rad efter transkribering
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Exekvera funktionen (anpassa till din affärslogik)
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)
}
}))
# Be modellen att fortsätta
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Dirigerar funktionsanropet."""
# Implementera enligt din affärslogik
return {"error": f"Funktion {name} inte implementerad"}
Starta agenten
async def main():
agent = VoiceAgent(
api_key="sk-...",
instructions=(
"Du är en röstassistent för Corsen AI. "
"Du hjälper användare att hantera sina möten "
"och få information om våra tjänster. "
"Svara på franska, koncist och professionellt."
),
tools=[
{
"type": "function",
"name": "check_availability",
"description": "Kontrollerar tillgänglighet för en tidslucka",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string"},
"service": {"type": "string"}
},
"required": ["date"]
}
}
]
)
await agent.start()
asyncio.run(main())
Viktiga punkter
- En komplett röstagent kombinerar fyra moduler: ljud, session, verktyg och tillståndshantering
- Klassen
VoiceAgentkapslar in all logik bakom ett enkelt gränssnitt asyncio.gathermöjliggör parallell mikrofoninspelning och händelsebearbetning- Hantering av avbrott (att avbryta ett svar när användaren pratar) är avgörande
- Verktyg omvandlar agenten från en enkel röstchattbot till en assistent som kan vidta åtgärder