Пользовательские агенты

Описание каждого параметра, метода и поля. Если вы впервые осуществляете инструментирование, начните с руководства — эта страница предназначена для справки.

Руководство пользовательских агентов

Установка, инструментирование, методы событий, практический пример и типичные проблемы.

Используете фреймворк?

LangChain, CrewAI, LlamaIndex и Pydantic AI инструментируют себя одним вызовом.

Python 3.10 или новее. Без зависимостей во время выполнения.

Установка

pip install failproofai-sdk

Пакет устанавливается как failproofai-sdk и импортируется в Python как failproofai_sdk. Дополнения фреймворков, такие как failproofai-sdk[langgraph], устанавливают сам фреймворк; адаптеры всегда идут в базовом пакете.

Подключение daemon Failproof

Панель управления
CLI

Перейдите в Admin → Keys и создайте ключ с разрешением events:add.
Подключите daemon Failproof к Cloud на машине агента.
Запустите одну сеанс с инструментированием, затем найдите его точный ID в Observe → Events.
Перейдите в Observe → Sessions, выберите ту же среду и откройте восстановленную трассировку.

failproofai config \
  --connect https://app.befailproof.ai \
  --token <events-add-key>
failproofai config --status

Конфигурация

import failproofai_sdk

failproofai_sdk.configure(
    base_dir=None,
    flush_interval=0.5,
    environment="production",
)

Аргумент	Что он делает
`environment`	Метка для каждого события — `production`, `staging`, `prod-eu`. По умолчанию `dev`.
`flush_interval`	Как часто фоновый поток записывает на диск, в секундах. По умолчанию `0.5`.
`base_dir`	Где писать. По умолчанию спул daemon, что подходит в большинстве случаев.

Задайте через переменную окружения:

Переменная	Что она делает
`AGENTEYE_ENVIRONMENT`	Задаёт `environment` без изменения кода, для случаев, когда метка относится к развёртыванию, а не к приложению. Аргумент `configure()` имеет приоритет.
`FAILPROOFAI_HOME`	Перемещает корень Failproof AI, содержащий спул.
`FAILPROOFAI_SDK_STRICT`	`1` заставляет ошибки инструментирования генерировать исключение вместо логирования.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` заставляет проблему совместимости фреймворка генерировать исключение вместо предупреждения.

Без запятых в environment. Система приёма разбивает это поле по запятым для построения фильтров и пропускает любое событие, метка которого содержит запятую — весь запуск может молча исчезнуть. Пишите prod-eu, а не prod,eu.configure(environment="prod,eu") генерирует исключение, чтобы вы узнали сразу. AGENTEYE_ENVIRONMENT не может генерировать исключение — вас никто не вызывает — поэтому она выдаёт предупреждение один раз и откатывается на dev.

События ставятся в очередь в памяти и записываются в фоне каждые flush_interval секунд, с финальной записью при выходе интерпретатора. Процесс, грубо завершённый, теряет всё, что ещё не было записано.

Идентификация

Каждое событие принадлежит сеансу и агенту. Области заполняют оба, поэтому вы редко их передаёте:

with failproofai_sdk.session():
    with failproofai_sdk.agent("planner"):
        failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1")

Передача session_id или agent_id явно всё ещё работает и имеет приоритет. Если ни один не привязан и не передан, вызов генерирует TypeError вместо отправки события, которое Cloud молча отбросит.

Идентификация работает через переменные контекста. Она следует за задачами asyncio автоматически, но не новыми потоками — оберните рабочий код в failproofai_sdk.propagate() или его события окажутся неприкреплёнными.

Каталог событий

Пятнадцать методов. Большинство идут в парах — вы вызываете открывающий, затем закрывающий, и SDK измеряет интервал.

	Открывает	Закрывает
Агенты	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
Модели	`model_request`	`model_response`
Инструменты	`tool_use`	`tool_result`
Хуки	`hook_triggered`	`hook_completed`
Люди	`human_wait`	`human_input`

Три работают отдельно: error, human_pause, human_interrupt.

Каждое поле для каждого метода

Каждый метод также принимает session_id и agent_id, которые области заполняют для вас. Всё, оставленное как None, отбрасывается вместо отправки в JSON как null, и каждый метод возвращает None.

Метод	Обязательно	Опционально
`agent_start`	—	`goal`, `parent_id`
`agent_end`	—	`outcome`, `summary`
`agent_pause`	`pause_id`	`reason`, `user_id`
`agent_resume`	`pause_id`	`reason`, `user_id`
`model_request`	—	`model`, `messages`, `system`, `tools`, `request_id`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `duration_ms`
`tool_use`	`tool_name`, `tool_call_id`	`input`
`tool_result`	`tool_name`, `tool_call_id`	`output`, `error`
`hook_triggered`	`hook_name`, `hook_id`	`trigger_event`, `input`
`hook_completed`	`hook_name`, `hook_id`	`outcome`, `output`, `error`
`error`	`error_type`, `message`	`traceback`
`human_wait`	`input_id`	`prompt`, `options`, `reason`
`human_input`	`input_id`	`response`
`human_pause`	—	`reason`, `user_id`
`human_interrupt`	—	`reason`, `user_id`, `at_step`

Чтобы отметить запуск как неудачный, outcome должен быть одним из failed, error, timeout или rejected. Всё остальное — включая похожее "failure" — считается успехом.

Парирование и длительность

Одно правило: передайте закрывающему событию тот же id, что и его открывающему. Это то, что их связывает, и что позволяет SDK измерить интервал.

Пара	Сопоставляется по
`tool_use` → `tool_result`	`tool_call_id`
`hook_triggered` → `hook_completed`	`hook_id`
`agent_pause` → `agent_resume`	`pause_id`
`human_wait` → `human_input`	`input_id`
`model_request` → `model_response`	`request_id`

Не передавайте duration_ms сами. SDK измеряет его, и передача генерирует ValueError. Одно исключение — model_response, где только вы знаете реальную задержку поставщика. Передайте целое число миллисекунд — float генерирует исключение, потому что столбец 32-битное целое и иначе остался бы пуст.

Граничные случаи

Id’ы должны быть уникальны только в пределах вида, в пределах сеанса. Вызов инструмента и хук могут разделять один; два одновременно запущенных сеанса могут переиспользовать те же id’ы без коллизии.
Они не привязаны к агенту. Пара, открытая под одним агентом и закрытая под другим, всё ещё совпадает — это нормальный случай в коде с несколькими агентами.
request_id опционален, но рекомендуется. Без него события модели парируются в порядке поступления, поэтому два одновременных вызова в одном агенте могут неправильно спариться.
Пара, разделённая между процессами, всё ещё совпадает в Cloud, но SDK не может её измерить — ничто ни в одном процессе не видело обе половины.
Максимум 10 000 открывающих ждут закрывающего одновременно. После этого самый старый отбрасывается, поэтому утечка не может расти без ограничений.

Ваши собственные поля

Любой дополнительный ключевой аргумент, который вы передаёте, хранится с событием:

failproofai_sdk.event.tool_use(
    tool_name="search", tool_call_id="c1",
    fw_tenant="acme", fw_region="eu-west-1",     # ваши собственные
)

Предпочитайте JSON типы, если хотите запрашивать их позже. Всё остальное — UUID, datetime, Decimal, set, bytes, объект модели — хранится как строка.

Добавляйте префикс к названиям ваших полей. Дополнительные поля применяются последними, поэтому поле, названное model, tool_name или outcome, молча перезапишет реальное. Адаптеры фреймворков используют fw_; делайте то же самое и ничто не может конфликтовать.Это также почему неправильно написанное опциональное поле никогда не ошибается — оно просто становится новым пользовательским полем. Если стандартное поле отсутствует в Cloud, сначала проверьте орфографию.

Эти пять имён зарезервированы и отклоняются сразу: timestamp, session_id, agent_id, type, environment.

Доставка и проверка

Панель управления
CLI

В Observe → Events сначала проверьте наличие agent_start и наличие agent_end в конце. Затем откройте Observe → Sessions и подтвердите, что события модели, инструмента, человека, хука и ошибок появляются в предполагаемом порядке. Используйте ID сеанса как первичный ключ устранения неполадок.

failproofai flush --wait --timeout 60
failproofai config --status
fp sessions --since 1h --env production --session-id <session-id>
fp events --since 1h --session-id <session-id> --full

Если Cloud пуста, проверьте $FAILPROOFAI_HOME/custom-agents/events, иначе ~/.failproofai/custom-agents/events. JSONL файлы доказывают эмиссию SDK; растущий спул указывает на конфигурацию daemon или доставку, а пустой спул указывает на инструментирование или время жизни процесса.

Проверяйте спул только когда daemon остановлен. Во время его работы он собирает и удаляет каждый пакет в течение миллисекунд, поэтому список директории гонится с коллектором и показывает гораздо меньше событий, чем было излучено.

Предотвращение сбоев в пользовательской среде выполнения

Используйте результаты аудита и связанные трассировки для определения небезопасного действия, требуемого доказательства и предполагаемого ответа. Пользовательская интеграция обеспечения должна выявить действие перед выполнением, передать его структурированный ввод в механизм политик и применить результирующее решение allow, instruct или deny. Свяжитесь с Failproof AI и мы поможем отобразить границы модели, инструмента и жизненного цикла вашей среды выполнения на хуки политик, затем проверим интеграцию с вами.

Connect your agents

Reference

Пользовательские агенты

Руководство пользовательских агентов

Используете фреймворк?

Установка

Подключение daemon Failproof

Конфигурация

Идентификация

Каталог событий

Парирование и длительность

Ваши собственные поля

Доставка и проверка

Предотвращение сбоев в пользовательской среде выполнения

Руководство пользовательских агентов

Используете фреймворк?

​Установка

​Подключение daemon Failproof

​Конфигурация

​Идентификация

​Каталог событий

​Парирование и длительность

​Ваши собственные поля

​Доставка и проверка

​Предотвращение сбоев в пользовательской среде выполнения

Установка

Подключение daemon Failproof

Конфигурация

Идентификация

Каталог событий

Парирование и длительность

Ваши собственные поля

Доставка и проверка

Предотвращение сбоев в пользовательской среде выполнения