> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/ru/agenteye/python-sdk) — это не библиотека, и она ничего не меняет в том, как работает SDK.

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

SDK небольшой: тринадцать методов событий, все только по ключевым словам. Кодирующий агент может прочитать справочник [Python SDK](/ru/agenteye/python-sdk) и создать правдоподобное инструментирование за минуту.

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

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

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

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

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

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

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

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

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

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

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

## Требования

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

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

Skill находится в публичной коллекции [`FailproofAI/skills`](https://github.com/FailproofAI/skills):

```bash theme={null}
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 читает ваш цикл агента перед тем как предложить что-либо.

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

```text theme={null}
вы   ▸ Добавьте 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](/ru/agenteye/python-sdk)**: полная справка событий — каждый тип события и поле — позади того, что этот skill автоматизирует.
* **[Sessions](/ru/agenteye/sessions)**: что производит ваше инструментирование, когда события приземляются.
* **[Evaluator Agent Skill](/ru/agenteye/evaluator-skill)**: следующий шаг, когда запуски приземляются — их оценка.
* **[CLI Agent Skill](/ru/agenteye/cli-skill)**: чтение вашей телеметрии обратно.