Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Praćenje i opservabilnost

Lekcija 14 od 25 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Praćenje i opservabilnost
  2. Ugrađeno praćenje
  3. Imenovanje tragova
  4. Razbijanje radnog tijeka na korake
  5. Prilagođeni procesori praćenja
  6. Izvoz u vanjske sustave
  7. Ne izgubi posljednje tragove
  8. Onemogućavanje praćenja
  9. Ključni pokazatelji za praćenje
  10. Ključne točke

Ažurirano 3. studenoga 2026. Procesi praćenja (trace processors) prethodno su čitali trace.start_time, trace.end_time i span.name, koji ne postoje u SDK-u: trag (trace) nema vremensku oznaku, a raspon (span) sadrži started_at, ended_at i span_data. Procesor izvoza nije implementirao on_trace_start, apstraktnu metodu: njegovo instanciranje izazivalo je TypeError. “Ugniježđeni tragovi” stvarali su novi trag unutar traga, što SDK označava kao vjerojatnu pogrešku: koraci sada koriste custom_span(). Dodaci: flush_traces(), rukovanje osjetljivim podacima i Politika nulte zadržavanja podataka (Zero Data Retention). Kod verificiran s openai-agents 0.24.0. Izvori: Tracing (SDK dokumentacija) · openai-agents-python.

Praćenje i opservabilnost

Agent u proizvodnji je crna kutija ako ne pratiš njegove radnje. Kada se korisnik požali na apsurdan odgovor, nemaš ni točan zahtjev, ni pozvane alate, ni vrijednosti koje su vratili. Praćenje (tracing) u SDK-u bilježi svaki korak izvršavanja: pozive modelu, korištene alate, predaje (handoffs) i zaštitne mehanizme (guardrails). To je tvoj primarni alat za otklanjanje pogrešaka, optimizaciju i reviziju tvojih agenata.

Ugrađeno praćenje

Dobre vijesti: ne moraš ništa omogućavati. SDK automatski prati svako izvršavanje i prema zadanim postavkama šalje tragove na OpenAI nadzornu ploču na platform.openai.com. Agent u nastavku, napisan bez ijedne upute za praćenje, već stvara upotrebljiv trag.

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",
)

# Svako izvršavanje automatski stvara trag
result = Runner.run_sync(agent, "Search for the pro laptop")

Posjeti nadzornu ploču da vidiš potpuni trag: trajanje, utrošeni tokeni, pozvani alati i konačni odgovor.

Imenovanje tragova

Nakon nekoliko stotina izvršavanja, nadzorna ploča postaje nediferencirani popis. Daj svojim tragovima smislena imena kako bi ih mogao lako pronaći – ime poslovne putanje bolje je od tehničkog ID-a.

from agents import trace

with trace("premium-customer-order"):
    result = await Runner.run(
        agent,
        "I want to order 5 laptops for my team",
    )

Ime traga pojavljuje se na nadzornoj ploči i olakšava filtriranje.

Razbijanje radnog tijeka na korake

Za radni tijek s više poziva, otvori jedan trag oko cijele stvari, a zatim označi svaki korak s custom_span(). Ne ugnježđuj trace() unutar drugog: SDK tada bilježi upozorenje Trace already exists. Creating a new trace, but this is probably a mistake. Rasponi (spans), međutim, dizajnirani su za ugnježđivanje: svaki sjedi ispod trenutnog raspona.

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 nadzornoj ploči, trag order-workflow prikazuje tri koraka, a ispod svakoga automatske raspone izvršavanja: agent, pozivi modelu, alati. group_id povezuje tragove iz istog razgovora, na primjer koristeći tvoj ID niti.

Prema zadanim postavkama, SDK omata svaki Runner.run() u trag nazvan Agent workflow, a unutar tragova agent, svako generiranje modela, svaki poziv funkcije, zaštitne mehanizme i predaje. Za kompaktniju hijerarhiju, dokumentacija predlaže isključivanje automatskih zadataka i raspona okreta (turn spans):

from agents import RunConfig

result = await Runner.run(
    agent,
    "Hello",
    run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)

Prilagođeni procesori praćenja

OpenAI nadzorna ploča je zgodna, ali tvoj operativni tim vjerojatno prati sve ostalo drugdje. Da bi poslao tragove u svoj vlastiti sustav, napiši procesor: on prima događaje početka i kraja, kako za cijeli trag tako i za svaki raspon. Sve šest metoda TracingProcessor su apstraktne: implementiraj ih sve, čak i ako su prazne, inače će instanciranje propasti.

Evo što svaki objekt zapravo izlaže: trag ima trace_id i name, a njegova metoda export() također vraća group_id i metadata; nema vremensku oznaku. Raspon ima span_id, trace_id, parent_id, started_at i ended_at (ISO 8601 nizovi) te span_data, čiji je atribut type vrijednost agent, generation, function, handoff, guardrail, custom i tako dalje. Trajanje traga stoga se mjeri u 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"[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() dodaje tvoj procesor originalnom: tragovi se i dalje šalju na OpenAI nadzornu ploču. set_trace_processors() zamjenjuje zadane procesore: ništa više ne ide na OpenAI, osim ako sam ručno ne vratiš njihov izvoznik na popis.

Izvoz u vanjske sustave

Za alat opservabilnosti, trebaš samo preformatirati raspone. Primjer u nastavku zapisuje jedan JSON redak po završenom rasponu, format koji većina kolekcionara zapisa zna ingestirati; span.export() već pruža potpuni rječnik.

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 što izvoziš: prema zadanim postavkama, rasponi generiranja sadrže ulaze i izlaze modela, a rasponi funkcija sadrže argumente alata i rezultate. Da bi ih isključio, proslijedi RunConfig(trace_include_sensitive_data=False) ili postavi varijablu okruženja OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Za gotova integracijska rješenja, dokumentacija SDK-a navodi mnogo alata trećih strana koji pružaju vlastiti procesor.

Ne izgubi posljednje tragove

Zadani izvoznik šalje tragove u pozadini, svakih nekoliko sekundi. U radniku (worker) koji obrađuje zadatke i ne zaustavlja se, ili u kratkoj skripti, pozovi flush_traces() nakon zatvaranja traga kako bi prisilio slanje:

from agents import flush_traces

with trace("nightly-processing"):
    await Runner.run(agent, "Summarize today's tickets")
flush_traces()  # nakon što trag završi, nikada usred njega

Onemogućavanje praćenja

Postoji jedan slučaj u kojem praćenje više odmaže nego pomaže: skup testova koji pokreće stotine lažnih agenata i zagađuje tvoju nadzornu ploču. U testovima ili tijekom lokalnog razvoja možeš ga stoga onemogućiti, bilo globalno ili za pojedinačno izvršavanje.

from agents import RunConfig, set_tracing_disabled

# Potpuno onemogući (ili varijabla okruženja OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)

# Ili za pojedinačno izvršavanje
result = await Runner.run(agent, "Test message", run_config=RunConfig(tracing_disabled=True))

Još jedna točka, ova ugovorna: prema dokumentaciji, praćenje prema OpenAIju nije dostupno za organizacije koje podliježu politici Nulte zadržavanja podataka (Zero Data Retention). U tom slučaju, samo tvoj vlastiti procesor, instaliran s set_trace_processors(), dat će ti tragove.

Ključni pokazatelji za praćenje

Što sada trebaš gledati? U proizvodnji je šest pokazatelja dovoljno za kvalificiranje zdravlja agenta. Ukupna latencija – vrijeme između zahtjeva i konačnog odgovora – ono je što tvoji korisnici osjete; najčešće je objašnjena brojem okreta, odnosno brojem puta koliko se petlja agenta izvršila. Utrošeni tokeni, i ulazni i izlazni po izvršavanju, pokreću tvoj račun.

Ostala tri odnose se na kvalitetu. Stopa neuspjeha alata, postotak alata koji vraćaju pogrešku, otkriva nestabilan API treće strane ili loše generirane argumente. Stopa okidanja zaštitnih mehanizama, vidljiva u rasponima guardrail, mjeri učestalost blokada: nagli skok signalizira ili napad ili zaštitni mehanizam koji je postao previše strog. Konačno, distribucija predaja govori ti koji agent najčešće odgovara – i time whether tvoje trijaže šalju zahtjeve tamo gdje trebaju ići.

Ključne točke

  • SDK automatski prati svako izvršavanje na OpenAI nadzornu ploču (osim za organizacije na politici Nulte zadržavanja podataka)
  • Jedan trace() po radnom tijeku; označi korake s custom_span(), i koristi group_id za povezivanje tragova iz razgovora
  • Trag nema vremensku oznaku; raspon ima started_at, ended_at i span_data.type
  • TracingProcessor implementira svojih šest metoda; add_trace_processor() dodaje, set_trace_processors() zamjenjuje
  • trace_include_sensitive_data=False isključuje ulaze i izlaze; flush_traces() prisiljava slanje
  • Onemogući praćenje u testovima s set_tracing_disabled(True) ili RunConfig(tracing_disabled=True)