failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/ru/agenteye/python-sdk-skill.mdx

@@ -0,0 +1,131 @@
+---
+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 настаивает на этом.
+
+## Как это соотносится с другими skills
+
+Три skills, один чистый разделение:
+
+| Skill | Используйте его когда | Что он трогает |
+|---|---|---|
+| **Python SDK skill** (эта страница) | Вы хотите, чтобы ваш агент *выдавал* телеметрию — "добавить наблюдаемость", "почему мой агент не показывается?" | Пишет код в репо вашего агента. Ничего не читает. |
+| **[Evaluator skill](/ru/agenteye/evaluator-skill)** | Вы хотите *оценить* запуски — "что нам вообще измерять?" | Пишет код в вашу репо; читает телеметрию |
+| **[CLI skill](/ru/agenteye/cli-skill)** | Вы хотите *прочитать* что случилось, или управлять вашим развёртыванием | Управляет CLI как вы, включая изменения |
+
+Они передают друг другу в этом порядке: этот skill запускает поток событий, эвалюатор их оценивает, CLI читает их обратно. Нечего оценивать и нечего читать, пока ваш агент не выдаёт сессии, поэтому если вы начинаете с нуля, начните отсюда.
+
+## Предусловия
+
+1. **Python 3.10+** и кодовая база агента, которую вы хотите инструментировать.
+2. **SDK.** Он распространяется среди клиентов как приватное колесо вместо общедоступного индекса — ваш онбординг охватывает как его получить и установить. Skill знает путь установки и попросит вас, если не сможет его найти.
+3. **Ничего больше.** Нет входа на панель, нет API ключа, нет сети. Skill проверяет по файлам событий, которые пишет SDK, поэтому может завершиться и доказать свою работу оффлайн.
+
+## Где его получить
+
+Skill находится в общей коллекции [`FailproofAI/skills`](https://github.com/FailproofAI/skills):
+
+```bash
+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
+you   ▸ Add Failproof AI Observability to this agent.
+
+agent ▸ Read your loop — one tool dispatcher in tools.py, one Anthropic
+        wrapper in llm.py. Two questions before I write anything.
+
+        What counts as one run? You handle requests concurrently, so I'd
+        use the request id you already have in ctx.request_id — then a
+        session here and a request in your logs are the same string.
+
+        And who are the actors? I see a planner path and a researcher
+        path. Label them separately, or is that one agent to you?
+
+you   ▸ Request id is right. They're one agent, call it "assistant".
+
+agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and
+        agent_end bracket handle_request, including the error path. Used
+        a context-local for identity — your dispatcher runs tools in a
+        thread pool, and the simpler approach would have mixed concurrent
+        runs into one session without complaining.
+
+        Verified against a real run: 11 events across 4 files —
+        agent_start, model_request/response, tool_use/tool_result x3,
+        agent_end (outcome=success). environment=production, one session
+        per request, durations paired.
+
+        One thing I did NOT do: your worker pool in batch.py submits
+        straight to the executor, so events from there would be dropped.
+        Want me to fix those too?
+```
+
+Закономерность, на которую стоит обратить внимание: он прочитал код перед предложением, задал только вопросы, на которые вы можете ответить, переиспользовал уже имеющийся id, выбрал форму, безопасную для одновременности *потому что* увидел пул потоков, и **проверил путём чтения фактических событий** вместо объявления успеха — затем отметил единственное место, которое, как он знал, молча провалилось.
+
+## Что вы можете у неё спросить
+
+- *"Почему мой агент не показывается на панели?"* → прочитает лестницу: записываются ли события, есть ли там `agent_start`, правильно ли окружение, читает ли сборщик из того же места.
+- *"Всё приходит под dev."* → окружение никогда не было установлено, или было сброшено позже.
+- *"Добавь отслеживание токенов."* → находит ваш LLM wrapper и записывает модель, причину остановки и использование.
+- *"Инструментируй субагентов тоже."* → одна сессия, различные метки агентов, вложенные под своим родителем.
+- *"Напиши тесты для инструментировки."* → указывает SDK на временную директорию и проверяет события, которые она написала.
+
+## На что нужно обратить внимание
+
+**Позвольте ей проверить.** Шаг, который делает этот skill стоящим использования — последний — запуск вашего агента и чтение событий обратно. Агент, который пишет инструментировку и останавливается, выполнил лёгкую половину, а половину, которая молча падает, другую.
+
+**Согласуйте имена перед кодом.** `session_id` и `agent_id` — оси, по которым каждая поверхность группирует. Переименование их позже разделяет историю: старые запуски сохраняют старые метки и ваши тренды ломаются. Skill попросит; ответ стоит минуты размышления.
+
+**Если ваш агент предлагает установить SDK из общедоступного индекса, skill не загрузился.** SDK распространяется приватно. Это предложение — надёжный признак того, что ваш кодирующий агент угадывает вместо следования skill — остановите его там и проверьте что skill установлен.
+
+Кроме того его радиус взрыва небольшой: он пишет код в вашу рабочую директорию и файлы событий, где вы ему скажете. Он ничего не читает из вашего развёртывания и не меняет о нём ничего.
+
+## Следующие шаги
+
+- **[Python SDK](/ru/agenteye/python-sdk)**: полная справка по событиям — каждый тип события и поле — стоящая за этим что automation этого skill.
+- **[Sessions](/ru/agenteye/sessions)**: что производит ваша инструментировка как только события приходят.
+- **[Evaluator Agent Skill](/ru/agenteye/evaluator-skill)**: следующий шаг как только запуски приходят — их оценка.
+- **[CLI Agent Skill](/ru/agenteye/cli-skill)**: чтение вашей телеметрии обратно.

package/.next/standalone/docs-old/ru/agenteye/python-sdk.mdx

@@ -0,0 +1,437 @@
+---
+---
+title: "Python SDK"
+description: "Посмотрите, что именно сделали ваши AI-агенты в продакшене: каждый запуск агента, вызов инструмента, запрос к модели, хук и вмешательство человека."
+---
+
+
+Посмотрите, что именно сделали ваши AI-агенты в продакшене: каждый запуск агента, вызов инструмента, запрос к модели, хук и вмешательство человека. Python SDK Failproof AI Observability записывает эту цепочку событий изнутри кода вашего агента, чтобы вы могли отлаживать, аудировать и оценивать происходящее. Используйте его, когда захотите, чтобы Failproof AI Observability наблюдал за вашими агентами.
+
+Под капотом SDK записывает структурированные события в локальные JSONL-файлы, а демон сборщика подхватывает их и автоматически отправляет на платформу. Вам не нужно самостоятельно управлять этими файлами.
+
+> **Совет:** Новичок в Failproof AI Observability? Эта страница является полным справочником событий SDK.
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+---
+
+## Установка
+
+SDK распространяется клиентам как приватный wheel, а не из публичного индекса пакетов. В процессе подключения объясняется, как его получить, установить и зафиксировать версию — обратитесь к вашему контакту Failproof AI, если вам нужен доступ.
+
+После установки проверьте её наличие:
+
+```bash
+python -c "import agenteye; print(agenteye.__version__)"
+```
+
+Предпочитаете позволить кодирующему агенту выполнить всю интеграцию? [Python SDK Agent Skill](/ru/agenteye/python-sdk-skill) знает путь установки, планирует точки инструментирования, пишет их и проверяет, что события доходят.
+
+---
+
+## Быстрый старт
+
+```python
+import agenteye
+
+agenteye.configure(environment="production")
+
+agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")
+
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    input={"query": "latest AI research"},
+)
+
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    output={"results": ["..."]},
+)
+
+agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")
+```
+
+### Инструментирование реального вызова
+
+На практике вы оборачиваете существующий код агента. Заключите вызов модели с `model_request` перед и `model_response` после, чтобы два события охватывали реальный запрос и Failproof AI Observability смогла их связать:
+
+```python
+import anthropic
+import agenteye
+
+agenteye.configure(environment="production")
+client = anthropic.Anthropic()
+
+messages = [{"role": "user", "content": "Summarise today's incidents."}]
+
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6",
+    messages=messages,
+)
+
+reply = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=512,
+    messages=messages,
+)
+
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model=reply.model,
+    stop_reason=reply.stop_reason,
+    input_tokens=reply.usage.input_tokens,
+    output_tokens=reply.usage.output_tokens,
+    content=[block.model_dump() for block in reply.content],
+)
+```
+
+Оборачивайте вызовы инструментов аналогично с `tool_use` и `tool_result`, переиспользуя один `tool_call_id` для обеих операций.
+
+Вот как выглядят эти события на дашборде — они раскрашены по типам и фильтруются по среде, агенту и сессии:
+
+![Живой поток событий, раскрашенный по типам событий и фильтруемый по среде, агенту и сессии](/agenteye/images/events-stream.png)
+
+---
+
+## configure()
+
+```python
+agenteye.configure(
+    base_dir=None,           # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye
+    flush_interval=0.5,      # float, seconds between flush cycles
+    environment=None,        # str | None. Deployment environment label
+)
+```
+
+Вызовите один раз перед любым вызовом `event.*`. Безопасно опустить; значения по умолчанию работают из коробки. Все аргументы являются только именованными; передавайте их по имени, как показано выше.
+
+Когда `base_dir` равен `None` (по умолчанию), SDK читает `$AGENTEYE_HOME`, если он установлен,
+в противном случае возвращается к `~/.agenteye`. Это соответствует собственному разрешению сборщика,
+поэтому одна переменная окружения `AGENTEYE_HOME` настраивает общую очередь событий для обоих
+SDK и сборщика.
+
+---
+
+## Окружение
+
+Помечайте каждое событие средой развёртывания (`production`, `staging`, `qa`, `canary` и т. д.). Установите один раз; SDK автоматически прикрепляет его к каждому событию.
+
+**Вариант 1: через `configure()`:**
+
+```python
+agenteye.configure(environment="production")
+```
+
+**Вариант 2: через переменную окружения:**
+
+```bash
+export AGENTEYE_ENVIRONMENT=production
+```
+
+**Приоритет:** `configure(environment=...)` имеет приоритет над переменной окружения. Если ничего не установлено, по умолчанию используется `"dev"`.
+
+Значение окружения появляется как фильтр первого уровня на дашборде и хранится на сервере для быстрых запросов.
+
+> **Предупреждение:** Значения окружения не должны содержать буквальную запятую `,`. Фильтры дашборда используют множественный выбор, разделённый запятыми (`?environment=prod,staging`), поэтому окружение с именем `prod,blue` было бы разделено на два значения. События с окружениями, содержащими запятые, отклоняются при приёме.
+
+---
+
+## Данные и приватность
+
+SDK записывает только поля, которые вы явно передаёте. Подсказки, сообщения, входные и выходные данные инструментов, а также содержимое модели захватываются исключительно потому, что вы передаёте их в вызов `event.*`. Ничто не читается из вашего процесса и не захватывается неявно. Любое поле, которое вы не установили, полностью опускается из события; оно не записывается на диск.
+
+Это делает редактирование вашим выбором и вашей ответственностью. Если подсказка или полезная нагрузка инструмента содержит PII или секреты, которые вы не хотите хранить, очистите или замаскируйте их перед передачей методу события.
+
+---
+
+## Справочник событий
+
+Большинство событий поступают в парах начало/конец, которые разделяют идентификатор корреляции: `tool_use` и `tool_result` разделяют `tool_call_id`, `hook_triggered` и `hook_completed` разделяют `hook_id`, а `human_wait` и `human_input` разделяют `input_id`. Выпустите событие начала, выполните работу, затем выпустите событие завершения с тем же ID. Failproof AI Observability соответствует паре и вычисляет `duration_ms` за вас, поэтому вы никогда не передаёте `duration_ms` сами.
+
+![Граф выполнения сессии в стиле git рядом с временной шкалой событий, реконструированный из парных событий, с панелью разбивки инструмента/модели/хука](/agenteye/images/session-detail.png)
+
+Все методы событий требуют эти два поля:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `session_id` | `str` | Определяет верхнеуровневый запуск агента |
+| `agent_id` | `str` | Определяет, какой агент в сессии выпустил событие |
+
+Все методы также принимают произвольные `**kwargs` для пользовательских метаданных (см. [Пользовательские поля](#custom-fields)).
+
+---
+
+### `event.agent_start()`
+
+Выпускается, когда агент начинает работу.
+
+```python
+agenteye.event.agent_start(
+    session_id="run-001",
+    agent_id="planner",
+    goal="answer user query",   # str | None
+    parent_id=None,             # str | None - parent agent_id for nested agents
+)
+```
+
+---
+
+### `event.agent_end()`
+
+Выпускается, когда агент завершает работу.
+
+```python
+agenteye.event.agent_end(
+    session_id="run-001",
+    agent_id="planner",
+    outcome="success",          # str | None
+    summary="Answered query",   # str | None
+)
+```
+
+---
+
+### `event.tool_use()`
+
+Выпускается, когда агент вызывает инструмент. Сопарьте с `tool_result`; SDK автоматически вычисляет `duration_ms`.
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",     # str, required
+    tool_call_id="toolu_01",    # str, required - correlation key for the matching tool_result
+    input={"query": "..."},     # dict | None
+)
+```
+
+---
+
+### `event.tool_result()`
+
+Выпускается, когда инструмент возвращает результат. Коррелирует с `tool_use` через `tool_call_id`.
+
+```python
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",        # must match the prior tool_use
+    output={"results": ["..."]},    # Any | None
+    error=None,                     # str | None - set if the tool raised
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+---
+
+### `event.model_request()`
+
+Выпускается непосредственно перед отправкой подсказки в LLM.
+
+```python
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
+    messages=[                   # list[dict] | None - conversation turns
+        {"role": "user", "content": "..."},
+    ],
+    system="You are helpful.",   # Any | None - str or list of content blocks
+    tools=[                      # list[dict] | None - tool schemas offered to the model
+        {"name": "search", "input_schema": {"type": "object"}},
+    ],
+)
+```
+
+Записи `messages` принимают либо простую строку `content`, либо список блоков в стиле Anthropic `content`. Параметры выборки (`temperature`, `max_tokens` и т. д.) можно передать в виде дополнительных kwargs.
+
+---
+
+### `event.model_response()`
+
+Выпускается, когда LLM возвращает ответ.
+
+```python
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
+    stop_reason="end_turn",     # str | None
+    input_tokens=1024,          # int | None
+    output_tokens=256,          # int | None
+    content=[                    # Any | None - str, or list of content blocks
+        {"type": "text", "text": "..."},
+    ],
+    role="assistant",            # str | None
+)
+```
+
+`content` принимает либо простую строку (универсальные провайдеры), либо список блоков контента в стиле Anthropic. Вызовы инструментов находятся внутри `content` как блоки `{"type": "tool_use", ...}`, без отдельного поля `tool_calls`.
+
+---
+
+### `event.hook_triggered()`
+
+Выпускается, когда срабатывает хук. Сопарьте с `hook_completed`; SDK автоматически вычисляет `duration_ms`.
+
+```python
+agenteye.event.hook_triggered(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",   # str, required
+    hook_id="hook-abc",         # str, required - correlation key
+    trigger_event="tool_use",   # str | None
+    input={"tool": "search"},   # Any | None
+)
+```
+
+---
+
+### `event.hook_completed()`
+
+Выпускается, когда хук завершается. Коррелирует с `hook_triggered` через `hook_id`.
+
+```python
+agenteye.event.hook_completed(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",
+    hook_id="hook-abc",         # must match the prior hook_triggered
+    outcome="allow",            # str | None
+    output=None,                # Any | None
+    error=None,                 # str | None
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+---
+
+### `event.error()`
+
+Выпускается, когда возникает необработанная ошибка.
+
+```python
+agenteye.event.error(
+    session_id="run-001",
+    agent_id="planner",
+    error_type="TimeoutError",  # str, required
+    message="timed out",        # str, required
+    traceback="Traceback...",   # str | None
+)
+```
+
+---
+
+## События взаимодействия человека и системы
+
+События взаимодействия человека и системы предоставляют вам контроль над моментами, когда человек вступает в выполнение агента (ожидание одобрения, предоставление ввода, пауза или остановка агента). Они позволяют измерить, сколько времени люди берут для ответа (SDK автоматически вычисляет `duration_ms` для парных событий), аудировать, кто приостановил или прервал агента, и создавать рабочие процессы одобрения и контроля, которые отображаются на дашборде.
+
+### `event.human_wait()`
+
+Выпускается, когда агент приостанавливает выполнение в ожидании ввода человека. Сопарьте с `human_input`; SDK автоматически вычисляет `duration_ms` (сколько времени человек занял на ответ).
+
+```python
+agenteye.event.human_wait(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",                          # str, required - correlation key for the matching human_input
+    prompt="Do you approve this action?",        # str | None - the question shown to the human
+    options=["approve", "reject", "defer"],      # list[str] | None - choices presented to the human
+    reason="approval_required",                  # str | None - why the agent is waiting
+)
+```
+
+### `event.human_input()`
+
+Выпускается, когда человек предоставляет ввод и агент возобновляет работу. Коррелирует с `human_wait` через `input_id`. `duration_ms` вычисляется автоматически и не должна передаваться вызывающей стороной.
+
+```python
+agenteye.event.human_input(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",    # str, required - must match the prior human_wait
+    response="approve",    # str | None - the human's answer (free text or selected option)
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+### `event.human_pause()`
+
+Выпускается, когда человек активно приостанавливает агента (например, через управление дашборда). Агент приостановлен, но не завершен.
+
+```python
+agenteye.event.human_pause(
+    session_id="run-001",
+    agent_id="planner",
+    reason="user_requested",  # str | None
+    user_id="usr_42",         # str | None - who paused the agent
+)
+```
+
+### `event.human_interrupt()`
+
+Выпускается, когда человек активно останавливает агента во время выполнения. В отличие от `human_pause`, работа агента завершается, а не приостанавливается.
+
+```python
+agenteye.event.human_interrupt(
+    session_id="run-001",
+    agent_id="planner",
+    reason="output_incorrect",       # str | None
+    user_id="usr_42",                # str | None - who interrupted the agent
+    at_step="tool_use:web_search",   # str | None - what the agent was doing when stopped
+)
+```
+
+---
+
+## Пользовательские поля
+
+Любые дополнительные аргументы ключевого слова добавляются к событию после стандартных полей:
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="db_query",
+    tool_call_id="toolu_02",
+    tenant_id="acme",           # custom field
+    region="us-east-1",         # custom field
+)
+```
+
+`timestamp`, `type` и `environment` зарезервированы и вызывают `ValueError` (`Reserved field names cannot be used as custom fields: [...]`), если переданы как пользовательские поля. `session_id` и `agent_id` являются обязательными параметрами для каждого метода события и не могут быть переданы второй раз; Python вызовет `TypeError`, если вы это сделаете. Вместо этого установите окружение с помощью `configure(environment=...)` (или переменной `AGENTEYE_ENVIRONMENT`).
+
+Сохраняйте полезные нагрузки как структурированный JSON, если хотите запрашивать их поля. Значения, которые JSON не поддерживает изначально — такие как даты/время, UUID, десятичные числа, наборы, байты или объекты моделей — преобразуются в строки, чтобы запись продолжалась безопасно.
+
+---
+
+## Как записываются события
+
+События буферизуются в процессе и записываются на диск каждые `flush_interval` секунд (по умолчанию 500 мс). Каждая запись в буфер записывает один JSONL-файл:
+
+```text
+~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl
+```
+
+Сборщик отслеживает этот каталог и автоматически загружает файлы. Вам не нужно напрямую управлять этими файлами.
+
+Каждый файл записывается атомарно: SDK пишет во временный файл, а затем переименовывает его на место, поэтому сборщик никогда не видит наполовину записанного файла. Финальная запись в буфер также выполняется при выходе процесса, поэтому события, буферизованные в последний интервал, не теряются. Если сборщик в автономном режиме, события просто накапливаются как файлы на диске и отправляются, когда он снова включается.
+
+---
+
+## Дальнейшие шаги
+
+- [Поток событий](/ru/agenteye/event-stream): смотрите эти события в прямом эфире, раскрашенные и фильтруемые по среде, агенту и сессии.
+- [Сессии](/ru/agenteye/sessions): смотрите, как парные события реконструируют каждый запуск агента как граф выполнения и временную шкалу.

package/.next/standalone/docs-old/ru/agenteye/queries.mdx

@@ -0,0 +1,56 @@
+---
+title: "Запросы"
+description: "Задавайте любые вопросы о данных вашего агента и получайте ответы за секунды."
+---
+
+
+Задавайте любые вопросы о данных вашего агента и получайте ответы за секунды. Observability от Failproof AI предоставляет вам библиотеку сохранённых готовых к запуску запросов над вашими событиями и оценками, чтобы вы начали с рабочего примера вместо пустого редактора SQL.
+
+![Библиотека сохранённых запросов: сетка переиспользуемых запросов, как встроенных предустановок, так и пользовательских](/agenteye/images/queries.png)
+
+*Ваша библиотека сохранённых запросов на `/<org-slug>/queries`: встроенные предустановки рядом с запросами, которые сохранила ваша команда.*
+
+## Начните с предустановки, а не с пустой страницы
+
+Вам не нужно помнить названия таблиц или писать SQL с нуля. Библиотека открывается со встроенными предустановками для вопросов, которые команды задают чаще всего, расположенными рядом с запросами, которые сохранила и назвала ваша команда. Выберите тот, который близок к тому, что вам нужно, и вы будете на полпути к ответу.
+
+Каждый сохранённый запрос имеет область действия организации и является общим, поэтому полезные запросы, которые пишут ваши коллеги, становятся и вашими. Назовите запрос и добавьте описание один раз, и любой в вашей организации сможет его найти, запустить или позже закрепить его результаты на панели управления.
+
+Найдите его на `/<org-slug>/queries`.
+
+## Отредактируйте его и запустите в редакторе SQL
+
+Откройте любой запрос, и он откроется в редакторе SQL, где вы сможете его изменить и сразу увидеть ответ: без экспорта, без круговорота, без ожидания помощи от кого-то другого.
+
+![Редактор SQL-запросов с запущенным сохранённым запросом, боковой панелью схемы и таблицей результатов](/agenteye/images/query-lab.png)
+
+*Редактор SQL: ваш запрос слева, боковая панель схемы, чтобы вы никогда не угадывали название колонки, и таблица результатов снизу.*
+
+- **Боковая панель схемы** показывает таблицы аналитики и их колонки, чтобы вы могли составить запрос без поиска названий полей.
+- **Таблица результатов в реальном времени** возвращает строки в момент запуска, поэтому вы итерируете за секунды вместо того, чтобы гадать и пересчитывать.
+- **Только чтение по умолчанию.** Запросы выполняются для хранилища событий и проверяются на сервере: разрешены только операторы `SELECT` и `WITH` с тайм-аутом и ограничением на количество строк. Поисковый запрос никогда не может изменить ваши данные, и вышедший из-под контроля запрос будет остановлен за вас.
+
+Довольны результатом? Сохраните его обратно в библиотеку, чтобы вся команда его унаследовала, или закрепите его результат на панели управления как линейную диаграмму, столбчатую диаграмму, площадную диаграмму или круговую диаграмму.
+
+## Запускайте их из терминала или позвольте помощнику их написать
+
+Те же сохранённые запросы следуют за вами, где бы вы ни работали:
+
+- **Из терминала.** CLI `agenteye` выводит список, запускает и сохраняет те же самые запросы, поэтому вы можете вставить результат в скрипт, интегрировать его в CI или передать кодирующему агенту.
+
+```bash
+agenteye query list                 # те же сохранённые запросы из вашего терминала
+agenteye query run errs --arg prod  # запустить один и вывести строки (добавьте --json для передачи)
+```
+
+  См. [CLI и агенты](/ru/agenteye/cli-and-agents) для полного набора команд.
+
+- **От AI-помощника.** Не уверены, как сформулировать SQL? Спросите встроенного в панель [AI-помощника](/ru/agenteye/assistant) на простом английском языке, и он напишет запрос и сохранит его в вашу библиотеку за вас.
+
+Запуск сохранённого запроса контролируется разрешением `queries:run`, отделённым от разрешений на создание или удаление запросов, поэтому вы можете предоставить доступ на чтение без разрешения переписывать библиотеку.
+
+## Связанное
+
+- [Панели управления](/ru/agenteye/dashboards): закрепляйте результаты запросов на общих диаграммах уровня организации.
+- [AI-помощник](/ru/agenteye/assistant): задавайте вопросы на простом английском языке и получайте запрос в ответ.
+- [CLI и агенты](/ru/agenteye/cli-and-agents): запускайте и сохраняйте те же запросы из вашего терминала.