Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Tracing ir stebimumas

Paskaita 14 iš 25 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Tracing ir stebimumas
  2. Integruotas Tracing
  3. „Trace“ pavadinimų suteikimas
  4. Darbo eigos skaidymas į žingsnius
  5. Tinkinti „Trace“ procesoriai
  6. Eksportavimas į išorines sistemas
  7. Nepraleisk paskutinių „Trace“
  8. „Tracing“ išjungimas
  9. Pagrindiniai stebimi rodikliai
  10. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 3 d. Anksčiau „trace“ procesoriai nuskaitydavo trace.start_time, trace.end_time ir span.name, kurių SDK nėra: „trace“ neturi laiko žymos, o „span“ turi started_at, ended_at ir span_data. Eksporto procesorius neįgyvendino abstraktaus metodo on_trace_start: jį kuriant buvo išmetama TypeError. „Įdėtieji traces“ sukurdavo naują „trace“ kito „trace“ viduje, ką SDK pažymi kaip tikėtiną klaidą: dabar žingsniams naudojama custom_span(). Papildymai: flush_traces(), jautrių duomenų tvarkymas ir „Zero Data Retention“. Kodas patikrintas su openai-agents 0.24.0. Šaltiniai: Tracing (SDK dokumentacija) · openai-agents-python.

Tracing ir stebimumas

Veikiantis agentas be „tracing“ yra juoda dėžė. Kai klientas skundžiasi absurdišku atsakymu, neturi nei tikslaus užklausos teksto, nei iškviestų įrankių, nei jų grąžintų reikšmių. SDK tracing funkcija įrašo kiekvieną vykdymo žingsnį: modelio kvietimus, naudojamus įrankius, perdavimus (handoffs) ir apsaugos mechanizmus (guardrails). Tai tavo pagrindinis įrankis derinimui, optimizavimui ir agentų auditui.

Integruotas Tracing

Geros žinios: nieko papildomai įjungti nereikia. SDK automatiškai fiksuoja kiekvieną vykdymą ir pagal nutylėjimą siunčia duomenis į „OpenAI“ skydelį adresu platform.openai.com. Toliau pateiktas agentas, parašytas be jokios „tracing“ instrukcijos, jau sukuria naudotiną „trace“.

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

# Kiekvienas vykdymas automatiškai sukuria trace
result = Runner.run_sync(agent, "Search for the pro laptop")

Apsilankyk skydelyje, kad pamatytum išsamų „trace“: trukmę, sunaudotus tokenus, iškvietus įrankius ir galutinį atsakymą.

„Trace“ pavadinimų suteikimas

Po kelių šimtų vykdymų skydelis virsta vienoda sąrašu. Suteik savo „trace“ prasmingus pavadinimus, kad galėtum juos lengvai rasti – verslo proceso pavadinimas yra geriau nei techninis ID.

from agents import trace

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

„Trace“ pavadinimas atsiranda skydelyje ir palengvina filtravimą.

Darbo eigos skaidymas į žingsnius

Darbo eigai, kurioje yra keli kvietimai, sukurk vieną „trace“ visam procesui, o kiekvieną žingsnį pažymėk naudodamas custom_span(). Nedėk trace() į kitą trace() vidų: tuomet SDK užfiksuoja įspėjimą Trace already exists. Creating a new trace, but this is probably a mistake. Tačiau „span“ yra sukurti taip, kad būtų įdedami vienas į kitą: kiekvienas jų atsiduria po dabartiniu „span“.

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

Skydelyje order-workflow „trace“ rodo tris žingsnius, o po kiekvienu – automatinius vykdymo „span“: agentą, modelio kvietimus, įrankius. group_id susieja tos pačios pokalbio sesijos „trace“, pavyzdžiui, naudojant tavo gijos (thread) ID.

Pagal nutylėjimą SDK apgaubia kiekvieną Runner.run() „trace“, pavadintu Agent workflow, o „trace“ viduje fiksuoja agentą, kiekvieną modelio generavimą, funkcijos kvietimą, apsaugos mechanizmus ir perdavimus. Glaudesnei hierarchijai dokumentacija siūlo išjungti automatinius užduočių ir posūkių „span“:

from agents import RunConfig

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

Tinkinti „Trace“ procesoriai

„OpenAI“ skydelis yra patogus, tačiau tavo operacijų komanda tikriausiai stebi viską kitur. Norėdamas siųsti „trace“ į savo sistemą, parašyk procesorių: jis gauna pradžios ir pabaigos įvykius tiek visam „trace“, tiek kiekvienam „span“. Visi šeši TracingProcessor metodai yra abstraktūs: turi juos visus įgyvendinti (net jei tuščius), kitaip sukūrimas nepavyks.

Štai ką iš tikrųjų pateikia kiekvienas objektas: trace turi trace_id ir name, o jo export() metodas taip pat grąžina group_id ir metadata; jis neturi laiko žymos. Span turi span_id, trace_id, parent_id, started_at ir ended_at (ISO 8601 eilutės) bei span_data, kurio type atributas gali būti agent, generation, function, handoff, guardrail, custom ir kt. Todėl „trace“ trukmė matuojama procesoriaus viduje.

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() prideda tavo procesorių prie originalaus: „trace“ toliau siunčiami į „OpenAI“ skydelį. set_trace_processors() pakeičia numatytuosius procesorius: į „OpenAI“ nebeišsiunčiama nieko, nebent pats į sąrašą vėl įtrauktum jų eksportuotoją.

Eksportavimas į išorines sistemas

Stebimumo įrankiui tau tereikia performuoti „span“. Toliau pateiktame pavyzdyje kiekvienas baigtas „span“ įrašomas kaip viena JSON eilutė – formatas, kurį dauguma žurnalų rinkiklių moka apdoroti; span.export() jau pateikia pilną žodyną.

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

Atidžiai stebėk, ką eksportuoji: pagal nutylėjimą generavimo „span“ turi modelio įvestis ir išvestis, o funkcijų „span“ – įrankių argumentus ir rezultatus. Norėdamas jų neįtraukti, perduok RunConfig(trace_include_sensitive_data=False) arba nustatyk aplinkos kintamąjį OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Paruoštiems integravimams SDK dokumentacijoje išvardyta daug trečiųjų šalių įrankių, kurie pateikia savo procesorius.

Nepraleisk paskutinių „Trace“

Numatytasis eksportuotojas „trace“ siunčia fone, kas kelias sekundes. Darbuotojui (worker), kuris apdoroja užduotis ir nesustoja, arba trumpame scenarijuje, po „trace“ uždarymo iškviesk flush_traces(), kad priverstum išsiųsti duomenis:

from agents import flush_traces

with trace("nightly-processing"):
    await Runner.run(agent, "Summarize today's tickets")
flush_traces()  # po trace pabaigos, niekada viduryje

„Tracing“ išjungimas

Yra vienas atvejis, kai „tracing“ labiau trukdo nei padeda: testų rinkinys, kuris paleidžia šimtus imituojamų agentų ir užteršia tavo skydelį. Testų metu arba kuriant lokalai todėl gali jį išjungti – arba globaliai, arba vienam vykdymui.

from agents import RunConfig, set_tracing_disabled

# Visiškai išjungti (arba aplinkos kintamasis OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)

# Arba vienam vykdymui
result = await Runner.run(agent, "Test message", run_config=RunConfig(tracing_disabled=True))

Dar vienas, sutartinis punktas: pagal dokumentaciją „tracing“ į „OpenAI“ nėra prieinamas organizacijoms, taikančioms „Zero Data Retention“ politiką. Tokiu atveju „trace“ gausi tik naudodamas savo procesorių, įdiegtą su set_trace_processors().

Pagrindiniai stebimi rodikliai

Į ką turėtum atkreipti dėmesį? Veikloje pakanka šešių rodiklių agento būklei įvertinti. Bendra delsos trukmė – laikas tarp užklausos ir galutinio atsakymo – tai, ką jaučia tavo vartotojai; ją dažniausiai lemia posūkių skaičius, tai yra, kiek kartų agento ciklas buvo vykdytas. Sunaudoti tokenai (įvesties ir išvesties) vienam vykdymui lemia tavo sąskaitą.

Kiti trys rodikliai susiję su kokybe. Įrankių klaidų dažnis – procentas įrankių, grąžinančių klaidą – atskleidžia nestabilų trečiosios šalies API arba netinkamai sugeneruotus argumentus. Apsaugos mechanizmų suaktyvinimo dažnis, matomas guardrail „span“, rodo blokavimų dažnumą: staigus šuolis signalizuoja arba apie ataką, arba apie per daug sugriežtintą apsaugos mechanizmą. Galiausiai, perdavimų (handoff) pasiskirstymas parodo, kuris agentas atsako dažniausiai – ir taip patvirtina, ar tavo triažas siunčia užklausas ten, kur reikia.

Svarbiausi punktai

  • SDK automatiškai fiksuoja kiekvieną vykdymą į „OpenAI“ skydelį (išskyrus organizacijas, taikančias „Zero Data Retention“)
  • Vienas trace() vienai darbo eigai; žingsnius žymėk su custom_span(), o pokalbio „trace“ susiek naudodamas group_id
  • „Trace“ neturi laiko žymos; „span“ turi started_at, ended_at ir span_data.type
  • TracingProcessor turi įgyvendinti šešis metodus; add_trace_processor() prideda, set_trace_processors() pakeičia
  • trace_include_sensitive_data=False neįtraukia įvesčių ir išvesčių; flush_traces() priverčia išsiųsti
  • Testuose išjunk „tracing“ naudodamas set_tracing_disabled(True) arba RunConfig(tracing_disabled=True)