Salt la conținutul principal
Română— Alege o limbă
Meniu

Urmărire și observabilitate

Lecția 14 din 25 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Urmărire și observabilitate
  2. Urmărire integrată
  3. Denumirea urmelor
  4. Divizarea unui flux de lucru în pași
  5. Procesoare personalizate de urmărire
  6. Exportul către sisteme externe
  7. Nu pierdeți ultimele urme
  8. Dezactivarea urmăririi
  9. Metrici cheie de monitorizat
  10. Puncte cheie

Actualizat la 3 noiembrie 2026. Procesoarele de urmărire citeau anterior trace.start_time, trace.end_time și span.name, care nu există în SDK: o urmă nu are timestamp, iar un span conține started_at, ended_at și span_data. Procesorul de export nu implementa metoda abstractă on_trace_start: instanțierea sa genera o eroare TypeError. „Urile imbricate“ creau o nouă urmă în interiorul unei urme, lucru pe care SDK îl semnalează ca o eroare probabilă: pașii folosesc acum custom_span(). Noutăți: flush_traces(), gestionarea datelor sensibile și Zero Data Retention. Cod verificat cu openai-agents 0.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 cu custom_span() și folosiți group_id pentru a lega urmele dintr-o conversație
  • O urmă nu are timestamp; un span are started_at, ended_at și span_data.type
  • Un TracingProcessor implementează cele șase metode ale sale; add_trace_processor() adaugă, set_trace_processors() înlocuiește
  • trace_include_sensitive_data=False exclude intrările și ieșirile; flush_traces() forțează trimiterea
  • Dezactivați urmărirea în teste cu set_tracing_disabled(True) sau RunConfig(tracing_disabled=True)