Stwórz kompletnego agenta głosowego
Na tej stronie
Zaktualizowano 2 listopada 2026 — Modele audio. Kilka modeli w tym kursie jest przestarzałych:
tts-1,tts-1-hdorazgpt-4o-mini-ttsprzestaną 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-realtimeoraz starsze modele audio 20 stycznia 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeoraz/v1/audio/translations26 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 aniserver_vad, anisemantic_vad. W sesji konwersacyjnej, takiej jak ta, gdzie VAD waliduje każdą turę, dokumentacja wskazuje na użyciegpt-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.
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
VoiceAgentenkapsuluje całą logikę za pomocą prostego interfejsu asyncio.gatherumoż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