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

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

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

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

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

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

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

Установка

pip install failproofai-sdk

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

Подключение демона Failproof

Dashboard
CLI

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

Прочитайте ключ events:add в оболочку. read -s получает его на подсказке без эха, поэтому он никогда не появится в команде или истории оболочки:

read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN

Затем настройте машину и проверьте, что она подключена:

failproofai config
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`	Куда писать. По умолчанию spooling демона, что вам нужно, если вы не знаете иное.

Устанавливается переменной окружения:

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

Без запятых в environment. Ingest разбивает это поле на запятые для построения фильтров и пропускает любое событие, метка которого содержит запятую — вся сессия молча исчезает. Пишите 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 вместо того, чтобы излучить событие, которое облако молча отбросит.

Идентичность ездит на переменных контекста. Она автоматически следует за 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" — считается успехом.

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

Одно правило: дайте закрывающему событию тот же идентификатор, что и его открывающий. Это то, что их спаривает и позволяет 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, где только вы знаете реальную задержку провайдера. Передайте целое число миллисекунд — число с плавающей точкой выбросит, потому что столбец — это 32-битное целое число и в противном случае окажется пустым.

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

Идентификаторы нужно делать уникальными только для своего вида, в каждой сессии. Вызов инструмента и хук могут поделиться одним; две сессии, запущенные одновременно, могут переиспользовать одни и те же идентификаторы без столкновений.
Они не привязаны к агенту. Пара, открытая под одним агентом и закрытая под другим, по-прежнему совпадает — что является нормальным случаем в многоагентном коде.
request_id опционален, но рекомендуется. Без него события модели спариваются в порядке их поступления, поэтому два одновременных вызова в одном агенте могут неправильно спариться.
Пара, разбитая между процессами, по-прежнему совпадает в облаке, но 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_; делайте то же самое и ничто не может столкнуться.Вот почему опечатка в опциональном поле никогда не вызывает ошибку — это просто становится новым пользовательским полем. Если стандартного поля нет в облаке, сначала проверьте орфографию.

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

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

Dashboard
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

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

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

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

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

Connect your agents

Reference

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

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

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

Установка

Подключение демона Failproof

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

Идентичность

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

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

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

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

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

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

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

​Установка

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

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

​Идентичность

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

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

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

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

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

Установка

Подключение демона Failproof

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

Идентичность

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

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

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

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

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