Traçage

Une session regroupe la conversation et le travail de votre agent. Elle peut comporter plusieurs tours, chacun correspondant à un cycle de travail. Une trace détaille 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 présente les actions de votre agent et les données enregistrées pour chaque étape : entrées, sorties, durée et statut.

Pour consulter le statut d’une session, les événements en direct, les sorties enregistrées et les données d’utilisation via l’API, consultez d’abord le guide 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.

Ouvrir 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 les sessions par modèle, statut ou date.
3. Sélectionnez la session pour afficher sa chronologie et la liste de ses tours.
4. Dépliez un tour, puis sélectionnez une étape dans la chronologie ou la liste des événements pour en consulter les détails.

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

Lire une trace

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

1. Session : chaque entrée de Journaux → Agents correspond à une session. Ouvrez-la pour afficher sa chronologie et la liste de ses tours. Par exemple, un utilisateur peut poser une question sur une commande, puis demander une précision dans la même session.
2. Tour : dépliez un tour pour examiner le travail effectué pendant ce cycle. Un tour peut comprendre plusieurs réponses du modèle et appels d’outils. Un nouveau message envoyé après la fin du tour lance un autre 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 en est à l’origine. Chaque étape enregistrée est appelée span.

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

Agent

Un span d’agent regroupe le travail effectué par l’agent racine ou par un sous-agent, c’est-à-dire un autre agent chargé d’une partie de la tâche. Les réponses du modèle et les appels d’outils figurent sous l’agent qui en est à l’origine.

Le panneau de détails affiche les informations suivantes :

• Type d’agent : agent racine (root) ou sous-agent (subagent).
• Agent : son identifiant, son nom, son modèle et ses instructions, lorsque ces informations ont été enregistrées.
• Utilisation : le nombre de tokens enregistré pour cet agent. Ce décompte exclut les tokens de ses sous-agents.
• Durée et Statut d’exécution : le temps consacré au travail enregistré et son issue (terminé, en échec ou incomplet).

Génération

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

Lors de l’inférence, le modèle lit les données d’entrée et produit une réponse. Cette réponse peut demander l’appel d’un outil. Une fois le résultat de l’outil reçu, le modèle peut produire une autre réponse lors d’une nouvelle génération.

• Entrée : les entrées enregistrées pour cette réponse, par exemple un message de l’utilisateur ou le résultat d’un outil.
• Sortie : les éléments produits par le modèle et enregistrés, par exemple le texte d’une réponse ou un appel d’outil.
• Modèle : le modèle utilisé pour la réponse, si cette information a été enregistrée.

Outil

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

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

• Appel : la requête adressée à l’outil, avec son nom et les arguments, s’ils sont présents.
• Résultat : la réponse enregistrée de l’outil, si elle est disponible.
• Statut d’exécution et Erreur : l’issue de l’appel et les détails de l’erreur, si ces informations ont été enregistrées.

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 dans output et error lorsqu’elles sont disponibles. Le panneau Résultat peut être vide, car la réponse MCP est stockée dans Appel.

Chronologie et statut

La chronologie indique l’ordre des étapes et permet de repérer celles qui se chevauchent. Zoom avant permet d’examiner les étapes les plus courtes en détail. Ajuster la chronologie affiche la session entière.

Chaque span indique sa durée et son statut d’exécution. Les spans en échec peuvent aussi contenir les détails de l’erreur enregistrée.

La durée d’un span d’agent englobe ses étapes enfants. Certaines étapes peuvent se chevaucher : si deux sous-agents s’exécutent simultanément pendant 10 secondes, le temps écoulé est d’environ 10 secondes.

Consommation de tokens

Dans le résumé de la session, Tokens indique la consommation de la session. Dans un span d’agent, Utilisation indique le nombre de tokens enregistré pour cet agent.

Les données d’utilisation peuvent arriver après la fin du tour. Une valeur vide ou null signifie que le nombre de tokens est inconnu. Elle ne signifie pas que l’agent a consommé zéro token. Les décomptes peuvent évoluer à mesure que de nouvelles données arrivent et ne constituent pas une facture définitive.

Disponibilité des traces

Les traces sont produites après la fin du tour. La réponse de l’agent peut s’afficher avant que sa trace ou ses données de consommation de tokens soient disponibles.

Les événements de session en direct indiquent la progression de l’agent pendant qu’il travaille.

Exporter les traces d’une session

Téléchargez les traces d’une 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’identifiant de votre session. Cet exemple utilise cURL et jq pour enregistrer une page dans 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. Si has_more vaut true, demandez la page suivante en passant la valeur de last_id dans after et en conservant la même valeur pour order. Enregistrez ou téléversez chaque page avant de récupérer la suivante. Répétez l’opération jusqu’à ce que has_more vaille false.

Chaque requête exporte uniquement les traces disponibles au moment de l’appel. Pour exporter l’historique, attendez que les tours de la session se terminent et que les traces apparaissent. L’exportation n’active pas l’envoi automatique des traces futures.

Exporter 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’identifiant 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 ses pages de traces comme indiqué ci-dessus.
2. Si la liste des sessions contient has_more: true, passez la valeur de last_id de cette liste dans 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 contienne has_more: false.

Le filtre porte sur l’agent racine de la session. Utilisez des curseurs distincts pour la liste des sessions et pour les 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 qu’un sous-agent exécute une commande et qu’un autre récupère des documents. Les noms des sous-agents ont été 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 indique 1 tour, 10 appels d’outils et 252 468 tokens. Le statut de la session est Inactive. Le Tour 1 a le statut Terminé et a duré 1 min 37 s.

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

L’arborescence ci-dessous regroupe les générations et les appels d’outils répétés. Elle indique le parent de chaque étape. La chronologie précise quand chaque étape s’est déroulé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

Réponses du modèle et délégation

Dans la première Génération de l’agent racine, le champ Entrée contient le message de l’utilisateur. Le champ Sortie contient des messages et deux éléments spawn_agent_call. Ces appels apparaissent aussi sous forme de spans de type Outil, et les sous-agents ainsi créés apparaissent sous forme de spans de type Agent sous l’agent racine.

Le sous-agent A a ses propres générations et un appel à l’outil command_execution. Le sous-agent B compte trois générations, deux appels MCP à notion.fetch et un appel à send_input_call. Les réponses du modèle et les appels d’outils figurent dans le span de leur sous-agent respectif.

L’agent racine compte é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.

Exemple d’appel d’outil MCP

Le span demo_capability_probe de l’agent racine est un span de type Outil dont l’exécution s’est terminée en 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 présente une partie de l’appel enregistré. Le même panneau contient ses arguments et la réponse MCP dans output. Le panneau Résultat affiche null. Le champ Span parent pointe vers l’agent racine.

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

Durées et consommation de tokens dans cette session

Les spans des deux sous-agents se chevauchent sur la chronologie. Le sous-agent A travaille pendant 24 s et le sous-agent B pendant 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.

Pour chaque span d’agent, le panneau Utilisation indique 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.