Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Tracciamento e osservabilità

Lezione 14 di 25 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Tracciamento e osservabilità
  2. Tracciamento integrato
  3. Dare un nome alle tracce
  4. Suddividere un flusso di lavoro in passaggi
  5. Processori di traccia personalizzati
  6. Esportazione verso sistemi esterni
  7. Non perdere le ultime tracce
  8. Disabilitare il tracciamento
  9. Metriche chiave da monitorare
  10. Punti chiave

Aggiornato il 3 novembre 2026. In precedenza, i processori di traccia leggevano trace.start_time, trace.end_time e span.name, attributi che non esistono nell’SDK: una traccia non ha timestamp, mentre uno span contiene started_at, ended_at e span_data. Il processore di esportazione non implementava on_trace_start, un metodo astratto: la sua istanziazione generava un TypeError. Le “tracce annidate” creavano una nuova traccia all’interno di un’altra, situazione che l’SDK segnala come probabile errore: ora i passaggi utilizzano custom_span(). Novità: flush_traces(), gestione dei dati sensibili e Zero Data Retention. Codice verificato con openai-agents 0.24.0. Fonti: Tracing (documentazione SDK) · openai-agents-python.

Tracciamento e osservabilità

Un agente in produzione è una scatola nera se non ne tracci le azioni. Quando un cliente si lamenta di una risposta assurda, non hai né la richiesta esatta, né gli strumenti chiamati, né i valori restituiti. Il tracciamento dell’SDK registra ogni passo dell’esecuzione: chiamate al modello, strumenti utilizzati, passaggi di consegne (handoffs) e guardrail. Questo è il tuo strumento principale per il debug, l’ottimizzazione e l’audit dei tuoi agenti.

Tracciamento integrato

Buone notizie: non devi abilitare nulla. L’SDK traccia automaticamente ogni esecuzione e, per impostazione predefinita, invia le tracce alla dashboard OpenAI all’indirizzo platform.openai.com. L’agente seguente, scritto senza una singola istruzione di tracciamento, produce già una traccia utilizzabile.

from agents import Agent, Runner, function_tool

@function_tool
def search_product(name: str) -> str:
    """Cerca un prodotto nel catalogo."""
    return f"Prodotto trovato: {name}, prezzo €29,99"

agent = Agent(
    name="Agente Shop",
    instructions="Aiuti i clienti a trovare prodotti.",
    tools=[search_product],
    model="gpt-5.6-terra",
)

# Ogni esecuzione crea automaticamente una traccia
result = Runner.run_sync(agent, "Cerca il laptop pro")

Visita la dashboard per vedere la traccia completa: durata, token consumati, strumenti chiamati e la risposta finale.

Dare un nome alle tracce

Dopo alcune centinaia di esecuzioni, la dashboard diventa un elenco indifferenziato. Assegna alle tue tracce nomi significativi per trovarle facilmente: un nome legato al percorso di business è meglio di un ID tecnico.

from agents import trace

with trace("ordine-cliente-premium"):
    result = await Runner.run(
        agent,
        "Voglio ordinare 5 laptop per il mio team",
    )

Il nome della traccia appare nella dashboard e semplifica il filtraggio.

Suddividere un flusso di lavoro in passaggi

Per un flusso di lavoro con più chiamate, apri una traccia attorno all’intero processo, quindi marca ogni passaggio con custom_span(). Non annidare una trace() dentro un’altra: l’SDK registrerebbe l’avviso Trace already exists. Creating a new trace, but this is probably a mistake. Gli span, invece, sono progettati per essere annidati: ognuno si posiziona sotto lo span corrente.

from agents import Runner, custom_span, trace


async def process_order(message: str, conversation_id: str):
    with trace("flusso-ordine", group_id=conversation_id):
        with custom_span("passo-1-comprensione"):
            result_understanding = await Runner.run(triage_agent, message)

        with custom_span("passo-2-elaborazione"):
            result_processing = await Runner.run(
                order_agent,
                result_understanding.to_input_list(),
            )

        with custom_span("passo-3-conferma", data={"step": 3}):
            result_final = await Runner.run(
                confirmation_agent,
                result_processing.to_input_list(),
            )

    return result_final.final_output

Nella dashboard, la traccia flusso-ordine mostra i tre passaggi e, sotto ciascuno, gli span automatici di esecuzione: agente, chiamate al modello, strumenti. Il group_id collega le tracce della stessa conversazione, ad esempio utilizzando il tuo ID thread.

Per impostazione predefinita, l’SDK avvolge ogni Runner.run() in una traccia denominata Agent workflow e, all’interno delle tracce, include l’agente, ogni generazione del modello, ogni chiamata di funzione, i guardrail e i passaggi di consegna. Per una gerarchia più compatta, la documentazione suggerisce di tagliare gli span automatici di attività e turno:

from agents import RunConfig

result = await Runner.run(
    agent,
    "Ciao",
    run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)

Processori di traccia personalizzati

La dashboard OpenAI è comoda, ma il tuo team operativo probabilmente monitora tutto il resto altrove. Per inviare le tracce al tuo sistema, scrivi un processore: riceve eventi di inizio e fine, sia per la traccia completa che per ogni span. Tutti e sei i metodi di TracingProcessor sono astratti: devi implementarli tutti, anche se vuoti, altrimenti l’istanziazione fallirà.

Ecco cosa espone effettivamente ogni oggetto: una traccia ha un trace_id e un name, e il suo metodo export() restituisce anche group_id e metadata; non ha timestamp. Uno span ha span_id, trace_id, parent_id, started_at ed ended_at (stringhe ISO 8601) e span_data, il cui attributo type può essere agent, generation, function, handoff, guardrail, custom e così via. La durata della traccia viene quindi calcolata nel processore.

import time
from datetime import datetime
from typing import Any

from agents import add_trace_processor
from agents.tracing import Span, Trace, TracingProcessor


class MyTraceProcessor(TracingProcessor):
    def __init__(self) -> None:
        self._starts: dict[str, float] = {}

    def on_trace_start(self, trace: Trace) -> None:
        self._starts[trace.trace_id] = time.monotonic()
        print(f"[INIZIO TRACCIA] {trace.name} - {trace.trace_id}")

    def on_trace_end(self, trace: Trace) -> None:
        duration = time.monotonic() - self._starts.pop(trace.trace_id, time.monotonic())
        print(f"[FINE TRACCIA] {trace.name} - durata: {duration:.2f} s")

    def on_span_start(self, span: Span[Any]) -> None:
        print(f"  [INIZIO SPAN] {span.span_data.type}")

    def on_span_end(self, span: Span[Any]) -> None:
        if span.started_at and span.ended_at:
            duration = datetime.fromisoformat(span.ended_at) - datetime.fromisoformat(span.started_at)
            print(f"  [FINE SPAN] {span.span_data.type} - {duration.total_seconds():.2f} s")

    def shutdown(self) -> None:
        pass

    def force_flush(self) -> None:
        pass


add_trace_processor(MyTraceProcessor())

add_trace_processor() aggiunge il tuo processore a quello originale: le tracce continuano ad andare alla dashboard OpenAI. set_trace_processors() sostituisce i processori predefiniti: nulla va più a OpenAI, a meno che tu non rimetta manualmente il suo esportatore nella lista.

Esportazione verso sistemi esterni

Per uno strumento di osservabilità, devi solo riformattare gli span. L’esempio seguente scrive una riga JSON per ogni span terminato, un formato che la maggior parte dei collettori di log sa ingerire; span.export() fornisce già un dizionario completo.

import json
import logging
from typing import Any

from agents.tracing import Span, Trace, TracingProcessor

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


class JsonExportProcessor(TracingProcessor):
    """Scrive ogni span terminato come JSON, per un collettore di log."""

    def on_trace_start(self, trace: Trace) -> None:
        pass

    def on_trace_end(self, trace: Trace) -> None:
        logger.info(json.dumps(trace.export(), default=str))

    def on_span_start(self, span: Span[Any]) -> None:
        pass

    def on_span_end(self, span: Span[Any]) -> None:
        logger.info(json.dumps(span.export(), default=str))

    def shutdown(self) -> None:
        pass

    def force_flush(self) -> None:
        pass

Fai attenzione a ciò che esporti: per impostazione predefinita, gli span di generazione contengono input e output del modello, e gli span di funzione contengono argomenti e risultati degli strumenti. Per escluderli, passa RunConfig(trace_include_sensitive_data=False) o imposta la variabile d’ambiente OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Per integrazioni già pronte, la documentazione dell’SDK elenca molti strumenti di terze parti che forniscono il proprio processore.

Non perdere le ultime tracce

L’esportatore predefinito invia le tracce in background, ogni pochi secondi. In un worker che elabora compiti senza fermarsi, o in uno script breve, chiama flush_traces() dopo aver chiuso la traccia per forzare l’invio:

from agents import flush_traces

with trace("elaborazione-notturna"):
    await Runner.run(agent, "Riassumi i ticket di oggi")
flush_traces()  # dopo la fine della traccia, mai nel mezzo

Disabilitare il tracciamento

C’è un caso in cui il tracciamento ostacola più di quanto aiuti: una suite di test che esegue centinaia di agenti mock e inquina la tua dashboard. Nei test o durante lo sviluppo locale, puoi quindi disabilitarlo, sia globalmente che per una singola esecuzione.

from agents import RunConfig, set_tracing_disabled

# Disabilita completamente (o variabile d'ambiente OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)

# Oppure per una singola esecuzione
result = await Runner.run(agent, "Messaggio di test", run_config=RunConfig(tracing_disabled=True))

Un ultimo punto, questo contrattuale: secondo la documentazione, il tracciamento verso OpenAI non è disponibile per le organizzazioni soggette a una politica di Zero Data Retention. In questo caso, solo il tuo processore personale, installato con set_trace_processors(), ti fornirà le tracce.

Metriche chiave da monitorare

Ora, cosa devi osservare? In produzione, sei indicatori sono sufficienti per qualificare la salute di un agente. La latenza totale—il tempo tra la richiesta e la risposta finale—è ciò che percepiscono i tuoi utenti; è spesso spiegata dal numero di turni, ovvero quante volte il ciclo dell’agente è stato eseguito. I token consumati, sia in input che in output per esecuzione, guidano la tua fatturazione.

Gli altri tre riguardano la qualità. Il tasso di fallimento degli strumenti, la percentuale di strumenti che restituiscono un errore, rivela un’API di terze parti instabile o argomenti generati male. Il tasso di attivazione dei guardrail, visibile negli span guardrail, misura la frequenza dei blocchi: un picco improvviso segnala o un attacco o un guardrail diventato troppo severo. Infine, la distribuzione dei passaggi di consegna ti dice quale agente risponde più spesso e quindi se il tuo triage sta inviando le richieste dove dovrebbero andare.

Punti chiave

  • L’SDK traccia automaticamente ogni esecuzione sulla dashboard OpenAI (tranne per le organizzazioni con Zero Data Retention)
  • Una trace() per flusso di lavoro; marca i passaggi con custom_span() e usa group_id per collegare le tracce di una conversazione
  • Una traccia non ha timestamp; uno span ha started_at, ended_at e span_data.type
  • Un TracingProcessor implementa i suoi sei metodi; add_trace_processor() aggiunge, set_trace_processors() sostituisce
  • trace_include_sensitive_data=False esclude input e output; flush_traces() forza l’invio
  • Disabilita il tracciamento nei test con set_tracing_disabled(True) o RunConfig(tracing_disabled=True)