Jäljitys ja havainnoitavuus
Tällä sivulla
Päivitetty 3. marraskuuta 2026. Jäljityskäsittelijät lukivat aiemmin arvot
trace.start_time,trace.end_timejaspan.name, joita ei ole olemassa SDK:ssa: jäljityksellä ei ole aikaleimaa, ja span-objekti sisältää kentätstarted_at,ended_atjaspan_data. Vientikäsittelijä ei toteuttanut abstraktia metodiaon_trace_start: sen luominen aiheuttiTypeError-virheen. “Sisäkkäiset jäljitykset” loivat uuden jäljityksen olemassa olevan sisään, minkä SDK merkitsee todennäköiseksi virheeksi: vaiheet käyttävät nyt funktiotacustom_span(). Uudet ominaisuudet:flush_traces(), arkaluonteisten tietojen käsittely ja Zero Data Retention (ei tietojen säilytystä). Koodi on varmennettu versiollaopenai-agents0.24.0. Lähteet: Tracing (SDK-dokumentaatio) · openai-agents-python.
Jäljitys ja havainnoitavuus
Tuotannossa oleva agentti on musta laatikko, ellei sen toimintaa jäljitä. Kun asiakas valitsee absurdistista vastauksesta, sinulla ei ole käytössäsi tarkkaa pyyntöä, kutsuttuja työkaluja eikä niiden palauttamia arvoja. SDK:n jäljitys tallentaa jokaisen suoritusvaiheen: mallikutsut, käytetyt työkalut, siirrot (handoffs) ja suojaukset (guardrails). Tämä on ensisijainen työkalusi agenttien vianetsintään, optimointiin ja auditointiin.
Sisäänrakennettu jäljitys
Hyviä uutisia: sinun ei tarvitse ottaa mitään käyttöön erikseen. SDK jäljittää automaattisesti jokaisen suorituksen ja lähettää jäljet oletusarvoisesti OpenAI:n kojelaudalle osoitteeseen platform.openai.com. Alla oleva agentti, joka on kirjoitettu ilman ainuttakaan jäljityskomentoa, tuottaa jo käyttökelpoisen jäljen.
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")
Vieraile kojelaudalla nähdäksesi täydellisen jäljen: kesto, kulutetut tokenit, kutsutut työkalut ja lopullinen vastaus.
Jäljitysten nimeäminen
Muutaman sadan suorituksen jälkeen kojelauta muuttuu erottamattomaksi listaksi. Anna jäljillesi merkityksellisiä nimiä, jotta löydät ne helposti – liiketoimintaprosessin nimi on parempi kuin tekninen tunniste.
from agents import trace
with trace("premium-customer-order"):
result = await Runner.run(
agent,
"I want to order 5 laptops for my team",
)
Jäljityksen nimi näkyy kojelaudalla ja helpottaa suodatusta.
Työnkulun jakaminen vaiheisiin
Monia kutsuja sisältävässä työnkulussa avaa yksi jäljitys koko prosessin ympärille ja merkitse sitten jokainen vaihe funktiolla custom_span(). Älä sijoita trace()-funktiota toisen sisään: SDK kirjaa tällöin varoituksen Trace already exists. Creating a new trace, but this is probably a mistake. Span-objektit on kuitenkin suunniteltu sisäkkäisiksi: kukin niistä sijoittuu nykyisen spanin alle.
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
Kojelaudalla order-workflow-jäljitys näyttää kolme vaihetta, ja kunkin alla näkyvät automaattiset suoritusspanit: agentti, mallikutsut ja työkalut. group_id yhdistää saman keskustelun jäljet, esimerkiksi käyttämällä säikeen tunnustasi (thread ID).
Oletusarvoisesti SDK käärii jokaisen Runner.run()-kutsun jäljitykseen, jonka nimi on Agent workflow. Jäljitysten sisällä se luo spanit agentille, jokaiselle mallin generoinnille, funktiokutsulle, suojaukselle ja siirrolle. Tiiviimmän hierarkian saamiseksi dokumentaatio ehdottaa automaattisten tehtävä- ja vuorospaanien poissulkemista:
from agents import RunConfig
result = await Runner.run(
agent,
"Hello",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Mukautetut jäljityskäsittelijät
OpenAI:n kojelauta on kätevä, mutta operaatiotiimisi todennäköisesti valvoo kaikkea muuta muualla. Lähettääksesi jäljet omaan järjestelmääsi, kirjoita käsittelijä: se vastaanottaa käynnistys- ja lopetustapahtumat sekä koko jäljitykselle että jokaiselle spanille. Kaikki kuusi TracingProcessor-luokan metodia ovat abstrakteja: toteuta ne kaikki, vaikka tyhjinä, muuten luominen epäonnistuu.
Tässä on erittely siitä, mitä kukin objekti todella tarjoaa: jäljityksellä (trace) on trace_id ja name, ja sen export()-metodi palauttaa myös group_id:n ja metadata:n; sillä ei ole aikaleimaa. Spanilla on span_id, trace_id, parent_id, started_at ja ended_at (ISO 8601 -merkkijonoja) sekä span_data, jonka type-attribuutti voi olla agent, generation, function, handoff, guardrail, custom jne. Jäljityksen kesto mitataan siis käsittelijän sisällä.
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() lisää käsittelijäsi alkuperäisen lisäksi: jäljet jatkavat kulkuaan OpenAI:n kojelaudalle. set_trace_processors() korvaa oletuskäsittelijät: mitään ei enää lähetetä OpenAI:hun, ellet lisää sen vientiä itse takaisin listaan.
Vienti ulkoisiin järjestelmiin
Havainnoitavuustyökalua varten sinun tarvitsee vain muotoilla spanit uudelleen. Alla oleva esimerkki kirjoittaa yhden JSON-rivin kutakin valmistunutta spania kohden; tämä on muoto, jonka useimmat lokikeräilijät osaavat käsitellä. span.export() tarjoaa jo valmiin täydellisen sanakirjan.
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
Varo, mitä viet: oletusarvoisesti generointispanit sisältävät mallin syötteet ja tulosteet, ja funktiospanit sisältävät työkalujen argumentit ja tulokset. Sulkeaksesi ne pois, välitä parametri RunConfig(trace_include_sensitive_data=False) tai aseta ympäristömuuttuja OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Valmiita integraatioita varten SDK:n dokumentaatio listaa useita kolmansien osapuolten työkaluja, jotka tarjoavat oman käsittelijänsä.
Älä menetä viimeisiä jälkiä
Oletusarvoinen viejä lähettää jäljet taustalla muutaman sekunnin välein. Tehtäviä käsittelevässä workerissa, joka ei pysähdy, tai lyhyessä skriptissä, kutsu flush_traces() jäljityksen sulkemisen jälkeen pakottaaksesi lähetyksen:
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
Jäljityksen poistaminen käytöstä
On yksi tilanne, jossa jäljitys haittaa enemmän kuin auttaa: testisarja, joka ajaa satoja mock-agentteja ja saastuttaa kojelautasi. Testeissä tai paikallisen kehityksen aikana voitkin poistaa sen käytöstä joko globaalisti tai yksittäistä suoritusta varten.
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))
Yksi viimeinen, sopimuksellinen seikka: dokumentaation mukaan jäljitys OpenAI:hun ei ole saatavilla organisaatioille, jotka noudattavat Zero Data Retention -käytäntöä. Tällöin vain oma käsittelijäsi, joka on asennettu funktiolla set_trace_processors(), tuottaa jälkiä.
Seurattavat keskeiset mittarit
Mitä sinun pitäisi siis tarkkailla? Tuotannossa kuusi indikaattoria riittää arvioimaan agentin terveydentilaa. Kokonaislatenssi – aika pyynnön ja lopullisen vastauksen välillä – on se, mitä käyttäjäsi tuntevat; sen selittää useimmiten vuorojen määrä, eli kertojen lukumäärä, jotka agenttisilmukka suoritti. Kulutetut tokenit, sekä syöte että tuloste suorituskohtaisesti, määräävät laskusi suuruuden.
Muut kolse liittyvät laatuun. Työkalujen virheprosentti, eli prosenttiosuus työkaluista, jotka palauttavat virheen, paljastaa epävakaa kolmannen osapuolen API:n tai huonosti generoidut argumentit. Suojausten laukaisuprosentti, joka näkyy guardrail-spaneissa, mittaa estojen tiheyttä: äkillinen piikki kertoo joko hyökkäyksestä tai liian tiukaksi muuttuneesta suojauksesta. Lopuksi siirtojen (handoff) jakauma kertoo, mikä agentti vastaa useimmiten – ja siten sen, ohjaako triage-pyyntösi oikeisiin paikkoihin.
Keskeiset asiat
- SDK jäljittää automaattisesti jokaisen suorituksen OpenAI:n kojelaudalle (lukuun ottamatta Zero Data Retention -käytäntöä noudattavia organisaatioita)
- Yksi
trace()työnkulkua kohden; merkitse vaiheetcustom_span()-funktiolla ja käytägroup_id:tä yhdistääksesi saman keskustelun jäljet - Jäljityksellä ei ole aikaleimaa; spanilla on
started_at,ended_atjaspan_data.type TracingProcessortoteuttaa kuusi metodia;add_trace_processor()lisää,set_trace_processors()korvaatrace_include_sensitive_data=Falsesulkee pois syötteet ja tulosteet;flush_traces()pakottaa lähetyksen- Poista jäljitys käytöstä testeissä funktiolla
set_tracing_disabled(True)tai parametrillaRunConfig(tracing_disabled=True)