Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Rianú agus Inbhreathnaitheacht

Ceacht 14 as 25 Nuashonraithe 3 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Rianú agus Inbhreathnaitheacht
  2. Rianú Inbhunaithe
  3. Ainmniú Rianta
  4. Obairshreabhan a Bhriseadh ina gCéimeanna
  5. Próiseálaithe Rianta Saincheaptha
  6. Onnmhairiú chuig Córais Sheachtracha
  7. Ná Caill na Rianta Deireanacha
  8. Rianú a Dhíchumasú
  9. Príomhthomhais le Monatóireacht a Dhéanamh Orthu
  10. Príomhphointí

Nuashonraithe an 3 Samhain 2026. Léadh próiseálaithe rianta roimhe seo trace.start_time, trace.end_time, agus span.name, nach bhfuil ann san SDK: níl stampa ama ag rian, agus iompraíonn spás started_at, ended_at, agus span_data. Níor chuir an próiseálaí onnmhairithe on_trace_start i bhfeidhm, modh teibí: tharraing a shamhlú TypeError suas. Chruthaigh “rianta neadaithe” rian nua laistigh de rian, rud a mheasann an SDK mar earráid dóchúil: úsáideann céimeanna anois custom_span(). Breiseáin: flush_traces(), láimhseáil sonraí íogaire, agus Coinneáil Sonraí Nialasach (Zero Data Retention). Fíoraíodh an cód le openai-agents 0.24.0. Foinse: Rianú (doiciméadú SDK) · openai-agents-python.

Rianú agus Inbhreathnaitheacht

Is bosca dubh é gníomhaire i dtáirgeadh mura ndéanann tú a ghníomhaíochtaí a rianú. Nuair a dhéanann custaiméir gearán faoi fhreagra absurd, níl ná an t-iarratas cruinn agat, ná na huirlisí a glaodh, ná na luachanna a thug siad ar ais. Déanann rianú an SDK gach céim den fhorghníomhú a thaifeadadh: glaonna samhaltaithe, uirlisí a úsáideadh, aistrithe láimhe, agus cosaintí (guardrails). Is é seo do phríomhuirlis chun do ghníomhairí a dhífhabhtú, a bharrfheabhsú, agus a iniúchadh.

Rianú Inbhunaithe

Dea-scéal: ní gá duit aon rud a chumasú. Déanann an SDK gach forghníomhú a rianú go huathoibríoch, agus seolann sé rianta chuig deasc OpenAI ag platform.openai.com de réir réamhshocraithe. Cruthaíonn an gníomhaire thíos, scríofa gan treoir rianta amháin, rian inúsáidte cheana féin.

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

# Cruthaíonn gach forghníomhú rian go huathoibríoch
result = Runner.run_sync(agent, "Search for the pro laptop")

Tabhair cuairt ar an deasc chun an rian iomlán a fheiceáil: fad, tocainí a úsáideadh, uirlisí a glaodh, agus an fhreagra dheireanach.

Ainmniú Rianta

Tar éis cúpla céad forghníomhú, déanann an deasc liosta gan idirdhealú de. Tabhair ainmneacha bríocha do do chuid rianta ionas gur féidir leat iad a aimsiú go héasca – is fearr ainm turais gnó ná ID teicniúil.

from agents import trace

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

Feictear ainm an rianta ar an deasc agus déanann sé scagadh níos fusa.

Obairshreabhan a Bhriseadh ina gCéimeanna

I gcás oibriúshreafa le glaonna iolracha, osclaigh rian amháin timpeall an ruda iomláin, ansin marcáil gach céim le custom_span(). Ná neadaigh trace() laistigh de cheann eile: ansin logálann an SDK an rabhadh Trace already exists. Creating a new trace, but this is probably a mistake. Dearadh spásanna, áfach, chun bheith neadaithe: suíonn gach ceann faoin spás reatha.

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

Ar an deasc, taispeánann an rian order-workflow na trí chéim, agus faoi gach ceann, na spásanna uathoibríocha forghníomhaithe: gníomhaire, glaonna samhaltaithe, uirlisí. Nascann an group_id rianta ón gcomhrá céanna, mar shampla ag baint úsáide as d’ID snáithe.

De réir réamhshocraithe, cuimsíonn an SDK gach Runner.run() i rian darbh ainm Agent workflow, agus laistigh de rianta an gníomhaire, gach giniúint samhail, gach glao feidhme, cosaintí, agus aistrithe láimhe. Chun hierarcha níos dlúithe a bheith agat, molann an doiciméadú spásanna tasc agus casadh uathoibríocha a ghearradh:

from agents import RunConfig

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

Próiseálaithe Rianta Saincheaptha

Tá an deasc OpenAI áisiúil, ach is dócha go ndéanann d’fhoireann oibríochtaí monatóireacht ar gach rud eile in áit eile. Chun rianta a sheoladh chuig do chóras féin, scríobh próiseálaí: faigheann sé imeachtaí tosaigh agus deiridh, don rian iomlán chomh maith le gach spás. Tá na sé mhodh de TracingProcessor teibí: cuir i bhfeidhm iad go léir, fiú má tá siad folamh, nó teipfidh ar an samhlú.

Seo an méid a nochtann gach oibiacht i ndáiríre: tá trace_id agus name ag rian, agus filleann a mhodh export() freisin group_id agus metadata; níl aon stampa ama aige. Tá span_id, trace_id, parent_id, started_at agus ended_at (teaghráin ISO 8601), agus span_data ag spás, a bhfuil an tréith type aige mar agent, generation, function, handoff, guardrail, custom, agus mar sin de. Dá bhrí sin, déantar fad an rianta a thomhas sa phróiseálaí.

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

Cuireann add_trace_processor() do phróiseálaí leis an gceann bunaidh: leanann rianta ag dul chuig deasc OpenAI. Ionadaíonn set_trace_processors() na próiseálaithe réamhshocraithe: ní théann aon rud chuig OpenAI a thuilleadh, mura gcuireann tú a onnmhaireoir ar ais sa liosta tú féin.

Onnmhairiú chuig Córais Sheachtracha

I gcás uirlis inbhreathnaitheachta, níl le déanamh agat ach na spásanna a athfhormáidiú. Scríobhann an sampla thíos líne JSON amháin in aghaidh gach spás críochnaithe, formáid a bhfuil a fhios ag formhór na mbailitheoirí log conas í a ionghabháil; soláthraíonn span.export() foclóir iomlán cheana féin.

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

Bí airdeallach ar an méid a onnmhairíonn tú: de réir réamhshocraithe, bíonn ionchuir agus aschuir samhail i spásanna giniúna, agus bíonn argóintí uirlisí agus torthaí i spásanna feidhme. Chun iad a eisiamh, rith RunConfig(trace_include_sensitive_data=False) nó socraigh an athróg timpeallachta OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Maidir le comhtháthú réidh le húsáid, liostaíonn doiciméadú an SDK go leor uirlisí tríú páirtí a sholáthraíonn a bpróiseálaí féin.

Ná Caill na Rianta Deireanacha

Seolann an t-onnmhaireoir réamhshocraithe rianta sa chúlra, gach cúpla soicind. I ngníomhaí a phróiseálann tascanna agus nach stopann, nó i script ghearr, glaoigh flush_traces() tar éis an rian a dhúnadh chun seoladh a éigní:

from agents import flush_traces

with trace("nightly-processing"):
    await Runner.run(agent, "Summarize today's tickets")
flush_traces()  # tar éis don rian deireadh a bheith leis, riamh sa lár

Rianú a Dhíchumasú

Tá cás amháin ann ina chuireann rianú bac níos mó ná mar a chuidíonn sé: sraith tástála a ritheann na céadta gníomhairí bréige agus a thruaillíonn do dheasc. Dá bhrí sin, is féidir leat é a dhíchumasú i dtástálacha nó le linn forbartha áitiúil, go domhanda nó d’fhorghníomhú amháin.

from agents import RunConfig, set_tracing_disabled

# Díchumasaigh go hiomlán (nó athróg timpeallachta OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)

# Nó d'fhorghníomhú amháin
result = await Runner.run(agent, "Test message", run_config=RunConfig(tracing_disabled=True))

Pointe amháin eile, ceann conarthach seo: de réir na doiciméadachta, níl rianú chuig OpenAI ar fáil d’eagraíochtaí atá faoi réir polasaí Coinneáil Sonraí Nialasaigh (Zero Data Retention). Sa chás seo, ní thabharfaidh ach do phróiseálaí féin, suiteáilte le set_trace_processors(), rianta duit.

Príomhthomhais le Monatóireacht a Dhéanamh Orthu

Anois, cad ba chóir duit a bhreathnú air? I dtáirgeadh, tá sé tháscaire go leor chun sláinte gníomhaire a cháiliú. Is é moill iomlán—an t-am idir an t-iarratas agus an fhreagra dheireanach—an rud a mhothaíonn do chustaiméirí; is minic a mhínítear é leis an líon casadh, is é sin, an líon uaireanta a ritheadh lúb an ghníomhaire. Tiomáineann tocainí a úsáideadh, ionchur agus aschur araon in aghaidh gach forghníomhaithe, do bhille.

Baineann na trí cinn eile le cáilíocht. Nochtann an ráta teipe uirlisí, an céatadán d’uirlisí a fhilltear earráid, API tríú páirtí éagobhsaí nó argóintí a giniúint go dona. Tomhaiseann an ráta spreagtha cosanta, infheicthe i spásanna guardrail, minicíocht na mbloc: léiríonn buaic tobann ionsaí nó cosaint atá ró-dhian anois. Ar deireadh, insíonn an dáileadh aistrithe láimhe duit cé acu gníomhaire a fhreagraíonn is minice—agus dá bhrí sin an bhfuil do thriáil ag seoladh iarratas chuig an áit ar chóir dóibh dul.

Príomhphointí

  • Déanann an SDK gach forghníomhú a rianú go huathoibríoch chuig deasc OpenAI (seachas d’eagraíochtaí ar Coinneáil Sonraí Nialasach)
  • Rian trace() amháin in aghaidh an oibriúshreafa; marcáil céimeanna le custom_span(), agus úsáid group_id chun rianta ó chomhrá a nascadh
  • Níl aon stampa ama ag rian; tá started_at, ended_at, agus span_data.type ag spás
  • Cuireann TracingProcessor a shé mhodh i bhfeidhm; cuireann add_trace_processor() leis, ionadaíonn set_trace_processors()
  • Eisíonn trace_include_sensitive_data=False ionchuir agus aschuir; éigníonn flush_traces() seoladh
  • Díchumasaigh rianú i dtástálacha le set_tracing_disabled(True) nó RunConfig(tracing_disabled=True)