Гайд · TNWS AI

Как вручную создать turn_span для цикла агента

WebPythonChatGPT#OpenAI Agents SDK #tracing #Python

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

Записываем два шага собственного agent loop через turn_span с номерами и agent_name, затем проверяем последовательность.

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

В этом гайде решается задача: показать отдельные итерации собственного цикла агента, который не использует стандартный Runner. Используется официальный интерфейс turn_span(turn, agent_name). Материал нужен, когда стандартной автоматической трассировки Runner недостаточно или требуется строго проверить tracing context. Если обычный Runner уже создаёт тот же span, ручное дублирование запрещено: оно искажает дерево и длительность.

Факты проверены 12 сентября 2026 года (проверены сигнатура, параметры, контекстный жизненный цикл, экспорт и негативные сценарии; при обновлении зависимости контракт, обработку исключений и изоляцию параллельных контекстов нужно проверить повторно) по руководству OpenAI Agents SDK по tracing и официальному API reference. turn_span принимает целый номер turn и имя агента и представляет одну итерацию agent loop. Изменяемые цены, тарифы и неподтверждённые лимиты не используются. Версию пакета берите из 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 trace, turn_span

seen=[]
with trace("custom_agent_loop"):
    for number in (1,2):
        with turn_span(turn=number,agent_name="Planner") as span:
            seen.append((span.span_data.turn,span.span_data.agent_name))
assert seen==[(1,"Planner"),(2,"Planner")]
print(seen)

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

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

Вход: Две итерации Planner с номерами 1 и 2.

Ожидаемый результат: В trace записаны два turn spans в ожидаемой последовательности: (1, Planner), затем (2, Planner).

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

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

Передайте дважды turn=1. Валидатор цикла должен отклонить повтор; helper записывает значение, но не обеспечивает монотонность сам.

Негативный тест показывает границу 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.

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

Операция: turn_span(turn, agent_name)
Причина ручной настройки: <конкретная причина>
Ожидаемый 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.