Izsekojamība un novērojamība
Šajā lapā
Atjaunināts 2026. gada 3. novembrī. Iepriekš izsekošanas procesori nolasīja
trace.start_time,trace.end_timeunspan.name, kas SDK neeksistē: izsekošanai nav laika zīmoga, bet diapazonam (span) irstarted_at,ended_atunspan_data. Eksporta procesors neieviesa abstrakto metodion_trace_start: tā inicializēšana izraisījaTypeError. “Ligzdotas izsekošanas” radīja jaunu izsekošanu citas iekšienē, ko SDK atzīmē kā iespējamu kļūdu: tagad soļos izmantocustom_span(). Papildinājumi:flush_traces(), sensitīvu datu apstrāde un nulles datu saglabāšana (Zero Data Retention). Kods pārbaudīts aropenai-agents0.24.0. Avoti: Tracing (SDK dokumentācija) · openai-agents-python.
Izsekojamība un novērojamība
Aģents darbības vidē ir melnā kaste, ja tu neizseko tā darbības. Kad klients sūdzas par absurdu atbildi, tev nav nedz precīzā pieprasījuma, nedz izsaukto rīku, nedz to atgriezto vērtību. SDK izsekošana fiksē katru izpildes soli: modeļa izsaukumus, izmantotos rīkus, nodošanas (handoffs) un aizsargbarjeras. Tas ir tavs galvenais rīks aģentu atkļūdošanai, optimizēšanai un auditēšanai.
Iebūvētā izsekošana
Labās ziņas: tev nekas nav jāaktivizē. SDK automātiski izseko katru izpildi un pēc noklusējuma nosūta datus uz OpenAI paneli vietnē platform.openai.com. Tālāk redzamais aģents, uzrakstīts bez nevienas izsekošanas instrukcijas, jau ģenerē lietojamu izsekošanas ierakstu.
from agents import Agent, Runner, function_tool
@function_tool
def search_product(name: str) -> str:
"""Meklē produktu katalogā."""
return f"Atrasts produkts: {name}, cena 29,99 €"
agent = Agent(
name="Veikala aģents",
instructions="Tu palīdzi klientiem atrast produktus.",
tools=[search_product],
model="gpt-5.6-terra",
)
# Katra izpilde automātiski rada izsekošanas ierakstu
result = Runner.run_sync(agent, "Meklē pro klases portatīvo datoru")
Apmeklē paneli, lai redzētu pilnu izsekošanas ierakstu: ilgumu, patērētos tokenus, izsauktos rīkus un gala atbildi.
Izsekošanas ierakstu nosaukšana
Pēc dažiem simtiem izpildu paneļa saraksts kļūst vienveidīgs. Piešķir saviem izsekošanas ierakstiem jēdzīgus nosaukumus, lai tos viegli atrastu — biznesa procesa nosaukums ir labāks par tehnisku ID.
from agents import trace
with trace("premium-klienta-pasutijums"):
result = await Runner.run(
agent,
"Vēlos pasūtīt 5 portatīvos datorus savai komandai",
)
Izsekošanas nosaukums parādās panelī un atvieglo filtrēšanu.
Darbplūsmas sadalīšana soļos
Darbplūsmai ar vairākiem izsaukumiem izveido vienu izsekošanas ierakstu ap visu procesu, tad katru soli atzīmē ar custom_span(). Nelieto trace() ligzdoti cita trace() iekšienē: tad SDK reģistrē brīdinājumu Trace already exists. Creating a new trace, but this is probably a mistake. Diapazoni (spans) turpretī ir paredzēti ligzdošanai: katrs atrodas zem pašreizējā diapazona.
from agents import Runner, custom_span, trace
async def process_order(message: str, conversation_id: str):
with trace("pasutijuma-darbplūsma", group_id=conversation_id):
with custom_span("1-solis-izpratne"):
result_understanding = await Runner.run(triage_agent, message)
with custom_span("2-solis-apstrade"):
result_processing = await Runner.run(
order_agent,
result_understanding.to_input_list(),
)
with custom_span("3-solis-apstiprinajums", data={"step": 3}):
result_final = await Runner.run(
confirmation_agent,
result_processing.to_input_list(),
)
return result_final.final_output
Panelī izsekošanas ieraksts pasutijuma-darbplūsma rāda trīs soļus, un zem katra — automātiskos izpildes diapazonus: aģents, modeļa izsaukumi, rīki. group_id saista vienas sarunas izsekošanas ierakstus, piemēram, izmantojot tavu pavediena ID.
Pēc noklusējuma SDK ietver katru Runner.run() izsekošanas ierakstā ar nosaukumu Agent workflow, un tajā iekšienē — aģentu, katru modeļa ģenerēšanu, katru funkcijas izsaukumu, aizsargbarjeras un nodošanas. Kompaktākai hierarhijai dokumentācija iesaka izslēgt automātiskos uzdevumu un kārtu diapazonus:
from agents import RunConfig
result = await Runner.run(
agent,
"Sveiki",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Pielāgoti izsekošanas procesori
OpenAI panelis ir ērts, taču tava operāciju komanda, visticamāk, visu pārējo uzrauga citur. Lai nosūtītu datus uz savu sistēmu, uzraksti procesoru: tas saņem sākuma un beigu notikumus gan visai izsekošanai, gan katram diapazonam. Visas sešas TracingProcessor metodes ir abstraktas: tās visas ir jāievieš, pat ja tukšas, pretējā gadījumā inicializēšana neizdosies.
Lūk, ko katrs objekts faktiski piedāvā: izsekošanai ir trace_id un name, un tās export() metode atgriež arī group_id un metadata; tai nav laika zīmoga. Diapazonam ir span_id, trace_id, parent_id, started_at un ended_at (ISO 8601 virknes) un span_data, kura atribūts type ir agent, generation, function, handoff, guardrail, custom utt. Tādējādi izsekošanas ilgumu mēra procesorā.
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"[IZSEKOŠANAS SĀKUMS] {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"[IZSEKOŠANAS BEIGAS] {trace.name} - ilgums: {duration:.2f} s")
def on_span_start(self, span: Span[Any]) -> None:
print(f" [DIAPAZONA SĀKUMS] {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" [DIAPAZONA BEIGAS] {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() pievieno tavu procesoru oriģinālajam: izsekošanas dati turpina nonākt OpenAI panelī. set_trace_processors() aizvieto noklusējuma procesorus: OpenAI vairs nekas nenonāk, ja vien pats manuāli neatgriezīsi to eksportētāju sarakstā.
Eksportēšana uz ārējām sistēmām
Novērojamības rīkam tev tikai jāpārformatē diapazoni. Tālāk redzamais piemērs katram pabeigtam diapazonam raksta vienu JSON rindiņu — formātu, ko pazīst vairums žurnālu vākšanas rīku; span.export() jau nodrošina pilnu vārdnīcu.
import json
import logging
from typing import Any
from agents.tracing import Span, Trace, TracingProcessor
logger = logging.getLogger("agent-traces")
class JsonExportProcessor(TracingProcessor):
"""Raksta katru pabeigtu diapazonu kā JSON žurnālu vākšanas rīkam."""
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
Uzmanies, ko eksportē: pēc noklusējuma ģenerēšanas diapazoni satur modeļa ievades un izvades, bet funkciju diapazoni — rīku argumentus un rezultātus. Lai tos izslēgtu, nodod RunConfig(trace_include_sensitive_data=False) vai iestati vides mainīgo OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Gataviem integrācijas risinājumiem SDK dokumentācija uzskaita daudzus trešo pušu rīkus, kas nodrošina savus procesorus.
Nezaudē pēdējos izsekošanas ierakstus
Noklusējuma eksportētājs izsekošanas datus nosūta fonā ik pēc dažām sekundēm. Strādniekā, kas apstrādā uzdevumus un neapstājas, vai īsā skriptā pēc izsekošanas ieraksta aizvēršanas izsauc flush_traces(), lai piespiestu nosūtīšanu:
from agents import flush_traces
with trace("nakts-apstrade"):
await Runner.run(agent, "Apkopoj šodienas biļetes")
flush_traces() # pēc izsekošanas beigām, nekad vidū
Izsekošanas atspējošana
Ir viens gadījums, kad izsekošana vairāk traucē nekā palīdz: testu komplekts, kas palaiž simtiem mock aģentu un piesārņo tavu paneli. Testos vai lokālās izstrādes laikā to vari atspējot — vai nu globāli, vai vienai izpildei.
from agents import RunConfig, set_tracing_disabled
# Pilnībā atspējot (vai vides mainīgais OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)
# Vai vienai izpildei
result = await Runner.run(agent, "Testa ziņojums", run_config=RunConfig(tracing_disabled=True))
Vēl viens punkts, šoreiz līgumisks: saskaņā ar dokumentāciju izsekošana uz OpenAI nav pieejama organizācijām, uz kurām attiecas nulles datu saglabāšanas (Zero Data Retention) politika. Šādā gadījumā izsekošanas datus nodrošinās tikai tavs paša procesors, uzstādīts ar set_trace_processors().
Galvenie uzraudzāmie rādītāji
Ko tieši tev vajadzētu vērot? Darbības vidē pietiek ar sešiem rādītājiem, lai novērtētu aģenta veselību. Kopējā latentums — laiks starp pieprasījumu un gala atbildi — ir tas, ko sajūt tavi lietotāji; to visbiežāk nosaka kārtu skaits, proti, cik reižu aģenta cikls ir izpildījies. Patērētie tokeni, gan ievade, gan izvade vienā izpildē, nosaka tavus izdevumus.
Pārējie trīs attiecas uz kvalitāti. Rīku kļūmju līmenis — procentuālā daļa rīku, kas atgriež kļūdu — norāda uz nestabilu trešās puses API vai slikti ģenerētiem argumentiem. Aizsargbarjeru aktivizēšanās līmenis, redzams guardrail diapazonos, mēra bloķēšanas biežumu: pēkšņs pieaugums signalizē vai nu uzbrukumu, vai pārāk stingru aizsargbarjeru. Visbeidzot, nodošanu sadalījums parāda, kurš aģents atbild visbiežāk — un tādējādi, vai tava triāža nosūta pieprasījumus tur, kur tiem jānonāk.
Galvenās atziņas
- SDK automātiski izseko katru izpildi uz OpenAI paneli (izņemot organizācijas ar nulles datu saglabāšanas politiku)
- Viena
trace()vienai darbplūsmai; soļus atzīmē arcustom_span(), un izmantogroup_id, lai saistītu vienas sarunas izsekošanas ierakstus - Izsekošanai nav laika zīmoga; diapazonam ir
started_at,ended_atunspan_data.type TracingProcessorievieš visas sešas metodes;add_trace_processor()pievieno,set_trace_processors()aizvietotrace_include_sensitive_data=Falseizslēdz ievades un izvades;flush_traces()piespiež nosūtīšanu- Testos atspējo izsekošanu ar
set_tracing_disabled(True)vaiRunConfig(tracing_disabled=True)