Sledovanie a pozorovateľnosť
Na tejto strane
Aktualizované 3. novembra 2026. Spracovateľky stôp (trace processors) predtým čítali
trace.start_time,trace.end_timeaspan.name, ktoré v SDK neexistujú: stopa nemá časovú pečiatku a rozsah (span) obsahujestarted_at,ended_ataspan_data. Exportná procesorka neimplementovala abstraktnú metóduon_trace_start: jej inštancovanie vyvolaloTypeError. „Vnorené stopy“ vytvárali novú stopu vnútri stopy, čo SDK označuje ako pravdepodobnú chybu: kroky teraz používajúcustom_span(). Doplnené:flush_traces(), zaobchádzanie s citlivými údajmi a zásada Zero Data Retention. Kód overený sopenai-agents0.24.0. Zdroje: Tracing (dokumentácia SDK) · openai-agents-python.
Sledovanie a pozorovateľnosť
Agent v produkcii je čiernou skrinkou, ak nesleduješ jeho činnosť. Keď si zákazník sťažuje na absurdnú odpoveď, nemáš k dispozícii ani presnú požiadavku, ani volané nástroje, ani hodnoty, ktoré vrátili. Sledovanie (tracing) v SDK zaznamenáva každý krok vykonávania: volania modelu, použité nástroje, odovzdania (handoffs) a ochranné mechanizmy (guardrails). Je to tvoj hlavný nástroj na ladenie, optimalizáciu a auditovanie tvojich agentov.
Vstavané sledovanie
Dobrá správa: nemusíš nič povoľovať. SDK automaticky sleduje každé vykonanie a predvolene odosiela stopy na dashboard OpenAI na adrese platform.openai.com. Nasledujúci agent, napísaný bez jediného pokynu pre sledovanie, už vytvára použiteľnú stopu.
from agents import Agent, Runner, function_tool
@function_tool
def search_product(name: str) -> str:
"""Searches for a product in the catalog."""
return f"Product found: {name}, price €29.99"
agent = Agent(
name="Shop Agent",
instructions="You help customers find products.",
tools=[search_product],
model="gpt-5.6-terra",
)
# Every execution automatically creates a trace
result = Runner.run_sync(agent, "Search for the pro laptop")
Navštív dashboard a uvidíš kompletnú stopu: trvanie, spotrebované tokeny, volané nástroje a finálnu odpoveď.
Pomenovávanie stôp
Po niekoľkých stovkách vykonaní sa dashboard zmení na nerozlíšiteľný zoznam. Dávaj svojim stopám zmysluplné názvy, aby si ich ľahko našiel – názov obchodného procesu je lepší ako technické ID.
from agents import trace
with trace("premium-customer-order"):
result = await Runner.run(
agent,
"I want to order 5 laptops for my team",
)
Názov stopy sa zobrazí na dashboarde a uľahčí filtrovanie.
Rozdelenie workflow na kroky
Pre workflow s viacerými volaniami otvor jednu stopu okolo celého procesu a každý krok označ pomocou custom_span(). Nevnorávaj trace() dovnútra inej: SDK potom zapíše varovanie Trace already exists. Creating a new trace, but this is probably a mistake. Rozsahy (spans) sú však navrhnuté tak, aby sa vnárali: každý z nich sedí pod aktuálnym rozsahom.
from agents import Runner, custom_span, trace
async def process_order(message: str, conversation_id: str):
with trace("order-workflow", group_id=conversation_id):
with custom_span("step-1-understanding"):
result_understanding = await Runner.run(triage_agent, message)
with custom_span("step-2-processing"):
result_processing = await Runner.run(
order_agent,
result_understanding.to_input_list(),
)
with custom_span("step-3-confirmation", data={"step": 3}):
result_final = await Runner.run(
confirmation_agent,
result_processing.to_input_list(),
)
return result_final.final_output
Na dashboarde stopa order-workflow zobrazuje tri kroky a pod každým automatické rozsahy vykonávania: agent, volania modelu, nástroje. group_id spája stopy z tej istej konverzácie, napríklad použitím ID tvojej vlákna (thread ID).
SDK predvolene obalí každé Runner.run() do stopy s názvom Agent workflow a vo vnútri stôp sleduje agenta, každú generáciu modelu, každé volanie funkcie, ochranné mechanizmy a odovzdania. Pre kompaktnejšiu hierarchiu dokumentácia odporúča vypnúť automatické rozsahy úloh a ťahov (turns):
from agents import RunConfig
result = await Runner.run(
agent,
"Hello",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Vlastné procesorky stôp
Dashboard OpenAI je pohodlný, ale tvoj operačný tím pravdepodobne monitoruje všetko ostatné inde. Ak chceš odosielať stopy do vlastného systému, napíš procesorku: dostáva udalosti štartu a konca, a to pre celú stopu aj pre každý rozsah. Všetkých šesť metód TracingProcessor je abstraktných: musíš ich všetky implementovať, aj keď prázdne, inak inštancovanie zlyhá.
Tu je to, čo každý objekt skutočne poskytuje: stopa má trace_id a name a jej metóda export() vracia aj group_id a metadata; nemá časovú pečiatku. Rozsah (span) má span_id, trace_id, parent_id, started_at a ended_at (reťazce ISO 8601) a span_data, ktorého atribút type je agent, generation, function, handoff, guardrail, custom a podobne. Trvanie stopy sa preto meria v procesorke.
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"[TRACE START] {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"[TRACE END] {trace.name} - duration: {duration:.2f} s")
def on_span_start(self, span: Span[Any]) -> None:
print(f" [SPAN START] {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" [SPAN END] {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() pridá tvoju procesorku k pôvodnej: stopy pokračujú v odosielaní na dashboard OpenAI. set_trace_processors() nahradí predvolené procesorky: nič už nepôjde na OpenAI, pokiaľ tam sám manuálne nepridáš späť ich exportér.
Export do externých systémov
Pre nástroj pozorovateľnosti stačí preformátovať rozsahy. Nasledujúci príklad zapisuje jeden riadok JSON na každý dokončený rozsah, formát, ktorý väčšina zberačov logov vie spracovať; span.export() už poskytuje kompletný slovník.
import json
import logging
from typing import Any
from agents.tracing import Span, Trace, TracingProcessor
logger = logging.getLogger("agent-traces")
class JsonExportProcessor(TracingProcessor):
"""Writes each finished span as JSON, for a log collector."""
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
Dávaj pozor na to, čo exportuješ: rozsahy generácie predvolene obsahujú vstupy a výstupy modelu a rozsahy funkcií obsahujú argumenty nástrojov a výsledky. Ak ich chceš vylúčiť, odovzdaj RunConfig(trace_include_sensitive_data=False) alebo nastav premennú prostredia OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Pre hotové integrácie dokumentácia SDK uvádza mnoho nástrojov tretích strán, ktoré poskytujú vlastnú procesorku.
Nestrácaj posledné stopy
Predvolený exportér odosiela stopy na pozadí každých pár sekúnd. V workeri, ktorý spracováva úlohy a nezastavuje sa, alebo v krátkom skripte, zavolaj flush_traces() po uzavretí stopy, aby si vynútil odoslanie:
from agents import flush_traces
with trace("nightly-processing"):
await Runner.run(agent, "Summarize today's tickets")
flush_traces() # after the trace ends, never in the middle
Vypnutie sledovania
Existuje jeden prípad, keď sledovanie viac škodí než pomáha: testovacia sada, ktorá spúšťa stovky fiktívnych agentov a zaplavuje tvoj dashboard. V testoch alebo počas lokálneho vývoja ho preto môžeš vypnúť, buď globálne, alebo pre jednotlivé vykonanie.
from agents import RunConfig, set_tracing_disabled
# Disable completely (or environment variable OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)
# Or for a single execution
result = await Runner.run(agent, "Test message", run_config=RunConfig(tracing_disabled=True))
Ešte jedna dôležitá poznámka, tentoraz zmluvná: podľa dokumentácie nie je sledovanie smerujúce na OpenAI dostupné pre organizácie, ktoré podliehajú politike Zero Data Retention. V takom prípade ti stopy poskytnú len tvoje vlastné procesorky nainštalované pomocou set_trace_processors().
Kľúčové metriky na monitorovanie
Na čo by si sa mal zamerať? V produkcii stačí šesť ukazovateľov na posúdenie zdravia agenta. Celková latencia – čas medzi požiadavkou a finálnou odpoveďou – je to, čo cítia tvoji používatelia; najčastejšie ju vysvetľuje počet ťahov (turns), teda koľkokrát sa slučka agenta vykonala. Spotrebované tokeny, vstupné aj výstupné na jedno vykonanie, určujú tvoju faktúru.
Ďalšie tri súvisia s kvalitou. Miera zlyhania nástrojov, percento nástrojov, ktoré vrátia chybu, odhaľuje nestabilné API tretej strany alebo zle generované argumenty. Miera spustenia ochranných mechanizmov (guardrail trigger rate), viditeľná v rozsahoch guardrail, meria frekvenciu blokovaní: náhly nárast signalizuje buď útok, alebo príliš prísny ochranný mechanizmus. Nakoniec, distribúcia odovzdaní (handoff distribution) ti povie, ktorý agent odpovedá najčastejšie – a teda či tvoje triedenie smeruje požiadavky tam, kam majú.
Kľúčové poznatky
- SDK automaticky sleduje každé vykonanie na dashboard OpenAI (okrem organizácií s politikou Zero Data Retention)
- Jedna
trace()na workflow; kroky označ pomocoucustom_span()a použijgroup_idna prepojenie stôp z konverzácie - Stopa nemá časovú pečiatku; rozsah má
started_at,ended_ataspan_data.type TracingProcessorimplementuje svojich šesť metód;add_trace_processor()pridáva,set_trace_processors()nahrádzatrace_include_sensitive_data=Falsevylúči vstupy a výstupy;flush_traces()vynúti odoslanie- Vypni sledovanie v testoch pomocou
set_tracing_disabled(True)aleboRunConfig(tracing_disabled=True)