Rianú agus Inbhreathnaitheacht
Ar an leathanach seo
Nuashonraithe an 3 Samhain 2026. Léadh próiseálaithe rianta roimhe seo
trace.start_time,trace.end_time, agusspan.name, nach bhfuil ann san SDK: níl stampa ama ag rian, agus iompraíonn spásstarted_at,ended_at, agusspan_data. Níor chuir an próiseálaí onnmhairitheon_trace_starti bhfeidhm, modh teibí: tharraing a shamhlúTypeErrorsuas. Chruthaigh “rianta neadaithe” rian nua laistigh de rian, rud a mheasann an SDK mar earráid dóchúil: úsáideann céimeanna anoiscustom_span(). Breiseáin:flush_traces(), láimhseáil sonraí íogaire, agus Coinneáil Sonraí Nialasach (Zero Data Retention). Fíoraíodh an cód leopenai-agents0.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 lecustom_span(), agus úsáidgroup_idchun rianta ó chomhrá a nascadh - Níl aon stampa ama ag rian; tá
started_at,ended_at, agusspan_data.typeag spás - Cuireann
TracingProcessora shé mhodh i bhfeidhm; cuireannadd_trace_processor()leis, ionadaíonnset_trace_processors() - Eisíonn
trace_include_sensitive_data=Falseionchuir agus aschuir; éigníonnflush_traces()seoladh - Díchumasaigh rianú i dtástálacha le
set_tracing_disabled(True)nóRunConfig(tracing_disabled=True)