> ## 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.

# AgentEyeを始める

> AgentEye の入門ドキュメントです。

このガイドでは、AgentEye のセットアップを一通り説明します。サーバーとダッシュボードのデプロイ、エージェントマシンへのコレクターのインストール、そして Python エージェントコードへの計装を順を追って解説します。

***

## AgentEye とは？

AgentEye は **AI エージェント向けのセルフホスト型観測・評価プラットフォーム**です。エージェントの動作（実行の各ステップ）を記録し、完了した実行の品質を自動でスコアリングします。これにより、本番環境でのエージェントの挙動を把握し、ユーザーが問題に気づく前にリグレッションを検出できます。

データは一方向に流れます。エージェントコードが **Python SDK** を通じて **イベント** を送出 → 軽量な **コレクター** デーモンがイベントをバッチ処理して **サーバー** に送信 → イベントと分析データが **ClickHouse** に保存（組織、ユーザー、API キー、ダッシュボード、保存クエリなどの運用状態は **Postgres** に格納）→ すべてを **ダッシュボード** で閲覧。

主な機能：

* **イベント** — 各エージェント実行のステップごとの生データ（ツール呼び出し、モデル呼び出し、フック、エラー）。
* **セッション** — それらのイベントを実行ごとの1行にまとめたもの。各実行は**自動評価**されてスコアが付与されます。
* **評価** — 独自の評価サービスが生成する品質スコア。手動レビューなしに品質低下を検出できます。
* **クエリ＆ダッシュボード** — データに対して保存した ClickHouse SQL を、共有・組織スコープのダッシュボードにグラフ表示。
* **アラート＆インシデント** — 閾値ルールによる通知（メール、Slack、Webhook、ダッシュボード内）と、トリアージのためのインシデントワークフロー。
* **CLI＆AI アシスタント** — ターミナルクライアント（`agenteye`）と、自然言語で質問できるダッシュボード内アシスタント。

これらすべてを自社インフラで運用できます。単一の Docker Compose スタック（本ガイド）、本番向け Kubernetes インストール、または単一の同居ポッドとして構成できます。このガイドでは Compose スタックをエンドツーエンドでセットアップします。

***

## ステップ 1: 認証

AgentEye のすべての成果物は `agenteye-enterprise` GitHub 組織から配布されています。エンタープライズ開発者は自分の GitHub PAT を生成できます。正確な手順と必要な権限については [enterprise-docs/github-token.md](/ja/agenteye/github-token) を参照してください。

```bash theme={null}
export AGENTEYE_TOKEN=<your-github-pat>

# Authenticate Docker against GHCR
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
```

***

## ステップ 2: サーバーとダッシュボードをデプロイする

サーバーはコレクターからイベントを受信してクエリ可能な状態にし、ダッシュボードはそれを閲覧する場所です。取り込まれたイベントと分析データは ClickHouse（必須の分析ストア）に保存され、Postgres には組織、ユーザー、API キー、ダッシュボード、保存クエリなどの運用状態が格納されます。

**公開されている Compose ファイルをダウンロード：**

```bash theme={null}
mkdir -p ./agenteye
curl -fsSL \
  -H "Authorization: token $AGENTEYE_TOKEN" \
  https://raw.githubusercontent.com/agenteye-enterprise/releases/main/docker-compose.yml \
  -o ./agenteye/docker-compose.yml
cd agenteye
```

**シークレットを設定：**

デプロイがデフォルトの `admin` 認証情報で動かないよう、`.env` ファイルを作成します。最低限 `ADMIN_KEY` と `POSTGRES_PASSWORD` を設定してください：

```bash theme={null}
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret
```

**スタックを起動：**

```bash theme={null}
docker compose up -d
```

これにより、必須の ClickHouse 分析ストアとオプションの Redis キャッシュを含む、サーバーとダッシュボードを含むフルスタックが起動します。サーバーが起動するには ClickHouse が正常稼働している必要があります。

サーバーは `http://localhost:8080`、ダッシュボードは `http://localhost:3000` でリッスンしています。

本番デプロイ（カスタム Postgres、TLS、リバースプロキシ）については [enterprise-docs/deployment.md](/ja/agenteye/deployment) を参照してください。

***

## ステップ 3: コレクター用 API キーを作成する

各コレクターはスコープ付き API キーで認証します。ステップ 2 で設定した `ADMIN_KEY` を使って API キーを作成します：

```bash theme={null}
curl -s -X POST http://localhost:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}'
```

`key` の値は自分で指定します。ステップ 4 のコレクター設定でこの値を使用してください。キー管理の詳細は [enterprise-docs/api-keys.md](/ja/agenteye/api-keys) を参照してください。

***

## ステップ 4: コレクターをインストールする

AI エージェントを実行するすべてのマシンにコレクターデーモンをインストールします。

**バイナリをダウンロード（Linux x86\_64）：**

```bash theme={null}
VERSION=0.0.1-beta.13
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "collector/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-collector-linux-x86_64'
chmod +x agenteye-collector-linux-x86_64
sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector
```

> これは **Linux x86\_64** ビルドをダウンロードします。macOS（Apple Silicon または Intel）、Linux arm64、または Docker / systemd / launchd のセットアップについては [collector-installation.md](/ja/agenteye/collector-installation) を参照してください。各プラットフォームのダウンロード先が記載されています。上記コマンドは Linux バイナリをインストールするため、他の環境では動作しません。

**設定：**

```bash theme={null}
mkdir -p ~/.agenteye
cat > ~/.agenteye/config.json <<EOF
{
  "url": "http://your-server-host:8080/events",
  "key": "the-key-from-step-3"
}
EOF
```

**デーモンを起動：**

```bash theme={null}
agenteye-collector start
```

ワンショットフラッシュで接続を確認します（保留中のイベントを全て送信後に終了）：

```bash theme={null}
agenteye-collector flush
```

Docker、systemd、launchd のセットアップについては [enterprise-docs/collector-installation.md](/ja/agenteye/collector-installation) を参照してください。

***

## ステップ 5: Python SDK をインストールする

エージェントコードを計装したい各マシンに、GitHub Releases から wheel をインストールします。

```bash theme={null}
VERSION=0.0.1b9
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "python-sdk/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-*.whl'
pip install agenteye-${VERSION}-py3-none-any.whl
```

***

## ステップ 6: エージェントを計装する

エージェントコードにイベントを追加します。最低限、`agent_start` と `agent_end` を送出してください：

```python theme={null}
import agenteye

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="my-agent",
    goal="answer the user query",
)

# your agent logic here

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="my-agent",
    outcome="success",
)
```

イベントはバッファリングされ、500 ミリ秒ごとに `$AGENTEYE_HOME/events/`（`AGENTEYE_HOME` が未設定の場合は `~/.agenteye/events/`）にフラッシュされます。コレクターが自動的に処理します。

イベント API の詳細は [enterprise-docs/python-sdk.md](/ja/agenteye/python-sdk) を参照してください。

***

## ステップ 7: ダッシュボードでイベントを確認する

`http://your-dashboard-host:3000` を開いてサインインします。AgentEye はワンタイムコード（またはワンクリックのマジックリンク）をメールで送信するため、パスワード管理は不要です。

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/login.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=8f83cb747193d872f7883cb709587635" alt="ワンタイムコードをメールに送信する AgentEye のサインイン画面" width="2880" height="1800" data-path="agenteye/images/login.png" />

ログイン後、**Events** ページにすべての取り込まれたイベントのライブストリームが表示されます。`session_id` や `agent_id` でフィルタリングして特定の実行にドリルダウンできます。

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/events-stream.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=79714903a85d10773f4f9b36cb44b1cf" alt="イベントタイプ別に色分けされ、環境・エージェント・セッションでフィルタリング可能なライブイベントストリーム" width="2880" height="1800" data-path="agenteye/images/events-stream.png" />

**Sessions** ページでは、これらのイベントが実行ごとの1行にまとめられます。AgentEye は完了したセッションを自動評価するため、すべての実行にスコアが付与され、手動レビューなしに品質リグレッションを検出できます。最新の評価スコアが各行に一目でわかるよう表示されます：

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/sessions-list.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=10de161665eef64465d3d100e80b643f" alt="実行ごとの1行表示、ステータスバッジと評価スコアバッジ付きのセッション一覧" width="2880" height="1800" data-path="agenteye/images/sessions-list.png" />

セッションのスコアリング方法の設定については [enterprise-docs/evaluation-suite.md](/ja/agenteye/evaluation-suite) を参照してください。

セッションをクリックすると **実行グラフ** が開きます。エージェント、ツール、フック、モデル呼び出しが時系列でどのように展開したかを git スタイルで表示し、並列サブエージェントは独自のレーンに表示、右パネルには実行ごとの内訳が表示されます：

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/session-detail.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=63cc2480e8124a05ea6a0a92d5f20690" alt="セッションの git スタイル実行グラフとイベントタイムライン、ツール/モデル/フックの内訳パネル" width="2880" height="1800" data-path="agenteye/images/session-detail.png" />

***

## ステップ 8: 探索、チャート表示、アラート設定

イベントが流れ始めると、**analyze** ページで未加工のアクティビティを実用的な知見に変換できます。エージェントの挙動を計測し、チームで知見を共有し、問題が発生した瞬間に通知を受け取ることができます。ダッシュボードページは組織スコープで、アドレスバーに表示される URL は組織スラグ（`/<org>/…`）でプレフィックスされます。

* **Queries**（`/<org>/queries`）：イベントと評価データに対する保存済み再利用可能なクエリのライブラリ（組み込みプリセットと独自クエリ）から始めます……

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/queries.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=1b42be492d5b650b4bd6b8a2241f6633" alt="保存クエリライブラリ：組み込みプリセットとカスタムクエリが並んだグリッド" width="2880" height="1800" data-path="agenteye/images/queries.png" />

……次に SQL コンポーザーで開いて調整し、ライブ結果とともに実行できます：

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/query-lab.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=aec1a1d95bb0bf1280d62a2e2430f20e" alt="保存クエリを実行している SQL クエリコンポーザー、スキーマサイドバーとライブ結果グリッド付き" width="2880" height="1800" data-path="agenteye/images/query-lab.png" />

* **Dashboards**（`/<org>/dashboards`）：クエリを折れ線、棒、エリア、円グラフのタイルとして固定し、共有・組織全体のダッシュボードを作成。

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/dashboard-fleet.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=d1fed0deace0ebb0bc02421f3b994107" alt="保存クエリから構築されたダッシュボード：時間別イベント数の折れ線、エラータイプ別の棒グラフ、レイテンシのエリアチャート、モデル別トークン数" width="2880" height="1800" data-path="agenteye/images/dashboard-fleet.png" />

* **Alerts**（`/<org>/alerts`）：任意の閾値をページングルールに昇格させ、メール、Slack、Webhook、またはダッシュボード内で通知を受け取ります。[enterprise-docs/alerts.md](/ja/agenteye/alerts) を参照してください。

***

## 次のステップ

* [デプロイメント](/ja/agenteye/deployment)：本番環境向けの強化
* [API キー](/ja/agenteye/api-keys)：アクセス管理
* [トラブルシューティング](/ja/agenteye/troubleshooting)：問題の診断