Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Jälitamine ja vaadeldavus

Õppetund 14 / 25 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Jälitamine ja vaadeldavus
  2. Sisseehitatud jälitamine
  3. Jälituste nimetamine
  4. Töövoogu sammudeks jaotamine
  5. Kohandatud jälitusprotsessorid
  6. Eksportimine välistesse süsteemidesse
  7. Ära kaota viimaseid jälitusi
  8. Jälitamise keelamine
  9. Peamised jälgitavad näitajad
  10. Peamised punktid

Uuendatud 3. novembril 2026. Jälitusprotsessorid lugesid varem trace.start_time, trace.end_time ja span.name, mida SDK-s ei eksisteeri: jälitusel puudub ajatempel ja lõigul (span) on olemas started_at, ended_at ning span_data. Ekspordiprotsessor ei rakendanud abstraktset meetodit on_trace_start: selle instantsimine tekitas vea TypeError. “Pesastatud jälitused” lõid uue jälituse olemasoleva sees, mida SDK märgib tõenäolise veana: sammud kasutavad nüüd custom_span(). Lisandused: flush_traces(), tundlike andmete käsitlemine ja Nullandmete säilitamine (Zero Data Retention). Kood on kontrollitud versiooniga openai-agents 0.24.0. Allikad: Jälitamine (SDK dokumentatsioon) · openai-agents-python.

Jälitamine ja vaadeldavus

Tootmises olev agent on must kast, kui sa ei jälita selle tegevust. Kui klient kaebab absurdsesse vastusesse, puudub sul nii täpne päring, kasutatud tööriistad kui ka nende tagastatud väärtused. SDK jälitamine salvestab iga täitmise sammu: mudeli väljakutsed, kasutatud tööriistad, üleandmised (handoffs) ja turvapiirded (guardrails). See on sinu peamine vahend agentide silumiseks, optimeerimiseks ja auditeerimiseks.

Sisseehitatud jälitamine

Hea uudis: sa ei pea midagi lubama. SDK jälitab automaatselt iga täitmist ja saadab jälitused vaikimisi OpenAI armatuurlauale aadressil platform.openai.com. Allpool olev agent, mis on kirjutatud ilma ühegi jälitusjuhendita, loob juba kasutatava jälituse.

from agents import Agent, Runner, function_tool

@function_tool
def search_product(name: str) -> str:
    """Otsib toodet kataloogist."""
    return f"Toode leitud: {name}, hind 29,99 €"

agent = Agent(
    name="Poepidaja agent",
    instructions="Aidad klientidel tooteid leida.",
    tools=[search_product],
    model="gpt-5.6-terra",
)

# Iga täitmine loob automaatselt jälituse
result = Runner.run_sync(agent, "Otsi pro sülearvutit")

Külasta armatuurlauda, et näha terviklikku jälitust: kestus, tarbitud tokenid, kutsutud tööriistad ja lõplik vastus.

Jälituste nimetamine

Paarisaja täitmise järel muutub armatuurlaud eristamatuks loendiks. Anna oma jälitustele tähenduslikud nimed, et saaksid neid hõlpsasti leida – ärinime kasutamine on parem kui tehniline ID.

from agents import trace

with trace("premium-klient-tellimus"):
    result = await Runner.run(
        agent,
        "Soovin tellida oma meeskonnale 5 sülearvutit",
    )

Jälituse nimi ilmub armatuurlauale ja muudab filtreerimise lihtsamaks.

Töövoogu sammudeks jaotamine

Mitme väljakutsega töövoogu puhul ava üks jälitus kogu protsessi ümber ja märgi iga samm custom_span() abil. Ära pesasta trace() teise trace() sisse: SDK logib siis hoiatuse Trace already exists. Creating a new trace, but this is probably a mistake. Lõigud (spans) on aga mõeldud pesastamiseks: üks asetseb praeguse lõigu all.

from agents import Runner, custom_span, trace


async def process_order(message: str, conversation_id: str):
    with trace("tellimus-too", group_id=conversation_id):
        with custom_span("samm-1-moistmine"):
            result_understanding = await Runner.run(triage_agent, message)

        with custom_span("samm-2-tootlemine"):
            result_processing = await Runner.run(
                order_agent,
                result_understanding.to_input_list(),
            )

        with custom_span("samm-3-kinnitamine", data={"step": 3}):
            result_final = await Runner.run(
                confirmation_agent,
                result_processing.to_input_list(),
            )

    return result_final.final_output

Armatuurlaual näitab tellimus-too jälitus kolme sammu ja igaühe all automaatseid täitmislõike: agent, mudeli väljakutsed, tööriistad. group_id seob sama vestluse jälitused, kasutades näiteks sinu lõime ID-d.

Vaikimisi mähib SDK iga Runner.run() jälituseks nimega Agent workflow ja jälituste sees agent, iga mudeli genereerimine, iga funktsioonikutsed, turvapiirded ja üleandmised. Kompaktsema hierarhia jaoks soovitab dokumentatsioon automaatsed ülesande ja pöörde lõigud välja lülitada:

from agents import RunConfig

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

Kohandatud jälitusprotsessorid

OpenAI armatuurlaud on mugav, kuid sinu toimingute meeskond jälgib tõenäoliselt kõike mujal. Et saata jälitused oma süsteemi, kirjuta protsessor: see saab algus- ja lõpusündmusi nii terve jälituse kui ka iga lõigu kohta. Kõik kuus TracingProcessor meetodit on abstraktsed: rakenda need kõik, isegi kui tühjadena, vastasel juhul instantsimine ebaõnnestub.

Siin on see, mida iga objekt tegelikult pakub: jälitusel on trace_id ja name, ning selle export() meetod tagastab ka group_id ja metadata; sellel puudub ajatempel. Lõigul on span_id, trace_id, parent_id, started_at ja ended_at (ISO 8601 stringid) ning span_data, mille atribuut type on agent, generation, function, handoff, guardrail, custom jne. Jälituse kestust mõõdetakse seega protsessoris.

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"[JÄLGITUSE ALGUS] {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"[JÄLGITUSE LÕPP] {trace.name} - kestus: {duration:.2f} s")

    def on_span_start(self, span: Span[Any]) -> None:
        print(f"  [LÕIGU ALGUS] {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"  [LÕIGU LÕPP] {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() lisab sinu protsessori algsele: jälitused jätkavad teekonda OpenAI armatuurlauale. set_trace_processors() asendab vaikimisi protsessorid: OpenAI ei saa enam midagi, kui sa ei lisa selle eksportijat ise nimekirja tagasi.

Eksportimine välistesse süsteemidesse

Vaadeldavuse tööriista jaoks tuleb lihtsalt lõigud ümber vormindada. Allpool olev näide kirjutab iga lõppenud lõigu kohta ühe JSON-realise, formaadi, mida enamik logikogureid osaleb tarbida; span.export() pakub juba täielikku sõnastikku.

import json
import logging
from typing import Any

from agents.tracing import Span, Trace, TracingProcessor

logger = logging.getLogger("agent-jalgitus")


class JsonExportProcessor(TracingProcessor):
    """Kirjutab iga lõppenud lõigu JSON-na logikogurile."""

    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

Jälgi, mida ekspordid: vaikimisi sisaldavad genereerimislõigud mudeli sisendeid ja väljundeid ning funktsioonilõigud tööriista argumente ja tulemusi. Et need välja jätta, edasta RunConfig(trace_include_sensitive_data=False) või määra keskkonnamuutuja OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Valmis integratsioonide jaoks loetleb SDK dokumentatsioon palju kolmandate osapoolte tööriistu, mis pakuvad oma protsessorit.

Ära kaota viimaseid jälitusi

Vaikimisi eksportija saadab jälitused taustal, iga paari sekundi tagant. Töötajas, mis töötleb ülesandeid ja ei peatu, või lühikeses skriptis, kutsu pärast jälituse sulgemist flush_traces(), et sundida saatmist:

from agents import flush_traces

with trace("igaoine-tootlemine"):
    await Runner.run(agent, "Tee kokkuvõte tänastest piletitest")
flush_traces()  # pärast jälituse lõppu, mitte kunagi keskel

Jälitamise keelamine

On üks juhtum, kus jälitamine takistab rohkem kui aitab: testikomplekt, mis käitab sadu mock-agentte ja saastab sinu armatuurlauda. Testides või kohaliku arenduse ajal saad selle seega keelata, kas globaalselt või ühe täitmise jaoks.

from agents import RunConfig, set_tracing_disabled

# Keela täielikult (või keskkonnamuutuja OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)

# Või ühe täitmise jaoks
result = await Runner.run(agent, "Testteade", run_config=RunConfig(tracing_disabled=True))

Viimane punkt, seekord lepinguline: dokumentatsiooni kohaselt ei ole jälitamine OpenAI-sse saadaval organisatsioonidele, kelle suhtes kehtib Nullandmete säilitamise (Zero Data Retention) poliitika. Sel juhul annavad sulle jälitused ainult sinu enda protsessor, mis on paigaldatud set_trace_processors() abil.

Peamised jälgitavad näitajad

Millele siis tähelepanu pöörata? Tootmises piisab kuuest näitajast, et hinnata agendi tervist. Kogulatentsus – aeg päringust lõpliku vastuseni – on see, mida kasutajad tunnevad; seda seletab kõige sagedamini pöörete arv, ehk kordi, kui agendi tsükkel käivitus. Tarbitud tokenid, nii sisend kui väljund ühe täitmise kohta, määravad sinu arve.

Ülejäänud kolm puudutavad kvaliteeti. Tööriista tõrgete määr, protsent tööriistadest, mis tagastavad vea, paljastab ebastabiilse kolmanda osapoole API või halvasti genereeritud argumendid. Turvapiirde käivitumise määr, nähtav guardrail lõikudes, mõõdab blokeeringute sagedust: järsk tõus annab märku kas rünnakust või liiga rangeks muutunud turvapiirdest. Lõpuks näitab üleandmiste jaotus, milline agent vastab kõige sagedamini – ja seega, kas sinu triaaž saadab päringud sinna, kuhu need kuuluvad.

Peamised punktid

  • SDK jälitab automaatselt iga täitmist OpenAI armatuurlauale (välja arvatud Nullandmete säilitamise poliitikaga organisatsioonid)
  • Üks trace() töövoogu kohta; märgi sammud custom_span() abil ja kasuta group_id vestluse jälituste sidumiseks
  • Jälitusel puudub ajatempel; lõigul on started_at, ended_at ja span_data.type
  • TracingProcessor rakendab oma kuut meetodit; add_trace_processor() lisab, set_trace_processors() asendab
  • trace_include_sensitive_data=False jätab sisendid ja väljundid välja; flush_traces() sunnib saatmist
  • Keela jälitamine testides käsuga set_tracing_disabled(True) või RunConfig(tracing_disabled=True)