kibana-agent-builder

Kibana Agent Builder

Agent Builder のツールとエージェントを作成、確認、更新、削除、テストできます。スコープを限定した検索ツール、パラメーター化された ES|QL、ワークフロー連携を通じて、Elasticsearch のデータに基づく LLM の応答を生成します。

環境設定

このスキルは elastic CLI を通じて Elasticsearch の操作を実行します。 elastic CLI がインストールされていない場合は、何に必要なのかをユーザーに伝えてください。認証情報を推測したり、HTTP API を直接呼び出したり、ほかの回避策を試みたりしないでください。

このスキルでは、HTTP の省略形式で操作を記載しています（例：GET /、GET /_cat/indices、GET /{index}/_mapping、GET /{index}/_settings/index.mode、POST /_query）。このドキュメントの最後にある操作の表に、各省略形式に対応する elastic CLI コマンドが記載されています。HTTP API を直接呼び出さず、必ず CLI を使用してください。

リソースモデル

Agent Builder では、3 種類の異なるリソースを扱います。それぞれを混同しないでください。

種類	目的	代表的な API
ツール	エージェントがデータの取得や操作に使用する、再利用可能な関数（index_search、esql、workflow）	POST kbn:/api/agent_builder/tools
エージェント	指示と厳選されたツールセットを備えた LLM エンティティ	POST kbn:/api/agent_builder/agents
チャット／会話	既存のエージェントとの一時的なメッセージングセッション	POST kbn:/api/agent_builder/converse/async

ツールを作成しても、エージェントは作成されません。エージェントを一覧表示したり、チャットしたりしても、ツールは作成されません。ユーザーが「エージェントを作成」または「ツールを作成」と依頼した場合は、書き込み API を呼び出す前に、どちらのリソースを指しているのか確認してください。

組み込みツールには platform.core.* のプレフィックスが付いています（例：platform.core.search）。カスタムツールとエージェントはユーザーが定義します。組み込みツールの一覧、コンテキストエンジニアリング、セキュリティに関する注意事項については、architecture-guide.md を参照してください。

プロセス

1. タスクを分類します。 ユーザーが必要としているのがツール、エージェント、それとも既存のエージェントとのチャットなのかを判断します。既存のものについて尋ねている場合（「どんなエージェントがありますか？」「エージェントを一覧表示して」など）は、読み取り専用の確認として扱い、作成、更新、削除を提案する前に、稼働中のデータに基づいて回答します。

2. 書き込みを行う前に、既存のリソースを確認します。 作成または更新する場合：

   • GET kbn:/api/agent_builder/tools を呼び出して、利用可能なツール（組み込みとカスタム）を一覧表示します。ツール ID をでっち上げないでください。
   • GET kbn:/api/agent_builder/agents を呼び出して既存のエージェントを一覧表示し、ID や名前の重複を避けます。

   ユーザーが既存のエージェントについてのみ尋ねている場合は、GET kbn:/api/agent_builder/agents の後で処理を終了します。各エージェントの ID と名前を列挙してください。一覧が空の場合は、その旨を明確に伝えてください。エージェントを捏造しないでください。ユーザーが明示的に作成を依頼し、対象の ID が未使用であることを確認できた場合にのみ、作成に進みます。

3. ツールタスクでは、ツールの種類を選びます。 意図に最も適した、範囲を絞ったツールの種類を選びます。

   • 既知のインデックスパターンを対象とした自由形式の検索 → 特定のパターン（例：customer-feedback-*）を指定した index_search を使用します。ユーザーが明示的に求めていない限り、* や全インデックスを対象とするスコープは使用しないでください。
   • 固定された分析、集計、またはパラメーター化されたクエリ → ?param プレースホルダーと params オブジェクトを使った esql を使用します。パラメーターがない場合は {} を使用します。
   • 取得以外の複数ステップの自動化 → 既存のワークフロー ID を参照する workflow を使用します。 ES|QL の構文とクエリ設計については、elasticsearch-esql スキルに従ってください。ワークフロー YAML については、 kibana-workflows スキルに従ってください。

4. ツールのペイロードを作成します。 必須フィールド：id、type、description、configuration。任意：tags。

   API の制約（違反すると 400 が返されます）：

   • POST で受け付けるのは id、type、description、configuration、tags のみです。ツールでは name は無効です。
   • インデックス検索の設定では、"index" ではなく "pattern" を使用します。
   • ES|QL ツールでは、空の場合も "params" が必要です："params": {}。
   • 各パラメーターで受け付けるのは type と description のみです。default や optional は使用できません。デフォルト値はクエリにハードコードしてください。
   • ツールへの PUT で受け付けるのは description、configuration、tags のみです。id と type は変更できません。

   インデックス検索の例（スコープを絞ったパターン）：

   {
     "id": "customer_feedback_search",
     "type": "index_search",
     "description": "Searches customer feedback and support tickets in the customer-feedback indices.",
     "configuration": {
       "pattern": "customer-feedback-*"
     }
   }
   

   ES|QL の例（LIMIT を含むパラメーター化クエリ）：

   {
     "id": "feedback_sentiment_trend",
     "type": "esql",
     "description": "Returns positive vs negative feedback counts by product category over a lookback window.",
     "configuration": {
       "query": "FROM customer-feedback-* | WHERE @timestamp >= NOW() - ?lookback_days::integer * 1d | STATS positive = COUNT(*) WHERE sentiment == \"positive\", negative = COUNT(*) WHERE sentiment == \"negative\" BY product_category | SORT negative DESC | LIMIT 20",
       "params": {
         "lookback_days": {
           "type": "integer",
           "description": "Number of days to look back, e.g. 7, 30, 90"
         }
       }
     }
   }
   

5. ツールを作成して検証します。 ペイロードを指定して POST kbn:/api/agent_builder/tools を呼び出します。GET kbn:/api/agent_builder/tools/{toolId} を呼び出して成功を確認し、作成された ID、タイプ、説明、設定をユーザーに報告してください。実際の API レスポンスを得るまでは、成功したと主張しないでください。

   必要に応じて、tool_id と tool_params を渡し、POST kbn:/api/agent_builder/tools/_execute で ES|QL ツールを検証できます。トークンの使用量を制御するため、ES|QL クエリには必ず | LIMIT N を含めてください。

6. エージェントのペイロードを作成します（エージェントタスクの場合）。 必須フィールド：id、name、description、configuration。 設定には instructions と、ステップ 2 で取得した tool_ids を含む tools 配列が必要です。使用できるのは、GET kbn:/api/agent_builder/tools が返した ID のみです。

   名前から安定した id を導出してください（小文字、ハイフン、英数字）。POST する前にステップ 2 のエージェント一覧を確認し、競合がないか確認してください。

   {
     "id": "customer-feedback-agent",
     "name": "Customer Feedback Analyst",
     "description": "Analyzes customer sentiment and feedback trends.",
     "configuration": {
       "instructions": "Always use tools to retrieve data. Never answer data questions from memory.",
       "tools": [
         {
           "tool_ids": ["customer_feedback_search", "platform.core.search"]
         }
       ]
     }
   }
   

   エージェントの更新に関する制約： PUT で受け付けるのは description、configuration、tags のみです（該当する場合は avatar/labels も含みます）。更新時に id、name、type などの変更できないフィールドを送信しないでください。400 エラーの原因になります。

7. エージェントを作成して検証します。 POST kbn:/api/agent_builder/agents を呼び出します。GET kbn:/api/agent_builder/agents または GET kbn:/api/agent_builder/agents/{agentId} で確認してください。実際のレスポンスを報告してください。

8. 更新または削除します（依頼された場合）。 破壊的な操作を行う前に、必ずユーザーに確認してください。

   • ツールを更新：PUT kbn:/api/agent_builder/tools/{toolId}
   • ツールを削除：DELETE kbn:/api/agent_builder/tools/{toolId}
   • エージェントを更新：PUT kbn:/api/agent_builder/agents/{agentId}
   • エージェントを削除：DELETE kbn:/api/agent_builder/agents/{agentId}

9. チャットします（依頼された場合）。 チャットはエージェントやツールの作成ではありません。既存の agent_id とユーザー入力を指定して、POST kbn:/api/agent_builder/converse/async を使用します。複数ステップの推論とツール呼び出しが想定されるため、ストリーミングの完了まで十分な時間を確保してください。

ガイドライン

• 作成前に確認します。 リソースを作成する前に、必ずエージェント（関連する場合はツールも）を一覧表示してください。「どのようなエージェントがありますか？」と尋ねられた場合は、ユーザーが後で新しいエージェントを作りたいとも述べていても、まずその質問に読み取り専用で回答してください。
• インデックス検索の範囲を狭くします。 * よりも customer-feedback-* を優先してください。広いパターンは、ノイズ、トークンコスト、RBAC の対象範囲を増やします。
• 説明的なツールの説明を記述します。 エージェントは説明だけを基にツールを選択します。各ツールをいつ使うべきか、また、きっかけとなるフレーズの例を含めてください。
• ツールセットを最小限にします。 割り当てるツールが増えるたびに、ターンごとにエージェントのシステムプロンプトで使用するトークンが増えます。
• デプロイ前に ES|QL を検証します。 パラメーターやクエリの形式が複雑な場合は、作成後にツールを実行してください。
• 集計と KEEP を使用します。 分析に関する質問では、生のドキュメントをそのまま出力するより、要約統計を優先してください。

例

インデックス検索ツールを作成する（評価パターン）

ユーザー：「customer-feedback-* インデックスを検索するカスタム Agent Builder ツールを作成してください。ツール ID は 'eval-feedback-search' にしてください。」

1. ツールを一覧表示し、eval-feedback-search がまだ存在しないことを確認します。
2. customer-feedback-* にスコープを限定した index_search を選択します（* は指定しません）。
3. ID、説明、configuration.pattern を指定してツールを POST します。
4. ID でツールを GET し、作成できたことをユーザーに確認します。

作成前に「既存のエージェントは？」に回答する

ユーザー：「Kibana Agent Builder で新しいエージェントを作成したいです。既存のエージェントを教えてください。」

1. GET kbn:/api/agent_builder/agents を呼び出します（読み取り専用）。
2. 既存のエージェント ID と名前を列挙します（存在しない場合は、その旨を伝えます）。
3. この手順では、何も作成、更新、削除しないでください。
4. その後、ユーザーが作成を依頼した場合に限り、上記の一覧を踏まえて未使用の ID を選びます。

確認後にエージェントを作成する

ユーザー：「esql-sales-data ツールを使って sales-helper エージェントを作成してください。」

1. ツールを一覧表示し、esql-sales-data が存在することを確認します。
2. エージェントを一覧表示し、競合する ID がないことを確認します。
3. 指示と選択したツール ID を指定してエージェントを POST します。
4. エージェントを GET して確認し、結果を報告します。

参考資料

• architecture-guide.md — 組み込みツール、コンテキストエンジニアリング、トークンの最適化、 MCP/A2A 統合、権限
• use-cases.md — ツールとエージェントのペイロード例を含む、顧客フィードバック、マーケティングキャンペーン、契約分析の各エージェント向けプレイブック

Operations

HTTP API (shorthand)	elastic CLI command
GET kbn:/api/agent_builder/tools	elastic kb agent-builder get-agent-builder-tools
POST kbn:/api/agent_builder/tools	elastic kb agent-builder post-agent-builder-tools --id '<id>' --type '<type>' --description '<desc>' --configuration '<json>'
GET kbn:/api/agent_builder/tools/{toolId}	elastic kb agent-builder get-agent-builder-tools-toolid --tool-id '<toolId>'
PUT kbn:/api/agent_builder/tools/{toolId}	elastic kb agent-builder put-agent-builder-tools-toolid --tool-id '<toolId>' [--description '<desc>'] [--configuration '<json>']
DELETE kbn:/api/agent_builder/tools/{toolId}	elastic kb agent-builder delete-agent-builder-tools-toolid --tool-id '<toolId>' [--force]
POST kbn:/api/agent_builder/tools/_execute	elastic kb agent-builder post-agent-builder-tools-execute --tool-id '<toolId>' --tool-params '<json>'
GET kbn:/api/agent_builder/agents	elastic kb agent-builder get-agent-builder-agents
POST kbn:/api/agent_builder/agents	elastic kb agent-builder post-agent-builder-agents --id '<id>' --name '<name>' --description '<desc>' --configuration '<json>'
GET kbn:/api/agent_builder/agents/{agentId}	elastic kb agent-builder get-agent-builder-agents-id --id '<agentId>'
PUT kbn:/api/agent_builder/agents/{agentId}	elastic kb agent-builder put-agent-builder-agents-id --id '<agentId>' [--description '<desc>'] [--configuration '<json>']
DELETE kbn:/api/agent_builder/agents/{agentId}	elastic kb agent-builder delete-agent-builder-agents-id --id '<agentId>'
POST kbn:/api/agent_builder/converse/async	elastic kb agent-builder post-agent-builder-converse-async --agent-id '<agentId>' --input '<message>'