Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Bygg en komplett röstagent

Lektion 14 av 18 Uppdaterad 3 november 2026 Utvecklare
På denna sida
  1. Bygg en komplett röstagent
  2. Agentarkitektur
  3. Klassen VoiceAgent
  4. Modul för ljudinspelning
  5. Modul för händelsebearbetning
  6. Modul för verktygshantering
  7. Starta agenten
  8. Viktiga punkter

Uppdaterad 2 november 2026 — Ljudmodeller. Flera modeller i denna kurs är avvecklade: tts-1, tts-1-hd och gpt-4o-mini-tts upphör den 6 januari 2027 (efträdare: gpt-realtime-2.1-mini, vilket OpenAI:s TTS-guide anger inte stöds av /v1/audio/speech: migreringen av talgenerering flyttas till Realtime API); gpt-realtime, gpt-4o-realtime och äldre ljudmodeller den 20 januari 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe och /v1/audio/translations den 26 februari 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). För full duplex-röst har GPT-Live 1 funnits tillgänglig i API:t sedan den 10 september 2026.

Korrigerad 3 november 2026. Inmatningstranskribering använde gpt-live-transcribe, vilket endast fungerar i en transkriberingssession och varken stöder server_vad eller semantic_vad. I en konversationssession som denna, där VAD validerar varje tur, specificerar dokumentationen gpt-transcribe, som transkriberar validerade turer och använder tidigare turer som kontext. Källor: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Bygg en komplett röstagent

Den här lektionen sammanför alla begrepp som behandlats hittills för att bygga en fullt fungerande röstagent från början till slut. Du kommer att skapa en assistent som lyssnar på användaren, förstår deras begäran, utför åtgärder och svarar med röst – allt i realtid via Realtime API.

Agentarkitektur

Fyra moduler, och framför allt en begränsning som driver hela arkitekturen: allt måste ske samtidigt. Mikrofonen fångar ljud medan modellen svarar, händelser anländer medan ljud spelas upp, och användaren kan avbryta när som helst. En röstagent är inte en fråga-och-svar-loop; det är ett system där flera strömmar avancerar parallellt – vilket är anledningen till att vi förlitar oss kraftigt på asyncio i det följande.

Ljud
Inspelning och uppspelning
Session
WebSocket och konfiguration
Verktyg
Affärsåtgärder
Tillstånd
Konversationshantering

Klassen VoiceAgent

Klassen samlar det tillstånd som dessa parallella strömmar måste dela: anslutningen, den aktuella sessionen och svaret som för närvarande spelas upp. Just eftersom flera uppgifter kommer åt detta tillstånd samtidigt är ett objekt att föredra framför en uppsättning globala variabler – när du behöver avbryta ett pågående svar måste du veta att ett existerar.

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

class VoiceAgent:
    """Komplett röstagent baserad på 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):
        """Upprättar anslutningen och konfigurerar sessionen."""
        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)

        # Vänta på session.created
        event = json.loads(await self.ws.recv())
        print(f"Session: {event['session']['id']}")

        # Konfigurera
        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("Röstagent redo.")

    async def start(self):
        """Startar röstagenten."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Modul för ljudinspelning

    async def _capture_audio(self):
        """Fångar mikrofoninmatning och skickar den till 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 för händelsebearbetning

    async def _process_events(self):
        """Bearbetar alla händelser från servern."""
        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"\nFel: {event['error']['message']}")

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

Modul för verktygshantering

Denna modul omvandlar agenten från en enkel röstchattbot till en assistent som kan vidta åtgärder. Skillnaden från klassisk funktionsanrop ligger i tidsbegränsningen: användaren är uppkopplad utan någon visuell framstegsindikator. Om exekveringen tar mer än en sekund eller två, låt agenten prata medan den arbetar – »Låt mig kolla upp det åt dig direkt« – eftersom tystnad i en röstkonversation låter som ett avbrott.

    async def _handle_response_done(self, event):
        """Hanterar funktionsanrop i svaret."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Ny rad efter transkribering
            return

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

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

            # Exekvera funktionen (anpassa till din affärslogik)
            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)
                }
            }))

        # Be modellen att fortsätta
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Dirigerar funktionsanropet."""
        # Implementera enligt din affärslogik
        return {"error": f"Funktion {name} inte implementerad"}

Starta agenten

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "Du är en röstassistent för Corsen AI. "
            "Du hjälper användare att hantera sina möten "
            "och få information om våra tjänster. "
            "Svara på franska, koncist och professionellt."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Kontrollerar tillgänglighet för en tidslucka",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Viktiga punkter

  • En komplett röstagent kombinerar fyra moduler: ljud, session, verktyg och tillståndshantering
  • Klassen VoiceAgent kapslar in all logik bakom ett enkelt gränssnitt
  • asyncio.gather möjliggör parallell mikrofoninspelning och händelsebearbetning
  • Hantering av avbrott (att avbryta ett svar när användaren pratar) är avgörande
  • Verktyg omvandlar agenten från en enkel röstchattbot till en assistent som kan vidta åtgärder