Установка
Инструментирование
session_id и agent_id. Области привязывают идентификацию на переменные контекста и каждый вызов события читает её обратно, поэтому вам никогда не нужно передавать id через функции.
Все три работают с async with наравне с with.
Вложенные агенты строят дерево. parent_id и глубина вычисляются из стека:
Как закрывается область
agent() обрабатывает исключения за вас:
agent_end, потому что панель управления закрывает span при agent_end и всё после этого не атрибутируется ничему. Отмена — не ошибка, поэтому отменённые запуски не загромождают поверхность ошибок. Исключение всегда переиспускается: область никогда его не подавляет.
Методы события
Пятнадцать методов в шести семействах. Большинство идут парами — вы генерируете открывающее событие, затем закрывающее, и SDK измеряет промежуток между ними.Пример
Цикл вызовов инструментов против OpenAI API без фреймворка агента:docs/manual/examples/.
Потоки и async
Переменные контекста автоматически распространяются в asyncio задачи. Они не распространяются в новые потоки, потому что поток начинается с пустым контекстом.propagate() события рабочего выбросят TypeError с названием исправления вместо приземления без session. Это намеренно: событие без session пропускается при обработке и ему ответили 200, что — это скрытый отказ, который существует уровень идентификации чтобы предотвратить.
Инструментирование фреймворка без адаптера
Каждый фреймворк агента даёт вам те же три точки. Отобразите их — и у вас есть полная трассировка. Четыре поставляемых адаптера делают ровно это.Ограничьте запуск
Ограничьте каждый инструмент
Сопряжьте каждый вызов модели
Почему нет адаптера AutoGen
Почему нет адаптера AutoGen
autogen-coreне обслуживается с сентября 2025.- AG2 не раскрывает точку регистрации масштаба процесса, эквивалентную хукам других фреймворков, поэтому инструментирование означает обёртывание каждого агента на каждом месте конструирования.
Глубже
Как запись фактически работает. Ничего из этого не требуется для начала.Как выглядит запись по фреймворку
Как выглядит запись по фреймворку
- LangGraph
- CrewAI
- LlamaIndex
- Pydantic AI
- Custom agents
Как session начинается и заканчивается
Как session начинается и заканчивается
session_id.Статус выводится из формы трассировки:agent_end для вас, и при завершении они закрывают всё ещё открытое и отмечают его неполным — упавший запуск урегулируется как done с видимым пробелом вместо вечного зависания.interrupt() LangGraph пауза запуска, root span намеренно остаётся открыт, и возобновляющий вызов его закрывает. Оба вызова — одна session.Identity: session_id, agent_id, и кто их создаёт
Identity: session_id, agent_id, и кто их создаёт
session_id и agent_id опциональны для каждого метода события. Опущены — они разрешаются из вмещающей области:TypeError с названием исправления вместо того чтобы генерировать событие без session, которое ingest пропустит при ответе 200.Области привязывают идентификацию на переменные контекста. Они распространяются в asyncio задачи автоматически но не в новые потоки — оберните рабочего в failproofai_sdk.propagate().Кто создаёт какой id
Как адаптеры разрешают session_id
Первое совпадение выигрывает:- Явная опция
session_id - Per-call метаданные
- Вмещающая область
session() - Метаданные фреймворка
- Собственный run id фреймворка
Держите agent_id низко-кардинальным
Это первичный фасет на каждой поверхности панели управления и LowCardinality(String) колонка. Per-run значение деградирует колонку и заполняет выпадающий фильтр одной записью за запуск.Адаптеры защищают эту колонку для вас:fw_agent_id / fw_run_id, где остаётся queryable без того чтобы быть фасетом.Типы событий, сгруппированные — и какой фреймворк что записывает
Типы событий, сгруппированные — и какой фреймворк что записывает
human_pause и human_interrupt описывают человека, действующего на агента, что ни один фреймворк не сигнализирует — генерируйте их сами.Пары, корреляция и длительность
Пары, корреляция и длительность
Правила корреляции
- Переиспользуйте тот же
tool_call_id,hook_id,pause_idилиinput_idдля соответствующего события завершения. - SDK вычисляет
duration_msдляtool_result,hook_completed,agent_resumeиhuman_input. Передача его этим методам выброситValueError. duration_msпринят наmodel_response, потому что только вызывающий знает реальную задержку провайдера. Это должно быть целое число — float выброситValueErrorна месте вызова, потому что сервер читает колонку как 32-битное целое число без знака и сохранит NULL для чего-либо ещё.- Ключи корреляции ограничены видом и session, поэтому вызов инструмента и hook могут безопасно разделить id, и две одновременные session могут переиспользовать те же id без столкновения. Они не ограничены агентом: пара открытая под одним агентом и закрытая под другим всё ещё коррелирует, это обычный случай в multi-agent фреймворках.
request_idсопрягаетmodel_requestсmodel_response. Без него события модели сопрягаются в порядке за агента, поэтому одновременные вызовы неправильно сопрягаются.- Пара разделённая через процессы всё ещё коррелирует downstream, но SDK не может вычислить её in-process длительность.
- Ожидающая карта держит максимум 10,000 стартов и вытеснит самую старую запись когда полна.
Что в пакете и как instrument() находит ваш фреймворк
Что в пакете и как instrument() находит ваш фреймворк
failproofai-sdk устанавливает всё, все четыре адаптера включены. Extras вытягивают фреймворк, а не адаптер.import failproofai_sdk контрактно ноль-зависимости, принудительно тестом который устанавливает построенное колесо с --no-deps и другое которое доказывает что ни один фреймворк не достигает sys.modules.sys.modules, не список установленных пакетов, поэтому фреймворк, который вы установили но никогда не импортировали, не инструментируется и никогда не импортируется от вашего имени. Чтобы увидеть что подключено:instrument("crewai") на машине без CrewAI не выбросит. Это логирует предупреждение и возвращает (), поэтому один отсутствующий фреймворк никогда не возьмёт процесс который также инструментирует других.Предупреждение несёт базовую ImportError, и это сообщение называет точную команду установки — поэтому исправление в ваших логах, не спрятано.FAILPROOFAI_SDK_STRICT=1 чтобы это выбросило вместо этого. Этот флаг читается один раз и кэшируется, поэтому экспортируйте его перед тем как ваш процесс начнётся вместо того чтобы устанавливать mid-run.Как события достигают Cloud
Как события достигают Cloud
.tmp сначала, затем fsync, затем атомарное переименование:.jsonl, поэтому никогда не может прочитать наполовину написанный файл. Stem несёт timestamp, process id и sequence number, поэтому два процесса flushing в той же миллисекунде не могут столкнуться. Очередь ограничена 10,000 событиями; сверх этого она отбрасывает самое старое и логирует.Daemon доставляет ваши батчи. Он их не открывает и не переписывает.ls гонится по collector и показывает fraction того что вы генерировали — неразличимый от SDK который ничего не записал.Чтобы подтвердить события действительно приземлились, проверьте панель управления. Чтобы看着 spool заполняться, сначала остановите daemon.Когда инструментирование не работает
Когда инструментирование не работает
try и всё что SDK делает происходит вне его.FAILPROOFAI_SDK_STRICT=1 чтобы сделать проглоченную ошибку громкой.Частые проблемы
Span никогда не завершается
Span никогда не завершается
model_request без model_response или tool_use без tool_result. Используйте области, которые гарантируют пару даже когда тело выбросит. Если вы вызываете методы события напрямую, используйте try и finally.Передача duration_ms выбросит ValueError
Передача duration_ms выбросит ValueError
tool_result, hook_completed, agent_resume и human_input. Принято на model_response, потому что только вы знаете реальную задержку провайдера, и это должно быть целое число.События от рабочего потока выбросят TypeError
События от рабочего потока выбросят TypeError
failproofai_sdk.propagate(). См. Потоки и async.Дополнительное поле исчезло или переписало что-то
Дополнительное поле исчезло или переписало что-то
model или outcome переписало бы его и изменило сохранённую колонку. Пространство имён ваши; адаптеры используют префикс fw_.Фильтр агента имеет тысячи записей
Фильтр агента имеет тысячи записей
agent_id — низко-кардинальный фасет и вы положили в него run id. Используйте role или имя узла и положите реальный id в поле payload.
