failproofai 1.0.1-beta.1 → 1.0.1

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

@@ -0,0 +1,179 @@
+---
+title: "エージェント向けCLIレシピ"
+description: "セッション・イベント・評価データをスクリプトやコーディングエージェントが自動化できる形に変換する、コピペ可能なクエリパターンとjqレシピ集。"
+---
+
+
+セッション・イベント・評価データをスクリプトやコーディングエージェントから直接取得（および再評価のトリガー）できます。stdout にクリーンな JSON を出力するため、そのまま `jq` にパイプ可能です。これらのレシピは、Failproof AI Observability のデータを、ダッシュボードをクリックせずにターミナルユーザーや AI コーディングエージェント（Claude Code、Cursor）がクエリ・自動化できる形に変換します。
+
+以下のパターンは、Failproof AI Observability CLI（`agenteye`）ですぐにコピペして使えます。インストール・認証・全オプションの一覧は [CLI](/ja/agenteye/cli) を参照してください。組み込みヘルプは `agenteye -h` または `agenteye <command> -h` で確認できます。
+
+## 基本ルール
+
+1. **グローバルオプションはコマンドの*前*に置く。** `agenteye --json sessions` が正しい。`agenteye sessions --json` は誤り。グローバルオプションは `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color` です。
+2. **出力をパースする際は必ず `--json` を渡す。** データは JSON として **stdout** に出力され、人間向けのステータスメッセージやエラーは **stderr** に出力されるため、stdout をクリーンな状態で `jq` にパイプできます。
+3. **終了コードで分岐する**（stderr のテキストではなく）: `0` 正常 · `1` 予期しないエラー · `2` 引数不正 · `3` ダッシュボードに接続できない · `4` 未ログインまたはセッション期限切れ · `5` 権限不足 · `6` リソースが見つからない。
+4. **`-h` で探索する。** 各コマンドにはフィルター・値のフォーマット・JSON の形状がドキュメント化されています。
+
+## 初回セットアップ
+
+```bash
+export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # --base-url を毎回指定しなくて済むように
+agenteye login --email you@example.com                       # メールで届いたコードを貼り付ける（有効期限 約24時間）
+```
+
+## 作業前に認証を確認する
+
+`whoami` はセッションが存在しないか期限切れの場合でもエラーにならず、代わりに `logged_in:false` を返します。そのためエージェントが認証状態を安全に確認できます（ベース URL が未設定またはダッシュボードに接続できない場合は非ゼロで終了することがあります）。
+
+```bash
+if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then
+  echo "Not authenticated. Run: agenteye login" >&2; exit 1
+fi
+```
+
+## 失敗または低スコアのセッションを探す
+
+```bash
+# 直近24時間で評価がエラーになったセッション
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+
+# 特定エージェントの helpfulness スコアが 0.5 以下の評価
+agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
+  | jq '.evaluations[] | {session_id, scores}'
+```
+
+スコアのフィルタリングは `sessions` ではなく **`evals`** に対して行います。`--score KEY:MIN..MAX` は繰り返し指定可能で AND 結合されます。どちらの境界も省略可能です（`..0.5` は ≤ 0.5、`0.9..` は ≥ 0.9）。1 リクエストあたり最大 20 個のスコアフィルターを指定でき、それ以上は HTTP 400 を返します。`sessions` は `evals` と `--env`、`--status`、`--agent-id`、`--session-id`、時間範囲フィルターを共有しますが、`--score` は使えません。
+
+## セッションを最初から最後まで読む
+
+`session show` のような単一コマンドはありません。イベントの記録とセッションの評価を組み合わせて使います。
+
+```bash
+# セッションの最新評価（ステータス + スコア）
+agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'
+
+# 実行中の全イベント（完全な取得には --limit を増やす）
+agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
+
+# セッション内のツール呼び出しのみ（生のペイロードを取得するには --full が必要）
+agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \
+  | jq '.events[].payload'
+```
+
+> **注意:** デフォルトでは、`events` はペイロードなしの高速フィードを読み取ります。各イベントはサーバーが計算した 1 行の `summary` と `is_error` やトークン数などのフラグを持ちますが、`payload` は `{}` として返されます。生のペイロードを取得するには `--full`（または `--fields payload`）を追加してください。フルフィードは大規模になると遅くなるため、`--full` と単一の `--session-id` を組み合わせて範囲を限定してください。
+
+## すべてを取得する（ページネーション）
+
+結果は最新順でカーソルページネーションが使われます。
+
+```bash
+# 一括取得: 200 行ページで最大 500 行を取得
+agenteye --json events --session-id run-001 --limit 500 --all > events.json
+
+# 手動ページング: next_cursor を次のリクエストに渡す
+page=$(agenteye --json events --limit 100)
+cursor=$(echo "$page" | jq -r '.next_cursor // empty')
+[ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor"
+```
+
+## --fields で出力を絞り込む
+
+テーブルと `--json` の両方でキーを制限し、エージェントが読む量を減らします。
+
+```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
+```
+
+不明なフィールド名は有効なリストとともに（終了コード `2` で）拒否されるため、フィールド名の探索にも使えます。
+
+## 有効なフィルター値を確認する
+
+```bash
+agenteye --json list envs | jq -r '.values[]'           # --env に使える値
+agenteye --json list tools | jq -r '.values[]'          # ツール名（agents、models、event_types なども）
+agenteye --json list score_filters | jq -r '.values[]'  # --score KEY:MIN..MAX の有効な KEY
+```
+
+## 組織を選択する（マルチテナント）
+
+複数の組織に所属している場合は、ログイン時にアクティブなテナントを選択します（保存されます）。
+
+```bash
+agenteye login --org acme --email you@corp.com   # ログインと同時にテナントを設定
+agenteye --json orgs list | jq -r '.orgs[].org_slug'
+agenteye --org globex --json sessions --since 24h   # 1 コマンドだけオーバーライド
+```
+
+`--org` なしでマルチ組織ログインを行うと非ゼロで終了し、選択肢の組織リストが表示されます。
+
+## SDK/コレクター用の API キーを作成する
+
+```bash
+# シークレットは一度だけ表示される。--json の場合は .key フィールド
+key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
+agenteye keys regenerate ci-bot --yes    # ローテート。失効させるには agenteye keys disable ci-bot --yes
+```
+
+## 保存済みまたはアドホッククエリを実行する
+
+```bash
+agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
+agenteye --json query run errs --arg prod | jq '.rows'   # 保存済みクエリ + 位置引数 $1
+```
+
+## インシデントを非インタラクティブにトリアージする
+
+```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
+```
+
+> **注意:** ミューテーション操作は `--json` が指定されているか stdin が TTY でない場合、確認プロンプトを自動的にスキップするため、エージェントがハングすることはありません。それ以外の場所で明示的にスキップするには `--yes`/`-y` を渡してください。
+
+## スクリプトでの終了コード処理
+
+```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 出力の形状
+
+| コマンド | stdout JSON（`--json` 指定時） |
+|---|---|
+| `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` または `{"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` は一度だけ表示） |
+| `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` |
+| `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` |
+| `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` |
+| create/update/delete（任意） | リソースオブジェクト、または削除時は `{"deleted": true, "id"}` |
+| 失敗時（任意、`--json` 指定時） | stdout に `{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` |
+
+- **event** アイテム（`events`）の各フィールド: `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`。`payload` は `--full`（または `--fields payload`）を指定しない限り `{}` です。
+- **evaluation** アイテム（`evals`）の各フィールド: `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`。
+- **session** アイテム（`sessions`）の各フィールド: `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`。
+
+各コマンドの `--fields` は、そのアイテムのフィールド名のみを受け付けます。`sessions` と `evals` ではフィールドセットが異なるため、一方で有効な名前が他方では拒否されることがあります。
+
+## 次のステップ
+
+- [CLI](/ja/agenteye/cli): インストール・認証・全コマンドのオプションリファレンス。
+- [CLI エージェントスキル](/ja/agenteye/cli-skill): これらのレシピをコーディングエージェントが読み込めるスキルとしてパッケージ化する方法。
+- [API キー](/ja/agenteye/api-keys): CLI・SDK・コレクターが認証に使うキーの作成とスコープ設定。
+- [Python SDK](/ja/agenteye/python-sdk): Failproof AI Observability にイベントを送信して、これらのレシピがクエリできるデータを用意する方法。

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

@@ -0,0 +1,159 @@
+---
+title: "Failproof AI Observability CLI エージェントスキル"
+description: "コーディングエージェントに「今日何か壊れてる？」と聞くだけで、ライブの Failproof AI Observability データから回答を得られます。コマンドを暗記する必要はありません。"
+---
+
+
+コーディングエージェントに *「今日何か壊れてる？」* と聞くだけで、ライブの Failproof AI Observability データから回答を得られます。コマンドを暗記する必要はありません。**Failproof AI Observability CLI スキル**（`agenteye-cli`）は *エージェントスキル* です。これは、Claude Code や Codex などのコーディングエージェントがオンデマンドで読み込む小さな指示フォルダです。このスキルにより、エージェントは *「CI にイベントのプッシュだけできるキーを作って」* や *「発火中のインシデントを Ack して私にアサインして」* といった平易な英語のリクエストを通じて、[`agenteye` CLI](/ja/agenteye/cli) を使って Observability のデプロイを操作できるようになります。
+
+これは**サービスでも独立したバイナリでもありません**。デプロイするものは何もありません。すでにインストール済みの CLI の上で動作し、エージェントが `agenteye --json …` を呼び出してクリーンな JSON をパースし、散文で回答します。エージェントができることはすべて、同じコマンドを入力すれば自分でもできます。
+
+---
+
+## 他の Failproof AI Observability インターフェースとの関係
+
+Failproof AI Observability では、同じデータとコントロールに到達する方法が4つあります。それぞれ補完し合う関係です：
+
+| インターフェース | 内容 | 実行場所 | 使いどころ |
+|---|---|---|---|
+| **[CLI](/ja/agenteye/cli)** | `agenteye` のコマンド・フラグリファレンス | ターミナル | 特定のコマンドを実行またはスクリプト化したいとき |
+| **[CLI レシピ](/ja/agenteye/cli-recipes)** | コピペ可能な `jq`/パイプラインパターン | ターミナル / スクリプト | CLI を自動化に組み込みたいとき |
+| **CLI スキル**（このドキュメント） | CLI への自然言語フロントドア | ワークステーション上のコーディングエージェント | コマンドを選ばずに *ただ聞く* だけにしたいとき |
+| **[Evaluator スキル](/ja/agenteye/evaluator-skill)** | スコアリングサービスを設計・構築するための兄弟スキル | ワークステーション上のコーディングエージェント | eval スコアを *読む* のではなく *生成* したいとき |
+| **[Python SDK スキル](/ja/agenteye/python-sdk-skill)** | エージェントがテレメトリを送出できるようにする兄弟スキル | ワークステーション上のコーディングエージェント | このスキルが読み取るイベントをエージェントに *生成* させたいとき |
+| **[ダッシュボード内 AI アシスタント](/ja/agenteye/assistant)** | ダッシュボードに埋め込まれたチャット | サーバーサイド（ダッシュボード内） | データに対するダッシュボード内 Q&A を使いたいとき |
+
+スキル自体は独自の権限を持ちません。あなたの言葉を CLI コールに変換し、あなたとして実行するだけです：
+
+```mermaid
+flowchart TD
+    YOU["あなた: 「発火中のインシデントを Ack して」"] --> AGENT["コーディングエージェント (Claude Code / Codex)<br/>agenteye-cli スキルを読み込む"]
+    AGENT --> CLI["agenteye --json incidents ack ..."]
+    CLI -->|認証済み CLI セッション| API["Observability ダッシュボード API"]
+```
+
+### ダッシュボード内 AI アシスタントとの違い：重要な区別
+
+これらは影響範囲が大きく異なる2つの別ツールです：
+
+- **ダッシュボード内 AI アシスタント**（[AI アシスタント](/ja/agenteye/assistant)）はダッシュボードに埋め込まれたチャットで、エージェントサービスによってバックアップされています。**読み取り専用＋承認ゲート付き作成**：保存クエリやダッシュボードの下書きを作成できますが、書き込みはすべてあなたの明示的なクリック承認を求めて停止し、削除は行いません。`agent:use` 権限でゲートされており、閲覧中の組織のデータのみを参照します。
+- **CLI スキル**は *あなたの* ワークステーション上の *あなたの* コーディングエージェント内で動作し、**あなた**として `agenteye` CLI を操作します。API キーの作成・ローテーション・無効化、組織設定の変更、インシデントの解決、保存クエリの削除など、**ミューテーションを含む CLI の全機能**を実行できます。制限はあなたの CLI ログインの権限のみです。これらのコマンドを手動で実行するのと同じくらい慎重に扱ってください。
+
+---
+
+## 前提条件
+
+1. **`agenteye` CLI がインストール済み**で `PATH` に通っていること（[CLI](/ja/agenteye/cli) リファレンス参照：`pipx install agenteye`）。
+2. **ダッシュボード URL** が設定されていること（`AGENTEYE_DASHBOARD_URL`、またはエージェントが `--base-url` を渡す）。
+3. **ログイン済みセッション**：事前に `agenteye login` を実行しておくこと。スキルはメールで送られるワンタイムコードによるログインを**完了できません**。セッションが存在しないか期限切れの場合（CLI 終了コード `4`）、`agenteye login` を実行するよう案内します。
+
+---
+
+## 入手方法
+
+このスキルは Failproof AI の公開スキルコレクションで公開されています：
+
+**[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli)
+
+一切ゲートはありません。リポジトリは公開されており、スキルは独自の認証情報を必要としません。**公開**の `agenteye` CLI をあなたのダッシュボードに対して、あなたがログインしたセッションを使って動かすだけだからです。誰かに許可を求める必要はありません。
+
+スキルは独自のフォルダとして提供されており、`pipx install agenteye` パッケージには**含まれていません**。そこを探さないようにしてください。
+
+## スキルのインストール
+
+最も手軽な方法は [`skills`](https://skills.sh) CLI です。フォルダを取得し、エージェントが参照する場所に配置します：
+
+```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
+```
+
+インストール後は他のスキルと同様に管理できます：
+
+```bash
+npx skills list -a claude-code      # インストール済みスキルの確認
+npx skills update agenteye-cli      # 最新バージョンに更新
+npx skills remove agenteye-cli      # 削除
+```
+
+手動でインストールしたい場合も可能です。エージェントスキルは `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 が自動でスキルを選択します。明示的に呼び出す場合は `$agenteye-cli` を使用してください。
+
+---
+
+## 安全性：エージェントが CLI を実行するときミューテーションは確認を求めません
+
+> **警告：** エージェントに変更を加えさせる前に必ずお読みください。
+
+`agenteye` CLI は通常、破壊的な操作の前に *「本当によろしいですか？」* と尋ねます。しかし、**ターミナルに接続されていない場合（コーディングエージェントが実行する方法はまさにこれです）は確認を自動スキップし、`--json` もスキップします。** そのため、エージェントに対して安全確認プロンプトは**表示されません**。
+
+スキルはこれを補うように設計されています。実行するコマンドを明示し、**状態変更の前に明示的な OK を求める**よう指示されています。この規律を守ってください。エージェントを通じて Failproof AI Observability を操作するとき、*あなた自身*が確認ステップです。注意すべき状態変更コマンドは以下のとおりです：
+
+- `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`）はすべて読み取り専用で、何も変更しません。
+
+エージェントは**あなた**として動作するため、あなたのログインが許可していることしかできません。権限は**組織ごと**に解決されます（[API キー](/ja/agenteye/api-keys)を参照）。権限のないコマンドは終了コード `5` と該当する権限名を返すため、エージェントは不透明に失敗するのではなく、管理者に何を依頼すればよいかを正確に伝えられます。
+
+---
+
+## 何を聞けるか
+
+実際のやり取りの例です。まず読み取り、次に OK を待つ変更：
+
+```text
+you   ▸ Is anything broken in the last day?
+
+agent ▸ Running: agenteye --json errors --since 24h --aggregate
+        3 error types in the last 24h. The biggest is TimeoutError
+        (18 hits, all on the checkout-agent), then RateLimited (5).
+        Want the failing sessions for TimeoutError?
+
+you   ▸ Give CI a key that can only push events.
+
+agent ▸ This creates an API key. I'll run:
+          agenteye keys create ci --add events:add
+        OK to proceed?
+
+you   ▸ yes
+
+agent ▸ Done. Key "ci" created with events:add only.
+        The secret is shown only once, so store it now. I can't reprint it.
+```
+
+スキルは各平易な英語の意図を適切な `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`（あなたに確認後）。
+- *「発火中のインシデントを Ack して私にアサインして。」* → `incidents list --state firing` → `incidents ack <id>` / `incidents assign <id> you@…`。
+
+これらの背後にある正確なコマンド、フラグ、JSON の形式については、[CLI](/ja/agenteye/cli) リファレンスと[エージェント向け CLI レシピ](/ja/agenteye/cli-recipes)を参照してください。
+
+---
+
+## 次のステップ
+
+- **[CLI](/ja/agenteye/cli)**：`agenteye` のコマンドとフラグの完全リファレンス。
+- **[エージェント向け CLI レシピ](/ja/agenteye/cli-recipes)**：コピペ可能な `jq` パターンと終了コードの処理。
+- **[Evaluator エージェントスキル](/ja/agenteye/evaluator-skill)**：`agenteye evals` が読み取るスコアを生成する評価器を構築するための兄弟スキル。
+- **[Python SDK エージェントスキル](/ja/agenteye/python-sdk-skill)**：`agenteye` が読み取るテレメトリを送出するようにエージェントを計装する兄弟スキル。
+- **[AI アシスタント](/ja/agenteye/assistant)**：ダッシュボード内アシスタント（このターミナルスキルとは別物です）。
+- **[API キー](/ja/agenteye/api-keys)**：スキルが実行できる内容を制限する組織ごとの権限モデル。