Vytvořte kompletního hlasového agenta
Na této stránce
Aktualizováno 2. listopadu 2026 — Zvukové modely. Několik modelů v tomto kurzu je zastaralých:
tts-1,tts-1-hdagpt-4o-mini-ttspřestanou fungovat 6. ledna 2027 (nástupce:gpt-realtime-2.1-mini, který podle průvodce OpenAI TTS není podporován endpointem/v1/audio/speech: migrace syntézy řeči přechází na Realtime API);gpt-realtime,gpt-4o-realtimea starší zvukové modely skončí 20. ledna 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribea/v1/audio/translationsskončí 26. února 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Pro plně duplexní hlasovou komunikaci je GPT-Live 1 dostupné v API od 10. září 2026.
Opraveno 3. listopadu 2026. Vstupní přepis používal
gpt-live-transcribe, který funguje pouze v relaci typu transcription a nepodporuje aniserver_vad, anisemantic_vad. V konverzační relaci, jako je tato, kde VAD validuje každý obrat, dokumentace specifikuje použitígpt-transcribe, který přepisuje validované obraty a využívá předchozí obraty jako kontext. Zdroje: Přepis v reálném čase · GPT-Transcribe · GPT-Live-Transcribe.
Vytvořte kompletního hlasového agenta
Tato lekce spojuje všechny doposud probírané koncepty do funkčního end-to-end hlasového agenta. Vytvoříš asistenta, který poslouchá uživatele, rozumí jeho požadavkům, vykonává akce a odpovídá hlasem – vše v reálném čase prostřednictvím Realtime API.
Architektura agenta
Čtyři moduly a především jedno omezení, které řídí celou architekturu: vše se musí dít najednou. Mikrofon nahrává, zatímco model odpovídá, události přicházejí, zatímco se přehrává zvuk, a uživatel může kdykoli přerušit tok. Hlasový agent není smyčka otázek a odpovědí; je to systém, kde běží více streamů paralelně – proto se v následujícím kódu silně spoléháme na asyncio.
Třída VoiceAgent
Tato třída sdružuje stav, který musí tyto paralelní streamy sdílet: připojení, aktuální relaci a právě přehrávanou odpověď. Právě proto, že k tomuto stavu přistupuje více úloh současně, je objekt vhodnější než sada globálních proměnných – když potřebuješ zrušit probíhající odpověď, musíš vědět, že existuje.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Kompletní hlasový agent založený 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):
"""Naváže připojení a nakonfiguruje relaci."""
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)
# Počkej na session.created
event = json.loads(await self.ws.recv())
print(f"Relace: {event['session']['id']}")
# Konfigurace
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("Hlasový agent připraven.")
async def start(self):
"""Spustí hlasového agenta."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Modul pro záznam zvuku
async def _capture_audio(self):
"""Zaznamenává vstup z mikrofonu a odesílá jej do 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 pro zpracování událostí
async def _process_events(self):
"""Zpracovává všechny události ze serveru."""
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"\nChyba: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Modul pro správu nástrojů
Tento modul promění agenta z jednoduchého hlasového chatbota v asistenta schopného podnikat kroky. Rozdíl oproti klasickému volání funkcí spočívá v časovém omezení: uživatel je na lince bez vizuální indikace průběhu. Pokud执行 trvá déle než sekundu nebo dvě, nechej agenta mluvit, zatímco pracuje – „Hned to pro vás zkontroluji“ – protože ticho v hlasové konverzaci působí jako výpadek.
async def _handle_response_done(self, event):
"""Zpracovává volání funkcí v odpovědi."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # Nový řádek po přepisu
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Spuštění funkce (přizpůsobte své obchodní logice)
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)
}
}))
# Požádej model o pokračování
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Směruje volání funkce."""
# Implementuj podle své obchodní logiky
return {"error": f"Funkce {name} není implementována"}
Spuštění agenta
async def main():
agent = VoiceAgent(
api_key="sk-...",
instructions=(
"Jsi hlasový asistent pro Corsen AI. "
"Pomáháš uživatelům spravovat jejich schůzky "
"a získávat informace o našich službách. "
"Odpovídej francouzsky, stručně a profesionálně."
),
tools=[
{
"type": "function",
"name": "check_availability",
"description": "Zkontroluje dostupnost pro daný časový úsek",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string"},
"service": {"type": "string"}
},
"required": ["date"]
}
}
]
)
await agent.start()
asyncio.run(main())
Klíčové poznatky
- Kompletní hlasový agent kombinuje čtyři moduly: audio, relaci, nástroje a správu stavu
- Třída
VoiceAgentzapouzdřuje veškerou logiku za jednoduché rozhraní asyncio.gatherumožňuje paralelní záznam z mikrofonu a zpracování událostí- Zvládání přerušení (zrušení odpovědi, když uživatel začne mluvit) je zásadní
- Nástroje promění agenta z jednoduchého hlasového chatbota v asistenta schopného akce