failproofai 1.0.1-beta.1 → 1.0.2-beta.0

package/.next/standalone/docs-old/ru/agenteye/cli-recipes.mdx

@@ -0,0 +1,179 @@
+---
+title: "CLI recipes for agents"
+description: "Copy-paste query patterns and jq recipes that turn session, event, and evaluation data into something a script or coding agent can automate."
+---
+
+
+Pull session, event, and evaluation data (and trigger re-evaluations) straight from a script or coding agent, with clean JSON on stdout that pipes directly into `jq`. These recipes turn Failproof AI Observability's data into something a terminal user or an AI coding agent (Claude Code, Cursor) can query and automate, without clicking through the dashboard.
+
+The patterns below are copy-paste ready for the Failproof AI Observability CLI (`agenteye`). For installation, authentication, and the full option list see [CLI](/ru/agenteye/cli); run `agenteye -h` or `agenteye <command> -h` for the built-in help.
+
+## Golden rules
+
+1. **Global options go *before* the command.** `agenteye --json sessions` is correct; `agenteye sessions --json` is not. The globals are `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`.
+2. **Pass `--json` whenever you parse output.** Data goes to **stdout** as JSON; human status and errors go to **stderr**, so stdout stays clean to pipe into `jq`.
+3. **Branch on the exit code**, not on stderr text: `0` ok · `1` unexpected error · `2` bad arguments · `3` cannot reach the dashboard · `4` not logged in or expired · `5` missing permission · `6` resource not found.
+4. **Discover with `-h`.** Every command documents its filters, value formats, and JSON shape.
+
+## One-time setup
+
+```bash
+export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # so you don't repeat --base-url
+agenteye login --email you@example.com                       # paste the emailed code; valid ~24h
+```
+
+## Confirm auth before doing work
+
+`whoami` never errors on a missing or expired session; it reports `logged_in:false` instead, so an agent can probe auth state safely. (It can still exit non-zero if no base URL is set or the dashboard is unreachable.)
+
+```bash
+if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then
+  echo "Not authenticated. Run: agenteye login" >&2; exit 1
+fi
+```
+
+## Find failing or low-scoring sessions
+
+```bash
+# sessions in the last 24h whose evaluation errored
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+
+# evaluations scoring <= 0.5 on helpfulness, for one agent
+agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
+  | jq '.evaluations[] | {session_id, scores}'
+```
+
+Score filtering lives on **`evals`**, not `sessions`. `--score KEY:MIN..MAX` is repeatable and AND-combined; either bound is optional (`..0.5` means ≤ 0.5, `0.9..` means ≥ 0.9). You can pass up to 20 score filters per request; more returns HTTP 400. `sessions` shares the `--env`, `--status`, `--agent-id`, `--session-id`, and time-range filters with `evals`, but has no `--score`.
+
+## Read one session end-to-end
+
+There is no single `session show` command. Combine the event trail with the session's evaluation:
+
+```bash
+# the session's latest evaluation (status + scores)
+agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'
+
+# every event in the run (raise --limit for a full sweep)
+agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
+
+# just the tool calls in a session (--full is required to get the raw payload)
+agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \
+  | jq '.events[].payload'
+```
+
+> **Note:** By default, `events` reads a fast, payload-free feed. Each event carries a server-computed one-line `summary` plus flags like `is_error` and token counts, but `payload` comes back as `{}`. To pull the raw payload, add `--full` (or `--fields payload`). The full feed is slower at scale, so keep it bounded: pair `--full` with a single `--session-id`.
+
+## Fetch everything (pagination)
+
+Results are newest-first and cursor-paginated.
+
+```bash
+# one shot: fetch up to 500 rows in 200-row pages
+agenteye --json events --session-id run-001 --limit 500 --all > events.json
+
+# manual paging: feed next_cursor back in
+page=$(agenteye --json events --limit 100)
+cursor=$(echo "$page" | jq -r '.next_cursor // empty')
+[ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor"
+```
+
+## Slim the output with --fields
+
+Restrict the keys (in both the table and `--json`) to reduce what an agent must read.
+
+```bash
+agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]'
+agenteye --json events --session-id run-001 --fields ts,event_type --all
+```
+
+Unknown field names are rejected (exit `2`) with the valid list, a cheap way to discover field names.
+
+## Discover valid filter values
+
+```bash
+agenteye --json list envs | jq -r '.values[]'           # values for --env
+agenteye --json list tools | jq -r '.values[]'          # tool names; also agents, models, event_types, …
+agenteye --json list score_filters | jq -r '.values[]'  # valid KEY for --score KEY:MIN..MAX
+```
+
+## Pick your org (multi-tenant)
+
+If you belong to more than one org, choose the active tenant at login (it's saved):
+
+```bash
+agenteye login --org acme --email you@corp.com   # set the tenant in the same step as login
+agenteye --json orgs list | jq -r '.orgs[].org_slug'
+agenteye --org globex --json sessions --since 24h   # override for one command
+```
+
+A multi-org login without `--org` exits non-zero and prints the orgs to choose from.
+
+## Provision an API key for the SDK/collector
+
+```bash
+# the secret is printed ONCE, with --json it's the .key field
+key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
+agenteye keys regenerate ci-bot --yes    # rotate; agenteye keys disable ci-bot --yes to revoke
+```
+
+## Run a saved or ad-hoc query
+
+```bash
+agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
+agenteye --json query run errs --arg prod | jq '.rows'   # a saved query + a positional $1
+```
+
+## Triage an incident non-interactively
+
+```bash
+id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id')
+agenteye incidents ack "$id"
+agenteye incidents assign "$id" --assignee you@corp.com
+agenteye incidents resolve "$id" --yes
+```
+
+> **Note:** Mutations auto-skip their confirmation prompt under `--json` or when stdin isn't a TTY, so agents never hang; pass `--yes`/`-y` to skip it explicitly elsewhere.
+
+## Exit-code handling in a script
+
+```bash
+out=$(agenteye --json sessions --since 1h) || code=$?
+case "${code:-0}" in
+  0) echo "$out" | jq '.sessions | length' ;;
+  4) echo "Session expired - run 'agenteye login'." >&2 ;;
+  5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;;
+  3) echo "Dashboard unreachable - check the URL." >&2 ;;
+  *) echo "Unexpected error (exit ${code})." >&2 ;;
+esac
+```
+
+## JSON output shapes
+
+| Command | stdout JSON (with `--json`) |
+|---|---|
+| `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` or `{"logged_in": false}` |
+| `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` |
+| `events` | `{"events": [...], "next_cursor": <cursor or null>}` |
+| `evals` | `{"evaluations": [...], "next_cursor": <cursor or null>}` |
+| `sessions` | `{"sessions": [...], "next_cursor": <cursor or null>}` |
+| `errors` | `{"errors": [...], "next_cursor": <cursor or null>}` |
+| `list <kind>` | `{"kind", "values": [...]}` |
+| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` shown once) |
+| `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` |
+| `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` |
+| `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` |
+| create/update/delete (any) | the resource object, or `{"deleted": true, "id"}` for deletes |
+| failure (any, with `--json`) | `{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` on stdout |
+
+- Each **event** item (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. Note that `payload` is `{}` unless you request the full feed with `--full` (or `--fields payload`).
+- Each **evaluation** item (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`.
+- Each **session** item (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`.
+
+Each command's `--fields` accepts exactly its own item's field names. The set differs between `sessions` and `evals`, so a name valid for one may be rejected by the other.
+
+## Next steps
+
+- [CLI](/ru/agenteye/cli): installation, authentication, and the full option reference for every command.
+- [CLI agent skill](/ru/agenteye/cli-skill): package these recipes as a skill your coding agent can load.
+- [API keys](/ru/agenteye/api-keys): create and scope the keys the CLI, SDK, and collector authenticate with.
+- [Python SDK](/ru/agenteye/python-sdk): send events into Failproof AI Observability so there is data for these recipes to query.

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

@@ -0,0 +1,159 @@
+---
+title: "Failproof AI Observability CLI Agent Skill"
+description: "Спросите у вашего coding agent \"сегодня что-нибудь сломалось?\" и позвольте ему ответить на основе ваших live данных Failproof AI Observability, без необходимости запоминать команды."
+---
+
+
+Спросите у вашего coding agent *«сегодня что-нибудь сломалось?»* и позвольте ему ответить на основе ваших live данных Failproof AI Observability, без необходимости запоминать команды. **Failproof AI Observability CLI skill** (`agenteye-cli`) — это *Agent Skill*: небольшая папка с инструкциями, которую coding agent, такой как Claude Code или Codex, загружает по требованию. Она учит agent управлять вашей Observability deploymentом через [`agenteye` CLI](/ru/agenteye/cli) на основе запросов на обычном английском языке, таких как *«выдай CI ключ, который может только отправлять события»* или *«подтверди активный инцидент и назначь его на меня»*.
+
+Это **не** сервис и не отдельный бинарный файл; нет ничего, что нужно разворачивать. Он работает поверх уже установленного вами CLI: agent выполняет `agenteye --json …`, парсит чистый JSON и отвечает вам прозой. Всё, что он может сделать, вы можете сделать сами, набрав те же команды.
+
+---
+
+## Как это соотносится с другими интерфейсами Failproof AI Observability
+
+Failproof AI Observability предоставляет четыре способа доступа к одним и тем же данным и элементам управления. Они дополняют друг друга:
+
+| Интерфейс | Что это такое | Где выполняется | Используйте, когда |
+|---|---|---|---|
+| **[CLI](/ru/agenteye/cli)** | Справочник команд и флагов для `agenteye` | Ваш терминал | Вы хотите запустить или создать сценарий для конкретной команды |
+| **[CLI recipes](/ru/agenteye/cli-recipes)** | Шаблоны `jq`/pipelines для копирования и вставки | Ваш терминал / скрипты | Вы интегрируете CLI в автоматизацию |
+| **CLI skill** (этот документ) | Дверь с естественным языком для CLI | Ваш coding agent на рабочей станции | Вы просто хотите спросить и позволить agent выбрать команду |
+| **[Evaluator skill](/ru/agenteye/evaluator-skill)** | Родственный skill, который проектирует и создаёт ваш сервис оценивания | Ваш coding agent на рабочей станции | Вы хотите *производить* баллы оценивания, а не только их читать |
+| **[Python SDK skill](/ru/agenteye/python-sdk-skill)** | Родственный skill, который инструментирует agent, чтобы он вообще испускал телеметрию | Ваш coding agent на рабочей станции | Вы хотите, чтобы agent *производил* события, которые этот skill читает |
+| **[In-dashboard AI assistant](/ru/agenteye/assistant)** | Чат, встроенный в приборную панель | Серверная сторона (в приборной панели) | Вы хотите Q&A в приборной панели над вашими данными |
+
+Сам skill не имеет собственных привилегий; он просто преобразует ваши слова в вызовы CLI, которые выполняются от вас:
+
+```mermaid
+flowchart TD
+    YOU["вы: 'подтверди активный инцидент'"] --> AGENT["coding agent (Claude Code / Codex)<br/>загружает agenteye-cli skill"]
+    AGENT --> CLI["agenteye --json incidents ack ..."]
+    CLI -->|ваша аутентифицированная CLI сессия| API["Observability dashboard API"]
+```
+
+### в сравнении с in-dashboard AI assistant: важное различие
+
+Это два совершенно разных инструмента с очень разными областями влияния:
+
+- **In-dashboard AI assistant** ([AI assistant](/ru/agenteye/assistant)) — это чат, встроенный в приборную панель, поддерживаемый сервисом agent. Он **только для чтения плюс создание с одобрением**: он может создавать черновики сохранённых запросов и панелей управления, но каждая запись требует вашего явного подтверждения, и он никогда не удаляет. Он защищён разрешением `agent:use` и видит только данные организации, которую вы просматриваете.
+- **CLI skill** работает на *вашей* рабочей станции внутри *вашего* coding agent и управляет `agenteye` CLI от вас. Он может выполнять **полный набор CLI, включая изменения** (создание/ротация/отключение API ключей, изменение параметров org, разрешение инцидентов, удаление сохранённых запросов), ограниченные только разрешениями вашей CLI-сессии. Относитесь к этому ровно так же осторожно, как вы относились бы к выполнению этих команд вручную.
+
+---
+
+## Предварительные требования
+
+1. **`agenteye` CLI установлен** и находится в `PATH` (см. [CLI](/ru/agenteye/cli) справочник: `pipx install agenteye`).
+2. Ваш **URL приборной панели установлен** (`AGENTEYE_DASHBOARD_URL`, или agent передаёт `--base-url`).
+3. **Сессия с аутентификацией**: сначала запустите `agenteye login` сами. Skill **не может** завершить отправку одноразового кода по электронной почте за вас; он подскажет вам запустить `agenteye login`, если сессия отсутствует или истекла (CLI код выхода `4`).
+
+---
+
+## Где это взять
+
+Skill опубликован в публичной коллекции skills Failproof AI:
+
+**[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli)
+
+Ничто в нём не защищено — репозиторий открыт, и skill не требует собственных учётных данных, потому что он только управляет **публичным** `agenteye` CLI против *вашей* приборной панели, используя сессию, под которую *вы* вошли. Вам не нужно ничего у кого-то просить.
+
+Обратите внимание, что он поставляется как отдельная папка и **не находится** в пакете `pipx install agenteye`, поэтому не ищите его там.
+
+## Установка skill
+
+Самый быстрый способ — это [`skills`](https://skills.sh) CLI, который загружает папку и размещает её там, где ваш agent её ищет:
+
+```bash
+# Claude Code, только этот проект
+npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code
+
+# каждый проект (устанавливает в ~/.claude/skills/)
+npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy
+
+# Codex вместо этого
+npx skills add FailproofAI/skills --skill agenteye-cli -a codex
+```
+
+Затем управляйте им как любым другим skill:
+
+```bash
+npx skills list -a claude-code      # что установлено
+npx skills update agenteye-cli      # загрузить последнюю версию
+npx skills remove agenteye-cli      # удалить его
+```
+
+Предпочитаете установку вручную? Agent Skill — это просто папка, содержащая `SKILL.md` (плюс дополнительные справки), поэтому копирование тоже работает:
+
+- **Claude Code**: положите папку `agenteye-cli/` в `~/.claude/skills/` (каждый проект) или `<ваш-репо>/.claude/skills/` (только этот репо). Claude Code автоматически её обнаруживает — проверьте со списком `/skills` или просто задайте вопрос, который совпадает с её описанием.
+- **Codex (OpenAI)**: Codex читает тот же `SKILL.md`. Включённый `agents/openai.yaml` устанавливает `allow_implicit_invocation: true`, поэтому Codex автоматически выбирает skill, когда задача совпадает; в противном случае вызовите его явно как `$agenteye-cli`.
+
+---
+
+## Безопасность: изменения НЕ требуют подтверждения, когда agent запускает CLI
+
+> **Warning:** Прочитайте это перед тем, как позволить agent вносить изменения.
+
+`agenteye` CLI обычно запрашивает *«ты уверен?»* перед деструктивным действием. Он **автоматически пропускает это подтверждение, когда он не подключён к терминалу (что является в точности тем, как coding agent его запускает), и `--json` тоже пропускает это.** Поэтому подсказка о безопасности **не будет** активирована для agent.
+
+Skill написан, чтобы это компенсировать: ему дано указание указать точную команду, которую он будет запускать, и получить ваше явное **ОК перед любым изменением состояния**. Соблюдайте эту дисциплину. Когда вы управляете Failproof AI Observability через agent, *вы* — это шаг подтверждения. Команды, изменяющие состояние, на которые нужно обратить внимание:
+
+- `keys create` / `update` / `disable` / `regenerate`
+- `users create` / `update` / `disable` / `enable`
+- `settings set`
+- `alerts create` / `update` / `delete` / `test`
+- команды записи `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe`
+- `query create` / `update` / `delete`
+- `agent rename` / `delete`
+- `orgs switch`
+
+Всё под **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) — только для чтения и ничего не меняет.
+
+Поскольку agent действует от вас, он может делать только то, что разрешено вашей сессией; разрешения разрешаются **на организацию** (см. [API keys](/ru/agenteye/api-keys)). Команда, на которую у вас нет разрешения, возвращает код выхода `5` с точно названным разрешением, поэтому agent может точно сказать вам, что просить у администратора, вместо того чтобы неясно отказать.
+
+---
+
+## Что вы можете его попросить
+
+Вот что выглядит реальный обмен, сначала чтение, затем изменение, которое ждёт вашего ОК:
+
+```text
+вы   ▸ Что-нибудь сломалось за последний день?
+
+agent ▸ Запуск: agenteye --json errors --since 24h --aggregate
+        3 типа ошибок за последние 24 часа. Самый большой — TimeoutError
+        (18 попаданий, все на checkout-agent), затем RateLimited (5).
+        Хотите получить сбойные сессии для TimeoutError?
+
+вы   ▸ Выдай CI ключ, который может только отправлять события.
+
+agent ▸ Это создаёт API ключ. Я запущу:
+          agenteye keys create ci --add events:add
+        Продолжить?
+
+вы   ▸ да
+
+agent ▸ Готово. Ключ "ci" создан с только events:add.
+        Секрет показан только один раз, поэтому сохраните его сейчас. Я не могу его переиспечатать.
+```
+
+Skill отображает каждое намерение на простом языке на правильную `agenteye` команду, сначала открывая допустимые значения (`list <kind>`, `whoami`), чтобы не угадывать, и указывая точную команду перед любым изменением. Больше примеров:
+
+- *«Что-нибудь сломалось / сбойное за последние 24 часа?»* → `errors --since 24h --aggregate`, затем разбивка.
+- *«Почему сессия `run-001` сбойная?»* → `events --session-id run-001 --all` + `evals --session-id run-001`.
+- *«Как качество тренднулось на этой неделе?»* → `evals --aggregate --since 7d`, затем углубиться в низко оценённые прогоны.
+- *«Выдай CI ключ, который может только отправлять события»* → `keys create ci --add events:add` (он указывает команду, затем создаёт её и захватывает одноразовый секрет).
+- *«Кто имеет доступ? Сделай Dana только для чтения»* → `users list` → `users update dana@… --permission-set read-only` (после подтверждения с вами).
+- *«Подтверди активный инцидент и назначь его на меня»* → `incidents list --state firing` → `incidents ack <id>` / `incidents assign <id> you@…`.
+
+Для точных команд, флагов и JSON форм за этим смотрите справочник [CLI](/ru/agenteye/cli) и [CLI recipes для agents](/ru/agenteye/cli-recipes).
+
+---
+
+## Следующие шаги
+
+- **[CLI](/ru/agenteye/cli)**: полный справочник команд и флагов для `agenteye`.
+- **[CLI recipes для agents](/ru/agenteye/cli-recipes)**: шаблоны `jq` и обработка кодов выхода для копирования и вставки.
+- **[Evaluator agent skill](/ru/agenteye/evaluator-skill)**: родственный skill для создания evaluator, чьи баллы читает `agenteye evals`.
+- **[Python SDK agent skill](/ru/agenteye/python-sdk-skill)**: родственный skill для инструментирования agent, чтобы он испускал телеметрию, которую читает `agenteye`.
+- **[AI assistant](/ru/agenteye/assistant)**: in-dashboard ассистент (не путать с этим terminal skill).
+- **[API keys](/ru/agenteye/api-keys)**: модель разрешений на организацию, которая ограничивает то, что может делать skill.