Izgradi potpunog glasovnog agenta
Na ovoj stranici
Ažurirano 2. studenoga 2026. — Audio modeli. Nekoliko modela u ovom tečaju je zastarjelo:
tts-1,tts-1-hdigpt-4o-mini-ttsprestat ć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-realtimei stariji audio modeli 20. siječnja 2027. (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribei/v1/audio/translations26. 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 niserver_vadnisemantic_vad. U sesiji razgovora poput ove, gdje VAD validira svaki okret, dokumentacija specificiragpt-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.
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
VoiceAgentencapsulira svu logiku iza jednostavnog sučelja asyncio.gatheromoguć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