Проследяване и наблюдаемост
На тази страница
Обновено на 3 ноември 2026 г. Преди това процесорите за проследяване четяха
trace.start_time,trace.end_timeиspan.name, които не съществуват в SDK: един трасеуър няма времеви печат, а един интервал (span) съдържаstarted_at,ended_atиspan_data. Експортният процесор не имплементираше абстрактния методon_trace_start: инстанцирането му предизвиквашеTypeError. „Вложени трасеуъри“ създаваха ново трасе вътре в друго, което SDK маркира като вероятна грешка: стъпките вече използватcustom_span(). Добавки:flush_traces(), обработка на чувствителни данни и Политика за нулево запазване на данни (Zero Data Retention). Кодът е проверен сopenai-agents0.24.0. Източници: Tracing (SDK documentation) · openai-agents-python.
Проследяване и наблюдаемост
Агентът в продукционна среда е черна кутия, ако не проследявате действията му. Когато клиент се оплаче от абсурден отговор, Вие нямате нито точната заявка, нито използваните инструменти, нито върнатите от тях стойности. Проследяването на SDK записва всяка стъпка от изпълнението: повиквания към модела, използвани инструменти, предавания (handoffs) и предпазни механизми (guardrails). Това е Вашият основен инструмент за дебъгване, оптимизиране и одит на Вашите агенти.
Вградено проследяване
Добрата новина е, че не трябва да активирате нищо. SDK автоматично проследява всяко изпълнение и по подразбиране изпраща трасеуърите към таблото на OpenAI на адрес platform.openai.com. Агентът по-долу, написан без нито една инструкция за проследяване, вече генерира използваемо трасе.
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")
Посетете таблото, за да видите пълното трасе: продължителност, използвани токени, извикани инструменти и крайния отговор.
Именуване на трасеуъри
След няколкостотин изпълнения таблото се превръща в недиференциран списък. Дайте на Вашите трасеуъри смислени имена, за да ги намирате лесно – името на бизнес процеса е по-добро от технически идентификатор.
from agents import trace
with trace("premium-customer-order"):
result = await Runner.run(
agent,
"I want to order 5 laptops for my team",
)
Името на трасеуъра се появява в таблото и улеснява филтрирането.
Разбиване на работния поток на стъпки
За работен поток с множество повиквания отворете един трасеуър около целия процес, след което маркирайте всяка стъпка с custom_span(). Не влажайте trace() вътре в друг: тогава SDK записва предупреждението Trace already exists. Creating a new trace, but this is probably a mistake. Интервалите (spans) обаче са проектирани да се влагат: всеки един седи под текущия интервал.
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
В таблото трасеуърът order-workflow показва трите стъпки, а под всяка от тях – автоматичните интервали на изпълнение: агент, повиквания на модел, инструменти. group_id свързва трасеуъри от един и същи разговор, например чрез използване на Вашия ID на нишка.
По подразбиране SDK обгръща всяко Runner.run() в трасеуър с име Agent workflow, а вътре в трасеуърите – агентът, всяко генериране на модел, всяко извикване на функция, предпазните механизми и предаванията. За по-компактна йерархия документацията предлага изключване на автоматичните интервали за задачи и завъртания (turns):
from agents import RunConfig
result = await Runner.run(
agent,
"Hello",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Персонализирани процесори за проследяване
Таблото на OpenAI е удобно, но Вашият оперативен екип вероятно следи всичко останало на друго място. За да изпращате трасеуъри към Ваша собствена система, напишете процесор: той получава събития за начало и край, както за целия трасеуър, така и за всеки интервал. И шестте метода на TracingProcessor са абстрактни: имплементирайте ги всички, дори да са празни, иначе инстанцирането ще се провали.
Ето какво точно излага всеки обект: един трасеуър има trace_id и name, а неговият метод export() връща също group_id и metadata; той няма времеви печат. Един интервал има span_id, trace_id, parent_id, started_at и ended_at (низове във формат ISO 8601) и span_data, чийто атрибут type е agent, generation, function, handoff, guardrail, custom и т.н. Следователно продължителността на трасеуъра се измерва в процесора.
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() добавя Вашия процесор към оригиналния: трасеуърите продължават да отиват в таблото на OpenAI. set_trace_processors() замества процесорите по подразбиране: нищо повече не отива в OpenAI, освен ако сами не върнете неговия експортьор в списъка.
Експортиране към външни системи
За инструмент за наблюдаемост е необходимо само да преформатирате интервалите. Примерът по-долу записва един JSON ред за всеки завършен интервал – формат, който повечето колектори за логове умеят да приемат; span.export() вече предоставя пълен речник.
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
Следете какво експортирате: по подразбиране интервалите за генериране съдържат входовете и изходите на модела, а интервалите за функции съдържат аргументите и резултатите на инструментите. За да ги изключите, предайте RunConfig(trace_include_sensitive_data=False) или задайте променливата на средата OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. За готови интеграции документацията на SDK изброява много инструменти на трети страни, които предоставят собствен процесор.
Не губете последните трасеуъри
Експортьорът по подразбиране изпраща трасеуъри във фонов режим на всеки няколко секунди. В работен процес (worker), който обработва задачи и не спира, или в кратък скрипт, извикайте flush_traces() след затваряне на трасеуъра, за да принудите изпращането:
from agents import flush_traces
with trace("nightly-processing"):
await Runner.run(agent, "Summarize today's tickets")
flush_traces() # след приключване на трасеуъра, никога по средата
Деактивиране на проследяването
Има един случай, в който проследяването пречи повече, отколкото помага: тестови набор, който изпълнява стотици фиктивни агенти и замърсява Вашето табло. В тестове или по време на локална разработка можете да го деактивирате, както глобално, така и за едно изпълнение.
from agents import RunConfig, set_tracing_disabled
# Пълно деактивиране (или променлива на средата OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)
# Или за едно изпълнение
result = await Runner.run(agent, "Test message", run_config=RunConfig(tracing_disabled=True))
Една последна точка, този път договорна: според документацията проследяването към OpenAI не е налично за организации, подлежащи на политика за нулево запазване на данни (Zero Data Retention). В този случай само Вашият собствен процесор, инсталиран с set_trace_processors(), ще Ви осигури трасеуъри.
Ключови метрики за наблюдение
Сега, какво трябва да следите? В продукционна среда шест индикатора са достатъчни, за да оцените здравето на един агент. Общата латентност – времето между заявката и крайния отговор – е това, което потребителите усещат; най-често тя се обяснява с броя завъртания, тоест колко пъти цикълът на агента се е изпълнил. Консумираните токени, както входни, така и изходни за изпълнение, движат Вашата фактура.
Останалите три са свързани с качеството. Процентът на неуспех на инструментите, процентът инструменти, връщащи грешка, разкрива нестабилен API на трета страна или лошо генерирани аргументи. Честотата на задействане на предпазните механизми, видима в интервалите guardrail, измерва честотата на блокиранията: внезапно покачване сигнализира или за атака, или за твърде строг предпазен механизъм. Накрая, разпределението на предаванията Ви показва кой агент отговаря най-често – и следователно дали Вашата триажа изпраща заявките там, където трябва.
Ключови изводи
- SDK автоматично проследява всяко изпълнение към таблото на OpenAI (с изключение на организациите с политика за нулево запазване на данни)
- Един
trace()на работен поток; маркирайте стъпките сcustom_span()и използвайтеgroup_id, за да свържете трасеуъри от един разговор - Трасеуърът няма времеви печат; интервалът има
started_at,ended_atиspan_data.type TracingProcessorимплементира своите шест метода;add_trace_processor()добавя,set_trace_processors()заместваtrace_include_sensitive_data=Falseизключва входовете и изходите;flush_traces()принуждава изпращането- Деактивирайте проследяването в тестовете с
set_tracing_disabled(True)илиRunConfig(tracing_disabled=True)