Sporing og observerbarhed
På denne side
Opdateret 3. november 2026. Trace-processorer læste tidligere
trace.start_time,trace.end_timeogspan.name, som ikke findes i SDK’et: en trace har intet tidsstempel, og en span indeholderstarted_at,ended_atogspan_data. Eksport-processoren implementerede ikkeon_trace_start, en abstrakt metode: instantiering udløste enTypeError. “Nested traces” oprettede en ny trace inde i en trace, hvilket SDK’et flagrer som en sandsynlig fejl: trin bruger nucustom_span(). Tilføjelser:flush_traces(), håndtering af følsomme data og Zero Data Retention. Kode verificeret medopenai-agents0.24.0. Kilder: Tracing (SDK-dokumentation) · openai-agents-python.
Sporing og observerbarhed
En agent i produktion er en sort boks, hvis du ikke sporer dens handlinger. Når en kunde klager over et absurd svar, har du hverken den præcise anmodning, de værktøjer der blev kaldt, eller de værdier de returnerede. SDK’ets sporing registrerer hvert skridt i eksekveringen: modelkald, brugte værktøjer, overleveringer og guardrails. Dette er dit primære værktøj til fejlfinding, optimering og revision af dine agenter.
Indbygget sporing
Gode nyheder: Du behøver ikke aktivere noget. SDK’et sporer automatisk hver eksekvering og sender som standard spor til OpenAI-dashboardet på platform.openai.com. Agenten nedenfor, skrevet uden en eneste sporingsinstruks, producerer allerede en brugbar trace.
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",
)
# Every execution automatically creates a trace
result = Runner.run_sync(agent, "Search for the pro laptop")
Besøg dashboardet for at se den komplette trace: varighed, forbrugte tokens, kaldte værktøjer og det endelige svar.
Navngivning af traces
Efter et par hundrede eksekveringer bliver dashboardet til en udifferentieret liste. Giv dine traces meningsfulde navne, så du nemt kan finde dem – et navn baseret på forretningsgangen er bedre end et teknisk ID.
from agents import trace
with trace("premium-customer-order"):
result = await Runner.run(
agent,
"I want to order 5 laptops for my team",
)
Trace-navnet vises i dashboardet og gør filtrering lettere.
Opdeling af en workflow i trin
For en workflow med flere kald skal du åbne én trace omkring det hele og derefter markere hvert trin med custom_span(). Undgå at næste en trace() inde i en anden: SDK’et logger så advarslen Trace already exists. Creating a new trace, but this is probably a mistake. Spans er derimod designet til at kunne næstes: hver enkelt placeres under den aktuelle span.
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 dashboardet viser order-workflow-tracen de tre trin, og under hvert trin ses de automatiske spans for eksekvering: agent, modelkald, værktøjer. group_id linker traces fra samme samtale, for eksempel ved brug af din thread-ID.
Som standard pakker SDK’et hver Runner.run() ind i en trace med navnet Agent workflow, og inde i traces ses agenten, hver modelgenerering, hvert funktionskald, guardrails og overleveringer. For en mere kompakt hierarki foreslår dokumentationen at fjerne automatiske task- og turn-spans:
from agents import RunConfig
result = await Runner.run(
agent,
"Hello",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Brugerdefinerede trace-processorer
OpenAI-dashboardet er praktisk, men dit driftsteam overvåger sandsynligvis alt andet andre steder. For at sende spor til dit eget system skal du skrive en processor: den modtager start- og slutbegivenheder for både den komplette trace og for hver span. Alle seks metoder i TracingProcessor er abstrakte: implementer dem alle, selvom de er tomme, ellers vil instantieringen fejle.
Her er hvad hvert objekt faktisk eksponerer: en trace har en trace_id og et name, og dens export()-metode returnerer også group_id og metadata; den har intet tidsstempel. En span har span_id, trace_id, parent_id, started_at og ended_at (ISO 8601-strenge) samt span_data, hvis type-attribut er agent, generation, function, handoff, guardrail, custom og så videre. Trace-varigheden måles derfor i processoren.
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() tilføjer din processor til den oprindelige: spor fortsætter med at gå til OpenAI-dashboardet. set_trace_processors() erstatter standardprocessorerne: intet sendes længere til OpenAI, medmindre du selv sætter deres eksportør tilbage på listen.
Eksport til eksterne systemer
Til et observerbarhedsværktøj skal du blot omformatere spans. Eksemplet nedenfor skriver én JSON-linje per afsluttet span, et format de fleste log-collectors kan indlæse; span.export() leverer allerede en komplet ordbog.
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
Pas på, hvad du eksporterer: som standard indeholder generation-spans model-inputs og -outputs, og function-spans indeholder værktøjsargumenter og resultater. For at udelukke dem skal du sende RunConfig(trace_include_sensitive_data=False) eller sætte miljøvariablen OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Til færdige integrationer lister SDK-dokumentationen mange tredjepartsværktøjer, der leverer deres egen processor.
Mist ikke de sidste spor
Standard-eksportøren sender spor i baggrunden hvert par sekund. I en worker, der behandler opgaver uden at stoppe, eller i et kort script, skal du kalde flush_traces() efter lukning af tracen for at gennemtvinge sending:
from agents import flush_traces
with trace("nightly-processing"):
await Runner.run(agent, "Summarize today's tickets")
flush_traces() # after the trace ends, never in the middle
Deaktivering af sporing
Der er ét tilfælde, hvor sporing hindrer mere end den hjælper: en testsuite, der kører hundreder af mock-agenter og forurener dit dashboard. I tests eller under lokal udvikling kan du derfor deaktivere det, enten globalt eller for en enkelt eksekvering.
from agents import RunConfig, set_tracing_disabled
# Disable completely (or environment variable OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)
# Or for a single execution
result = await Runner.run(agent, "Test message", run_config=RunConfig(tracing_disabled=True))
Et sidste punkt, dette er kontraktuelt: ifølge dokumentationen er sporing til OpenAI ikke tilgængelig for organisationer, der er underlagt en Zero Data Retention-politik. I dette tilfælde er det kun din egen processor, installeret med set_trace_processors(), der vil give dig spor.
Nøgletal at overvåge
Hvad skal du så kigge efter? I produktion er seks indikatorer nok til at kvalificere en agents sundhedstilstand. Total latenstid – tiden mellem anmodning og endeligt svar – er det, dine brugere mærker; den forklares oftest af antallet af omdrejninger, altså hvor mange gange agent-loopen kørte. Forbrugte tokens, både input og output per eksekvering, driver din regning.
De andre tre relaterer sig til kvalitet. Fejlprocenten for værktøjer, procentdelen af værktøjer der returnerer en fejl, afslører en ustabil tredjeparts-API eller dårligt genererede argumenter. Udløsningsraten for guardrails, synlig i guardrail-spans, måler hyppigheden af blokeringer: en pludselig stigning signalerer enten et angreb eller en guardrail, der er blevet for streng. Endelig fortæller fordelingen af overleveringer dig, hvilken agent der svarer oftest – og dermed om din triage sender anmodninger hen, hvor de skal.
Vigtige pointer
- SDK’et sporer automatisk hver eksekvering til OpenAI-dashboardet (undtagen for organisationer med Zero Data Retention)
- Én
trace()per workflow; marker trin medcustom_span(), og bruggroup_idtil at linke traces fra en samtale - En trace har intet tidsstempel; en span har
started_at,ended_atogspan_data.type - En
TracingProcessorimplementerer sine seks metoder;add_trace_processor()tilføjer,set_trace_processors()erstatter trace_include_sensitive_data=Falseudelukker inputs og outputs;flush_traces()gennemtvinger sending- Deaktiver sporing i tests med
set_tracing_disabled(True)ellerRunConfig(tracing_disabled=True)