Python sdk skill

title: “Failproof AI Observability Python SDK Agent Skill” description: “Переходите от неинструментированного агента к событиям, которые можно увидеть, когда ваш кодирующий агент находит точки инструментирования, пишет их и подтверждает, что они работают.”

Скажите своему кодирующему агенту «добавь Failproof AI Observability к этому агенту» и позвольте ему прочитать ваш цикл, разобраться, где должна быть инструментирование, написать его и проверить события перед завершением работы. Python SDK skill (agenteye-python-sdk) — это Agent Skill: папка инструкций, которую кодирующий агент, такой как Claude Code или Codex, загружает по требованию, когда задача ей соответствует. Она учит агента использовать Python SDK — это не библиотека, и она ничего не меняет в том, как работает SDK.

Инструментирование легко писать, но легко сделать это неправильно незаметно

SDK небольшой: тринадцать методов событий, все только по ключевым словам. Кодирующий агент может прочитать справочник Python SDK и создать правдоподобное инструментирование за минуту. Подвох в том, что этот SDK не выбрасывает исключение, когда вы ошибаетесь, и неправильное инструментирование выглядит так же, как правильное, пока кто-нибудь не откроет панель управления и не обнаружит, что она пуста. Ошибки, которые стоят реального времени — это всегда молчание:

Ошибка	Что вы видите
Нет `agent_start`	Каждое событие попадает. Нулевые сессии.
Переменная окружения никогда не установлена	Всё работает, скатегоризировано как `dev`.
`outcome="failure"`	Запуск показывается зелёным — только `failed`, `error`, `timeout`, `rejected` считаются.
Опечатка в имени поля	Принимается и сохраняется как новое поле.
События, отправленные из пула потоков	Молча отбрасываются.

Ничто из этого не выбрасывает исключение. Ничто не появляется в тестах. Всё это предусмотрено в skill’е, сформулировано как контракт с проверкой, которая это ловит.

Что он делает, по порядку

Skill выполняет те же три этапа, которые выполнил бы внимательный инженер:

План. Он читает ваш цикл агента и задаёт два вопроса, ответить на которые можете только вы: что считается одним запуском (ваш session_id) и кто различаемые акторы (ваш agent_id). Он согласует это перед написанием кода, потому что изменение их позже разбивает вашу историю и ломает тренды.
Написание. Он привязывает идентичность один раз за запуск вместо прохождения через каждый сайт вызова и выбирает форму, безопасную для параллелизма — деталь, которая имеет значение, потому что очевидный способ молча смешивает два перекрывающихся запуска в одну сессию.
Проверка. Он запускает ваш агент и читает полученные файлы событий, проверяя наличие agent_start, правильность окружения и что один запуск произвёл одну сессию.

Третий этап — это то, что люди пропускают. SDK пишет события в локальные файлы, поэтому полная интеграция может быть доказана на ноутбуке без сервера, без API ключа и без сети — именно поэтому skill настаивает на том, чтобы это сделать.

Как это соотносится с другими skill’ами

Три skill’а, одно чистое разделение:

Skill	Используйте, когда	Что он трогает
Python SDK skill (эта страница)	Вы хотите, чтобы ваш агент выпускал телеметрию — «добавить наблюдаемость», «почему мой агент не отображается?»	Пишет код в репо вашего агента. Ничего не читает.
Evaluator skill	Вы хотите оценить запуски — «что вообще мы должны измерять?»	Пишет код в вашем репо; читает телеметрию
CLI skill	Вы хотите прочитать, что произошло, или управлять вашим развёртыванием	Управляет CLI как вы, включая изменения

Они передают друг другу в таком порядке: этот skill запускает события, evaluator их оценивает, CLI их читает. Нечего оценивать и нечего читать, пока ваш агент не выпускает сессии, поэтому если вы начинаете с нуля, начните здесь.

Требования

Python 3.10+ и кодовая база агента, который вы хотите инструментировать.
SDK. Он распространяется клиентам как приватный wheel вместо публичного индекса — ваша подготовка описывает, как его получить и установить. Skill знает путь установки и будет вас спрашивать, а не гадать, если он его не найдёт.
Ничего больше. Нет входа в панель управления, нет API ключа, нет сети. Skill проверяет против файлов событий, которые пишет SDK, поэтому может закончить и доказать свою работу оффлайн.

Где его получить

Skill находится в публичной коллекции FailproofAI/skills:

npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code

Добавьте -g для установки на каждый проект вместо только текущего, и --copy если ваше окружение не следует символическим ссылкам. Для Codex передайте -a codex.

Установка вручную

Agent Skills — это папки, содержащие SKILL.md плюс ссылки. Если вы предпочитаете не использовать установщик:

Claude Code: скопируйте папку agenteye-python-sdk/ в ~/.claude/skills/ (каждый проект) или <your-repo>/.claude/skills/ (только этот репо). Claude Code автоматически её обнаружит — проверьте список /skills или просто спросите что-нибудь, что ей соответствует.
Codex: Codex читает одинаковый SKILL.md. Bundled agents/openai.yaml устанавливает allow_implicit_invocation: true, поэтому она автоматически выбирается, когда задача ей соответствует; иначе вызовите её как $agenteye-python-sdk.

Запустите ваш агент в репозитории, содержащем код, который вы хотите инструментировать — skill читает ваш цикл агента перед тем как предложить что-либо.

Как выглядит сессия

вы   ▸ Добавьте Failproof AI Observability к этому агенту.

агент ▸ Прочитал ваш цикл — один диспетчер инструментов в tools.py, один wrapper
        Anthropic в llm.py. Два вопроса перед тем как я что-то напишу.

        Что считается одним запуском? Вы обрабатываете запросы параллельно, поэтому я бы
        использовал id запроса, который у вас уже есть в ctx.request_id — тогда
        сессия здесь и запрос в ваших логах — одна и та же строка.

        И кто акторы? Я вижу путь планировщика и путь исследователя.
        Обозначить их отдельно, или это один агент для вас?

вы   ▸ Id запроса правильный. Они один агент, назовите его «assistant».

агент ▸ Готово. Завернул диспетчер и LLM клиент; agent_start и
        agent_end заключают handle_request, включая путь ошибки. Использовал
        context-local для идентичности — ваш диспетчер запускает инструменты в пуле потоков,
        и более простой подход смешал бы параллельные запуски в одну сессию молча.

        Проверено против реального запуска: 11 событий через 4 файла —
        agent_start, model_request/response, tool_use/tool_result x3,
        agent_end (outcome=success). environment=production, одна сессия
        на запрос, длительности спарены.

        Одно, что я НЕ сделал: ваш пул воркеров в batch.py отправляет
        прямо в executor, поэтому события оттуда будут отброшены.
        Хотите, чтобы я и это исправил?

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

Что вы можете у него попросить

«Почему мой агент не отображается на панели управления?» → проходит по лестнице: пишутся ли события, есть ли agent_start, правильно ли окружение, читает ли collector то же место.
«Всё приземляется под dev.» → окружение никогда не было установлено, или было переустановлено более поздним вызовом.
«Добавьте отслеживание токенов.» → находит ваш LLM wrapper и записывает модель, причину остановки и использование.
«Инструментируйте и суб-агентов.» → одна сессия, различные метки агентов, вложенные под их родителя.
«Напишите тесты для инструментирования.» → указывает SDK на временный каталог и делает assert для событий, которые он написал.

На что обратить внимание

Позвольте ему проверять. Шаг, который делает этот skill стоящим использования — последний — запуск вашего агента и чтение событий обратно. Агент, который пишет инструментирование и останавливается, сделал лёгкую половину, а половина, которая молча падает — другая. Согласуйте имена перед кодом. session_id и agent_id — это оси, по которым группируются все поверхности. Их переименование позже разбивает историю: старые запуски держат старые метки и ваши тренды ломаются. Skill будет спрашивать; ответ стоит минуты размышлений. Если ваш агент предлагает установить SDK с публичного индекса, skill не загрузился. SDK распространяется приватно. Это предложение — надёжный признак того, что ваш кодирующий агент гадает вместо того, чтобы следовать skill’у — остановите его там и проверьте, установлен ли skill. Кроме того его радиус взрыва мал: он пишет код в вашем рабочем каталоге и файлы событий там где вы ему скажете. Он ничего не читает из вашего развёртывания и ничего не меняет в нём.

Следующие шаги

Python SDK: полная справка событий — каждый тип события и поле — позади того, что этот skill автоматизирует.
Sessions: что производит ваше инструментирование, когда события приземляются.
Evaluator Agent Skill: следующий шаг, когда запуски приземляются — их оценка.
CLI Agent Skill: чтение вашей телеметрии обратно.

Overview

Features

SDK and CLI

Administration

Инструментирование легко писать, но легко сделать это неправильно незаметно

Что он делает, по порядку

Как это соотносится с другими skill’ами

Требования

Где его получить

Установка вручную

Как выглядит сессия

Что вы можете у него попросить

На что обратить внимание

Следующие шаги

​Инструментирование легко писать, но легко сделать это неправильно незаметно

​Что он делает, по порядку

​Как это соотносится с другими skill’ами

​Требования

​Где его получить

​Установка вручную

​Как выглядит сессия

​Что вы можете у него попросить

​На что обратить внимание

​Следующие шаги

Инструментирование легко писать, но легко сделать это неправильно незаметно

Что он делает, по порядку

Как это соотносится с другими skill’ами

Требования

Где его получить

Установка вручную

Как выглядит сессия

Что вы можете у него попросить

На что обратить внимание

Следующие шаги