Spårning och observerbarhet
På denna sida
Uppdaterad 3 november 2026. Spårningsprocessorer läste tidigare
trace.start_time,trace.end_timeochspan.name, vilka inte finns i SDK:t: en spårning har ingen tidsstämpel, och en span bär påstarted_at,ended_atochspan_data. Exportprocessorn implementerade inteon_trace_start, en abstrakt metod: att instansiera den gav ettTypeError. “Nästlade spårningar” skapade en ny spårning inuti en spårning, vilket SDK:t flaggar som ett troligt fel: steg använder nucustom_span(). Tillägg:flush_traces(), hantering av känsliga data och Zero Data Retention. Koden verifierad medopenai-agents0.24.0. Källor: Tracing (SDK-dokumentation) · openai-agents-python.
Spårning och observerbarhet
En agent i produktion är en svart låda om du inte spårar dess handlingar. När en kund klagar på ett absurt svar har du varken den exakta begäran, de verktyg som anropades eller de värden de returnerade. SDK:ts spårning registrerar varje steg i körningen: modellanrop, använda verktyg, överlämningar och skyddsräcken. Detta är ditt främsta verktyg för felsökning, optimering och granskning av dina agenter.
Inbyggd spårning
Goda nyheter: du behöver inte aktivera något. SDK:t spårar automatiskt varje körning och skickar som standard spårningar till OpenAI:s instrumentpanel på platform.openai.com. Agenten nedan, skriven utan en enda spårningsinstruktion, producerar redan en användbar spårning.
from agents import Agent, Runner, function_tool
@function_tool
def search_product(name: str) -> str:
"""Searches for a product in the catalog."""
return f"Product found: {name}, price €29.99"
agent = Agent(
name="Shop Agent",
instructions="You help customers find products.",
tools=[search_product],
model="gpt-5.6-terra",
)
# Varje körning skapar automatiskt en spårning
result = Runner.run_sync(agent, "Search for the pro laptop")
Besök instrumentpanelen för att se hela spårningen: varaktighet, förbrukade tokens, anropade verktyg och det slutgiltiga svaret.
Namnge spårningar
Efter några hundra körningar blir instrumentpanelen en odifferentierad lista. Ge dina spårningar meningsfulla namn så att du lätt hittar dem – ett namn baserat på affärsflödet är bättre än ett tekniskt ID.
from agents import trace
with trace("premium-customer-order"):
result = await Runner.run(
agent,
"I want to order 5 laptops for my team",
)
Spårningens namn visas i instrumentpanelen och underlättar filtrering.
Dela upp ett arbetsflöde i steg
För ett arbetsflöde med flera anrop öppnar du en spårning runt hela processen och markerar sedan varje steg med custom_span(). Nästla inte en trace() inuti en annan: SDK:t loggar då varningen Trace already exists. Creating a new trace, but this is probably a mistake. Span:ar är däremot designade för att nästlas: var och en placeras under den aktuella span:en.
from agents import Runner, custom_span, trace
async def process_order(message: str, conversation_id: str):
with trace("order-workflow", group_id=conversation_id):
with custom_span("step-1-understanding"):
result_understanding = await Runner.run(triage_agent, message)
with custom_span("step-2-processing"):
result_processing = await Runner.run(
order_agent,
result_understanding.to_input_list(),
)
with custom_span("step-3-confirmation", data={"step": 3}):
result_final = await Runner.run(
confirmation_agent,
result_processing.to_input_list(),
)
return result_final.final_output
I instrumentpanelen visar spårningen order-workflow de tre stegen, och under varje visas de automatiska span:arna för körningen: agent, modellanrop, verktyg. group_id länkar spårningar från samma konversation, till exempel genom att använda ditt tråd-ID.
Som standard slår SDK:t in varje Runner.run() i en spårning med namnet Agent workflow, och inuti spårningar finns agenten, varje modellgenerering, varje funktionsanrop, skyddsräcken och överlämningar. För en mer kompakt hierarki föreslår dokumentationen att du klipper bort automatiska uppgifts- och varvspan:ar:
from agents import RunConfig
result = await Runner.run(
agent,
"Hello",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Anpassade spårningsprocessorer
OpenAI:s instrumentpanel är bekväm, men ditt driftteam övervakar sannolikt allt annat någon annanstans. För att skicka spårningar till ditt eget system skriver du en processor: den tar emot start- och slutthändelser, både för hela spårningen och för varje span. Alla sex metoderna i TracingProcessor är abstrakta: implementera dem alla, även om de är tomma, annars misslyckas instansieringen.
Här är vad varje objekt faktiskt exponerar: en spårning har ett trace_id och ett name, och dess export()-metod returnerar även group_id och metadata; den har ingen tidsstämpel. En span har span_id, trace_id, parent_id, started_at och ended_at (ISO 8601-strängar) samt span_data, vars type-attribut är agent, generation, function, handoff, guardrail, custom och så vidare. Spårningens varaktighet mäts alltså i processorn.
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"[TRACE START] {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"[TRACE END] {trace.name} - duration: {duration:.2f} s")
def on_span_start(self, span: Span[Any]) -> None:
print(f" [SPAN START] {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 END] {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() lägger till din processor till den ursprungliga: spårningar fortsätter att gå till OpenAI:s instrumentpanel. set_trace_processors() ersätter standardprocessorerna: inget går längre till OpenAI om du inte själv lägger tillbaka dess exportör i listan.
Exportera till externa system
För ett observabilitetsverktyg behöver du bara formatera om span:arna. Exemplet nedan skriver en JSON-rad per avslutad span, ett format som de flesta loggsamlare kan ta emot; span.export() tillhandahåller redan en komplett ordbok.
import json
import logging
from typing import Any
from agents.tracing import Span, Trace, TracingProcessor
logger = logging.getLogger("agent-traces")
class JsonExportProcessor(TracingProcessor):
"""Writes each finished span as JSON, for a log collector."""
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
Var försiktig med vad du exporterar: som standard innehåller genereringsspan:ar modellens indata och utdata, och funktionsspan:ar innehåller verktygsargument och resultat. För att exkludera dessa skickar du RunConfig(trace_include_sensitive_data=False) eller sätter miljövariabeln OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. För färdiga integrationer listar SDK:dokumentationen många tredjepartsverktyg som tillhandahåller sin egen processor.
Tappa inte bort de sista spårningarna
Standardexportören skickar spårningar i bakgrunden var fewe sekunder. I en worker som bearbetar uppgifter utan att stoppa, eller i ett kort skript, anropar du flush_traces() efter att spårningen stängts för att tvinga fram sändning:
from agents import flush_traces
with trace("nightly-processing"):
await Runner.run(agent, "Summarize today's tickets")
flush_traces() # efter att spårningen avslutats, aldrig mitt i
Inaktivera spårning
Det finns ett fall där spårning stjälper mer än den hjälper: en testsvit som kör hundratals mockade agenter och förorenar din instrumentpanel. I tester eller under lokal utveckling kan du därför inaktivera det, antingen globalt eller för en enda körning.
from agents import RunConfig, set_tracing_disabled
# Inaktivera helt (eller miljövariabeln OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)
# Eller för en enda körning
result = await Runner.run(agent, "Test message", run_config=RunConfig(tracing_disabled=True))
En sista punkt, denna avtalsenlig: enligt dokumentationen är spårning till OpenAI inte tillgänglig för organisationer som omfattas av en policy för Zero Data Retention. I detta fall är det bara din egen processor, installerad med set_trace_processors(), som ger dig spårningar.
Viktiga nyckeltal att övervaka
Vad ska du då titta på? I produktion räcker sex indikatorer för att kvalificera en agents hälsa. Total latens – tiden mellan begäran och slutgiltigt svar – är det dina användare känner av; den förklaras oftast av antalet varv, det vill säga hur många gånger agentloopen kördes. Förbrukade tokens, både indata och utdata per körning, driver din faktura.
De andra tre rör kvalitet. Felprocenten för verktyg, andelen verktyg som returnerar ett fel, avslöjar ett instabilt tredjeparts-API eller dåligt genererade argument. Aktiveringsfrekvensen för skyddsräcken, synlig i guardrail-span:ar, mäter frekvensen av blockeringar: en plötslig topp signalerar antingen en attack eller att ett skyddsräcke blivit för strikt. Slutligen berättar fördelningen av överlämningar vilken agent som svarar oftast – och därmed om din triage skickar begäranden dit de ska.
Viktiga punkter
- SDK:t spårar automatiskt varje körning till OpenAI:s instrumentpanel (utom för organisationer med Zero Data Retention)
- En
trace()per arbetsflöde; markera steg medcustom_span()och användgroup_idför att länka spårningar från en konversation - En spårning har ingen tidsstämpel; en span har
started_at,ended_atochspan_data.type - En
TracingProcessorimplementerar sina sex metoder;add_trace_processor()lägger till,set_trace_processors()ersätter trace_include_sensitive_data=Falseexkluderar indata och utdata;flush_traces()tvingar fram sändning- Inaktivera spårning i tester med
set_tracing_disabled(True)ellerRunConfig(tracing_disabled=True)