Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Nyomkövetés és megfigyelhetőség

14. lecke 25 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Nyomkövetés és megfigyelhetőség
  2. Beépített nyomkövetés
  3. Nyomok elnevezése
  4. Munkafolyamatok lépésekre bontása
  5. Egyéni nyomkövetési feldolgozók
  6. Exportálás külső rendszerekbe
  7. Ne veszítsd el az utolsó nyomokat
  8. Nyomkövetés kikapcsolása
  9. Figyelemmel kísérendő kulcsmutatók
  10. Főbb megállapítások

Frissítve: 2026. november 3. A nyomkövetési feldolgozók korábban a trace.start_time, trace.end_time és span.name attribútumokat olvasták, amelyek nem léteznek az SDK-ban: egy nyomnak nincs időbélyege, míg egy span rendelkezik started_at, ended_at és span_data mezőkkel. Az exportáló feldolgozó nem valósította meg az on_trace_start absztrakt metódust: a példányosítása TypeError kivé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 a custom_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 az openai-agents 0.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éseket custom_span()-nel jelöld, és használd a group_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 és span_data.type attribútuma
  • Egy TracingProcessor implementálja a hat metódusát; az add_trace_processor() hozzáad, a set_trace_processors() lecserél
  • A trace_include_sensitive_data=False kizárja a bemeneteket és kimeneteket; a flush_traces() kényszeríti a küldést
  • Kapcsold ki a nyomkövetést tesztekben a set_tracing_disabled(True) vagy a RunConfig(tracing_disabled=True) használatával