在 Kibana Agent Builder 中创建/管理…

当需要通过 Kibana Agent Builder 创建、更新、删除、测试或查看 agent 与 tool 时使用。

适用场景

解决思路

1. 先分类任务：判断用户需要的是 tool、agent，还是与已有 agent 的 chat；若用户只是询问已存在什么（如“有哪些 agent”），则视为只读发现，先基于实时数据回答，再考虑创建/更新/删除。
2. 任何写操作前先发现已有资源：调用 GET kbn:/api/agent_builder/tools 列出可用工具（内置与自定义），不要臆造 tool ID；调用 GET kbn:/api/agent_builder/agents 列出已有 agent，避免重复 ID 或名称。
3. 若用户只问有哪些 agent，则在 GET kbn:/api/agent_builder/agents 后停止，逐一列出每个 agent 的 id 和 name；若列表为空就如实说明，不要编造 agent；只有用户明确要求创建且确认目标 id 未被占用时才继续创建。
4. 为 tool 任务选择最窄的工具类型：对已知索引模式的开放式搜索用 index_search 并指定具体 pattern（如 customer-feedback-*），除非用户明确要求，否则不要用 * 或全索引范围；固定分析、聚合或参数化查询用 esql 并带 ?param 占位符和 params 对象（无参数时用 {}）；超出检索的多步自动化用 workflow 并引用已有 workflow id。
5. ES|QL 语法与查询设计遵循 elasticsearch-esql 技能；workflow YAML 遵循 kibana-workflows 技能。
6. 构建 tool payload：必填字段为 id、type、description、configuration，可选 tags。
7. 遵守 tool API 约束（违反会返回 400）：POST 只接受 id、type、description、configuration、tags，tool 上不接受 name；index search 配置用 "pattern" 而非 "index"；ES|QL 工具必须带 "params"，即使为空也要写 "params": {}；每个 param 只接受 type 和 description，不接受 default 或 optional，默认值需硬编码进查询；PUT tool 只接受 description、configuration、tags，id 和 type 不可变。
8. 创建并验证 tool：调用 POST kbn:/api/agent_builder/tools 提交 payload，然后调用 GET kbn:/api/agent_builder/tools/{toolId} 确认成功，并向用户报告创建的 id、type、description 和 configuration；没有实时 API 响应不要声称成功。
9. 可选：用 POST kbn:/api/agent_builder/tools/_execute 并传入 tool_id 和 tool_params 来验证 ES|QL 工具；ES|QL 查询中始终包含 | LIMIT N 以控制 token 消耗。
10. 构建 agent payload（agent 任务）：必填字段为 id、name、description、configuration；configuration 必须包含 instructions 和 tools 数组，其中 tool_ids 只能来自第 2 步 GET kbn:/api/agent_builder/tools 返回的 ID。
11. 从 name 派生稳定的 id（小写、连字符、字母数字），post 前检查第 2 步的 agent 列表是否有冲突。
12. 遵守 agent 更新约束：PUT 只接受 description、configuration、tags（以及适用时的 avatar/labels），更新时不要发送 id、name、type 等不可变字段，否则会 400 报错。
13. 创建并验证 agent：调用 POST kbn:/api/agent_builder/agents，然后用 GET kbn:/api/agent_builder/agents 或 GET kbn:/api/agent_builder/agents/{agentId} 确认，并报告实时响应。
14. 更新或删除（被要求时）：先与用户确认破坏性操作；更新 tool 用 PUT kbn:/api/agent_builder/tools/{toolId}，删除 tool 用 DELETE kbn:/api/agent_builder/tools/{toolId}，更新 agent 用 PUT kbn:/api/agent_builder/agents/{agentId}，删除 agent 用 DELETE kbn:/api/agent_builder/agents/{agentId}。
15. 聊天（被要求时）：chat 不是创建 agent 或 tool；使用 POST kbn:/api/agent_builder/converse/async 并传入已有 agent_id 和用户输入；预期会有多步推理和工具调用，需留足流式完成时间。
16. 发现先于创建：创建资源前始终先列出 agents（相关时也列出 tools）；当被问“有哪些 agent”时，即使随后提到想新建 agent，也要先只读地回答该问题。
17. 索引搜索要窄范围：优先 customer-feedback-* 而非 *；宽泛 pattern 会增加噪声、token 成本和 RBAC 暴露面。
18. 编写描述性的 tool description：agent 仅依据 description 选择工具，需写明每个工具何时使用及示例触发短语。
19. 最小化工具集：每个分配的工具都会在每一轮向 agent 系统提示词增加 token。
20. 部署前验证 ES|QL：当参数或查询形态较复杂时，创建后执行该工具进行验证。
21. 使用聚合和 KEEP：分析类问题优先用汇总统计而非原始文档转储。

适用边界 · 注意事项

• 未安装 elastic CLI 时不要使用本技能；应告知用户为何需要它，不要猜测凭据、直接调用 HTTP API 或尝试其他变通方法。
• 用户只是询问已有 agent/tool 时，不要执行任何创建、更新或删除操作。
• 不要混淆 tool、agent 和 chat 三种资源：创建 tool 不会创建 agent，列出或与 agent 聊天也不会创建 tool。