Urmărire și observabilitate
Pe această pagină
Actualizat la 3 noiembrie 2026. Procesoarele de urmărire citeau anterior
trace.start_time,trace.end_timeșispan.name, care nu există în SDK: o urmă nu are timestamp, iar un span conținestarted_at,ended_atșispan_data. Procesorul de export nu implementa metoda abstractăon_trace_start: instanțierea sa genera o eroareTypeError. „Urile imbricate“ creau o nouă urmă în interiorul unei urme, lucru pe care SDK îl semnalează ca o eroare probabilă: pașii folosesc acumcustom_span(). Noutăți:flush_traces(), gestionarea datelor sensibile și Zero Data Retention. Cod verificat cuopenai-agents0.24.0. Surse: Tracing (documentație SDK) · openai-agents-python.
Urmărire și observabilitate
Un agent în producție este o cutie neagră dacă nu îi urmăriți acțiunile. Când un client se plânge de un răspuns absurd, nu aveți nici cererea exactă, nici instrumentele apelate, nici valorile returnate de acestea. Urmărirea din SDK înregistrează fiecare pas al execuției: apelurile modelului, instrumentele utilizate, transferurile între agenți și barierele de securitate. Aceasta este unealta dumneavoastră principală pentru depanare, optimizare și auditarea agenților.
Urmărire integrată
Vestea bună: nu trebuie să activați nimic. SDK urmărește automat fiecare execuție și, implicit, trimite urmele către panoul de control OpenAI de la platform.openai.com. Agentul de mai jos, scris fără o singură instrucțiune de urmărire, produce deja o urmă utilizabilă.
from agents import Agent, Runner, function_tool
@function_tool
def search_product(name: str) -> str:
"""Caută un produs în catalog."""
return f"Produs găsit: {name}, preț 29,99 €"
agent = Agent(
name="Agent Magazin",
instructions="Ajuți clienții să găsească produse.",
tools=[search_product],
model="gpt-5.6-terra",
)
# Fiecare execuție creează automat o urmă
result = Runner.run_sync(agent, "Caută laptopul pro")
Accesați panoul de control pentru a vedea urma completă: durata, tokenii consumați, instrumentele apelate și răspunsul final.
Denumirea urmelor
După câteva sute de execuții, panoul de control devine o listă nediferențiată. Dați urmelor dumneavoastră nume semnificative pentru a le găsi ușor; un nume de parcurs comercial este mai bun decât un ID tehnic.
from agents import trace
with trace("comanda-client-premium"):
result = await Runner.run(
agent,
"Doresc să comand 5 laptopuri pentru echipa mea",
)
Numele urmei apare în panoul de control și facilitează filtrarea.
Divizarea unui flux de lucru în pași
Pentru un flux de lucru cu mai multe apeluri, deschideți o singură urmă în jurul întregului proces, apoi marcați fiecare pas cu custom_span(). Nu imbricați un trace() în interiorul altuia: SDK va loga apoi avertismentul Trace already exists. Creating a new trace, but this is probably a mistake. Span-urile, însă, sunt concepute pentru a fi imbricate: fiecare se situează sub span-ul curent.
from agents import Runner, custom_span, trace
async def process_order(message: str, conversation_id: str):
with trace("flux-comanda", group_id=conversation_id):
with custom_span("pas-1-intelegere"):
result_understanding = await Runner.run(triage_agent, message)
with custom_span("pas-2-procesare"):
result_processing = await Runner.run(
order_agent,
result_understanding.to_input_list(),
)
with custom_span("pas-3-confirmare", data={"step": 3}):
result_final = await Runner.run(
confirmation_agent,
result_processing.to_input_list(),
)
return result_final.final_output
În panoul de control, urma flux-comanda afișează cei trei pași, iar sub fiecare, span-urile automate de execuție: agent, apeluri model, instrumente. group_id leagă urmele din aceeași conversație, folosind de exemplu ID-ul firului de discuție.
Implicit, SDK înfășoară fiecare Runner.run() într-o urmă numită Agent workflow, iar în interiorul urmelor se regăsesc agentul, fiecare generare de model, fiecare apel de funcție, barierele de securitate și transferurile. Pentru o ierarhie mai compactă, documentația sugerează eliminarea span-urilor automate de sarcină și de tur:
from agents import RunConfig
result = await Runner.run(
agent,
"Salut",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Procesoare personalizate de urmărire
Panoul de control OpenAI este convenabil, dar echipa dumneavoastră de operațiuni monitorizează probabil totul în altă parte. Pentru a trimite urme către propriul sistem, scrieți un procesor: acesta primește evenimente de start și de end, atât pentru urma completă, cât și pentru fiecare span. Toate cele șase metode ale TracingProcessor sunt abstracte: implementați-le pe toate, chiar și goale, altfel instanțierea va eșua.
Iată ce expune fiecare obiect în realitate: o urmă are un trace_id și un name, iar metoda sa export() returnează de asemenea group_id și metadata; nu are niciun timestamp. Un span are span_id, trace_id, parent_id, started_at și ended_at (șiruri ISO 8601) și span_data, al cărui atribut type este agent, generation, function, handoff, guardrail, custom și așa mai departe. Durata urmei este therefore măsurată în procesor.
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"[START URMĂ] {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"[SFÂRȘIT URMĂ] {trace.name} - durată: {duration:.2f} s")
def on_span_start(self, span: Span[Any]) -> None:
print(f" [START 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" [SFÂRȘIT 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() adaugă procesorul dumneavoastră la cel original: urmele continuă să meargă către panoul de control OpenAI. set_trace_processors() înlocuiește procesoarele implicite: nimic nu mai merge către OpenAI, decât dacă reintroduceți manual exportorul său în listă.
Exportul către sisteme externe
Pentru un instrument de observabilitate, trebuie doar să reformatați span-urile. Exemplul de mai jos scrie o linie JSON per span finalizat, un format pe care majoritatea colectoarelor de jurnale știu să îl ingereze; span.export() oferă deja un dicționar complet.
import json
import logging
from typing import Any
from agents.tracing import Span, Trace, TracingProcessor
logger = logging.getLogger("agent-traces")
class JsonExportProcessor(TracingProcessor):
"""Scrie fiecare span finalizat ca JSON, pentru un colector de jurnale."""
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
Fiți atenți la ceea ce exportați: implicit, span-urile de generare conțin intrările și ieșirile modelului, iar span-urile de funcție conțin argumentele și rezultatele instrumentelor. Pentru a le exclude, transmiteți RunConfig(trace_include_sensitive_data=False) sau setați variabila de mediu OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Pentru integrări gata făcute, documentația SDK listează multe instrumente terțe care oferă propriul procesor.
Nu pierdeți ultimele urme
Exportorul implicit trimite urmele în fundal, la fiecare câteva secunde. Într-un worker care procesează sarcini și nu se oprește, sau într-un script scurt, apelați flush_traces() după închiderea urmei pentru a forța trimiterea:
from agents import flush_traces
with trace("procesare-nocturnă"):
await Runner.run(agent, "Rezumă tichetele de astăzi")
flush_traces() # după ce urma se încheie, niciodată la mijloc
Dezactivarea urmăririi
Există un caz în care urmărirea încurcă mai mult decât ajută: o suită de teste care rulează sute de agenți mock și poluează panoul de control. În teste sau în timpul dezvoltării locale, o puteți dezactiva, fie global, fie pentru o singură execuție.
from agents import RunConfig, set_tracing_disabled
# Dezactivare completă (sau variabila de mediu OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)
# Sau pentru o singură execuție
result = await Runner.run(agent, "Mesaj de test", run_config=RunConfig(tracing_disabled=True))
Un ultim punct, acesta contractual: conform documentației, urmărirea către OpenAI nu este disponibilă pentru organizațiile supuse unei politici de Zero Data Retention. În acest caz, doar propriul procesor, instalat cu set_trace_processors(), vă va oferi urme.
Metrici cheie de monitorizat
Acum, la ce trebuie să vă uitați? În producție, șase indicatori sunt suficienți pentru a califica starea de sănătate a unui agent. Latenta totală—timpul dintre cerere și răspunsul final—este ceea ce simt utilizatorii dumneavoastră; aceasta este cel mai adesea explicată de numărul de tururi, adică numărul de ori cât bucla agentului s-a executat. Tokenii consumați, atât la intrare cât și la ieșire per execuție, determină factura dumneavoastră.
Celelalte trei se referă la calitate. Rata de eșec a instrumentelor, procentul de instrumente care returnează o eroare, relevă un API terț instabil sau argumente generate prost. Rata de declanșare a barierelor de securitate, vizibilă în span-urile guardrail, măsoară frecvența blocărilor: un vârf brusc semnalează fie un atac, fie o barieră devenită prea strictă. În final, distribuția transferurilor vă spune care agent răspunde cel mai des—și astfel dacă triajul dumneavoastră trimite cererile acolo unde trebuie.
Puncte cheie
- SDK urmărește automat fiecare execuție către panoul de control OpenAI (cu excepția organizațiilor aflate sub politica Zero Data Retention)
- O singură
trace()per flux de lucru; marcați pașii cucustom_span()și folosițigroup_idpentru a lega urmele dintr-o conversație - O urmă nu are timestamp; un span are
started_at,ended_atșispan_data.type - Un
TracingProcessorimplementează cele șase metode ale sale;add_trace_processor()adaugă,set_trace_processors()înlocuiește trace_include_sensitive_data=Falseexclude intrările și ieșirile;flush_traces()forțează trimiterea- Dezactivați urmărirea în teste cu
set_tracing_disabled(True)sauRunConfig(tracing_disabled=True)