Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Sporing og observerbarhed

Lektion 14 af 25 Opdateret 3. november 2026 Udvikler
På denne side
  1. Sporing og observerbarhed
  2. Indbygget sporing
  3. Navngivning af traces
  4. Opdeling af en workflow i trin
  5. Brugerdefinerede trace-processorer
  6. Eksport til eksterne systemer
  7. Mist ikke de sidste spor
  8. Deaktivering af sporing
  9. Nøgletal at overvåge
  10. Vigtige pointer

Opdateret 3. november 2026. Trace-processorer læste tidligere trace.start_time, trace.end_time og span.name, som ikke findes i SDK’et: en trace har intet tidsstempel, og en span indeholder started_at, ended_at og span_data. Eksport-processoren implementerede ikke on_trace_start, en abstrakt metode: instantiering udløste en TypeError. “Nested traces” oprettede en ny trace inde i en trace, hvilket SDK’et flagrer som en sandsynlig fejl: trin bruger nu custom_span(). Tilføjelser: flush_traces(), håndtering af følsomme data og Zero Data Retention. Kode verificeret med openai-agents 0.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.

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 med custom_span(), og brug group_id til at linke traces fra en samtale
  • En trace har intet tidsstempel; en span har started_at, ended_at og span_data.type
  • En TracingProcessor implementerer sine seks metoder; add_trace_processor() tilføjer, set_trace_processors() erstatter
  • trace_include_sensitive_data=False udelukker inputs og outputs; flush_traces() gennemtvinger sending
  • Deaktiver sporing i tests med set_tracing_disabled(True) eller RunConfig(tracing_disabled=True)