Sledenje in opazljivost
Na tej strani
Posodobljeno 3. novembra 2026. Procesi sledenja so prej brali
trace.start_time,trace.end_timeinspan.name, ki v SDK-ju ne obstajajo: sled nima časovnega žiga, razpon (span) pa vsebujestarted_at,ended_atinspan_data. Izvozni procesor ni implementiral abstraktne metodeon_trace_start: njena instantiation je sprožilaTypeError. „Gnezdenje sledi” je ustvarilo novo sled znotraj sledi, kar SDK označi kot verjetno napako: koraki zdaj uporabljajocustom_span(). Dodano:flush_traces(), ravnanje z občutljivimi podatki in politika ničelnega hrambe podatkov (Zero Data Retention). Koda preverjena zopenai-agents0.24.0. Viri: Sledenje (dokumentacija SDK) · openai-agents-python.
Sledenje in opazljivost
Agent v proizvodnem okolju je črna škatla, če ne slediš njegovim dejanjem. Ko se stranka pritoži zaradi absurdnega odgovora, nimaš niti točnega zahtevka, niti podatkov o uporabljenih orodjih, niti vrednosti, ki so jih vrnila. Sledenje v SDK-ju beleži vsak korak izvajanja: klice modelov, uporabljena orodja, predaje (handoffs) in varovalke (guardrails). To je tvoje glavno orodje za odpravljanje napak, optimizacijo in revizijo tvojih agentov.
Vgrajeno sledenje
Dobra novica: ničesar ni treba vklopiti. SDK samodejno sledi vsakemu izvajanju in privzeto pošilja sledi na nadzorno ploščo OpenAI na naslovu platform.openai.com. Spodnji agent, napisan brez ene same instrukcije za sledenje, že ustvari uporabno sled.
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")
Obišči nadzorno ploščo, da vidiš popolno sled: trajanje, porabljeni žetoni, poklicana orodja in končni odgovor.
Poimenovanje sledi
Po nekaj sto izvajanjih nadzorna plošča postane nediferenciran seznam. Daj svojim sledem smiselna imena, da jih boš lažje našel – ime poslovne poti je boljše od tehničnega ID-ja.
from agents import trace
with trace("premium-customer-order"):
result = await Runner.run(
agent,
"I want to order 5 laptops for my team",
)
Ime sledi se prikaže na nadzorni plošči in olajša filtriranje.
Razčlenitev delovnega toka na korake
Za delovni tok z več klici odpri eno sled okoli celotnega procesa, nato pa vsak korak označi z custom_span(). Ne gnezdi trace() znotraj drugega: SDK bo nato zapisal opozorilo Trace already exists. Creating a new trace, but this is probably a mistake. Razponi (spans) pa so zasnovani za gnezdenje: vsak sedi pod trenutnim razponom.
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 nadzorni plošči sled order-workflow prikazuje tri korake, pod vsakim pa samodejne razpone izvajanja: agent, klici modelov, orodja. group_id povezuje sledi iz istega pogovora, na primer z uporabo ID-ja tvoje nitki (thread ID).
Privzeto SDK ovije vsak Runner.run() v sled z imenom Agent workflow, znotraj sledi pa agent, vsaka generacija modela, vsak klic funkcije, varovalke in predaje. Za bolj kompaktno hierarhijo dokumentacija predlaga izključitev samodejnih razponov za naloge in obrate:
from agents import RunConfig
result = await Runner.run(
agent,
"Hello",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Procesi sledenja po meri
Nadzorna plošča OpenAI je priročna, a tvoja operativna ekipa verjetno spremlja vse drugje. Če želiš sledi pošiljati v svoj sistem, napiši procesor: ta prejme dogodke začetka in konca tako za celotno sled kot za vsak razpon. Vseh šest metod razreda TracingProcessor je abstraktnih: implementirati moraš vse, tudi če so prazne, sicer instantiation ne bo uspela.
Tukaj je, kaj dejansko izpostavlja vsak objekt: sled ima trace_id in name, njena metoda export() pa vrne tudi group_id in metadata; nima časovnega žiga. Razpon ima span_id, trace_id, parent_id, started_at in ended_at (niza ISO 8601) ter span_data, katerega atribut type je agent, generation, function, handoff, guardrail, custom itd. Trajanje sledi se zato meri v procesorju.
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() tvoj procesor doda obstoječemu: sledi še vedno potujejo na nadzorno ploščo OpenAI. set_trace_processors() privzete procesorje nadomesti: na OpenAI ne gre nič več, razen če njihovega izvoznika sam ročno vrneš na seznam.
Izvoz v zunanje sisteme
Za orodje opazljivosti moraš le preoblikovati razpone. Spodnji primer zapiše eno vrstico JSON za vsak končani razpon, format, ki ga večina zbiralnikov dnevnikov zna zaužiti; span.export() že ponuja popoln slovar.
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
Pazi, kaj izvoziš: privzeto razponi generacije vsebujejo vhode in izhode modela, razponi funkcij pa argumente orodij in rezultate. Če jih želiš izključiti, podaj RunConfig(trace_include_sensitive_data=False) ali nastavi okoljsko spremenljivko OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Za pripravljene integracije dokumentacija SDK navaja številna orodja tretjih strani, ki ponujajo svoj procesor.
Ne izgubi zadnjih sledi
Privzeti izvoznik pošilja sledi v ozadju, vsakih nekaj sekund. V delavcu, ki obdeluje naloge in se ne ustavi, ali v kratkem skriptu, pokliči flush_traces() po zaprtju sledi, da prisiliš pošiljanje:
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
Onemogočanje sledenja
Obstaja en primer, ko sledenje bolj škodi kot koristi: testni niz, ki požene na stotine lažnih agentov in onesnaži tvojo nadzorno ploščo. V testih ali med lokalnim razvojem ga lahko zato onemogočiš, bodisi globalno bodisi za posamezno izvajanje.
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 zadnja točka, tokrat pogodbenega značaja: glede na dokumentacijo sledenje do OpenAI ni na voljo za organizacije, ki zanje velja politika ničelnega hrambe podatkov (Zero Data Retention). V tem primeru ti bodo sledi zagotovili le tvoj lastni procesor, nameščen s set_trace_processors().
Ključni kazalniki za spremljanje
Na kaj torej moraš biti pozoren? V proizvodnem okolju zadostuje šest kazalnikov za oceno zdravja agenta. Skupna zakasnitev – čas med zahtevkom in končnim odgovorom – je tisto, kar čutijo tvoji uporabniki; najpogosteje jo pojasnjuje število obratov, torej koliko krat se je zanka agenta izvedla. Porabljeni žetoni, tako vhodni kot izhodni na izvajanje, poganjajo tvoje stroške.
Preostali trije se nanašajo na kakovost. Stopnja napak orodij, odstotek orodij, ki vrnejo napako, razkriva nestabilen API tretje strani ali slabo generirane argumente. Stopnja sprožitve varovalk, vidna v razponih guardrail, meri pogostost blokad: nenaden skok signalizira bodisi napad bodisi varovalko, ki je postala prestroga. Nazadnje, porazdelitev predaj ti pove, kateri agent najpogosteje odgovarja – in s tem, ali tvoje razvrščanje (triage) pošilja zahtevke tja, kamor spadajo.
Ključne ugotovitve
- SDK samodejno sledi vsakemu izvajanju na nadzorno ploščo OpenAI (razen za organizacije s politiko ničelnega hrambe podatkov)
- Ena
trace()na delovni tok; korake označi zcustom_span(), za povezavo sledi iz pogovora uporabigroup_id - Sled nima časovnega žiga; razpon ima
started_at,ended_atinspan_data.type TracingProcessorimplementira svojih šest metod;add_trace_processor()doda,set_trace_processors()nadomestitrace_include_sensitive_data=Falseizključi vhode in izhode;flush_traces()prisili pošiljanje- Onemogoči sledenje v testih z
set_tracing_disabled(True)aliRunConfig(tracing_disabled=True)