Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Tracing a pozorovatelnost

Lekce 14 z 25 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Tracing a pozorovatelnost
  2. Vestavěné trasování
  3. Pojmenovávání stop
  4. Rozdělení workflow na kroky
  5. Vlastní procesory trasování
  6. Export do externích systémů
  7. Neztrať poslední stopy
  8. Zakázání trasování
  9. Klíčové metriky ke sledování
  10. Klíčové poznatky

Aktualizováno 3. listopadu 2026. Procesory trasování dříve četly trace.start_time, trace.end_time a span.name, které v SDK neexistují: trace nemá časové razítko a span nese started_at, ended_at a span_data. Exportní procesor neimplementoval abstraktní metodu on_trace_start: jeho instantiace vyvolávala TypeError. „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 s openai-agents 0.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žij group_id k propojení stop z konverzace
  • Trace nemá časové razítko; span má started_at, ended_at a span_data.type
  • TracingProcessor implementuje svých šest metod; add_trace_processor() přidává, set_trace_processors() nahrazuje
  • trace_include_sensitive_data=False vylučuje vstupy a výstupy; flush_traces() vynutí odeslání
  • Zakáž trasování v testech pomocí set_tracing_disabled(True) nebo RunConfig(tracing_disabled=True)