> ## 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. # AIアシスタント > AgentEye AIアシスタントのドキュメント。 ダッシュボードにはオプションの**AIアシスタント**が含まれています。これはダッシュボードの右端にドッキングされたチャットパネルで、エージェントに関する自然言語の質問（「今週のプロダクション環境での品質トレンドはどうですか？」「今日エラーになったセッションはどれですか？」「このセッションを要約して」など）に回答し、ユーザーがアクションを許可した場合にはSQLクエリやダッシュボードを下書きして保存します。関連するセッション、クエリ、ダッシュボードへのクリッカブルリンクを引用として提示し、**ページ認識機能**を持っています。特定のセッションを表示中に「このセッションについて」と聞けば、何を指しているか正確に把握します。 ドックはデフォルトで幅**44pxの縦型レール**として表示されます：`›_` プロンプトグリフとカラーの健全性ドットが表示されます。レールをクリック（または `⌘J` / `Ctrl+J` を押す）するとフルチャットパネルに展開します。展開されたパネルは左端をドラッグすることで320〜640ピクセルの間で**リサイズ可能**で、お好みの幅はリロードをまたいで記憶されます。 これはダッシュボードからのみアクセス可能な小さな内部\*\*`agent`\*\*コンテナ（Claude Agents SDK上）として動作します。**デフォルトでは無効**になっており、LLMエンドポイントを設定するまで非表示のままです。 *** ## できること・できないこと * **質問しているユーザーが閲覧できる運用データを読み取ります。** イベント、評価、セッション、評価ジョブキュー、保存済みクエリ、保存済みダッシュボードをユーザーの読み取り権限に基づいてリクエストごとにスコープします。読み取りツールは即座に実行されます。 * **書き込みはアクション単位の承認によって制御されます。** 保存済みクエリの作成（`create_saved_query`、`update_saved_query`）、読み取り専用ロールに対する下書きSQLの検証実行（`run_query`）、それらのクエリからのダッシュボード組み立て（`create_dashboard`、`update_dashboard`、`add_query_to_dashboard`）が可能です。各書き込み操作ではチャット内に**承認 / 拒否 / 質問**のプロンプトが表示されて一時停止します。オペレーターが「承認」をクリックするまでSDKはツールを呼び出しません。**削除操作はアシスタントには一切提供されません**。破壊的な操作はオペレーターのみが実行できます。 * **下書きされたSQLは、ユーザーが記述したSQLと同じ `sql_guard` 検証および読み取り専用ロールを通過します**（SELECT/WITHのみ、複数ステートメント不可）。実行はクエリが参照するテーブルによってルーティングされます。分析テーブル（イベント、評価、セッション）を参照するクエリは組織の読み取り専用ClickHouseユーザーとして実行され（行ポリシーによってその組織にスコープされ、実行上限10秒、行数上限10万行）、リレーショナルテーブルのみを参照するクエリは読み取り専用Postgresロールで実行されます（10秒、1万行）。アシスタントはデータのアクセス範囲を拡大できません。オペレーターがすでに持っているクエリ範囲に対してのみ操作できます。 * **専用のアシスタントキー**（下記参照）を使用し、固定された権限セットで初期化されます。モデルが誤動作しても、そのスコープを超えることはできません。 * 各ダッシュボードユーザーがアシスタントを表示・使用するには **`agent:use`** 権限が必要です。ツールはリクエストごとにユーザー自身のデータ権限に合わせてフィルタリングされるため、`events:read` ユーザーはイベントツールを取得できますが、`dashboards:write` ツールは取得できません。 *** ## ページ認識AIドック：`/queries` ではコンポーザー、それ以外ではチャット 右側のアシスタントドックは**ページ認識**機能を持っています。モデルピッカー、会話履歴、モデル健全性ドット、チャット入力は変わりませんが、**空の状態のテンプレートチップ、プレースホルダーテキスト、ユーザーのメッセージが送信されるバックエンドエンドポイント**はすべて現在のルートに基づいて自動的に切り替わります。ドックは「現在いるページのAIヘルパー」になります。 **2つのバックエンド、ページごとに選択（チップ単位のオーバーライドあり）。** | ルート | ページデフォルトバックエンド | 理由 | | ------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- | | `/queries`、`/queries/new` | `POST /api/agent/compose-sql`（ツールループなし） | ユーザーがゼロから始める場合、1秒以内の初回トークンSQLがエディタに直接ストリーミングされる | | `/queries/`（既存） | `POST /api/agent/chat`（フルツールループアシスタント）、ページデフォルト | 自由入力メッセージでは何でも質問できる（「これを説明して」「これは何をしている？」など）。リファクタリングチップはチップ単位のkindによってcompose-sqlに切り替わる | | それ以外のすべてのページ | `POST /api/agent/chat`（フルツールループアシスタント） | 読み取りツール + 承認制の書き込みツール | `/queries/` のチップには明示的な `kind` が設定されており、1つのページで2つのフローをシームレスに混在させることができます。デフォルトのチップセットは2つの**chat**チップ（`explain the query on screen`、`what does this query do?`）と5つの**compose-sql**チップ（`parameterize by date range`、`add a status='error' filter`など）です。自由入力メッセージはページデフォルト（chat）にフォールスルーするため、「なぜこんなに遅いのか？」という質問は散文形式の回答を得られ、`parameterize by date range` チップをクリックするとcomposeエンドポイント経由でSQLが編集されます。 コンポーザーが**編集モード**で動作する場合（ユーザーが `/queries/` または既にSQLが読み込まれた `/queries/new` にいるため、空でない `currentSql` を参照している場合）、システムプロンプトは「新しいクエリを作成する」から「提供されたSQLを最小限に変更する：テーブル選択、カラム名、join構造、エイリアス、インデントを保持する」に切り替わります。モデルには変更前後の作業例（パラメータ化、フィルター追加、時間単位バケットへの変換）が別途提示されるため、チップクリックによるリファクタリングはゼロからの書き直しではなく、エディタのSQLに対する最小限の差分を生成します。 composeチップをクリック（または `/queries/new` で自由入力）すると → SQLがアシスタントメッセージにフェンスされた ` ```sql ` ブロックとしてストリーミングされます。**ストリームが完了した瞬間、Monacoが現在のルートにマウントされていれば、エディタは自動的に差分ビューで表示されます**（左側に元のSQL、右側に提案されたSQL、上部に `▾ AI proposed an edit` のキュー、下部に**承認 / 拒否**のピル）。ユーザーは差分を確認するために `エディタに挿入` ボタンを探してクリックする必要はありません。`エディタに挿入` ボタンはSQLブロックの下に手動再トリガーとして引き続き表示され（拒否後やユーザーが別のページに移動して戻った後に有用）、ユーザーが非エディタページ（例：保存済みクエリ一覧）にいる場合は唯一の手段となります。その場合、SQLを `sessionStorage` に保存して `/queries/new` にナビゲートし、新たにマウントされたエディタがマウント時にそのデータを読み取って同じ差分ビューを開きます。 提案されたSQLがすでにエディタにあるものとバイト単位で同一の場合（無操作の編集）、自動表示はスキップされます。空の差分は表示しません。その場合、`エディタに挿入` ボタンも無操作になります。 ユーザーが `/queries/new` で提案を承認した場合、ツールバーのプライマリアクションは `create` ではなく **`save`** と表示されます。SQLはアシスタントから渡されたものであり、メンタルモデルとしては「ゼロから書く」ではなく「これを確定させる」となります。ラベルはドックがSQLを挿入した時点で切り替わり、ページナビゲーションまで `save` のままです。`/queries/` ではボタンは常に `save` と表示されており、変更はありません。 `/queries` 以外では、ドックはこれまでどおりに動作します：ツール承認カード付きのフルチャット、ページコンテキスト認識、引用。 **権限 / ゲート。** composeエンドポイントはユーザーごとの `queries:run` 権限でゲートされます（読み取り相当。ユーザーは引き続き「承認」と「実行」をクリックする必要があり、「実行」はRustサーバー上の既存の `sql_guard` + `references_ch_tables` ルーティングを通過します）。chatエンドポイントは `agent:use` でゲートされます。どちらも `agent` コンテナに設定されたLLM接続が必要です。設定されていない場合、いずれのパスでもドックに「アシスタントはこのデプロイメントで設定されていません」というバナーが表示されます。 **拒否。** コンポーザーは読み取り専用分析クエリで満たせないリクエストを拒否し、SQLの代わりに `-- REFUSE: <1文の理由>` を出力します。データを書き込むリクエストや分析ビュー外のテーブル（`api_keys`、`users`、`dashboards`、`saved_queries`、`evaluation_jobs`）にアクセスするリクエストを拒否し、composeパスでの純粋な散文リクエスト（「これを説明して」「これは何をしている？」）も拒否します。それらはchatパスに属し、そこで散文形式の回答を提供します。ドックは拒否文字列をアシスタントメッセージ内のインライン赤色エラーチップとしてレンダリングします。何も挿入されません。 **モデル選択。** chatパスと共有されます。ドックヘッダーのモデルピッカーは両方のエンドポイントに適用されます（composeコールはエージェントサービスの `resolveModel()` に選択されたモデルを渡します）。`AGENTEYE_AGENT_MODELS` に複数のモデルがリストされている場合、オペレーターはコンポーザー用にHaikuクラスのオプション、チャット用にSonnetクラスのオプションを組み合わせることができ、ユーザーは会話ごとに選択できます。 **ページごとのテンプレート。** 各ページには独自のテンプレート（ヘッドライン、本文コピー、プレースホルダーテキスト、サジェスチョンチップ）があり、現在いるページに合わせてドックが適応します。特定のルートで提供されるチップはコンポーザーが調整されたインテントと同じものにマッピングされるため、サジェスチョンをクリックすると期待した編集が生成されます。 **無効化。** chatパスと同じです。ドックとコンポーザーはどちらも `agent` コンテナとそのLLM接続によってゲートされています。特定のユーザーにchatのみの動作をさせたい場合は `queries:run` 権限を削除します（これによりエディタの**実行**ボタンも無効になります）。コンポーザーのみの動作をさせたい場合は、そのユーザーのロールから `agent:use` を削除し、`queries:run` を別途再追加して作成済みSQLを実行できるようにします。 *** ## 有効化 `agent` サービスはDocker ComposeファイルおよびKubernetesマニフェストに含まれています。アシスタントを有効にするには、**(1)** LLMエンドポイントと **(2)** アシスタント専用のデータキーを提供します。 ### 1. LLM接続を選択する 以下のいずれかを選択し、`agent` サービスに対応する変数を設定します。 **a) Anthropic直接接続** ``` ANTHROPIC_API_KEY=sk-ant-... ``` **b) Portkey経由（推奨；モデルカタログスラッグ、キーのみ）** ``` PORTKEY_API_KEY= AGENTEYE_AGENT_MODEL=@/claude-sonnet-4-6 ``` これが最もシンプルな方法です。Portkeyで**Anthropicインテグレーション**（モデルカタログ）を設定すると**スラッグ**が付与されます。モデルを `@/` と指定すると、スラッグがプロバイダー + 認証情報のルーティングを担うため、**バーチャルキーは不要**で、Portkey APIキーのみで動作します。エージェントは `x-portkey-api-key` のみを送信してPortkeyゲートウェイを指定し、Portkeyが残りを解決します。（*プレーン*モデル名では「x-portkey-config or x-portkey-provider header is required」というエラーが発生します。`@slug/` プレフィックスがキーのみでの動作を可能にします。）セルフホストゲートウェイの場合は `PORTKEY_BASE_URL` を設定します。 スラッグではなくリクエストごとのルーティングを優先する場合は、プレーンな `AGENTEYE_AGENT_MODEL` と共に `PORTKEY_VIRTUAL_KEY=`（または `PORTKEY_CONFIG=`）を設定します。 **c) その他のAnthropicと互換性のあるゲートウェイ（LiteLLM、セルフホスト等）** ``` ANTHROPIC_BASE_URL=https://your-gateway # 改行区切りの「Name: Value」ヘッダー行（JSONではない）: ANTHROPIC_CUSTOM_HEADERS=x-my-header: value ``` **d) Amazon Bedrock / Google Vertex** ``` CLAUDE_CODE_USE_BEDROCK=1 # + 環境内の標準AWSクレデンシャル # または CLAUDE_CODE_USE_VERTEX=1 # + 環境内の標準GCPクレデンシャル ``` オプションで `AGENTEYE_AGENT_MODEL` でデフォルトモデルを固定できます（デフォルト: `claude-sonnet-4-6`）。ユーザーが複数のモデルから**選択**できるようにするには、`AGENTEYE_AGENT_MODELS` にカンマ区切りの許可リストを設定します（例: `@anthropic-prod/claude-opus-4-7,@anthropic-prod/claude-sonnet-4-6`）。モデルピッカーがチャットヘッダーに表示され、各ユーザーの選択が記憶されます。エージェントはこの許可リスト上のモデルのみを呼び出します。 ### 2. アシスタントキーを提供する 任意のランダムなシークレットを選択し、**agent** には `AGENTEYE_API_KEY` として、**server** には `AGENT_API_KEY` として同じ値を設定します。起動時にサーバーはこれを `dashboard-assistant` という名前の専用キーとして、以下の固定権限セットでシードします：`events:read`、`evaluations:read`、`dashboards:read`、`dashboards:write`、`queries:read`、`queries:write`、`queries:run`。書き込み権限は承認制のツールを通じてのみ行使されます（上記の「できること・できないこと」を参照）。**手動のキー発行ステップも管理キーの関与もありません**。権限セットはサーバーに固定されており、シードされたキーは**保護されています**：キーAPIを通じて無効化や再生成はできません。値を変更してサーバーを再起動することでローテーションできます。管理者/ダッシュボードキーを再利用しないでください。 ```bash theme={null} SECRET="$(openssl rand -base64 32)" # agentサービスで: AGENTEYE_API_KEY="$SECRET" # serverサービスで: AGENT_API_KEY="$SECRET" ``` Kubernetesでは自動的に設定されます：`AGENTEYE_API_KEY` を `agenteye-agent` シークレットに入れると、サーバーのDeploymentが同じ値を `AGENT_API_KEY` として読み取ります。 ### 3. ダッシュボード↔エージェント共有トークンを設定する **dashboard** と **agent** の両方のサービスに同じ `AGENTEYE_AGENT_TOKEN` を設定します。ダッシュボードは内部エージェントサービスを呼び出す際にこれを提示し、エージェントはこれのない呼び出しを拒否します。 ### 4. ユーザーにアクセスを付与する 関連するダッシュボードオペレーターに `agent:use` 権限を付与します（[enterprise-docs/api-keys.md](/ja/agenteye/api-keys) を参照）。この権限のないユーザーにはアシスタントが表示されません。 LLMエンドポイントと読み取り専用キーが設定されたら、**server**（読み取り専用キーをシードするため）と **agent** サービスを再起動します。アシスタントドックは `agent:use` ユーザーの右端に表示されます。デフォルトでは折りたたまれており、レールをクリックするか `⌘J` / `Ctrl+J` を押すと展開します。 *** ## 環境変数リファレンス **`agent`** サービスに設定： | 変数 | 用途 | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PORTKEY_API_KEY` | Portkeyを経由したルーティング（エージェントはこれからゲートウェイ接続を構築する） | | `PORTKEY_VIRTUAL_KEY` | Anthropicクレデンシャル用のPortkeyバーチャルキー（キーにデフォルト設定がある場合はオプション） | | `PORTKEY_CONFIG` / `PORTKEY_BASE_URL` | 名前付きPortkeyコンフィグ / セルフホストPortkeyゲートウェイURL（オプション） | | `PORTKEY_PROVIDER` | Portkeyプロバイダースラッグ — `PORTKEY_VIRTUAL_KEY` / `PORTKEY_CONFIG` のいずれも設定されていない場合のみ使用される、それらと並ぶ3番目のルーティングオプション | | `ANTHROPIC_API_KEY` | Anthropicへの直接アクセス（ゲートウェイ / Bedrock / Vertexの代替） | | `ANTHROPIC_AUTH_TOKEN` | `x-api-key` の代わりに `Authorization: Bearer` で認証するゲートウェイのBearerトークン（オプション） | | `ANTHROPIC_BASE_URL` | Portkey以外のゲートウェイのエンドポイント | | `ANTHROPIC_CUSTOM_HEADERS` | Portkey以外のゲートウェイ用の追加ヘッダー：改行区切りの `Name: Value` 行（JSONではない） | | `CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` | Bedrock / Vertex経由でルーティング | | `AGENTEYE_AGENT_MODEL` | デフォルトモデルID（デフォルト: `claude-sonnet-4-6`） | | `AGENTEYE_AGENT_MODELS` | ユーザーがチャットヘッダーで選択できるモデルのカンマ区切り許可リスト。単一の固定モデルにする場合は未設定のままにする。上記のデフォルトはこの中の1つである必要があります（そうでない場合は追加されます）。 | | `AGENTEYE_AGENT_MAX_CONCURRENCY` | ポッドあたりの最大同時チャット数（デフォルト4）。超過したリクエストには429が返される | | `AGENTEYE_API_KEY` | アシスタントのデータキー。サーバーの `AGENT_API_KEY` と**同じ**値を設定します。起動時に固定のスコープ付き権限セットでシードされます（ステップ2を参照）。 | | `AGENTEYE_AGENT_TOKEN` | ダッシュボードとの共有シークレット | | `AGENTEYE_SERVER_URL` | AgentEyeサーバーURL（デフォルト: `http://server:8080`） | | `AGENTEYE_AGENT_ALLOW_NO_ORG` | **マルチテナンシー。** デフォルトはオフ（フェイルクローズド）：アシスタントは組織コンテキストを持たない `/chat` リクエストを `400` で拒否します。これはアシスタントが実行するすべてのツールが1つの組織にスコープされているためです。ダッシュボードは組織認識後に常にそのコンテキストを送信するため、通常はこれを未設定のままにします。組織未認識のダッシュボードが組織認識エージェントと通信している移行期のロールアウト中にのみ `1` に設定し、拒否する代わりに `default` 組織にフォールバックするようにします。ダッシュボードのアップグレードが完了したらクリアします。 | | `AGENTEYE_AGENT_MAX_STEPS` | 回答あたりの最大ツール使用ステップ数（デフォルト8） | | `AGENTEYE_AGENT_TIMEOUT_MS` | `/chat` リクエスト全体のタイムアウト（全モデルターン + ツールステップ）、ミリ秒単位（デフォルト90000）。SQLツールには独自の10秒上限がある | | `AGENTEYE_AGENT_SELF_TELEMETRY` | アシスタント自身の実行をAgentEyeに記録するには `1` に設定 | | `AGENTEYE_TELEMETRY_API_KEY` | 自己計装用の `events:add` のみの別キー | | `AGENTEYE_AGENT_ENV` | アシスタント自身の自己テレメトリに適用される環境タグ（デフォルト: `prod`） | **`dashboard`** サービスに設定： | 変数 | 用途 | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `AGENTEYE_AGENT_URL` | ダッシュボードがエージェントサービスにアクセスする場所。バンドルされたKubernetesマニフェストとComposeファイルでは `http://agent:9100` に設定されています。未設定の場合、アシスタントは完全に非表示になります。 | | `AGENTEYE_AGENT_TOKEN` | エージェントのトークンと一致する必要があります | *** ## テレメトリとユーザーの質問内容の確認 プロンプトの**内容はデフォルトで自分のシステム内に留まります**。3つのレイヤー： 1. **会話ストア**：すべてのプロンプトと回答がAgentEyeデータベースに保存されます（ユーザーごと、プライベート）。アシスタントの履歴スイッチャーから再読み込み可能です。これがユーザーの質問内容の永続的な記録です。 2. **プロダクト分析**：ダッシュボードはアナリティクスに**メタデータのみ**を記録します（アシスタントの使用頻度、ツール数、レイテンシ）。このパスにプロンプトの**テキスト**は含まれません。 3. **自己計装（オプション）**：`AGENTEYE_AGENT_SELF_TELEMETRY=1` を設定（および `events:add` のみの `AGENTEYE_TELEMETRY_API_KEY`）すると、アシスタントは自身の実行を `dashboard-assistant` エージェントとしてAgentEyeに記録します。他のすべてに使用しているのと同じセッション/イベントビューでユーザープロンプトとアシスタントの推論を確認できます。注意：これらのイベントは `events:read` を持つ誰にでも表示されます。それが広すぎる場合は、この機能を無効のままにしてください。 *** ## 無効化 以下のいずれかでアシスタントが無効になります（ドックレールが消えます）： * ダッシュボードで `AGENTEYE_AGENT_URL` を未設定にする、**または** * エージェントでLLMエンドポイントを未設定のままにする（`ANTHROPIC_API_KEY` / ゲートウェイ / Bedrock / Vertex なし）、**または** * `agent` サービスをデプロイしない。 *** ## セキュリティサマリ * **サイレントな書き込みなし**：アシスタントの書き込みツール（`create_saved_query`、`update_saved_query`、`create_dashboard`、`update_dashboard`、`add_query_to_dashboard`）は、チャット内の承認ボタンをオペレーターが明示的にクリックしない限り実行できません。SDKのプリコールゲートは、バックチャンネル経由でエージェントに承認が届くまでツールをブロックします。このゲートを無効にする設定はありません。 * **固定された狭いデータスコープ**：アシスタントはサーバー内で固定された権限セット（`events:read`、`evaluations:read`、`dashboards:read`、`dashboards:write`、`queries:read`、`queries:write`、`queries:run`）を持つ専用キーでサーバーに認証します。作成できる書き込みは保存済みクエリとダッシュボードのみであり、モデルが試みた内容に関係なく、サーバーはそのスコープ外のものをすべて拒否します。 * **削除機能なし**：キーには削除権限がなく、削除ツールも公開されていません。オペレーターはダッシュボードUIを通じて削除し、アシスタントを通じては削除しません。 * **内部専用**：エージェントには公開ルートがなく、ダッシュボードのみが共有トークンを使って呼び出せます。（Kubernetesでは、NetworkPolicyがエージェントをAgentEyeサーバーとLLMエンドポイントのみに到達するよう制限します。） * **ユーザーごとのスコーピング**：`agent:use` ユーザーのみがアシスタントを利用でき、各ユーザーの読み取り権限に一致するツールのみが提供されます。 * **生のHTMLなし / リンク流出なし**：回答はサニタイズされたマークダウンとしてレンダリングされ、外部リンクは無効化されます。 一般的な問題については [enterprise-docs/troubleshooting.md](/ja/agenteye/troubleshooting) を参照してください。