Гайд · TNWS AI

Как вручную управлять trace.start и trace.finish в Agents SDK

WebPythonChatGPT#OpenAI Agents SDK #tracing #Python

13 сентября 2026 5 мин—

Запускаем и завершаем trace без with, правильно используем mark_as_current и reset_current и проверяем очистку контекста.

Практическая задача

В этом гайде решается задача: удерживать trace открытой через callback-границы, где context manager использовать неудобно. Используется официальный интерфейс trace.start(mark_as_current=True) и trace.finish(reset_current=True). Материал нужен, когда стандартной автоматической трассировки Runner недостаточно или требуется строго проверить tracing context. Если обычный Runner уже создаёт тот же span, ручное дублирование запрещено: оно искажает дерево и длительность.

Факты проверены 12 сентября 2026 года (проверены сигнатура, параметры, контекстный жизненный цикл, экспорт и негативные сценарии; при обновлении зависимости контракт, обработку исключений и изоляцию параллельных контекстов нужно проверить повторно) по руководству OpenAI Agents SDK по tracing и официальному API reference. при ручном жизненном цикле start и finish обязательны; mark_as_current и reset_current обновляют текущую trace в contextvar. Изменяемые цены, тарифы и неподтверждённые лимиты не используются. Версию пакета берите из lock-файла своего проекта.

Проверяемый результат

Критерий готовности — конкретное поле, parent_id, состояние contextvar, результат export или событие processor. Внешний dashboard полезен для просмотра, но не заменяет assert. Перед внедрением создайте baseline trace и сохраните только технические идентификаторы и типы spans.

Для примеров используйте staging и искусственные данные. Не помещайте в metadata, input, output и имя span реальные персональные данные, токены или полный ответ внутренней системы. Динамический ID клиента не должен становиться именем span: высокая кардинальность ухудшает анализ.

Пошаговая реализация

Создайте виртуальное окружение, установите openai-agents и зафиксируйте зависимость.
Откройте верхнеуровневую trace через context manager либо подготовьте ручной lifecycle с обязательным finally.
Создайте нужный span/helper только в той области, которую он должен измерять.
Передайте параметры строго по API reference. Не придумывайте дополнительные поля в типизированном helper.
Выполните операцию и проверьте бизнес-результат независимо от tracing.
Проверьте tracing-контракт: trace_id, span_id, parent_id, span_data или export.
Запустите негативный сценарий и убедитесь, что он даёт отличимый результат.
Проверьте два параллельных workflow: их текущие контексты не должны смешиваться.
Для собственного processor добавьте force_flush и shutdown в жизненный цикл worker.
Перед релизом выполните поиск тестового секретного маркера по сериализованным событиям.

Готовый код

from agents import get_current_trace, trace

tr=trace("callback_workflow")
try:
    tr.start(mark_as_current=True)
    assert get_current_trace() is tr
    print("active",tr.trace_id)
finally:
    tr.finish(reset_current=True)
assert get_current_trace() is None
print("finished")

Код содержит машинно проверяемые утверждения. В CI не заменяйте assert печатью. Если пример использует ConsoleSpanExporter, оставляйте его только в тестовой среде: вывод всей trace может содержать больше данных, чем разрешает production-политика.

Пример входа и ожидаемого результата

Вход: Trace callback_workflow запускается вручную и помечается текущей.

Ожидаемый результат: Между start и finish helper возвращает tr; после finish контекст пуст и печатается finished.

Проверяйте структуру, а не случайные значения или длительность. Для ID важны формат, уникальность и сохранение связи; для context helper — тот же объект внутри области и None снаружи; для очереди — факт flush и отдельный учёт отброшенных элементов.

Негативный тест

Смоделируйте исключение после start. Блок finally всё равно должен вызвать finish; без него trace останется незавершённой.

Негативный тест показывает границу API: helper не проверяет бизнес-маршрут, монотонность turn или безопасность данных за приложение. Ошибка tracing не должна подменять основной результат, но нарушение обязательной политики конфигурации должно останавливать деплой.

Встраивание в production

Сосредоточьте tracing-настройки в одном bootstrap-модуле. Глобальные processors нельзя регистрировать на каждом HTTP-запросе. Локальные trace и spans создавайте рядом с операцией, но через небольшую обёртку предметной области, которая фильтрует разрешённые поля.

Contextvars автоматически помогают с async concurrency, однако новый поток или задача, созданная особым способом, требует отдельного теста переноса контекста. Не храните current trace в глобальной переменной. Всегда обрабатывайте None: функция может быть вызвана вне instrumented workflow или tracing может быть отключён.

Для ручного start/finish применяйте try/finally. Для processor задайте bounded queue, быстрые callbacks и явные метрики delivered, retried, dropped. Не объявляйте «потерь нет», если измеряется только число успешных экспортов. Для сериализации оставляйте include_tracing_api_key=False.

Копируемый шаблон ревью

Операция: trace.start(mark_as_current=True) и trace.finish(reset_current=True)
Причина ручной настройки: <конкретная причина>
Ожидаемый parent: <trace/span>
Проверяемые поля: <список>
Вход без PII: <значение>
Ожидаемый результат: <точная структура>
Негативный тест: <сценарий>
Поведение при исключении: <finish/reset/shutdown>
Результат вне контекста: <None или другое>
Секретный маркер отсутствует в export: <да>
Параллельная изоляция: <пройдена>
Источник: https://openai.github.io/openai-agents-python/ref/tracing/

Чек-лист финальной проверки

FAQ

Почему лучше использовать with?

Context manager автоматически выполняет start и finish и корректно восстанавливает текущий контекст при исключении. Ручной lifecycle нужен только при реальной callback-границе.

Можно ли передавать собственный span_id?

Да, параметр предусмотрен, но используйте gen_span_id, чтобы получить корректный формат. Произвольный внешний ID предварительно валидируйте.

Что возвращают get_current_trace и get_current_span вне контекста?

Они возвращают None. Это нормальное состояние, а не исключение; вызывающий код обязан его обработать.

Нужно ли вызывать flush после каждого запроса?

Нет. BatchTraceProcessor экспортирует в фоне. Flush нужен, когда короткоживущая задача требует немедленной доставки перед завершением процесса или job.

Можно ли хранить tracing API key в to_json?

Метод имеет специальный флаг, но по умолчанию ключ исключён именно для защиты от случайного сохранения. Для обычного транспорта оставляйте значение False.