Tracing a pozorovatelnost
Na této stránce
Aktualizováno 3. listopadu 2026. Procesory trasování dříve četly
trace.start_time,trace.end_timeaspan.name, které v SDK neexistují: trace nemá časové razítko a span nesestarted_at,ended_ataspan_data. Exportní procesor neimplementoval abstraktní metoduon_trace_start: jeho instantiace vyvolávalaTypeError. „Vnořené trace“ vytvářely nové trace uvnitř trace, což SDK označuje jako pravděpodobnou chybu: kroky nyní používajícustom_span(). Novinky:flush_traces(), zpracování citlivých dat a Zero Data Retention. Kód ověřen sopenai-agents0.24.0. Zdroje: Tracing (dokumentace SDK) · openai-agents-python.
Tracing a pozorovatelnost
Agent v produkci je černou skříní, pokud nesleduješ jeho činnost. Když si zákazník stěžuje na absurdní odpověď, nemáš k dispozici ani přesný požadavek, ani volané nástroje, ani hodnoty, které vrátily. Tracing v SDK zaznamenává každý krok执行: volání modelu, použité nástroje, předávání úkolů (handoffs) a ochranná pravidla (guardrails). Je to tvůj hlavní nástroj pro ladění, optimalizaci a audit tvých agentů.
Vestavěné trasování
Dobrá zpráva: nemusíš nic povolovat. SDK automaticky trasuje každé执行 a ve výchozím nastavení odesílá stopy na dashboard OpenAI na adrese platform.openai.com. Následující agent, napsaný bez jediného pokynu pro trasování, již vytváří použitelnou stopu.
from agents import Agent, Runner, function_tool
@function_tool
def search_product(name: str) -> str:
"""Vyhledá produkt v katalogu."""
return f"Nalezen produkt: {name}, cena 29,99 €"
agent = Agent(
name="Shop Agent",
instructions="Pomáháš zákazníkům najít produkty.",
tools=[search_product],
model="gpt-5.6-terra",
)
# Každé执行 automaticky vytvoří stopu
result = Runner.run_sync(agent, "Vyhledej profesionální laptop")
Navštiv dashboard, abys viděl úplnou stopu: dobu trvání, spotřebované tokeny, volané nástroje a konečnou odpověď.
Pojmenovávání stop
Po několika stech执行 se dashboard změní v nerozlišený seznam. Dej svým stopám smysluplná jména, abys je snadno našel – název obchodního procesu je lepší než technické ID.
from agents import trace
with trace("objednavka-premium-zakaznika"):
result = await Runner.run(
agent,
"Chci objednat 5 laptopů pro svůj tým",
)
Název stopy se zobrazí na dashboardu a usnadní filtrování.
Rozdělení workflow na kroky
Pro workflow s více voláními otevři jednu stopu kolem celého procesu a každý krok označ pomocí custom_span(). Nevnořuj trace() do jiného trace(): SDK pak zapíše varování Trace already exists. Creating a new trace, but this is probably a mistake. Spany jsou však navrženy tak, aby se vnořovaly: každý z nich sedí pod aktuálním spanem.
from agents import Runner, custom_span, trace
async def process_order(message: str, conversation_id: str):
with trace("workflow-objednavky", group_id=conversation_id):
with custom_span("krok-1-pochopení"):
result_understanding = await Runner.run(triage_agent, message)
with custom_span("krok-2-zpracování"):
result_processing = await Runner.run(
order_agent,
result_understanding.to_input_list(),
)
with custom_span("krok-3-potvrzení", data={"step": 3}):
result_final = await Runner.run(
confirmation_agent,
result_processing.to_input_list(),
)
return result_final.final_output
Na dashboardu ukazuje stopa workflow-objednavky tři kroky a pod každým automatické spány执行: agent, volání modelu, nástroje. group_id propojuje stopy ze stejné konverzace, například pomocí ID tvého vlákna.
Ve výchozím nastavení SDK zabalí každé Runner.run() do stopy s názvem Agent workflow a uvnitř stop agenta, každé generování modelu, každé volání funkce, guardrails a handoffs. Pro kompaktnější hierarchii dokumentace navrhuje vypnout automatické spány úkolů a kol:
from agents import RunConfig
result = await Runner.run(
agent,
"Ahoj",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Vlastní procesory trasování
Dashboard OpenAI je pohodlný, ale tvůj operační tým pravděpodobně monitoruje vše ostatní jinde. Chcete-li odesílat stopy do vlastního systému, napiš procesor: přijímá události startu a konce pro celou stopu i pro každý span. Všech šest metod TracingProcessor je abstraktních: implementuj je všechny, i když prázdné, jinak instantiace selže.
Zde je přehled toho, co každý objekt skutečně poskytuje: trace má trace_id a name a jeho metoda export() vrací také group_id a metadata; nemá žádné časové razítko. Span má span_id, trace_id, parent_id, started_at a ended_at (řetězce ISO 8601) a span_data, jehož atribut type je agent, generation, function, handoff, guardrail, custom atd. Doba trvání stopy se tedy měří v procesoru.
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 TRACE] {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"[KONEC TRACE] {trace.name} - doba trvání: {duration:.2f} s")
def on_span_start(self, span: Span[Any]) -> None:
print(f" [START SPANU] {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" [KONEC SPANU] {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() přidá tvůj procesor k původnímu: stopy pokračují v odesílání na dashboard OpenAI. set_trace_processors() výchozí procesory nahradí: nic už nejde na OpenAI, pokud tam jeho exportér sám znovu nepřidáš do seznamu.
Export do externích systémů
Pro nástroj pozorovatelnosti stačí přformátovat spány. Níže uvedený příklad zapisuje jeden řádek JSON na každý dokončený span, formát, který většina sběračů logů umí zpracovat; span.export() již 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):
"""Zapisuje každý dokončený span jako JSON pro sběrač 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
Dej si pozor na to, co exportuješ: ve výchozím nastavení spány generování obsahují vstupy a výstupy modelu a spány funkcí obsahují argumenty nástrojů a výsledky. Chcete-li je vyloučit, předej RunConfig(trace_include_sensitive_data=False) nebo nastav proměnnou prostředí OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Pro hotové integrace dokumentace SDK uvádí mnoho nástrojů třetích stran, které poskytují vlastní procesor.
Neztrať poslední stopy
Výchozí exportér odesílá stopy na pozadí každých několik sekund. Ve workeru, který zpracovává úlohy a nezastavuje se, nebo v krátkém skriptu zavolej flush_traces() po uzavření stopy, aby se vynutilo odeslání:
from agents import flush_traces
with trace("nocní-zpracování"):
await Runner.run(agent, "Shrň dnešní tickety")
flush_traces() # až po skončení stopy, nikdy uprostřed
Zakázání trasování
Existuje jeden případ, kdy trasování více škodí než pomáhá: testovací sada, která spouští stovky mock agentů a znečišťuje tvůj dashboard. V testech nebo během lokálního vývoje jej tedy můžeš zakázat, buď globálně, nebo pro jedno执行.
from agents import RunConfig, set_tracing_disabled
# Úplné zakázání (nebo proměnná prostředí OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)
# Nebo pro jedno执行
result = await Runner.run(agent, "Testovací zpráva", run_config=RunConfig(tracing_disabled=True))
Ještě jedna poslední, tentokrát smluvní poznámka: podle dokumentace není trasování na OpenAI k dispozici pro organizace, které podléhají zásadám Zero Data Retention. V tomto případě ti stopy poskytnou pouze tvůj vlastní procesor nainstalovaný pomocí set_trace_processors().
Klíčové metriky ke sledování
Na co se tedy máš dívat? V produkci stačí šest indikátorů k posouzení zdraví agenta. Celková latence – čas mezi požadavkem a konečnou odpovědí – je to, co cítí tvoji uživatelé; nejčastěji ji vysvětluje počet kol, tedy kolikrát se smyčka agenta执行. Spotřebované tokeny, jak vstupní, tak výstupní na执行, řídí tvou fakturaci.
Další tři souvisejí s kvalitou. Míra selhání nástrojů, procento nástrojů, které vrátí chybu, odhaluje nestabilní API třetí strany nebo špatně generované argumenty. Míra spuštění guardrails, viditelná ve spánech guardrail, měří frekvenci blokování: náhlý nárůst signalizuje buď útok, nebo guardrail, který se stal příliš přísným. Nakonec distribuce handoffů ti říká, který agent odpovídá nejčastěji – a tedy zda tvé třídění odesílá požadavky tam, kam mají.
Klíčové poznatky
- SDK automaticky trasuje každé执行 na dashboard OpenAI (kromě organizací na Zero Data Retention)
- Jedno
trace()na workflow; kroky označ pomocícustom_span()a použijgroup_idk propojení stop z konverzace - Trace nemá časové razítko; span má
started_at,ended_ataspan_data.type TracingProcessorimplementuje svých šest metod;add_trace_processor()přidává,set_trace_processors()nahrazujetrace_include_sensitive_data=Falsevylučuje vstupy a výstupy;flush_traces()vynutí odeslání- Zakáž trasování v testech pomocí
set_tracing_disabled(True)neboRunConfig(tracing_disabled=True)