Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Vytvořte kompletního hlasového agenta

Lekce 14 z 18 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Vytvořte kompletního hlasového agenta
  2. Architektura agenta
  3. Třída VoiceAgent
  4. Modul pro záznam zvuku
  5. Modul pro zpracování událostí
  6. Modul pro správu nástrojů
  7. Spuštění agenta
  8. Klíčové poznatky

Aktualizováno 2. listopadu 2026 — Zvukové modely. Několik modelů v tomto kurzu je zastaralých: tts-1, tts-1-hd a gpt-4o-mini-tts př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-realtime a starší zvukové modely skončí 20. ledna 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe a /v1/audio/translations skončí 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 ani server_vad, ani semantic_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.

Audio
Záznam a přehrávání
Relace
WebSocket a konfigurace
Nástroje
Obchodní akce
Stav
Správa konverzace

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 VoiceAgent zapouzdřuje veškerou logiku za jednoduché rozhraní
  • asyncio.gather umožň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