Jälitamine ja vaadeldavus
Sellel lehel
Uuendatud 3. novembril 2026. Jälitusprotsessorid lugesid varem
trace.start_time,trace.end_timejaspan.name, mida SDK-s ei eksisteeri: jälitusel puudub ajatempel ja lõigul (span) on olemasstarted_at,ended_atningspan_data. Ekspordiprotsessor ei rakendanud abstraktset meetoditon_trace_start: selle instantsimine tekitas veaTypeError. “Pesastatud jälitused” lõid uue jälituse olemasoleva sees, mida SDK märgib tõenäolise veana: sammud kasutavad nüüdcustom_span(). Lisandused:flush_traces(), tundlike andmete käsitlemine ja Nullandmete säilitamine (Zero Data Retention). Kood on kontrollitud versioonigaopenai-agents0.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 sammudcustom_span()abil ja kasutagroup_idvestluse jälituste sidumiseks - Jälitusel puudub ajatempel; lõigul on
started_at,ended_atjaspan_data.type TracingProcessorrakendab oma kuut meetodit;add_trace_processor()lisab,set_trace_processors()asendabtrace_include_sensitive_data=Falsejätab sisendid ja väljundid välja;flush_traces()sunnib saatmist- Keela jälitamine testides käsuga
set_tracing_disabled(True)võiRunConfig(tracing_disabled=True)