Przejdź do głównej treści
Polski— Wybierz język
Menu

Śledzenie i obserwowalność

Lekcja 14 z 25 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Śledzenie i obserwowalność
  2. Wbudowane śledzenie
  3. Nadawanie nazw śladom
  4. Podział przepływu pracy na kroki
  5. Niestandardowe procesory śledzenia
  6. Eksportowanie do systemów zewnętrznych
  7. Nie trać ostatnich śladów
  8. Wyłączanie śledzenia
  9. Kluczowe wskaźniki do monitorowania
  10. Kluczowe wnioski

Zaktualizowano 3 listopada 2026. Procesory śledzenia wcześniej odczytywały trace.start_time, trace.end_time oraz span.name, które nie istnieją w SDK: ślad nie posiada znacznika czasu, a segment (span) zawiera started_at, ended_at i span_data. Procesor eksportu nie implementował metody abstrakcyjnej on_trace_start: jego instancjonowanie powodowało błąd TypeError. „Zagnieżdżone ślady“ tworzyły nowy ślad wewnątrz innego śladu, co SDK oznacza jako prawdopodobny błąd: kroki powinny teraz używać custom_span(). Dodatki: flush_traces(), obsługa danych wrażliwych oraz Zero Data Retention. Kod zweryfikowany z openai-agents 0.24.0. Źródła: Tracing (dokumentacja SDK) · openai-agents-python.

Śledzenie i obserwowalność

Agent działający w środowisku produkcyjnym jest czarną skrzynką, jeśli nie śledzisz jego działań. Gdy klient skarży się na absurdalną odpowiedź, nie masz ani dokładnego żądania, ani informacji o wywołanych narzędziach, ani wartości, które zwróciły. Śledzenie w SDK rejestruje każdy krok wykonania: wywołania modelu, użyte narzędzia, przekazania (handoffs) i blokady (guardrails). To Twoje główne narzędzie do debugowania, optymalizacji i audytu agentów.

Wbudowane śledzenie

Dobra wiadomość: nie musisz niczego włączać. SDK automatycznie śledzi każde wykonanie i domyślnie wysyła ślady do panelu OpenAI pod adresem platform.openai.com. Poniższy agent, napisany bez ani jednej instrukcji śledzenia, już generuje użyteczny ślad.

from agents import Agent, Runner, function_tool

@function_tool
def search_product(name: str) -> str:
    """Wyszukuje produkt w katalogu."""
    return f"Znaleziono produkt: {name}, cena 29,99 €"

agent = Agent(
    name="Agent sklepu",
    instructions="Pomagasz klientom znaleźć produkty.",
    tools=[search_product],
    model="gpt-5.6-terra",
)

# Każde wykonanie automatycznie tworzy ślad
result = Runner.run_sync(agent, "Wyszukaj laptopa pro")

Odwiedź panel, aby zobaczyć kompletny ślad: czas trwania, zużyte tokeny, wywołane narzędzia i końcową odpowiedź.

Nadawanie nazw śladom

Po kilkuset wykonaniach panel staje się nieodróżnialną listą. Nadaj swoim śladom znaczące nazwy, aby łatwo było je znaleźć – nazwa procesu biznesowego jest lepsza niż techniczny identyfikator.

from agents import trace

with trace("zamowienie-klienta-premium"):
    result = await Runner.run(
        agent,
        "Chcę zamówić 5 laptopów dla mojego zespołu",
    )

Nazwa śladu pojawia się w panelu i ułatwia filtrowanie.

Podział przepływu pracy na kroki

W przypadku przepływu pracy z wieloma wywołaniami otwórz jeden ślad wokół całości, a następnie oznacz każdy krok za pomocą custom_span(). Nie zagnieżdżaj trace() wewnątrz innego: SDK zgłosi wtedy ostrzeżenie Trace already exists. Creating a new trace, but this is probably a mistake. Segmenty (spans) są natomiast zaprojektowane do zagnieżdżania: każdy z nich znajduje się pod bieżącym segmentem.

from agents import Runner, custom_span, trace


async def process_order(message: str, conversation_id: str):
    with trace("przeplyw-zamowienia", group_id=conversation_id):
        with custom_span("krok-1-zrozumienie"):
            result_understanding = await Runner.run(triage_agent, message)

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

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

    return result_final.final_output

W panelu ślad przeplyw-zamowienia pokazuje trzy kroki, a pod każdym z nich automatyczne segmenty wykonania: agent, wywołania modelu, narzędzia. group_id łączy ślady z tej samej rozmowy, na przykład przy użyciu identyfikatora wątku.

Domyślnie SDK opakowuje każde Runner.run() w ślad o nazwie Agent workflow, a wewnątrz śladów znajdują się agent, każde generowanie modelu, każde wywołanie funkcji, blokady i przekazania. Aby uzyskać bardziej zwartą hierarchię, dokumentacja sugeruje wyłączenie automatycznych segmentów zadań i tur:

from agents import RunConfig

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

Niestandardowe procesory śledzenia

Panel OpenAI jest wygodny, ale Twój zespół operacyjny prawdopodobnie monitoruje wszystko inne gdzie indziej. Aby wysyłać ślady do własnego systemu, napisz procesor: otrzymuje on zdarzenia startu i końca, zarówno dla całego śladu, jak i dla każdego segmentu. Wszystkie sześć metod TracingProcessor jest abstrakcyjnych: musisz zaimplementować je wszystkie, nawet jeśli puste, w przeciwnym razie instancjonowanie się nie powiedzie.

Oto co faktycznie udostępnia każdy obiekt: ślad ma trace_id i name, a jego metoda export() zwraca również group_id i metadata; nie ma znacznika czasu. Segment ma span_id, trace_id, parent_id, started_at i ended_at (ciągi ISO 8601) oraz span_data, którego atrybut type to agent, generation, function, handoff, guardrail, custom i tak dalej. Czas trwania śladu jest więc mierzony w procesorze.

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"[START ŚLADU] {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"[KONIEC ŚLADU] {trace.name} - czas trwania: {duration:.2f} s")

    def on_span_start(self, span: Span[Any]) -> None:
        print(f"  [START SEGMENTU] {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"  [KONIEC SEGMENTU] {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() dodaje Twój procesor do oryginalnego: ślady nadal trafiają do panelu OpenAI. set_trace_processors() zastępuje domyślne procesory: nic nie trafia już do OpenAI, chyba że samodzielnie umieścisz jego eksporter na liście.

Eksportowanie do systemów zewnętrznych

W przypadku narzędzia do obserwowalności wystarczy sformatować segmenty na nowo. Poniższy przykład zapisuje jeden wiersz JSON na każdy zakończony segment – format, który większość kolektorów logów potrafi przyjąć; span.export() dostarcza już kompletny słownik.

import json
import logging
from typing import Any

from agents.tracing import Span, Trace, TracingProcessor

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


class JsonExportProcessor(TracingProcessor):
    """Zapisuje każdy zakończony segment jako JSON dla kolektora logów."""

    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

Uważaj na to, co eksportujesz: domyślnie segmenty generowania zawierają dane wejściowe i wyjściowe modelu, a segmenty funkcji zawierają argumenty narzędzi i wyniki. Aby je wykluczyć, przekaż RunConfig(trace_include_sensitive_data=False) lub ustaw zmienną środowiskową OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. W przypadku gotowych integracji dokumentacja SDK wymienia wiele narzędzi firm trzecich, które dostarczają własne procesory.

Nie trać ostatnich śladów

Domyślny eksporter wysyła ślady w tle, co kilka sekund. W workerze przetwarzającym zadania, który się nie zatrzymuje, lub w krótkim skrypcie, wywołaj flush_traces() po zamknięciu śladu, aby wymusić wysyłkę:

from agents import flush_traces

with trace("przetwarzanie-nocne"):
    await Runner.run(agent, "Podsumuj dzisiejsze zgłoszenia")
flush_traces()  # po zakończeniu śladu, nigdy w trakcie

Wyłączanie śledzenia

Istnieje jeden przypadek, w którym śledzenie bardziej przeszkadza niż pomaga: zestaw testów uruchamiający setki atrap agentów i zaśmiecający Twój panel. W testach lub podczas lokalnego rozwoju możesz więc wyłączyć tę funkcję, globalnie lub dla pojedynczego wykonania.

from agents import RunConfig, set_tracing_disabled

# Całkowite wyłączenie (lub zmienna środowiskowa OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)

# Lub dla pojedynczego wykonania
result = await Runner.run(agent, "Wiadomość testowa", run_config=RunConfig(tracing_disabled=True))

Jeszcze jedna kwestia, tym razem umowna: zgodnie z dokumentacją śledzenie w OpenAI nie jest dostępne dla organizacji objętych polityką Zero Data Retention. W takim przypadku tylko Twój własny procesor, zainstalowany za pomocą set_trace_processors(), zapewni Ci ślady.

Kluczowe wskaźniki do monitorowania

Na co więc patrzeć? W środowisku produkcyjnym sześć wskaźników wystarczy, aby ocenić kondycję agenta. Całkowita latencja – czas między żądaniem a końcową odpowiedzią – to coś, co odczuwają Twoi użytkownicy; najczęściej wyjaśnia ją liczba tur, czyli liczba wykonań pętli agenta. Zużyte tokeny, zarówno wejściowe, jak i wyjściowe na wykonanie, determinują Twój rachunek.

Pozostałe trzy dotyczą jakości. Wskaźnik awarii narzędzi, czyli procent narzędzi zwracających błąd, ujawnia niestabilne API strony trzeciej lub źle wygenerowane argumenty. Wskaźnik wyzwalania blokad, widoczny w segmentach guardrail, mierzy częstotliwość blokad: nagły skok sygnalizuje albo atak, albo blokadę, która stała się zbyt restrykcyjna. Na koniec rozklad przekazań mówi Ci, który agent odpowiada najczęściej – a tym samym, czy Twoje triage kieruje żądania tam, gdzie powinny trafić.

Kluczowe wnioski

  • SDK automatycznie śledzi każde wykonanie do panelu OpenAI (z wyjątkiem organizacji objętych polityką Zero Data Retention)
  • Jeden trace() na przepływ pracy; oznaczaj kroki za pomocą custom_span() i używaj group_id do łączenia śladów z rozmowy
  • Ślad nie ma znacznika czasu; segment ma started_at, ended_at i span_data.type
  • TracingProcessor implementuje swoje sześć metod; add_trace_processor() dodaje, set_trace_processors() zastępuje
  • trace_include_sensitive_data=False wyklucza dane wejściowe i wyjściowe; flush_traces() wymusza wysyłkę
  • Wyłącz śledzenie w testach za pomocą set_tracing_disabled(True) lub RunConfig(tracing_disabled=True)