Traçage

Une session regroupe la conversation et le travail de votre agent. Une session peut contenir plusieurs tours, chacun correspondant à un cycle de travail. Une trace montre les étapes d’un tour : réponses du modèle, appels d’outils et travail délégué à d’autres agents.

Le tableau de bord de traçage montre ce que votre agent a fait, notamment les entrées, les sorties, la durée et le statut enregistrés pour chaque étape.

Pour consulter le statut des sessions, les événements en direct, les sorties enregistrées et la consommation via l’API, commencez par la page Observabilité.

Le traçage est activé par défaut pour les nouvelles sessions. Vous pouvez examiner les traces dans le tableau de bord ou les exporter via l’API.

Ouvrez une trace

1. Ouvrez Journaux → Agents et sélectionnez le projet dans lequel vous avez exécuté votre agent.
2. Retrouvez votre session avec Rechercher dans les journaux. Utilisez Ajouter un filtre pour filtrer par modèle, statut ou date.
3. Sélectionnez la session pour ouvrir sa chronologie et sa liste de tours.
4. Développez un tour, puis sélectionnez une étape dans la chronologie ou la liste des événements pour en voir les détails.

Le résumé de la session affiche son statut, son modèle, son heure de début, sa dernière activité, son nombre de tours et sa consommation de tokens enregistrée.

Lisez une trace

Commencez par la session, puis explorez le détail d’un tour :

1. Session : chaque entrée de Journaux → Agents est une session. Ouvrez-la pour voir sa chronologie et sa liste de tours. Par exemple, un utilisateur peut poser une question sur une commande, puis une question complémentaire dans la même session.
2. Tour : développez un tour pour voir le travail effectué pendant ce cycle. Un tour peut inclure plusieurs réponses du modèle et appels d’outils. Un message de suivi envoyé après la fin du tour démarre un nouveau tour dans la même session.
3. Étapes du tour : la trace regroupe les réponses du modèle et les appels d’outils sous l’agent racine ou le sous-agent qui les a effectués. Chaque étape enregistrée est appelée un span.

Sélectionnez un span pour voir son statut, sa durée, ses heures de début et de fin ainsi que ses données enregistrées :

Agent

Un span d’agent regroupe le travail effectué par l’agent racine ou par un sous-agent : un autre agent chargé d’une partie de la tâche. Les réponses du modèle et les appels d’outils apparaissent sous l’agent qui les a effectués.

Le panneau de détails affiche :

• Type d’agent : agent racine (root) ou sous-agent (subagent).
• Agent : son identifiant, son nom, son modèle et ses instructions, lorsque ces informations sont enregistrées.
• Consommation : les nombres de tokens enregistrés pour cet agent. Ces décomptes concernent uniquement l’agent lui-même ; ils n’incluent pas ses sous-agents.
• Durée et Statut d’exécution : le temps pris par le travail enregistré et son état : terminé, en échec ou incomplet.

Génération

Un span de génération regroupe les entrées et les sorties enregistrées du modèle. Chaque tour peut comporter plusieurs générations.

Lors de l’inférence, le modèle lit ses entrées et produit une réponse. Cette réponse peut demander l’appel d’un outil. Une fois que l’outil a renvoyé son résultat, le modèle peut produire une autre réponse dans une nouvelle génération.

• Entrée : les entrées enregistrées associées à cette réponse, comme un message utilisateur ou le résultat d’un outil.
• Sortie : les éléments enregistrés produits par le modèle, comme le texte d’une réponse ou un appel d’outil.
• Modèle : le modèle utilisé pour la réponse, lorsque cette information est enregistrée.

Outil

Un span d’outil décrit un appel d’outil et son résultat enregistré.

Les spans d’outils comprennent les appels à vos fonctions et aux outils des serveurs MCP (Model Context Protocol). Les recherches web et l’exécution de commandes peuvent également apparaître sous forme de spans d’outils.

• Appel : la requête adressée à l’outil, y compris son nom et les arguments, lorsqu’ils sont présents.
• Résultat : la réponse enregistrée de l’outil, lorsqu’elle est disponible.
• Statut d’exécution et Erreur : l’issue enregistrée de l’exécution et les détails de l’erreur, lorsqu’ils sont présents.

Pour un appel d’outil MCP, Appel contient le libellé du serveur (server_label), le nom de l’outil (name) et les arguments (arguments). La réponse et l’erreur y sont enregistrées sous les clés output et error, lorsqu’elles sont disponibles. Le panneau distinct Résultat peut être vide, car la réponse MCP est stockée dans Appel.

Durées et statuts

La chronologie montre l’ordre des étapes et celles qui se chevauchent. Zoom avant permet de voir les étapes courtes plus en détail. Ajuster la chronologie permet d’afficher l’ensemble de la session.

Chaque span affiche sa durée et son statut d’exécution. Les spans en échec peuvent également inclure les détails enregistrés de l’erreur.

La durée d’un span d’agent inclut ses étapes enfants. Les étapes peuvent se chevaucher : deux sous-agents qui s’exécutent simultanément pendant 10 secondes représentent environ 10 secondes de temps écoulé.

Consommation de tokens

Le champ Tokens du résumé de la session indique la consommation de la session. Le panneau Consommation d’un span d’agent indique les nombres de tokens enregistrés pour cet agent.

Les données de consommation peuvent arriver après la fin du tour. Une valeur vide ou null signifie que le décompte est inconnu. Cela ne signifie pas que l’agent n’a utilisé aucun token. Les décomptes peuvent évoluer à mesure que de nouvelles données de consommation deviennent disponibles et ne constituent pas une facture définitive.

Disponibilité des traces

Les traces sont construites après la fin d’un tour. La réponse de l’agent peut apparaître avant que sa trace ou ses données de consommation de tokens soient disponibles.

Les événements de session en direct permettent de suivre la progression pendant que l’agent travaille encore.

Exportez les traces de session

Téléchargez les traces de session pour les examiner dans un autre outil de traçage. Le point de terminaison GET /v1/agents/sessions/{session_id}/traces renvoie une page de traces contenant des données JSON au format OpenTelemetry Protocol (OTLP).

Définissez OPENAI_API_KEY et remplacez sess_123 par l’ID de votre session. Cet exemple utilise cURL et jq pour enregistrer une page dans le fichier traces.otlp.json :

1
2
3
4
5
6curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions/sess_123/traces?limit=20&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  --output trace-page.json && \
jq '{resourceSpans: [.data[].otlp.resourceSpans[]]}' trace-page.json > traces.otlp.json

La commande regroupe les traces de cette page dans une seule charge utile OTLP. Envoyez-la au point de terminaison OTLP/HTTP de votre fournisseur de traçage en utilisant son mécanisme d’authentification.

Pour exporter toute la session, consultez trace-page.json. Lorsque has_more vaut true, demandez la page suivante en utilisant last_id comme valeur de after, tout en conservant la même valeur pour order. Enregistrez ou téléversez chaque page avant de récupérer la suivante, et répétez l’opération jusqu’à ce que has_more vaille false.

Les exportations incluent uniquement les traces disponibles au moment de chaque requête. Pour exporter l’historique, attendez que les tours de la session se terminent et laissez le temps aux traces d’apparaître. L’exportation ne met pas en place l’envoi automatique des traces futures.

Exportez les traces d’un agent

Pour exporter les traces des différentes sessions d’un agent, commencez par lister les sessions avec le filtre agent_id. Remplacez agent_123 par l’ID de votre agent :

1
2
3
4curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions?agent_id=agent_123&limit=100&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

1. Pour chaque session dans data, utilisez son id pour exporter toutes les pages de traces de cette session, comme décrit ci-dessus.
2. Lorsque la liste des sessions indique has_more: true, transmettez le last_id de cette liste comme valeur de after pour récupérer la page suivante. Conservez les mêmes valeurs pour agent_id et order.
3. Répétez l’opération jusqu’à ce que la liste des sessions indique has_more: false.

Le filtre porte sur l’agent racine de la session. Gérez séparément le curseur de la liste des sessions et le curseur des traces de chaque session.

Exemple : un tour avec deux sous-agents

Cet exemple s’appuie sur une session enregistrée. L’agent racine appelle un outil MCP pendant que deux sous-agents exécutent une commande et récupèrent des documents. Les noms des sous-agents sont simplifiés ci-dessous ; les décomptes et les durées proviennent de la trace enregistrée.

Session et tour

L’en-tête de la session affiche 1 tour, 10 appels d’outils et 252 468 tokens. Le statut de la session est Inactive, et le Tour 1 est Terminé, avec une durée de 1m 37s.

Développez le tour pour afficher l’agent racine et ses étapes enfants. La trace contient 3 spans d’agents (l’agent racine et deux sous-agents), 11 spans de génération et 10 spans d’outils.

Cette arborescence regroupe les générations et les appels d’outils répétés. Elle montre les relations parent-enfant ; la chronologie indique quand chaque étape s’est exécutée.

Session: Idle
└── Turn 1: Completed                              1m 37s
    └── Root agent                                1m 37s
        ├── 6 generations
        ├── 2 tools: spawn_agent_call
        ├── Subagent A                               24s
        │   ├── 2 generations
        │   └── Tool: command_execution               2s
        ├── Subagent B                               21s
        │   ├── 3 generations
        │   ├── 2 tools: notion.fetch              2s each
        │   └── Tool: send_input_call                 0ms
        ├── Tool: demo_capability_probe              87ms
        └── 3 tools: wait_for_agents_call

Travail du modèle et délégation

La première Génération de l’agent racine inclut le message de l’utilisateur dans Entrée. Sa Sortie contient des messages et deux éléments spawn_agent_call. Ces appels apparaissent également sous forme de spans Outil, et les sous-agents ainsi créés apparaissent sous forme de spans Agent rattachés à l’agent racine.

Le sous-agent A possède ses propres générations et un appel d’outil command_execution. Le sous-agent B possède trois générations, deux appels MCP notion.fetch et un appel send_input_call. Leurs réponses de modèle et leurs outils sont rattachés aux spans respectifs de ces sous-agents.

L’agent racine possède également trois spans d’outil wait_for_agents_call. Sa dernière génération contient un message et sa durée enregistrée est de 6 s.

Un appel d’outil MCP

Le span demo_capability_probe de l’agent racine est un span Outil terminé, d’une durée de 87 ms. Son Type d’outil est mcp_call.

Le panneau Appel contient les champs suivants :

123456{
  "type": "mcp_call",
  "server_label": "demo_local",
  "name": "demo_capability_probe",
  "status": "completed"
}

Cet extrait montre une partie de l’appel enregistré. Le même panneau contient ses arguments et la réponse MCP dans output. Le panneau distinct Résultat affiche null. Le champ Span parent du span pointe vers l’agent racine.

Les deux spans notion.fetch du sous-agent B ont la même structure : mcp_call comme type d’outil, la réponse MCP dans Appel et le sous-agent comme parent.

Durées et utilisation dans cette session

Les spans des deux sous-agents se chevauchent dans la chronologie. Le sous-agent A prend 24 s et le sous-agent B 21 s, tous deux au cours du span de 1 min 37 s de l’agent racine. Le tableau de bord arrondit les durées affichées.

Le panneau Consommation de chaque span d’agent affiche les nombres de tokens enregistrés pour cet agent :

Dans cette session enregistrée, la somme des totaux des trois agents correspond aux 252 468 tokens affichés dans l’en-tête de la session.