kibana-agent-builder

Kibana Agent Builder

创建、检查、更新、删除和测试 Agent Builder 工具与Agent。通过限定范围的搜索工具、参数化 ES|QL 和工作流集成，基于 Elasticsearch 数据为大模型的响应提供依据。

环境配置

此技能通过 elastic CLI 执行 Elasticsearch 操作。如果未安装 elastic CLI，请告知用户需要安装它。 不要猜测凭据、直接调用 HTTP API，也不要尝试其他变通方法。

此技能以 HTTP 简写形式引用操作（例如 GET /、GET /_cat/indices、GET /{index}/_mapping、 GET /{index}/_settings/index.mode、POST /_query）。本文档末尾的 Operations 表格 列出了各简写对应的 elastic CLI 命令 — 始终使用 CLI，而不是直接调用 HTTP API。

资源模型

Agent Builder 提供三种不同的资源类型 — 不要混为一谈：

类型	用途	常见 API
工具	Agent 用于检索或处理数据的可复用函数（index_search、esql、workflow）	POST kbn:/api/agent_builder/tools
Agent	配有指令和精选工具集的大模型实体	POST kbn:/api/agent_builder/agents
聊天 / 对话	与现有 Agent 进行临时消息交互的会话	POST kbn:/api/agent_builder/converse/async

创建工具不会创建 Agent。列出 Agent 或与其聊天不会创建工具。当用户要求“创建 Agent”或“创建工具”时，在调用写入 API 前先确认他们指的是哪种资源。

内置工具使用 platform.core.* 前缀（例如 platform.core.search）。自定义工具和 Agent 由用户定义。请阅读 architecture-guide.md，了解内置工具清单、上下文工程和安全说明。

流程

1. 对任务分类。 判断用户需要的是工具、Agent，还是与现有 Agent 聊天。如果 用户询问已有资源（“有哪些 Agent？”、“列出 Agent”），应将请求视为只读发现 — 先根据实时数据作答，再考虑创建、更新或删除。

2. 任何写入操作前，先发现现有资源。 创建或更新时：

   • 调用 GET kbn:/api/agent_builder/tools，列出可用工具（内置和自定义）。不要臆造工具 ID。
   • 调用 GET kbn:/api/agent_builder/agents，列出现有 Agent，避免 ID 或名称重复。

   如果用户只询问有哪些 Agent，在调用 GET kbn:/api/agent_builder/agents 后就停止。列出每个 Agent 的 ID 和名称。如果列表为空，请明确说明 — 不要捏造 Agent。只有在用户明确要求创建 Agent，且确认目标 ID 未被使用后，才继续创建。

3. 选择工具类型（针对工具任务）。 根据意图选择最适用且范围最窄的工具类型：

   • 在已知索引模式中进行开放式搜索 → 使用带有具体模式的 index_search（例如 customer-feedback-*），除非用户明确要求，否则不要使用 * 或覆盖所有索引的范围。
   • 固定分析、聚合或参数化查询 → 使用带有 ?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。
   • 索引搜索配置使用 "pattern"，而不是 "index"。
   • 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、type、description 和 configuration 报告给用户——没有实时 API 响应时，不要声称创建成功。

   也可以通过调用 POST kbn:/api/agent_builder/tools/_execute 验证 ES|QL 工具，并传入 tool_id 和 tool_params。ES|QL 查询中始终包含 | LIMIT N，以控制令牌用量。

6. 构建 Agent 负载（适用于 Agent 任务）。 必需字段：id、name、description、configuration。 configuration 必须包含 instructions，以及一个 tools 数组，其中的 tool_ids 必须取自步骤 2——仅使用 GET kbn:/api/agent_builder/tools 返回的 ID。

   根据名称生成稳定的 id（小写、连字符、字母数字）。发布前检查步骤 2 的 Agent 列表，避免冲突。

   {
     "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"]
         }
       ]
     }
   }
   

   Agent 更新约束： PUT 仅接受 description、configuration 和 tags（以及适用时的 avatar/labels）。更新时不要发送 id、name 或 type 等不可变字段，否则会导致 400 错误。

7. 创建并验证 Agent。 调用 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}
   • 更新 Agent：PUT kbn:/api/agent_builder/agents/{agentId}
   • 删除 Agent：DELETE kbn:/api/agent_builder/agents/{agentId}

9. 聊天（用户提出请求时）。 聊天不属于 Agent 或工具创建。使用现有的 agent_id 和用户输入调用 POST kbn:/api/agent_builder/converse/async。预计会进行多步推理并调用工具；请为流式传输完成留出充足时间。

指南

• 先发现，再创建。 创建资源前，始终列出 Agent（并在相关时列出工具）。用户询问“有哪些 Agent？”时，先以只读方式回答该问题——即使用户还提到之后想创建新 Agent。
• 严格限定索引搜索范围。 优先使用 customer-feedback-* 而不是 *。宽泛的模式会增加噪声、令牌成本和 RBAC 覆盖范围。
• 编写描述清晰的工具说明。 Agent 仅根据说明选择工具——请注明各工具的使用时机和示例触发语句。
• 尽量精简工具集。 每个分配的工具都会在每轮对话中增加 Agent 系统提示词的令牌用量。
• 部署前验证 ES|QL。 创建后，如果参数或查询结构并非简单明了，请执行该工具。
• 使用聚合和 KEEP。 对于分析类问题，优先使用汇总统计，而不是原始文档转储。

示例

创建索引搜索工具（评估模式）

用户：“创建一个自定义 Agent Builder 工具，用于搜索 customer-feedback-* 索引。工具 ID 使用 'eval-feedback-search'。”

1. 列出工具 — 确认 eval-feedback-search 尚不存在。
2. 选择作用于 customer-feedback-* 的 index_search（而不是 *）。
3. 发送包含 ID、描述和 configuration.pattern 的 POST 请求来创建工具。
4. 按 ID 获取工具，并向用户确认已创建。

创建之前先回答“已经有哪些 Agent？”

用户：“我想在 Kibana Agent Builder 中创建一个新 Agent。已经有哪些 Agent？”

1. 调用 GET kbn:/api/agent_builder/agents — 只读操作。
2. 列出已有 Agent 的 ID 和名称（如果没有，则说明不存在）。
3. 此步骤中不要创建、更新或删除任何内容。
4. 只有在用户随后要求创建时，才根据上述列表选择一个未使用的 ID。

发现现有 Agent 后创建 Agent

用户：“使用 esql-sales-data 工具创建一个 sales-helper Agent。”

1. 列出工具 — 确认 esql-sales-data 存在。
2. 列出 Agent — 确认没有 ID 冲突。
3. 发送包含指令和所选工具 ID 的 POST 请求来创建 Agent。
4. 获取 Agent 以进行验证，并向用户报告结果。

参考资料

• architecture-guide.md — 内置工具、上下文工程、令牌优化、 MCP/A2A 集成、权限
• use-cases.md — 客户反馈、营销活动和合同分析 Agent 的操作指南，以及工具和 Agent 请求示例

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>'