Tracing et observabilité

Un agent en production est une boîte noire si vous ne tracez pas ses actions. Le tracing du SDK enregistre chaque étape de l’exécution : les appels au modèle, les tools utilisés, les handoffs, et les guardrails. C’est votre outil principal pour débugger, optimiser et auditer vos agents.

Tracing intégré au SDK

Le SDK trace automatiquement chaque exécution. Par défaut, les traces sont envoyées au dashboard OpenAI sur platform.openai.com :

from agents import Agent, Runner, function_tool

@function_tool
def rechercher_produit(nom: str) -> str:
    """Recherche un produit dans le catalogue."""
    return f"Produit trouvé : {nom}, prix 29.99€"

agent = Agent(
    name="Agent boutique",
    instructions="Vous aidez les clients à trouver des produits.",
    tools=[rechercher_produit],
    model="gpt-5.3",
)

# Chaque exécution crée automatiquement une trace
result = Runner.run_sync(agent, "Cherchez le laptop pro")

Rendez-vous sur le dashboard pour voir la trace complète : durée, tokens consommés, tools appelés, et réponse finale.

Nommer les traces

Donnez des noms significatifs à vos traces pour les retrouver facilement :

from agents import trace

with trace("commande-client-premium"):
    result = await Runner.run(
        agent,
        "Je veux commander 5 laptops pour mon équipe",
    )

Le nom de la trace apparaît dans le dashboard et facilite le filtrage.

Traces imbriquées

Pour les workflows complexes, imbriquez les traces :

from agents import trace, Runner

async def traiter_commande(message: str):
    with trace("workflow-commande"):
        # Étape 1 : Comprendre la demande
        with trace("etape-1-comprehension"):
            result_comprehension = await Runner.run(agent_triage, message)

        # Étape 2 : Traiter la commande
        with trace("etape-2-traitement"):
            result_traitement = await Runner.run(
                agent_commande,
                result_comprehension.to_input_list(),
            )

        # Étape 3 : Confirmer
        with trace("etape-3-confirmation"):
            result_final = await Runner.run(
                agent_confirmation,
                result_traitement.to_input_list(),
            )

    return result_final.final_output

Dans le dashboard, vous verrez la trace parent avec trois sous-traces, chacune avec ses propres métriques.

Custom trace processors

Pour envoyer les traces vers votre propre système d’observabilité :

from agents.tracing import TracingProcessor, Span

class MonProcesseurDeTraces(TracingProcessor):
    def on_trace_start(self, trace):
        print(f"[TRACE START] {trace.name} - {trace.trace_id}")

    def on_trace_end(self, trace):
        duree = trace.end_time - trace.start_time
        print(f"[TRACE END] {trace.name} - durée: {duree:.2f}s")

    def on_span_start(self, span: Span):
        print(f"  [SPAN START] {span.name}")

    def on_span_end(self, span: Span):
        print(f"  [SPAN END] {span.name}")

    def shutdown(self):
        pass

    def force_flush(self):
        pass

# Enregistrer le processeur
from agents.tracing import add_trace_processor
add_trace_processor(MonProcesseurDeTraces())

Exporter vers des systèmes externes

Voici comment intégrer avec des outils d’observabilité courants :

import json
import logging
from agents.tracing import TracingProcessor

logger = logging.getLogger("agent-traces")

class DatadogTraceProcessor(TracingProcessor):
    """Envoie les traces vers Datadog APM."""

    def on_trace_end(self, trace):
        # Format compatible Datadog
        span_data = {
            "trace_id": trace.trace_id,
            "name": trace.name,
            "service": "agent-openai",
            "duration_ms": (trace.end_time - trace.start_time) * 1000,
        }
        logger.info(json.dumps(span_data))
        # En production : envoi via ddtrace

    def on_span_start(self, span):
        pass

    def on_span_end(self, span):
        pass

    def shutdown(self):
        pass

    def force_flush(self):
        pass

Désactiver le tracing

Dans les tests ou en développement local, vous pouvez désactiver le tracing :

from agents.tracing import set_tracing_disabled

# Désactiver complètement
set_tracing_disabled(True)

# Ou par exécution
with trace("test", disabled=True):
    result = await Runner.run(agent, "Message de test")

Métriques clés à surveiller

En production, surveillez ces métriques dans vos traces :

Latence totale : temps entre la requête et la réponse finale
Nombre de tours : combien de fois la boucle agent s’est exécutée
Tokens consommés : input + output tokens par exécution
Taux d’échec des tools : pourcentage de tools qui retournent une erreur
Taux de déclenchement des guardrails : fréquence des blocages
Distribution des handoffs : quel agent répond le plus souvent

Points clés à retenir

Le SDK trace automatiquement chaque exécution vers le dashboard OpenAI
Utilisez with trace("nom") pour nommer et imbriquer vos traces
Les custom TracingProcessor permettent d’exporter vers Datadog, Grafana, etc.
Surveillez la latence, les tokens, le taux d’erreur des tools et les guardrails
Désactivez le tracing dans les tests avec set_tracing_disabled(True)