Śledzenie i obserwowalność
Na tej stronie
Zaktualizowano 3 listopada 2026. Procesory śledzenia wcześniej odczytywały
trace.start_time,trace.end_timeorazspan.name, które nie istnieją w SDK: ślad nie posiada znacznika czasu, a segment (span) zawierastarted_at,ended_atispan_data. Procesor eksportu nie implementował metody abstrakcyjnejon_trace_start: jego instancjonowanie powodowało błądTypeError. „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 zopenai-agents0.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żywajgroup_iddo łączenia śladów z rozmowy - Ślad nie ma znacznika czasu; segment ma
started_at,ended_atispan_data.type TracingProcessorimplementuje swoje sześć metod;add_trace_processor()dodaje,set_trace_processors()zastępujetrace_include_sensitive_data=Falsewyklucza dane wejściowe i wyjściowe;flush_traces()wymusza wysyłkę- Wyłącz śledzenie w testach za pomocą
set_tracing_disabled(True)lubRunConfig(tracing_disabled=True)