Traçages d’agent

À propos des traçages

Traces are detailed records of everything an agent does during a run, including steps taken, data processed, decisions made, and results generated. Each trace captures a complete timeline of the agent’s behavior, including timestamps, errors, inputs/outputs, and contextual metadata. Use traces for:

• Débogage et dépannage : identifier exactement où un agent a échoué ou s'est comporté de manière inattendue.
• Analyse des performances : évaluer la latence, les erreurs et le flux des exécutions d'agents pour optimiser le comportement.
• Conformité et audit : maintenir un enregistrement vérifiable de ce que l'agent a fait, quand et comment, essentiel dans le cadre des audits ou des workflows réglementés.
• Amélioration continue : utiliser les éclairages qu'apportent les traçages pour affiner la logique de l'agent, adapter le comportement ou former de nouveaux modèles.

Le tableau suivant décrit les cas d'utilisation courants dans lesquels la visualisation du traçage peut améliorer votre capacité à déboguer, analyser et optimiser le comportement des agents. Chaque exemple met en évidence comment les données de traçage contribuent à obtenir des éclairages et à prendre de meilleures décisions lors du développement et de la surveillance de l'exécution.

Use case	Ce que les traçages vous aident à faire
L'agent échoue lors d'un appel d'outil	Trouver et inspecter l'étape exacte, les entrées, les sorties et les erreurs
Les performances sont médiocres	Utiliser des horodatages pour localiser les goulots d'étranglement
Enquêter sur un pic d'erreurs	Filtrer les exécutions par statut et tracer la tendance
Vérifier un correctif de production	Rejouer l'exécution initiale et confirmer que le problème ne se produit plus
Préparer un rapport d'audit	Exporter ou examiner les traçages qui montrent les chemins de décision et les données traitées

Types de traçages

Les traçages se présentent sous deux types distincts, chacun servant à comprendre et analyser le comportement de l'agent :

• Traçages de fonctionnement de l'agent : ces traçages capturent l'exécution étape par étape d'un agent pendant une exécution active ou programmée. Ils montrent comment l'agent a traité les données, invoqué les outils, géré les conditions et répondu à différents états en temps réel.
• Traçages de test d'évaluation : des traçages d'évaluation sont générés lorsqu'un agent est testé avec des entrées prédéfinies, généralement pendant l'évaluation de modèles, la validation de scénarios ou les scénarios de test. Ces derniers permettent d'évaluer la précision de l'agent, la qualité des décisions et le comportement dans des conditions contrôlées.

Accéder aux traçages

Vous pouvez accéder aux deux types de traçages à partir de deux emplacements clés :

• Agent Builder – Lors de la conception ou du test de votre agent, les traçages sont disponibles directement dans le générateur :
  • Le panneau inférieur s'ouvre automatiquement sur l'onglet Chemin d'exécution lorsque vous exécutez votre agent, affichant les traçages en temps réel de l'exécution actuelle. Vous pouvez également basculer vers l'onglet Historique pour afficher les exécutions passées et les ajouter directement aux ensembles d'évaluation.
  • Les onglets Évaluations et Sortie offrent une autre vue sur les exécutions récentes, où vous pouvez examiner le comportement et les résultats en parallèle de la définition de votre agent.
• Page Instances d'agent : accédez à la section Agents > Instances . À partir de là, sélectionnez un agent spécifique et sélectionnez n'importe quelle exécution afin d'ouvrir sa vue de traçage, qui comprend le panneau de traçage visuel complet et du journal.

Lorsque vous consultez les traçages des exécutions d'agents ou des exécutions d'évaluation, vous obtenez une meilleure visibilité sur l'exécution de l'agent. Vous pouvez :

• Voir les résultats de l'exécution, comme indiqué avec des nœuds codés par couleur : réussite, échec ou réessai.
• Placez la souris sur n'importe quel nœud pour afficher un aperçu : horodatages de début et de fin, statut d'exécution, extraits d'entrée et de sortie.
• Sélectionnez un nœud pour afficher les détails, notamment : les charges utiles JSON complètes, les journaux et les erreurs, les mesures de runtime (consommation de jetons, latence).

Gestion de l’accès aux données de traçage

Cette section explique comment les administrateurs peuvent configurer l’accès aux données de traçage à l’aide du modèle de contrôle d’accès basé sur les rôles.

Pour afficher les journaux de traçage, vous avez besoin des autorisations suivantes :

• Logs.View
• Jobs.View

Pour plus d’informations sur les autorisations des rôles par défaut, consultez la section Rôles par défaut.

La matrice suivante explique les résultats de visibilité en fonction des combinaisons d’autorisations. Ces combinaisons définissent les informations de traçage que vous pouvez afficher en fonction de vos autorisations basées sur vos rôles.

Logs.View	Jobs.View	Accès aux résultats
Activer (Enable)	Activer (Enable)	Tous les attributs
Activer (Enable)	Désactiver (Disable)	Tous les attributs
Désactiver (Disable)	Activer (Enable)	Attributs partiels (par ex., nom, type)
Désactiver (Disable)	Désactiver (Disable)	Aucun accès

Lorsque vous ne disposez pas des autorisations nécessaires pour afficher les données de traçage, un message s’affiche pour indiquer si l’accès est totalement ou partiellement limité et comment demander l’autorisation requise.

Feedback on agent runs (Preview)

Feedback is a critical mechanism for interpreting and improving agent runtimes. It enables you to review behavior, diagnose issues, and document meaningful patterns in how an agent makes decisions.

Beyond debugging, feedback acts as the core input to feedback-based episodic memory, allowing the agent to refine its decision policy gradually—without requiring full prompt rewrites for every adjustment.

The relationship between feedback and memory

While feedback acts as an annotation tool, its most powerful application is influencing episodic memory.

Providing feedback on a trace highlights behaviors the agent should replicate or avoid in future runs.

• Evolution over repetition: Unlike static resolutions, feedback-based memory allows the agent's behavior to improve over time. The agent learns to recognize patterns flagged as correct or incorrect.
• Targeted improvement: This approach is most valuable in flows where the agent is frequently "almost right" or where the decision policy is still developing.
• Selective memory: Not all feedback automatically becomes memory. You must actively determine which annotations represent high-value learning opportunities, to prevent low-quality or inconsistent feedback from degrading performance.

Where to apply feedback

You can provide feedback on any span within an agent trace. This flexibility allows you to annotate specific tool calls, guardrail checks, or LLM outputs when reviewing or diagnosing behavior.

Only feedback applied to the agent run span is eligible for episodic memory. While you may annotate any part of the trace for analysis, only feedback attached directly to the agent run span will be stored and retrieved as memory in future runs.

When to apply feedback

While providing feedback on all traces would maximize iterative learning, in practice you should concentrate on traces that offer the highest value for optimization.

Focus on the following scenarios:

• Critical scenarios: Traces involving high-stakes decisions or high-impact errors.
• Recurring patterns: Areas where the agent consistently struggles or exhibits repetitive faults.
• Difficult decisions: Instances where the agent faced a complex choice.
• Negative sentiment: Runs that resulted in a poor user experience.
• Model behavior: Examples that clearly illustrate a specific behavior you want the agent to strictly copy or strictly avoid.

Applying feedback is crucial for continuous improvement. It allows you to encode better behaviors incrementally, making agent runs more reliable and consistent.

• Prioritize traces: Focus on traces from critical scenarios, high-impact errors, or recurring patterns where the agent struggles.
• High-value scenarios: Prioritize runs that represent difficult decisions for the agent, show negative user sentiment, or clearly illustrate a behavior you want the agent to copy or avoid.
• Focus areas: Clearly identify what you are providing feedback on:
  • Output: Did the final result meet expectations?
  • Plan execution (trajectory): Did the agent perform the task steps in the expected order?
  • Comments: Use comments to enrich the feedback and inform memory retrieval.