Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Sledenje in opazljivost

Lekcija 14 od 25 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Sledenje in opazljivost
  2. Vgrajeno sledenje
  3. Poimenovanje sledi
  4. Razčlenitev delovnega toka na korake
  5. Procesi sledenja po meri
  6. Izvoz v zunanje sisteme
  7. Ne izgubi zadnjih sledi
  8. Onemogočanje sledenja
  9. Ključni kazalniki za spremljanje
  10. Ključne ugotovitve

Posodobljeno 3. novembra 2026. Procesi sledenja so prej brali trace.start_time, trace.end_time in span.name, ki v SDK-ju ne obstajajo: sled nima časovnega žiga, razpon (span) pa vsebuje started_at, ended_at in span_data. Izvozni procesor ni implementiral abstraktne metode on_trace_start: njena instantiation je sprožila TypeError. „Gnezdenje sledi” je ustvarilo novo sled znotraj sledi, kar SDK označi kot verjetno napako: koraki zdaj uporabljajo custom_span(). Dodano: flush_traces(), ravnanje z občutljivimi podatki in politika ničelnega hrambe podatkov (Zero Data Retention). Koda preverjena z openai-agents 0.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 z custom_span(), za povezavo sledi iz pogovora uporabi group_id
  • Sled nima časovnega žiga; razpon ima started_at, ended_at in span_data.type
  • TracingProcessor implementira svojih šest metod; add_trace_processor() doda, set_trace_processors() nadomesti
  • trace_include_sensitive_data=False izključi vhode in izhode; flush_traces() prisili pošiljanje
  • Onemogoči sledenje v testih z set_tracing_disabled(True) ali RunConfig(tracing_disabled=True)