Как получать ISO-время через TraceProvider.time_iso в Agents SDK

Сигнатуры и поведение проверены 13 сентября 2026 года по руководству OpenAI Agents SDK, общему API reference tracing и профильному reference. DefaultTraceProvider.time_iso возвращает текущее время UTC в строке ISO 8601 с информацией о часовом поясе. Цены, тарифы и неподтверждённые лимиты в материале не используются. Версию зависимости фиксируйте в lock-файле и повторяйте контрактные тесты после обновления.

Важно разделять бизнес-успех и успех telemetry. Ошибка exporter не должна превращать уже выполненную бизнес-операцию в повторную, иначе возможен дубль платежа или задания. Одновременно нельзя молча объявлять tracing надёжным: измеряйте созданные, завершённые, отправленные и отброшенные события отдельно.

Архитектура решения

В примере есть четыре слоя. Первый создаёт или получает provider. Второй формирует trace/span data только из разрешённых технических полей. Третий управляет start, finish, flush и shutdown. Четвёртый проверяет результат через свойства объекта или export. Такая схема отделяет конфигурацию от предметного кода и делает ошибки воспроизводимыми.

Не записывайте в name динамические идентификаторы пользователей: используйте стабильное имя операции, а корреляцию храните в безопасном group_id либо ограниченной metadata. Input и output могут содержать чувствительные данные, поэтому примеры используют исключительно искусственные значения. Для production создайте allowlist полей и тест с секретным маркером.

Пошаговая инструкция

1. Создайте отдельное виртуальное окружение и установите пакет openai-agents; точную версию зафиксируйте тем же инструментом зависимостей, который использует проект.
2. Вынесите tracing bootstrap в один модуль. Зафиксируйте, кто вызывает shutdown при завершении процесса.
3. Импортируйте только официальные классы и helpers, указанные в reference. Не обращайтесь к приватным полям с подчёркиванием в production-коде.
4. Подготовьте искусственный вход без токенов, email, текста реального клиента и содержимого внутренних документов.
5. Вызовите get_trace_provider().time_iso() и сохраните возвращённый объект, если его свойства участвуют в контрактной проверке.
6. Для ручного lifecycle используйте try/finally. Если объект становится текущим, при завершении обязательно восстановите contextvar.
7. Проверьте конкретные поля: формат ID, parent_id, span_data, started_at/ended_at, export либо identity provider.
8. Запустите негативный сценарий. Успех без такого теста не доказывает, что конфигурация ловит неправильную связь или утечку контекста.
9. В отдельном concurrency-тесте запустите две asyncio-задачи и убедитесь, что их current trace/span не смешиваются.
10. Перед выпуском вызовите flush там, где процесс короткоживущий, затем shutdown владельца processor/provider.

Готовый код

from datetime import datetime, timezone
from agents.tracing import get_trace_provider

provider = get_trace_provider()
stamp = provider.time_iso()
parsed = datetime.fromisoformat(stamp)

assert parsed.tzinfo is not None
assert parsed.utcoffset() == timezone.utc.utcoffset(parsed)
assert abs((datetime.now(timezone.utc)-parsed).total_seconds()) < 5
print(stamp)

Код можно скопировать в отдельный тестовый файл. Assertions являются частью решения: они превращают предположение о tracing в проверяемый контракт. Если пример использует тестовый ключ или домен example.test, не заменяйте их реальными значениями в репозитории. Секрет передавайте через менеджер секретов или переменную окружения только во время выполнения.

Реалистичный пример входа и результата

Вход: Worker формирует техническую отметку времени непосредственно перед созданием собственного span.

Ожидаемый результат: Строка разбирается datetime.fromisoformat, содержит UTC offset и отличается от текущего UTC-времени менее чем на пять секунд.

Проверяйте структуру, а не случайное значение сгенерированного ID или микросекунды времени. Для идентификатора важны префикс, формат, уникальность и сохранение связи. Для lifecycle важны наличие отметок и очистка contextvar. Для exporter важны полученная пачка, отсутствие секретов и корректное закрытие клиента.

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

Подмените timestamp локальной строкой без timezone. Проверка tzinfo должна отклонить такой результат.

Негативный сценарий должен быть автоматическим. Если он лишь описан в документации команды, регрессия останется незаметной. Поместите его рядом с позитивным тестом и запускайте в CI без реального сетевого экспорта. Для сетевой части используйте управляемый mock endpoint, который записывает количество запросов, заголовки без вывода секрета и последовательность кодов ответа.

Диагностика типичных ошибок