Premiers pas avec la Realtime API

Créez un agent vocal de parole à parole avec la Realtime API. Le modèle traite directement l’audio, conserve l’état de la conversation et peut appeler des outils. Ce guide vous montre d’abord comment utiliser le SDK Agents dans une application qui s’exécute dans le navigateur. Si vous souhaitez contrôler directement la connexion, consultez les guides de plus bas niveau.

Pour les conversations en duplex intégral où certaines tâches sont déléguées à un backend distinct, consultez GPT-Live. Pour comparer les architectures vocales et les pipelines qui enchaînent plusieurs étapes de traitement, consultez le guide Agents vocaux.

Créer un agent vocal de parole à parole

Utilisez la Realtime API pour que les échanges soient aussi fluides et immédiats qu’une conversation. C’est le meilleur point de départ pour un agent vocal qui doit laisser l’utilisateur l’interrompre, commencer à répondre à voix haute avec un délai minimal, respecter le rythme naturel des tours de parole et utiliser des outils en temps réel.

Dans le navigateur, une session se déroule généralement ainsi :

1. Votre serveur d’application crée un secret client éphémère pour la session Realtime.
2. Votre frontend crée une RealtimeSession.
3. La session se connecte via WebRTC dans le navigateur ou via WebSocket sur le serveur.
4. Au sein de cette session, l’agent gère les tours de parole, les outils, les interruptions et les transferts entre agents.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";

const ephemeralKey = process.env.OPENAI_REALTIME_EPHEMERAL_KEY;
if (!ephemeralKey)
  throw new Error("Set OPENAI_REALTIME_EPHEMERAL_KEY from your server.");

const agent = new RealtimeAgent({
  name: "Assistant",
  instructions: "You are a helpful voice assistant.",
});

const session = new RealtimeSession(agent, {
  model: "gpt-realtime-2.1",
});

await session.connect({
  apiKey: ephemeralKey,
});

Ajoutez ensuite des outils, des transferts entre agents et des garde-fous à votre RealtimeAgent comme vous le feriez pour un agent textuel. Gérez le transport audio au niveau de la session et placez la logique métier dans la définition de l’agent.

Pour contrôler le transport à plus bas niveau, consultez d’abord les guides suivants :

• Présentation de l’audio et de la voix
• Realtime API avec WebRTC
• Realtime API avec WebSocket

Identifiants de sécurité

Si votre application identifie chaque utilisateur final, joignez un identifiant de sécurité aux requêtes adressées à la Realtime API. OpenAI recommande ces identifiants, mais leur utilisation reste facultative. Ils aident OpenAI à détecter les comportements préjudiciables et à limiter les mesures prises à l’utilisateur concerné, sans les étendre à toute votre organisation. Utilisez une valeur stable qui préserve la confidentialité, comme le hachage d’un identifiant utilisateur interne.

Pour les requêtes adressées à la Realtime API, envoyez l’identifiant dans l’en-tête OpenAI-Safety-Identifier. Si vous utilisez des tokens éphémères, ajoutez cet en-tête à la requête côté serveur qui crée le secret client afin d’associer l’identifiant à la session. Si vous vous connectez depuis un serveur de confiance via WebSocket ou l’interface WebRTC unifiée, ajoutez l’en-tête à la requête de connexion.

Les identifiants de sécurité utilisés dans les requêtes à l’API Responses ou dans d’autres sessions ne sont pas repris automatiquement. Si vous utilisez le paramètre safety_identifier de l’API Responses ailleurs dans votre application, transmettez la même valeur stable chaque fois que vous créez une session Realtime ou que vous vous y connectez.

Migration de la version bêta vers la version généralement disponible (GA)

Si votre intégration Realtime utilise encore la version bêta, migrez vers l’interface GA avant d’entamer de nouveaux développements. Voici les principaux changements à apporter :

• Supprimez l’en-tête OpenAI-Beta: realtime=v1 lorsque vous appelez l’interface GA.
• Utilisez POST /v1/realtime/client_secrets pour créer des informations d’authentification éphémères pour les clients web ou mobiles.
• Utilisez /v1/realtime/calls pour établir des sessions WebRTC.
• Adaptez la structure des sessions et des événements à l’interface GA. En particulier, définissez session.type, déplacez la configuration de la sortie audio dans session.audio.output et utilisez les nouveaux noms d’événements de réponse, comme response.output_text.delta, response.output_audio.delta et response.output_audio_transcript.delta.
• Si vous migrez une application de parole à parole, partez de l’exemple pour navigateur. Si vous migrez un workflow de transcription, suivez le guide Transcription en temps réel.

Pour connaître la procédure actuelle avec l’interface GA, consultez la référence des événements client Realtime, la référence des sessions Realtime et l’exemple pour navigateur.

Étapes suivantes

• Gestion des conversations : configurez les sessions et gérez l’audio, le texte et les événements.
• Détection de l’activité vocale : configurez la détection automatique des tours de parole.
• Outils et MCP : ajoutez des fonctions, des serveurs MCP et des connecteurs.
• Rédaction de prompts pour les modèles vocaux : utilisez le guide correspondant à votre modèle Realtime.
• Optimisation des coûts : découvrez comment Realtime comptabilise l’utilisation et gère la mise en cache.
• Contrôles côté serveur : exécutez les outils et contrôlez les sessions depuis votre serveur.

Autres workflows audio

Le guide Audio et voix vous aide désormais à choisir un workflow et présente le vocabulaire commun aux différents workflows audio. Pour traduire en continu, consultez le guide Traduction en direct. Pour générer des sous-titres en direct, consultez le guide Transcription en direct. Pour transcrire un enregistrement audio, consultez le guide Transcription de fichiers.