Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Sledovanie a pozorovateľnosť

Lekcia 14 z 25 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Sledovanie a pozorovateľnosť
  2. Vstavané sledovanie
  3. Pomenovávanie stôp
  4. Rozdelenie workflow na kroky
  5. Vlastné procesorky stôp
  6. Export do externých systémov
  7. Nestrácaj posledné stopy
  8. Vypnutie sledovania
  9. Kľúčové metriky na monitorovanie
  10. Kľúčové poznatky

Aktualizované 3. novembra 2026. Spracovateľky stôp (trace processors) predtým čítali trace.start_time, trace.end_time a span.name, ktoré v SDK neexistujú: stopa nemá časovú pečiatku a rozsah (span) obsahuje started_at, ended_at a span_data. Exportná procesorka neimplementovala abstraktnú metódu on_trace_start: jej inštancovanie vyvolalo TypeError. „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ý s openai-agents 0.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č pomocou custom_span() a použij group_id na prepojenie stôp z konverzácie
  • Stopa nemá časovú pečiatku; rozsah má started_at, ended_at a span_data.type
  • TracingProcessor implementuje svojich šesť metód; add_trace_processor() pridáva, set_trace_processors() nahrádza
  • trace_include_sensitive_data=False vylúči vstupy a výstupy; flush_traces() vynúti odoslanie
  • Vypni sledovanie v testoch pomocou set_tracing_disabled(True) alebo RunConfig(tracing_disabled=True)