Nyomkövetés és megfigyelhetőség
Ezen az oldalon
Frissítve: 2026. november 3. A nyomkövetési feldolgozók korábban a
trace.start_time,trace.end_timeésspan.nameattribútumokat olvasták, amelyek nem léteznek az SDK-ban: egy nyomnak nincs időbélyege, míg egy span rendelkezikstarted_at,ended_atésspan_datamezőkkel. Az exportáló feldolgozó nem valósította meg azon_trace_startabsztrakt metódust: a példányosításaTypeErrorkivételt dobott. A „beágyazott nyomok“ egy új nyomt hoztak létre egy nyomon belül, amit az SDK valószínű hibaként jelöl: a lépések most acustom_span()használatát igénylik. Újdonságok:flush_traces(), érzékeny adatok kezelése és a Nulla Adatmegőrzés (Zero Data Retention). A kód ellenőrizve azopenai-agents0.24.0 verzióval. Források: Tracing (SDK dokumentáció) · openai-agents-python.
Nyomkövetés és megfigyelhetőség
Egy éles környezetben futó ügynök fekete doboz marad, ha nem követed nyomon a lépéseit. Amikor egy ügyfél abszurd válaszra panaszkodik, nincs meg sem a pontos kérés, sem a meghívott eszközök, sem a visszatérési értékeik. Az SDK nyomkövetési funkciója rögzíti a végrehajtás minden lépését: modellhívásokat, használt eszközöket, átadásokat (handoffs) és biztonsági korlátokat (guardrails). Ez az elsődleges eszközöd a hibakereséshez, optimalizáláshoz és az ügynökeid auditálásához.
Beépített nyomkövetés
Jó hír: semmit sem kell engedélyezned. Az SDK automatikusan nyomkövet minden végrehajtást, és alapértelmezetten az OpenAI irányítópultjára (platform.openai.com) küldi az adatokat. Az alábbi ügynök, amelyet egyetlen nyomkövetési utasítás nélkül írtak meg, már most is használható nyomt generál.
from agents import Agent, Runner, function_tool
@function_tool
def search_product(name: str) -> str:
"""Keresés egy termék után a katalógusban."""
return f"Termék megtalálva: {name}, ár 29,99 €"
agent = Agent(
name="Shop Agent",
instructions="Segítesz az ügyfeleknek termékeket találni.",
tools=[search_product],
model="gpt-5.6-terra",
)
# Minden végrehajtás automatikusan létrehoz egy nyomt
result = Runner.run_sync(agent, "Keresd meg a pro laptopot")
Látogass el az irányítópultra a teljes nyom megtekintéséhez: időtartam, felhasznált tokenek, meghívott eszközök és a végső válasz.
Nyomok elnevezése
Néhány száz végrehajtás után az irányítópult áttekinthetetlen listává válik. Adj értelmes neveket a nyomjaidnak, hogy könnyen megtaláld őket – egy üzleti folyamatnév sokkal jobb, mint egy technikai azonosító.
from agents import trace
with trace("premium-vasarlo-rendeles"):
result = await Runner.run(
agent,
"Szeretnék rendelni 5 laptopot a csapatomnak",
)
A nyom neve megjelenik az irányítópulton, és megkönnyíti a szűrést.
Munkafolyamatok lépésekre bontása
Több hívást tartalmazó munkafolyamat esetén nyiss egy nyomt az egész folyamat köré, majd jelöld meg az egyes lépéseket a custom_span() segítségével. Ne ágyazz be egy trace()-t egy másikba: az SDK ekkor a Trace already exists. Creating a new trace, but this is probably a mistake. figyelmeztetést naplózza. A spanok viszont kifejezetten arra készültek, hogy egymásba ágyazódjanak: mindegyik az aktuális span alá kerül.
from agents import Runner, custom_span, trace
async def process_order(message: str, conversation_id: str):
with trace("rendeles-munkafolyamat", group_id=conversation_id):
with custom_span("1-lepes-megertes"):
result_understanding = await Runner.run(triage_agent, message)
with custom_span("2-lepes-feldolgozas"):
result_processing = await Runner.run(
order_agent,
result_understanding.to_input_list(),
)
with custom_span("3-lepes-megerosites", data={"step": 3}):
result_final = await Runner.run(
confirmation_agent,
result_processing.to_input_list(),
)
return result_final.final_output
Az irányítópulton a rendeles-munkafolyamat nyom mutatja a három lépést, és mindegyik alatt az automatikus végrehajtási spanokat: ügynök, modellhívások, eszközök. A group_id összeköti az ugyanabból a beszélgetésből származó nyomokat, például a szálazonosítód (thread ID) használatával.
Alapértelmezetten az SDK minden Runner.run() hívást egy Agent workflow nevű nyomba csomagol, és a nyomokon belül rögzíti az ügynököt, minden modellgenerálást, minden függvényhívást, a biztonsági korlátokat és az átadásokat. A tömörebb hierarchia érdekében a dokumentáció javasolja az automatikus feladat- és fordulónapok (task and turn spans) kikapcsolását:
from agents import RunConfig
result = await Runner.run(
agent,
"Szia",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Egyéni nyomkövetési feldolgozók
Az OpenAI irányítópult kényelmes, de az üzemeltető csapatod valószínűleg máshol monitorozza a többi rendszert. Ha saját rendszerbe szeretnéd küldeni a nyomokat, írj egy feldolgozót: ez kapja meg a kezdő és záró eseményeket mind a teljes nyomra, mind az egyes spanokra vonatkozóan. A TracingProcessor mind a hat metódusa absztrakt: mindet implementálnod kell, még ha üresen is, különben a példányosítás sikertelen lesz.
Íme, mit tesznek elérhetővé ezek az objektumok valójában: egy nyomnak van trace_id-ja és name-je, az export() metódusa pedig visszaadja a group_id-t és a metadata-t is; nincs időbélyege. Egy spannak van span_id-ja, trace_id-ja, parent_id-ja, started_at és ended_at mezője (ISO 8601 formátumú karakterláncok), valamint span_data-ja, amelynek type attribútuma lehet agent, generation, function, handoff, guardrail, custom és így tovább. A nyom időtartamát tehát a feldolgozóban kell mérni.
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"[NYOM INDUL] {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"[NYOM VÉGE] {trace.name} - időtartam: {duration:.2f} mp")
def on_span_start(self, span: Span[Any]) -> None:
print(f" [SPAN INDUL] {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 VÉGE] {span.span_data.type} - {duration.total_seconds():.2f} mp")
def shutdown(self) -> None:
pass
def force_flush(self) -> None:
pass
add_trace_processor(MyTraceProcessor())
Az add_trace_processor() hozzáadja a feldolgozódat az eredetihez: a nyomok továbbra is eljutnak az OpenAI irányítópultra. A set_trace_processors() lecseréli az alapértelmezett feldolgozókat: innentől semmi sem megy az OpenAI-hoz, hacsak nem teszed vissza manuálisan az exportálójukat a listába.
Exportálás külső rendszerekbe
Egy megfigyelési eszközhöz csak át kell formáznod a spanokat. Az alábbi példa minden befejezett spanról egy JSON-sort ír, egy formátumot, amelyet a legtöbb naplógyűjtő ismer; a span.export() már eleve egy teljes szótárat biztosít.
import json
import logging
from typing import Any
from agents.tracing import Span, Trace, TracingProcessor
logger = logging.getLogger("agent-traces")
class JsonExportProcessor(TracingProcessor):
"""Minden befejezett spant JSON-ként ír ki egy naplógyűjtő számára."""
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
Figyeld, mit exportálsz: alapértelmezetten a generációs spanok tartalmazzák a modell bemeneteit és kimeneteit, a függvényspanok pedig az eszközök argumentumait és eredményeit. Ezek kizárásához add meg a RunConfig(trace_include_sensitive_data=False) paramétert, vagy állítsd be a OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false környezeti változót. A kész integrációkhoz az SDK dokumentációja számos harmadik féltől származó eszközt sorol fel, amelyek saját feldolgozót biztosítanak.
Ne veszítsd el az utolsó nyomokat
Az alapértelmezett exportáló a háttérben, néhány másodpercenként küldi el a nyomokat. Egy feladatokat feldolgozó és meg nem álló munkamenetben, vagy egy rövid szkriptben hívd meg a flush_traces() függvényt a nyom lezárása után a küldés kényszerítéséhez:
from agents import flush_traces
with trace("ejszakai-feldolgozas"):
await Runner.run(agent, "Foglald össze a mai jegyeket")
flush_traces() # a nyom vége után, soha ne közben
Nyomkövetés kikapcsolása
Van egy eset, amikor a nyomkövetés inkább hátráltat, mint segít: egy tesztkészlet, amely százszámra futtat mock ügynököket, és elszennyezi az irányítópultodat. Tesztek során vagy helyi fejlesztés közben ezért kikapcsolhatod, akár globálisan, akár egyetlen végrehajtásra.
from agents import RunConfig, set_tracing_disabled
# Teljes kikapcsolás (vagy a OPENAI_AGENTS_DISABLE_TRACING=1 környezeti változó)
set_tracing_disabled(True)
# Vagy egyetlen végrehajtásra
result = await Runner.run(agent, "Teszt üzenet", run_config=RunConfig(tracing_disabled=True))
Egy utolsó, szerződéses pont: a dokumentáció szerint az OpenAI felé történő nyomkövetés nem elérhető azoknak a szervezeteknek, amelyekre a Nulla Adatmegőrzési (Zero Data Retention) irányelv vonatkozik. Ebben az esetben csak a saját, a set_trace_processors() segítségével telepített feldolgozód biztosít nyomokat.
Figyelemmel kísérendő kulcsmutatók
Most akkor mire kell figyelned? Éles környezetben hat mutató elég egy ügynök egészségének megítéléséhez. A teljes késleltetés – a kérés és a végső válasz közötti idő – az, amit a felhasználóid éreznek; ezt leggyakrabban a fordulók száma magyarázza, vagyis hogy hányszor futott le az ügynök ciklusa. A felhasznált tokenek, mind bemenet, mind kimenet tekintetében végrehajtásonként, közvetlenül befolyásolják a számládat.
A másik három a minőségre vonatkozik. Az eszközhibák aránya, azaz azon eszközök százaléka, amelyek hibát adnak vissza, instabil harmadik féltől származó API-ra vagy rosszul generált argumentumokra utal. A biztonsági korlátok aktiválódási rátája, amely a guardrail spanokban látható, a blokkolások gyakoriságát méri: egy hirtelen csúcs vagy támadást jelez, vagy azt, hogy egy biztonsági korlát túl szigorúvá vált. Végül az átadások (handoff) eloszlása megmutatja, melyik ügynök válaszol a leggyakrabban – és így azt is, hogy a triázsod jó helyre irányítja-e a kéréseket.
Főbb megállapítások
- Az SDK automatikusan nyomkövet minden végrehajtást az OpenAI irányítópultra (kivéve a Nulla Adatmegőrzési irányelv alatt álló szervezeteket)
- Munkafolyamatonként egy
trace(); a lépéseketcustom_span()-nel jelöld, és használd agroup_id-t a beszélgetésből származó nyomok összekötésére - Egy nyomnak nincs időbélyege; egy spannak van
started_at,ended_atésspan_data.typeattribútuma - Egy
TracingProcessorimplementálja a hat metódusát; azadd_trace_processor()hozzáad, aset_trace_processors()lecserél - A
trace_include_sensitive_data=Falsekizárja a bemeneteket és kimeneteket; aflush_traces()kényszeríti a küldést - Kapcsold ki a nyomkövetést tesztekben a
set_tracing_disabled(True)vagy aRunConfig(tracing_disabled=True)használatával