Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Tracing en observability

Les 14 van 25 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Tracing en observability
  2. Ingebouwde tracing
  3. Traces een naam geven
  4. Een workflow opsplitsen in stappen
  5. Aangepaste trace-processors
  6. Exporteren naar externe systemen
  7. Verlies de laatste traces niet
  8. Tracing uitschakelen
  9. Belangrijke metrieken om te bewaken
  10. Belangrijkste punten

Bijgewerkt op 3 november 2026. Trace-processors lazen eerder trace.start_time, trace.end_time en span.name, die niet bestaan in de SDK: een trace heeft geen tijdstempel en een span bevat started_at, ended_at en span_data. De export-processor implementeerde on_trace_start niet, een abstracte methode: instantiëren hiervan leidde tot een TypeError. “Geneste traces” creëerden een nieuwe trace binnen een trace, wat de SDK markeert als een waarschijnlijke fout: stappen gebruiken nu custom_span(). Toevoegingen: flush_traces(), afhandeling van gevoelige gegevens en Zero Data Retention. Code geverifieerd met openai-agents 0.24.0. Bronnen: Tracing (SDK-documentatie) · openai-agents-python.

Tracing en observability

Een agent in productie is een black box als u zijn acties niet traceert. Wanneer een klant klaagt over een absurd antwoord, heeft u noch het exacte verzoek, noch de aangeroepen tools, noch de waarden die ze retourneerden. De tracing-functionaliteit van de SDK legt elke stap van de uitvoering vast: modelaanroepen, gebruikte tools, overdrachten (handoffs) en guardrails. Dit is uw primaire hulpmiddel voor het debuggen, optimaliseren en auditen van uw agents.

Ingebouwde tracing

Goed nieuws: u hoeft niets in te schakelen. De SDK traceert automatisch elke uitvoering en verzendt traces standaard naar het OpenAI-dashboard op platform.openai.com. De onderstaande agent, geschreven zonder een enkele tracing-instructie, produceert al een bruikbare 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")

Bezoek het dashboard om de volledige trace te bekijken: duur, verbruikte tokens, aangeroepen tools en het uiteindelijke antwoord.

Traces een naam geven

Na een paar honderd uitvoeringen wordt het dashboard een ongeordende lijst. Geef uw traces betekenisvolle namen zodat u ze gemakkelijk kunt vinden; een naam gebaseerd op de business-journey is beter dan een technische ID.

from agents import trace

with trace("premium-customer-order"):
    result = await Runner.run(
        agent,
        "I want to order 5 laptops for my team",
    )

De trace-naam verschijnt in het dashboard en maakt filteren eenvoudiger.

Een workflow opsplitsen in stappen

Voor een workflow met meerdere aanroepen opent u één trace rond het geheel en markeert u elke stap met custom_span(). Nestel geen trace() binnen een andere: de SDK logt dan de waarschuwing Trace already exists. Creating a new trace, but this is probably a mistake. Spans zijn daarentegen ontworpen om te nesten: elk zit onder de huidige 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

In het dashboard toont de order-workflow-trace de drie stappen, en onder elk de automatische spans van uitvoering: agent, modelaanroepen, tools. De group_id koppelt traces van dezelfde conversatie, bijvoorbeeld met behulp van uw thread-ID.

Standaard wikkelt de SDK elke Runner.run() in een trace met de naam Agent workflow, en binnen traces de agent, elke modelgeneratie, elke functieaanroep, guardrails en overdrachten. Voor een compactere hiërarchie suggereert de documentatie om automatische taak- en beurt-spans uit te schakelen:

from agents import RunConfig

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

Aangepaste trace-processors

Het OpenAI-dashboard is handig, maar uw operationele team bewaakt waarschijnlijk al het andere elders. Om traces naar uw eigen systeem te sturen, schrijft u een processor: deze ontvangt start- en einde-events, zowel voor de volledige trace als voor elke span. Alle zes methoden van TracingProcessor zijn abstract: implementeer ze allemaal, zelfs als ze leeg zijn, anders mislukt de instantiëring.

Hier is wat elk object daadwerkelijk blootlegt: een trace heeft een trace_id en een name, en de export()-methode retourneert ook group_id en metadata; het heeft geen tijdstempel. Een span heeft span_id, trace_id, parent_id, started_at en ended_at (ISO 8601-strings) en span_data, waarvan het type-attribuut agent, generation, function, handoff, guardrail, custom, enzovoort is. De traceduur wordt daarom in de processor gemeten.

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() voegt uw processor toe aan de oorspronkelijke: traces blijven naar het OpenAI-dashboard gaan. set_trace_processors() vervangt de standaardprocessors: er gaat niets meer naar OpenAI, tenzij u de exporter zelf weer in de lijst opneemt.

Exporteren naar externe systemen

Voor een observability-tool hoeft u alleen de spans opnieuw te formatteren. Het onderstaande voorbeeld schrijft één JSON-regel per voltooide span, een formaat dat de meeste log-collectors kunnen verwerken; span.export() levert al een compleet dictionary op.

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

Let op wat u exporteert: standaard bevatten generatie-spans modelinputs en -outputs, en functie-spans tool-argumenten en -resultaten. Om deze uit te sluiten, geeft u RunConfig(trace_include_sensitive_data=False) mee of stelt u de omgevingsvariabele OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false in. Voor kant-en-klare integraties somt de SDK-documentatie veel third-party tools op die hun eigen processor leveren.

Verlies de laatste traces niet

De standaard-exporteur verzendt traces op de achtergrond, om de paar seconden. In een worker die taken verwerkt en niet stopt, of in een kort script, roept u flush_traces() aan na het sluiten van de trace om verzending te forceren:

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

Tracing uitschakelen

Er is één geval waarin tracing meer hindert dan helpt: een testsuite die honderden mock-agents uitvoert en uw dashboard vervuilt. In tests of tijdens lokale ontwikkeling kunt u het daarom uitschakelen, zowel globaal als voor een enkele uitvoering.

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))

Nog één punt, dit is contractueel: volgens de documentatie is tracing naar OpenAI niet beschikbaar voor organisaties die onder een Zero Data Retention-beleid vallen. In dat geval geeft alleen uw eigen processor, geïnstalleerd met set_trace_processors(), u traces.

Belangrijke metrieken om te bewaken

Waar moet u nu op letten? In productie volstaan zes indicatoren om de gezondheid van een agent te kwalificeren. Totale latentie—de tijd tussen verzoek en definitief antwoord—is wat uw gebruikers voelen; dit wordt meestal verklaard door het aantal beurten, dat wil zeggen het aantal keren dat de agent-lus werd uitgevoerd. Verbruikte tokens, zowel input als output per uitvoering, bepalen uw factuur.

De andere drie hebben betrekking op kwaliteit. Het percentage tool-fouten, het percentage tools dat een fout retourneert, wijst op een onstabiele third-party API of slecht gegenereerde argumenten. Het percentage guardrail-triggers, zichtbaar in guardrail-spans, meet de frequentie van blokkades: een plotselinge piek signaleert entweder een aanval of een guardrail die te streng is geworden. Tot slot vertelt de verdeling van overdrachten (handoffs) u welke agent het vaakst antwoordt—en dus of uw triage verzoeken daarheen stuurt waar ze horen.

Belangrijkste punten

  • De SDK traceert automatisch elke uitvoering naar het OpenAI-dashboard (behalve voor organisaties met Zero Data Retention)
  • Één trace() per workflow; markeer stappen met custom_span() en gebruik group_id om traces van een conversatie te koppelen
  • Een trace heeft geen tijdstempel; een span heeft started_at, ended_at en span_data.type
  • Een TracingProcessor implementeert zijn zes methoden; add_trace_processor() voegt toe, set_trace_processors() vervangt
  • trace_include_sensitive_data=False sluit inputs en outputs uit; flush_traces() forceert verzending
  • Schakel tracing uit in tests met set_tracing_disabled(True) of RunConfig(tracing_disabled=True)