Przejdź do głównej treści
Polski— Wybierz język
Menu

Stwórz kompletnego agenta głosowego

Lekcja 14 z 18 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Stwórz kompletnego agenta głosowego
  2. Architektura agenta
  3. Klasa VoiceAgent
  4. Moduł rejestracji audio
  5. Moduł przetwarzania zdarzeń
  6. Moduł zarządzania narzędziami
  7. Uruchomienie agenta
  8. Kluczowe wnioski

Zaktualizowano 2 listopada 2026 — Modele audio. Kilka modeli w tym kursie jest przestarzałych: tts-1, tts-1-hd oraz gpt-4o-mini-tts przestaną działać 6 stycznia 2027 (następca: gpt-realtime-2.1-mini, który zgodnie z przewodnikiem OpenAI TTS nie jest obsługiwany przez /v1/audio/speech: migracja syntezy mowy przechodzi do Realtime API); gpt-realtime, gpt-4o-realtime oraz starsze modele audio 20 stycznia 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe oraz /v1/audio/translations 26 lutego 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Dla komunikacji pełnodupleksowej głosowej, GPT-Live 1 jest dostępny w API od 10 września 2026.

Skorygowano 3 listopada 2026. Transkrypcja wejścia używała gpt-live-transcribe, który działa wyłącznie w sesji transkrypcji i nie obsługuje ani server_vad, ani semantic_vad. W sesji konwersacyjnej, takiej jak ta, gdzie VAD waliduje każdą turę, dokumentacja wskazuje na użycie gpt-transcribe, który transkrybuje zwalidowane tury i wykorzystuje poprzednie tury jako kontekst. Źródła: Transkrypcja w czasie rzeczywistym · GPT-Transcribe · GPT-Live-Transcribe.

Stwórz kompletnego agenta głosowego

Ta lekcja łączy wszystkie dotychczas omówione koncepcje, aby zbudować w pełni funkcjonalnego agenta głosowego typu end-to-end. Stworzysz asystenta, który słucha użytkownika, rozumie jego żądania, wykonuje działania i odpowiada głosem – wszystko w czasie rzeczywistym poprzez Realtime API.

Architektura agenta

Cztery moduły i przede wszystkim jedno ograniczenie napędzające całą architekturę: wszystko musi dziać się jednocześnie. Mikrofon rejestruje dźwięk, podczas gdy model odpowiada, zdarzenia napływają, gdy odtwarzane jest audio, a użytkownik może przerwać w dowolnym momencie. Agent głosowy to nie pętla pytanie-odpowiedź; to system, w którym wiele strumieni postępuje równolegle – dlatego w dalszej części tak mocno polegamy na asyncio.

Audio
Rejestracja i odtwarzanie
Sesja
WebSocket i konfiguracja
Narzędzia
Działania biznesowe
Stan
Zarządzanie konwersacją

Klasa VoiceAgent

Klasa gromadzi stan, który muszą współdzielić te równoległe strumienie: połączenie, bieżącą sesję oraz obecnie odtwarzaną odpowiedź. Właśnie dlatego, że wiele zadań uzyskuje dostęp do tego stanu jednocześnie, obiekt jest lepszym rozwiązaniem niż zestaw zmiennych globalnych – gdy musisz anulować trwającą odpowiedź, musisz wiedzieć, że taka istnieje.

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

class VoiceAgent:
    """Kompletny agent głosowy oparty 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):
        """Nawiązuje połączenie i konfiguruje sesję."""
        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)

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

        # Konfiguracja
        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("Agent głosowy gotowy.")

    async def start(self):
        """Uruchamia agenta głosowego."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Moduł rejestracji audio

    async def _capture_audio(self):
        """Rejestruje wejście z mikrofonu i wysyła je 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
                }))

Moduł przetwarzania zdarzeń

    async def _process_events(self):
        """Przetwarza wszystkie zdarzenia z serwera."""
        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"\nBłąd: {event['error']['message']}")

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

Moduł zarządzania narzędziami

Ten moduł przekształca agenta z prostego czatbota głosowego w asystenta zdolnego do podejmowania działań. Różnica w stosunku do klasycznego wywoływania funkcji polega na ograniczeniu czasowym: użytkownik jest na linii bez wizualnego wskaźnika postępu. Jeśli wykonanie zajmie więcej niż sekundę lub dwie, spraw, by agent mówił podczas pracy – „Sprawdzam to dla Ciebie teraz“ – ponieważ cisza w rozmowie głosowej brzmi jak awaria.

    async def _handle_response_done(self, event):
        """Obsługuje wywołania funkcji w odpowiedzi."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Nowa linia po transkrypcji
            return

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

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

            # Wykonaj funkcję (dostosuj do swojej logiki biznesowej)
            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)
                }
            }))

        # Poproś model o kontynuację
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Dysponuje wywołaniem funkcji."""
        # Zaimplementuj zgodnie z Twoją logiką biznesową
        return {"error": f"Funkcja {name} nie została zaimplementowana"}

Uruchomienie agenta

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "Jesteś asystentem głosowym dla Corsen AI. "
            "Pomagasz użytkownikom zarządzać ich spotkaniami "
            "i uzyskiwać informacje o naszych usługach. "
            "Odpowiadaj po francusku, zwięźle i profesjonalnie."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Sprawdza dostępność dla wybranego terminu",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Kluczowe wnioski

  • Kompletny agent głosowy łączy cztery moduły: audio, sesję, narzędzia i zarządzanie stanem
  • Klasa VoiceAgent enkapsuluje całą logikę za pomocą prostego interfejsu
  • asyncio.gather umożliwia równoległą rejestrację z mikrofonu i przetwarzanie zdarzeń
  • Obsługa przerwań (anulowanie odpowiedzi, gdy użytkownik zaczyna mówić) jest kluczowa
  • Narzędzia przekształcają agenta z prostego czatbota głosowego w asystenta zdolnego do działania