Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Izgradi potpunog glasovnog agenta

Lekcija 14 od 18 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Izgradi potpunog glasovnog agenta
  2. Arhitektura agenta
  3. Klasa VoiceAgent
  4. Modul za snimanje zvuka
  5. Modul za obradu događaja
  6. Modul za upravljanje alatima
  7. Pokreni agenta
  8. Ključne točke

Ažurirano 2. studenoga 2026. — Audio modeli. Nekoliko modela u ovom tečaju je zastarjelo: tts-1, tts-1-hd i gpt-4o-mini-tts prestat će s radom 6. siječnja 2027. (nasljednik: gpt-realtime-2.1-mini, za koji OpenAI TTS vodič navodi da nije podržan od strane /v1/audio/speech: migracija sinteze govora prelazi na Realtime API); gpt-realtime, gpt-4o-realtime i stariji audio modeli 20. siječnja 2027. (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe i /v1/audio/translations 26. veljače 2027. (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Za full-duplex glas, GPT-Live 1 dostupan je u API-ju od 10. rujna 2026.

Ispravljeno 3. studenoga 2026. Ulazna transkripcija koristila je gpt-live-transcribe, koji radi samo u sesiji za transkripciju i ne podržava ni server_vad ni semantic_vad. U sesiji razgovora poput ove, gdje VAD validira svaki okret, dokumentacija specificira gpt-transcribe, koji transkribira validirane okrete i koristi prethodne okrete kao kontekst. Izvori: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Izgradi potpunog glasovnog agenta

Ova lekcija povezuje sve dosad obrađene koncepte kako bi se izgradio potpuno funkcionalan glasovni agent od kraja do kraja. Stvorit ćeš asistenta koji sluša korisnika, razumije njegov zahtjev, izvršava radnje i odgovara glasom – sve u stvarnom vremenu putem Realtime API-ja.

Arhitektura agenta

Četiri modula, a prije svega jedno ograničenje koje pokreće cijelu arhitekturu: sve se mora događati istovremeno. Mikrofon snima dok model odgovara, događaji stižu dok se audio reproducira, a korisnik može prekinuti razgovor u bilo kojem trenutku. Glasovni agent nije petlja pitanje-odgovor; to je sustav u kojem više streamova napreduje paralelno – zato se u nastavku uvelike oslanjamo na asyncio.

Audio
Snimanje i reprodukcija
Sesija
WebSocket i konfiguracija
Alati
Poslovne radnje
Stanje
Upravljanje razgovorom

Klasa VoiceAgent

Klasa okuplja stanje koje ovi paralelni streamovi moraju dijeliti: vezu, trenutnu sesiju i odgovor koji se trenutno reproducira. Upravo zato što više zadataka istovremeno pristupa ovom stanju, objekt je poželjniji od skupa globalnih varijabli – kada trebaš otkazati odgovor u tijeku, moraš znati da on postoji.

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

class VoiceAgent:
    """Potpuni glasovni agent temeljen na Realtime API-ju."""

    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):
        """Uspostavlja vezu i konfigurira sesiju."""
        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)

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

        # Konfiguriraj
        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("Glasovni agent spreman.")

    async def start(self):
        """Pokreće glasovnog agenta."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Modul za snimanje zvuka

    async def _capture_audio(self):
        """Snima ulaz s mikrofona i šalje ga Realtime API-ju."""
        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 za obradu događaja

    async def _process_events(self):
        """Obrađuje sve događaje sa servera."""
        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"\nGreška: {event['error']['message']}")

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

Modul za upravljanje alatima

Ovaj modul pretvara agenta iz jednostavnog glasovnog chatbota u asistenta sposobnog za poduzimanje radnji. Razlika u odnosu na klasično pozivanje funkcija leži u vremenskom ograničenju: korisnik je na liniji bez vizualnog indikatora napretka. Ako izvršenje traje više od sekunde ili dvije, neka agent govori dok radi – „Dopusti mi da to odmah provjerim za tebe“ – jer tišina u glasovnom razgovoru zvuči kao kvar.

    async def _handle_response_done(self, event):
        """Rukuje pozivima funkcija u odgovoru."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Novi red nakon transkripcije
            return

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

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

            # Izvrši funkciju (prilagodi svojoj poslovnoj logici)
            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)
                }
            }))

        # Zatraži od modela da nastavi
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Prosljeđuje poziv funkcije."""
        # Implementiraj prema svojoj poslovnoj logici
        return {"error": f"Funkcija {name} nije implementirana"}

Pokreni agenta

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "Ti si glasovni asistent za Corsen AI. "
            "Pomažeš korisnicima upravljati terminima "
            "i dobivati informacije o našim uslugama. "
            "Odgovaraj na francuskom, sažeto i profesionalno."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Provjerava dostupnost za vremenski termin",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Ključne točke

  • Potpuni glasovni agent kombinira četiri modula: audio, sesiju, alate i upravljanje stanjem
  • Klasa VoiceAgent encapsulira svu logiku iza jednostavnog sučelja
  • asyncio.gather omogućuje paralelno snimanje mikrofona i obradu događaja
  • Rukovanje prekidima (otkazivanje odgovora kada korisnik progovori) je ključno
  • Alati pretvaraju agenta iz jednostavnog glasovnog chatbota u asistenta sposobnog za djelovanje