Passer au contenu principal
L’interrogation des résultats est efficace, mais pour une expérience plus réactive et en temps réel, vous pouvez streamer les événements directement depuis un outil en cours d’exécution. Ce guide couvre les deux principaux types de streaming disponibles dans l’API :
  1. Streaming d’Exécution d’Outil : Pour surveiller les tâches d’outils de longue durée.
  2. Streaming de Session d’Agent : Pour recevoir des réponses de chat en temps réel des agents.

​
Streaming d’Exécution d’Outil

Ce guide montre comment se connecter au flux d’événements d’un outil en utilisant les Server-Sent Events (SSE). Il suppose que vous avez déjà lancé une exécution d’outil comme indiqué dans le guide Exécuter Votre Premier Outil.
1

Exécuter un Outil et Obtenir l'URL de Streaming

Tout d’abord, exécutez un outil comme vous le feriez normalement. La réponse initiale 202 Accepted contiendra une stream_url. C’est l’endpoint que nous utiliserons pour recevoir les événements en direct.
Réponse
{
  "execution_id": "exec_123456789",
  "status": "pending",
  "tool_id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
  "details_url": "https://app.ubik-agent.com/api/v1/tool-executions/exec_123456789",
  "stream_url": "https://app.ubik-agent.com/api/v1/tool-executions/exec_123456789/stream"
}
Copiez la stream_url pour l’étape suivante.
2

Se Connecter au Flux d'Événements

Maintenant, vous pouvez vous connecter à la stream_url en utilisant n’importe quel client compatible SSE. La connexion restera ouverte, et le serveur enverra les événements au fur et à mesure qu’ils se produisent.
# Utilisez l'option -N pour désactiver la mise en mémoire tampon
curl -X GET "https://app.ubik-agent.com/api/v1/tool-executions/exec_123456789/stream" \
     -H "X-API-KEY: VOTRE_CLE_API" \
     -N
Dans l’exemple JavaScript EventSource, nous passons la clé API comme paramètre de requête. Notre serveur est configuré pour accepter la clé API soit via l’en-tête X-API-KEY, soit via un paramètre de requête nommé api_key pour les connexions SSE, car EventSource ne prend pas en charge les en-têtes personnalisés.
3

Comprendre les Événements

Au fur et à mesure que l’outil s’exécute, vous recevrez une série d’objets JSON. Chaque objet contient un event_type et une charge utile data. Voici les types d’événements détaillés et leurs structures :

​
tool_update

Utilisé pour les mises à jour générales de progression ou les changements de données structurées.
{
  "event_type": "tool_update",
  "data": {
    "phase": "processing",        // Optionnel : Phase d'exécution actuelle
    "message": "Traitement...",   // Optionnel : Statut lisible par l'humain
    "output_key": "result",       // Optionnel : Clé pour les données structurées
    "data": { ... }               // Optionnel : Données structurées arbitraires
  }
}

​
tool_partial_update

Utilisé pour le contenu en streaming (par exemple, génération de texte, téléchargements partiels d’images).
{
  "event_type": "tool_partial_update",
  "data": {
    "content": "texte partiel...", // Le fragment de contenu
    "output_key": "response",      // Le champ de sortie en cours de streaming
    "data": { ... }                // Optionnel : Métadonnées supplémentaires
  }
}

​
tool_input_required

Envoyé lorsqu’un outil interactif met en pause l’exécution pour attendre une entrée de l’utilisateur.
{
  "event_type": "tool_input_required",
  "data": {
    "prompt": "Veuillez confirmer...", // Question pour l'utilisateur
    "input_types": ["text"],           // Types d'entrée autorisés
    "timeout": 300,                    // Délai d'attente en secondes
    "state": { ... }                   // État interne (opaque)
  }
}

​
final_result

L’événement final d’une exécution réussie.
{
  "event_type": "final_result",
  "data": {
    "outputs": {                   // Les sorties complètes de l'outil
      "response": "Texte complet...",
      "images": [...]
    }
  }
}

​
error

Indique qu’une erreur est survenue pendant l’exécution.
{
  "event_type": "error",
  "data": {
    "message": "Description de l'erreur",
    "code": "CODE_ERREUR"
  }
}

​
Exemple de Flux d’Événements

data: {"event_type": "tool_update", "data": {"phase": "retrieval", "message": "Récupération des documents pertinents..."}}

data: {"event_type": "tool_update", "data": {"phase": "generation", "message": "Génération de la réponse..."}}

data: {"event_type": "tool_partial_update", "data": {"content": "Les résultats financiers montrent..."}}

data: {"event_type": "tool_partial_update", "data": {"content": " une augmentation significative du chiffre d'affaires."}}

data: {"event_type": "final_result", "data": {"outputs": {"response": "Les résultats financiers montrent une augmentation significative du chiffre d'affaires."}}}

​
Streaming de Session d’Agent

Les Sessions d’Agent fournissent un ensemble différent d’événements adaptés aux interfaces conversationnelles. Lorsque vous envoyez un message avec "stream": true, le serveur diffuse le processus de réflexion de l’agent et les morceaux de réponse.

​
Événements de Session d’Agent

Contrairement aux exécutions d’outils, les événements de session d’agent sont souvent utilisés pour afficher une interface de chat en temps réel. Pour une liste complète des types d’événements et leur structure, veuillez consulter le Guide des Événements de Session d’Agent.

​
Endpoint de Stream Dédié

Bien que POST /agent-sessions/{id}/messages prenne en charge le streaming direct, UBIK fournit également un endpoint dédié pour s’abonner aux événements de session. Ceci est utile pour :
  1. Reconnexion : Reprendre un flux si la connexion est interrompue (les événements passés sont rejoués).
  2. Compatibilité Navigateur : Utiliser EventSource qui nécessite une requête GET et une authentification basée sur l’URL.
Endpoint : GET /agent-sessions/{session_id}/stream

​
Authentification avec JWT

Comme l’API EventSource standard des navigateurs ne peut pas envoyer d’en-têtes personnalisés (comme X-API-KEY), cet endpoint accepte un paramètre de requête token. Vous devez générer un JWT à courte durée de vie en utilisant /auth/token et le passer ici. Pour plus de détails sur la génération de jetons, voir le Guide Authentification & Sécurité. 
// 1. Obtenir un jeton à courte durée de vie depuis votre backend
const token = "eyJhbGciOiJIUz..."; 

// 2. Se connecter en utilisant le paramètre token
const streamUrl = `https://app.ubik-agent.com/api/v1/agent-sessions/${sessionId}/stream?token=${token}`;
const eventSource = new EventSource(streamUrl);