Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Jäljitys ja havainnoitavuus

Oppitunti 14 / 25 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Jäljitys ja havainnoitavuus
  2. Sisäänrakennettu jäljitys
  3. Jäljitysten nimeäminen
  4. Työnkulun jakaminen vaiheisiin
  5. Mukautetut jäljityskäsittelijät
  6. Vienti ulkoisiin järjestelmiin
  7. Älä menetä viimeisiä jälkiä
  8. Jäljityksen poistaminen käytöstä
  9. Seurattavat keskeiset mittarit
  10. Keskeiset asiat

Päivitetty 3. marraskuuta 2026. Jäljityskäsittelijät lukivat aiemmin arvot trace.start_time, trace.end_time ja span.name, joita ei ole olemassa SDK:ssa: jäljityksellä ei ole aikaleimaa, ja span-objekti sisältää kentät started_at, ended_at ja span_data. Vientikäsittelijä ei toteuttanut abstraktia metodia on_trace_start: sen luominen aiheutti TypeError-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 funktiota custom_span(). Uudet ominaisuudet: flush_traces(), arkaluonteisten tietojen käsittely ja Zero Data Retention (ei tietojen säilytystä). Koodi on varmennettu versiolla openai-agents 0.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 vaiheet custom_span()-funktiolla ja käytä group_id:tä yhdistääksesi saman keskustelun jäljet
  • Jäljityksellä ei ole aikaleimaa; spanilla on started_at, ended_at ja span_data.type
  • TracingProcessor toteuttaa kuusi metodia; add_trace_processor() lisää, set_trace_processors() korvaa
  • trace_include_sensitive_data=False sulkee pois syötteet ja tulosteet; flush_traces() pakottaa lähetyksen
  • Poista jäljitys käytöstä testeissä funktiolla set_tracing_disabled(True) tai parametrilla RunConfig(tracing_disabled=True)