Salt la conținutul principal
Română— Alege o limbă
Meniu

Construire un agent vocal complet

Lecția 14 din 18 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Construire un agent vocal complet
  2. Architecture de l’agent
  3. La classe VoiceAgent
  4. Module de capture audio
  5. Module de traitement des événements
  6. Module de gestion des outils
  7. Lancer l’agent
  8. Puncte cheie

Mis à jour le 2 novembre 2026 — Modèles audio. Plusieurs modèles de ce cours sont obsolètes : tts-1, tts-1-hd et gpt-4o-mini-tts cesseront de fonctionner le 6 janvier 2027 (successeur : gpt-realtime-2.1-mini, que le guide TTS d’OpenAI indique comme non pris en charge par /v1/audio/speech : la migration de la synthèse vocale passe vers l’API Realtime) ; gpt-realtime, gpt-4o-realtime et les anciens modèles audio le 20 janvier 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5) ; whisper-1, gpt-4o-transcribe et /v1/audio/translations le 26 février 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pour la voix en full-duplex, GPT-Live 1 est disponible dans l’API depuis le 10 septembre 2026.

Corrigé le 3 novembre 2026. La transcription d’entrée utilisait gpt-live-transcribe, qui ne fonctionne que dans une session de transcription et ne prend en charge ni server_vad ni semantic_vad. Dans une session de conversation comme celle-ci, où le VAD valide chaque tour de parole, la documentation spécifie gpt-transcribe, qui transcrit les tours validés et utilise les tours précédents comme contexte. Sources : Transcription en temps réel · GPT-Transcribe · GPT-Live-Transcribe.

Construire un agent vocal complet

Cette leçon rassemble tous les concepts abordés jusqu’ici pour construire un agent vocal entièrement fonctionnel de bout en bout. Vous allez créer un assistant qui écoute l’utilisateur, comprend sa demande, exécute des actions et répond vocalement, le tout en temps réel via l’API Realtime.

Architecture de l’agent

Quatre modules, et surtout une contrainte qui pilote toute l’architecture : tout doit se produire simultanément. Le microphone capture pendant que le modèle répond, les événements arrivent pendant que l’audio est lu, et l’utilisateur peut interrompre à tout moment. Un agent vocal n’est pas une boucle question-réponse ; c’est un système où plusieurs flux avancent en parallèle, c’est pourquoi nous nous appuyons fortement sur asyncio dans ce qui suit.

Audio
Capture et lecture
Session
WebSocket et configuration
Outils
Actions métier
État
Gestion de la conversation

La classe VoiceAgent

La classe regroupe l’état que ces flux parallèles doivent partager : la connexion, la session actuelle et la réponse en cours de lecture. Précisément parce que plusieurs tâches accèdent à cet état simultanément, un objet est préférable à un ensemble de variables globales : lorsque vous devez annuler une réponse en cours, vous devez savoir qu’elle existe.

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

class VoiceAgent:
    """Agent vocal complet basé sur l'API Realtime."""

    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):
        """Établit la connexion et configure la session."""
        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)

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

        # Configuration
        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 vocal prêt.")

    async def start(self):
        """Démarre l'agent vocal."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Module de capture audio

    async def _capture_audio(self):
        """Capture l'entrée du microphone et l'envoie à l'API Realtime."""
        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
                }))

Module de traitement des événements

    async def _process_events(self):
        """Traite tous les événements provenant du serveur."""
        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"\nErreur : {event['error']['message']}")

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

Module de gestion des outils

Ce module transforme l’agent d’un simple chatbot vocal en un assistant capable d’agir. La différence avec l’appel de fonctions classique réside dans la contrainte temporelle : l’utilisateur est en ligne sans indicateur de progression visuel. Si l’exécution prend plus d’une ou deux secondes, faites parler l’agent pendant qu’il travaille — „Laissez-moi vérifier cela pour vous immédiatement“ — car le silence dans une conversation vocale ressemble à une panne.

    async def _handle_response_done(self, event):
        """Gère les appels de fonction dans la réponse."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Nouvelle ligne après la transcription
            return

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

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

            # Exécuter la fonction (adapter à votre logique métier)
            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)
                }
            }))

        # Demander au modèle de continuer
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Aiguille l'appel de fonction."""
        # Implémenter selon votre logique métier
        return {"error": f"Fonction {name} non implémentée"}

Lancer l’agent

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "Vous êtes un assistant vocal pour Corsen AI. "
            "Vous aidez les utilisateurs à gérer leurs rendez-vous "
            "et à obtenir des informations sur nos services. "
            "Répondez en français, de manière concise et professionnelle."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Vérifie la disponibilité pour un créneau horaire",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Puncte cheie

  • Un agent vocal complet combine quatre modules : audio, session, outils et gestion d’état
  • La classe VoiceAgent encapsule toute la logique derrière une interface simple
  • asyncio.gather permet la capture du microphone et le traitement des événements en parallèle
  • La gestion des interruptions (annuler une réponse lorsque l’utilisateur parle) est essentielle
  • Les outils transforment l’agent d’un simple chatbot vocal en un assistant capable d’agir