Kibana Agent Builder 管理指南：创建、更新、删除智能体与自定义工具

kibana-agent-builder by elastic/agent-skills

261 周安装量

306 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/elastic/agent-skills --skill kibana-agent-builder

AI/机器学习自动化数据分析

🇨🇳中文介绍

在 Kibana 中管理 Agent Builder 智能体和工具

创建、更新、删除、检查 Agent Builder 智能体，并与之对话。创建、更新、删除、列出和测试自定义工具（ES|QL、索引搜索、工作流）。如果用户提供了名称，则使用 $ARGUMENTS 作为默认智能体名称。

前提条件

在运行任何脚本之前设置以下环境变量：

变量	必需	描述
`KIBANA_URL`	是	Kibana 基础 URL（例如，`https://my-deployment.kb.us-east-1.aws.elastic.cloud`）
`KIBANA_API_KEY`	否	用于身份验证的 API 密钥（首选）
`KIBANA_USERNAME`	否	基本身份验证的用户名（回退到）

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

896,800 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

142,000 周安装

Azure Data Explorer (Kusto) 查询技能：KQL数据分析、日志遥测与时间序列处理

138,800 周安装

ELASTICSEARCH_USERNAME

请提供 KIBANA_API_KEY 或 KIBANA_USERNAME + KIBANA_PASSWORD。

步骤 1：列出可用工具

node skills/kibana/agent-builder/scripts/agent-builder.js list-tools

如果脚本报告连接错误，请停止并告知用户验证其 KIBANA_URL 和身份验证环境变量。

查看可用工具列表。以 platform.core. 为前缀的工具是内置的。其他工具是自定义的或由连接器提供的。

步骤 2：列出已有智能体

node skills/kibana/agent-builder/scripts/agent-builder.js list-agents

这有助于避免名称冲突，并显示已配置的内容。

步骤 3：收集智能体详细信息

使用 $ARGUMENTS 作为默认名称，向用户确认或收集以下信息：

名称（必需）— 智能体的显示名称。默认值：$ARGUMENTS。
描述（可选）— 智能体功能的简要描述。默认值：与名称相同。
系统指令（可选）— 智能体的自定义系统提示。默认值：无。

步骤 4：选择工具

展示步骤 1 中的可用工具，并询问用户要包含哪些工具。根据智能体的用途建议一个合理的默认值。允许用户在建议列表中添加或删除工具。

步骤 5：创建智能体

node skills/kibana/agent-builder/scripts/agent-builder.js create-agent \
  --name "<agent_name>" \
  --description "<description>" \
  --instructions "<system_instructions>" \
  --tool-ids "<tool_id_1>,<tool_id_2>,<tool_id_3>"

--name 是必需的
--tool-ids 是来自步骤 4 的工具 ID 的逗号分隔列表
--description 如果省略则默认为名称
--instructions 如果用户未提供任何指令，则可以省略

步骤 6：验证创建

node skills/kibana/agent-builder/scripts/agent-builder.js list-agents

向用户展示新创建的智能体条目。如果出现，则报告成功。如果没有，则显示步骤 5 中的任何错误输出。

node skills/kibana/agent-builder/scripts/agent-builder.js get-agent --id "<agent_id>"

node skills/kibana/agent-builder/scripts/agent-builder.js update-agent \
  --id "<agent_id>" \
  --description "<new_description>" \
  --instructions "<new_instructions>" \
  --tool-ids "<tool_id_1>,<tool_id_2>"

除了 --id 之外的所有标志都是可选的 — 仅更新提供的字段。智能体的 id 和 name 是不可变的。

API 约束 : PUT 仅接受 description、configuration 和 tags。包含 id、name 或 type 会导致 400 错误。

node skills/kibana/agent-builder/scripts/agent-builder.js delete-agent --id "<agent_id>"

删除前务必与用户确认。删除是永久性的。

node skills/kibana/agent-builder/scripts/agent-builder.js chat \
  --id "<agent_id>" \
  --message "<user_message>"

使用流式端点 POST /api/agent_builder/converse/async，请求体中包含 agent_id 和 input。输出会在事件到达时显示 [推理]、[工具调用]、[工具结果] 和 [响应]。传递 --conversation-id 以继续现有对话。

注意： 此命令可能需要 30-60 秒，因为智能体需要推理和调用工具。通过 Bash 运行时，请使用更长的超时时间（例如 120 秒或 180 秒）。

自定义工具扩展了智能体在平台内置工具之外的能力。

预定义的、参数化的 ES|QL 查询。当您需要保证查询正确性、强制执行业务规则、分析聚合或细粒度数据访问控制时使用。

参数语法 : 在查询中使用 ?param_name。仅使用 type 和 description 定义每个参数。有效类型：string、integer、float、boolean、date、array。

{
  "id": "campaign_revenue_by_region",
  "type": "esql",
  "description": "按季度计算某个区域的确认收入。",
  "configuration": {
    "query": "FROM finance-orders-* | WHERE order_status == \"completed\" AND region == ?region | STATS total_revenue = SUM(amount) BY quarter | LIMIT 10",
    "params": {
      "region": {
        "type": "string",
        "description": "区域代码，例如 'US'、'EU'、'APAC'"
      }
    }
  }
}

将内置搜索功能限定到特定的索引模式。LLM 决定如何查询；您控制哪些索引可访问。

{
  "id": "customer_feedback_search",
  "type": "index_search",
  "description": "搜索客户反馈和支持工单。",
  "configuration": {
    "pattern": "customer-feedback-*"
  }
}

将智能体连接到 Elastic 工作流 — 一个 YAML 定义的多步骤自动化流程。当智能体需要执行数据检索之外的操作（发送通知、创建工单、调用外部 API）时使用。

{
  "id": "investigate-alert-workflow",
  "type": "workflow",
  "description": "触发自动警报调查。",
  "configuration": {
    "workflow_id": "security-alert-investigation"
  }
}

参数会根据工作流的 inputs 部分自动检测。

在创建工具之前请阅读这些内容 — 违反会导致 400 错误。

POST 主体字段 : 仅接受 id、type、description、configuration 和 tags。name 不是有效字段 — 请完全省略它。
params 对于 ES|QL 工具始终是必需的，即使为空 — 使用 "params": {}。
参数字段 : 每个参数仅接受 type 和 description。default 和 optional 无效，会导致 400 错误。请在查询中硬编码合理的默认值。
索引搜索配置 : 使用 "pattern"，而不是 "index"。使用 "index" 会导致验证错误。
PUT 限制 : 仅接受 description、configuration 和 tags。包含 id 或 type 会导致 400 错误 — 这些字段在创建后是不可变的。

node skills/kibana/agent-builder/scripts/agent-builder.js list-custom-tools

node skills/kibana/agent-builder/scripts/agent-builder.js get-tool --id "<tool_id>"

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "<tool_id>" \
  --type "esql" \
  --description "<description>" \
  --query "<esql_query>" \
  --params '{"region": {"type": "string", "description": "Region code"}}'

对于索引搜索工具：

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "<tool_id>" \
  --type "index_search" \
  --description "<description>" \
  --pattern "my-index-*"

对于工作流工具：

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "<tool_id>" \
  --type "workflow" \
  --description "<description>" \
  --workflow-id "my-workflow-name"

node skills/kibana/agent-builder/scripts/agent-builder.js update-tool \
  --id "<tool_id>" \
  --description "<new_description>" \
  --query "<new_query>"

只能更新 description、configuration 和 tags。id 和 type 是不可变的。

node skills/kibana/agent-builder/scripts/agent-builder.js delete-tool --id "<tool_id>"

node skills/kibana/agent-builder/scripts/agent-builder.js test-tool \
  --id "<tool_id>" \
  --params '{"region": "US"}'

通过 POST /api/agent_builder/tools/_execute 执行工具，并显示 ES|QL 结果的列名和行数。

User: /kibana-agent-builder sales-helper

列出工具 — 找到 platform.core.search、platform.core.list_indices 和一个自定义的 esql-sales-data 工具
列出智能体 — 无冲突
名称："sales-helper"，描述："帮助查询销售数据"
工具：esql-sales-data、platform.core.search、platform.core.list_indices
使用 --name "sales-helper" --tool-ids "esql-sales-data,platform.core.search,platform.core.list_indices" 创建
验证 — 智能体出现在列表中

更新智能体的指令

User: Update the sales-helper agent to focus on the APAC region

获取智能体 — get-agent --id "sales-helper" 查看当前配置
更新 — update-agent --id "sales-helper" --instructions "Focus on APAC sales data. Use esql-sales-data for queries."
验证 — get-agent --id "sales-helper" 确认新指令

User: Ask sales-helper what the top revenue products are

对话 — chat --id "sales-helper" --message "What are the top revenue products?"
显示智能体的响应

创建带参数的 ES|QL 工具

User: Create a tool that shows billing complaints by category for the last N days

查阅 elasticsearch-esql 技能以了解 ES|QL 语法
创建工具：

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool
--id "billing_complaint_summary"
--type "esql"
--description "Returns billing complaints grouped by sub-category for the last N days."
--query "FROM customer-feedback-* | WHERE @timestamp >= NOW() - ?days::integer * 1d AND MATCH(feedback_text, 'billing') | STATS count = COUNT(*) BY sub_category | SORT count DESC | LIMIT 10"
--params '{"days": {"type": "integer", "description": "Number of days to look back"}}'
测试：test-tool --id "billing_complaint_summary" --params '{"days": 30}'

创建索引搜索工具

User: Create a tool to search support transcripts



node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "transcript_search" \
  --type "index_search" \
  --description "Searches support call transcripts by topic, agent, or customer issue." \
  --pattern "support-transcripts"

阅读以下内容以获取详细指导：

references/architecture-guide.md — 核心概念、内置工具、上下文工程、最佳实践、令牌优化、REST API 端点、MCP/A2A 集成、权限
references/use-cases.md — 客户反馈分析、营销活动分析和合同分析智能体的完整操作手册

对于 ES|QL 语法、函数、运算符和参数规则，请使用 elasticsearch-esql 技能。对于工作流 YAML 结构、触发器类型、步骤类型和智能体-工作流模式，请使用 security-workflows 技能。

在创建智能体之前，始终运行 list-tools，以便用户可以从真实可用的工具中进行选择。
在创建智能体之前和之后，始终运行 list-agents，以检测冲突并验证成功。
不要编造工具 ID — 仅使用 list-tools 返回的 ID。
如果尚不存在自定义工具，建议创建一个或使用内置的平台工具。
智能体 ID 是根据名称自动生成的（小写、连字符、仅限字母数字）。
对于非默认的 Kibana 空间，请在运行脚本之前设置 KIBANA_SPACE_ID。
在运行 delete-agent 或 delete-tool 之前与用户确认 — 删除是永久性的。
始终在 ES|QL 查询中包含 | LIMIT N 以防止上下文窗口溢出。
编写描述性的工具描述 — 智能体仅根据描述决定调用哪个工具。
将索引搜索工具的范围限定得尽可能窄（例如，customer-feedback-* 而不是 *）。
使用 KEEP 仅返回需要的列，以减少令牌消耗。
在将 ES|QL 查询分配给智能体之前，使用 test-tool 进行验证。
对于没有参数的 ES|QL 工具，仍需包含 "params": {}。

🇺🇸English

Manage Agent Builder Agents and Tools in Kibana

Create, update, delete, inspect, and chat with Agent Builder agents. Create, update, delete, list, and test custom tools (ES|QL, index search, workflow). If the user provided a name, use $ARGUMENTS as the default agent name.

Prerequisites

Set these environment variables before running any script:

Variable	Required	Description
`KIBANA_URL`	Yes	Kibana base URL (e.g., `https://my-deployment.kb.us-east-1.aws.elastic.cloud`)
`KIBANA_API_KEY`	No	API key for authentication (preferred)
`KIBANA_USERNAME`	No	Username for basic auth (falls back to `ELASTICSEARCH_USERNAME`)
`KIBANA_PASSWORD`	No	Password for basic auth (falls back to `ELASTICSEARCH_PASSWORD`)
`KIBANA_SPACE_ID`	No	Kibana space ID (omit for default space)
`KIBANA_INSECURE`	No	Set to `true` to skip TLS verification

Provide either KIBANA_API_KEY or KIBANA_USERNAME + KIBANA_PASSWORD.

Agent Management

Create an Agent

Step 1: List available tools

node skills/kibana/agent-builder/scripts/agent-builder.js list-tools

If the script reports a connection error, stop and tell the user to verify their KIBANA_URL and authentication environment variables.

Review the list of available tools. Tools prefixed with platform.core. are built-in. Other tools are custom or connector-provided.

Step 2: List existing agents

node skills/kibana/agent-builder/scripts/agent-builder.js list-agents

This helps avoid name conflicts and shows what is already configured.

Step 3: Gather agent details

Using $ARGUMENTS as the default name, confirm or collect from the user:

Name (required) — The agent's display name. Default: $ARGUMENTS.
Description (optional) — Brief description of what the agent does. Default: same as name.
System instructions (optional) — Custom system prompt for the agent. Default: none.

Step 4: Select tools

Present the available tools from Step 1 and ask the user which ones to include. Suggest a reasonable default based on the agent's purpose. Let the user add or remove tools from the suggested list.

Step 5: Create the agent

node skills/kibana/agent-builder/scripts/agent-builder.js create-agent \
  --name "<agent_name>" \
  --description "<description>" \
  --instructions "<system_instructions>" \
  --tool-ids "<tool_id_1>,<tool_id_2>,<tool_id_3>"

Where:

--name is required
--tool-ids is a comma-separated list of tool IDs from Step 4
--description defaults to the name if omitted
--instructions can be omitted if the user did not provide any

Step 6: Verify creation

node skills/kibana/agent-builder/scripts/agent-builder.js list-agents

Show the user the newly created agent entry. If it appears, report success. If not, show any error output from Step 5.

Get an Agent

node skills/kibana/agent-builder/scripts/agent-builder.js get-agent --id "<agent_id>"

Update an Agent

node skills/kibana/agent-builder/scripts/agent-builder.js update-agent \
  --id "<agent_id>" \
  --description "<new_description>" \
  --instructions "<new_instructions>" \
  --tool-ids "<tool_id_1>,<tool_id_2>"

All flags except --id are optional — only provided fields are updated. The agent's id and name are immutable.

API constraint : PUT only accepts description, configuration, and tags. Including id, name, or type causes a 400 error.

Delete an Agent

node skills/kibana/agent-builder/scripts/agent-builder.js delete-agent --id "<agent_id>"

Always confirm with the user before deleting. Deletion is permanent.

Chat with an Agent

node skills/kibana/agent-builder/scripts/agent-builder.js chat \
  --id "<agent_id>" \
  --message "<user_message>"

Uses the streaming endpoint POST /api/agent_builder/converse/async with agent_id and input in the request body. Output shows [Reasoning], [Tool Call], [Tool Result], and [Response] as events arrive. Pass --conversation-id to continue an existing conversation.

Note: This command may take 30-60 seconds as the agent reasons and calls tools. Use a longer timeout (e.g., 120s or 180s) when running via Bash.

Tool Management

Custom tools extend what agents can do beyond the built-in platform tools.

Tool Types

ES|QL Tools

Pre-defined, parameterized ES|QL queries. Use when you need guaranteed query correctness, enforced business rules, analytics aggregations, or fine-grained data access control.

Parameter syntax : Use ?param_name in the query. Define each parameter with type and description only. Valid types: string, integer, float, boolean, date, array.

{
  "id": "campaign_revenue_by_region",
  "type": "esql",
  "description": "Calculates confirmed revenue for a region by quarter.",
  "configuration": {
    "query": "FROM finance-orders-* | WHERE order_status == \"completed\" AND region == ?region | STATS total_revenue = SUM(amount) BY quarter | LIMIT 10",
    "params": {
      "region": {
        "type": "string",
        "description": "Region code, e.g. 'US', 'EU', 'APAC'"
      }
    }
  }
}

Index Search Tools

Scope the built-in search capability to a specific index pattern. The LLM decides how to query; you control which indices are accessible.

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

Workflow Tools

Connect an agent to an Elastic Workflow — a YAML-defined multi-step automation. Use when the agent needs to take action beyond data retrieval (send notifications, create tickets, call external APIs).

{
  "id": "investigate-alert-workflow",
  "type": "workflow",
  "description": "Triggers automated alert investigation.",
  "configuration": {
    "workflow_id": "security-alert-investigation"
  }
}

Parameters are auto-detected from the workflow's inputs section.

Tool API Constraints

Read these before creating tools — violations cause 400 errors.

POST body fields : Only id, type, description, configuration, and tags are accepted. name is not a valid field — omit it entirely.
params is always required for ES|QL tools, even when empty — use "params": {}.
Param fields : Only type and description are accepted per parameter. and are and cause 400 errors. Hard-code sensible defaults in the query instead.

Tool Script Commands

List all tools

node skills/kibana/agent-builder/scripts/agent-builder.js list-custom-tools

Get a specific tool

node skills/kibana/agent-builder/scripts/agent-builder.js get-tool --id "<tool_id>"

Create a tool

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "<tool_id>" \
  --type "esql" \
  --description "<description>" \
  --query "<esql_query>" \
  --params '{"region": {"type": "string", "description": "Region code"}}'

For index search tools:

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "<tool_id>" \
  --type "index_search" \
  --description "<description>" \
  --pattern "my-index-*"

For workflow tools:

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "<tool_id>" \
  --type "workflow" \
  --description "<description>" \
  --workflow-id "my-workflow-name"

Update a tool

node skills/kibana/agent-builder/scripts/agent-builder.js update-tool \
  --id "<tool_id>" \
  --description "<new_description>" \
  --query "<new_query>"

Only description, configuration, and tags can be updated. id and type are immutable.

Delete a tool

node skills/kibana/agent-builder/scripts/agent-builder.js delete-tool --id "<tool_id>"

Test a tool

node skills/kibana/agent-builder/scripts/agent-builder.js test-tool \
  --id "<tool_id>" \
  --params '{"region": "US"}'

Executes the tool via POST /api/agent_builder/tools/_execute and displays column names and row counts for ES|QL results.

Examples

Create an agent

User: /kibana-agent-builder sales-helper

List tools — finds platform.core.search, platform.core.list_indices, and a custom esql-sales-data tool
List agents — no conflicts
Name: "sales-helper", Description: "Helps query sales data"
Tools: esql-sales-data, platform.core.search, platform.core.list_indices
Create with --name "sales-helper" --tool-ids "esql-sales-data,platform.core.search,platform.core.list_indices"
Verify — agent appears in list

Update an agent's instructions

User: Update the sales-helper agent to focus on the APAC region

Get agent — get-agent --id "sales-helper" to see current config
Update — update-agent --id "sales-helper" --instructions "Focus on APAC sales data. Use esql-sales-data for queries."
Verify — get-agent --id "sales-helper" to confirm new instructions

Chat with an agent

User: Ask sales-helper what the top revenue products are

Chat — chat --id "sales-helper" --message "What are the top revenue products?"
Display the agent's response

Create an ES|QL tool with parameters

User: Create a tool that shows billing complaints by category for the last N days

Consult the elasticsearch-esql skill for ES|QL syntax
Create tool:

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool
--id "billing_complaint_summary"
--type "esql"
--description "Returns billing complaints grouped by sub-category for the last N days."
--query "FROM customer-feedback-* | WHERE @timestamp >= NOW() - ?days::integer * 1d AND MATCH(feedback_text, 'billing') | STATS count = COUNT(*) BY sub_category | SORT count DESC | LIMIT 10"
--params '{"days": {"type": "integer", "description": "Number of days to look back"}}'
Test: test-tool --id "billing_complaint_summary" --params '{"days": 30}'

Create an index search tool

User: Create a tool to search support transcripts



node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "transcript_search" \
  --type "index_search" \
  --description "Searches support call transcripts by topic, agent, or customer issue." \
  --pattern "support-transcripts"

References

Read these for detailed guidance:

references/architecture-guide.md — Core concepts, built-in tools, context engineering, best practices, token optimization, REST API endpoints, MCP/A2A integration, permissions
references/use-cases.md — Full playbooks for Customer Feedback Analysis, Marketing Campaign Analysis, and Contract Analysis agents

For ES|QL syntax, functions, operators, and parameter rules, use the elasticsearch-esql skill. For workflow YAML structure, trigger types, step types, and agent-workflow patterns, use the security-workflows skill.

Guidelines

Always run list-tools before creating an agent so the user can choose from real, available tools.
Always run list-agents before and after creation to detect conflicts and verify success.
Do not invent tool IDs — only use IDs returned by list-tools.
If no custom tools exist yet, suggest creating one or using the built-in platform tools.
The agent ID is auto-generated from the name (lowercased, hyphens, alphanumeric only).
For non-default Kibana spaces, set KIBANA_SPACE_ID before running the script.
Confirm with the user before running delete-agent or delete-tool — deletion is permanent.
Always include | LIMIT N in ES|QL queries to prevent context window overflow.
Write descriptive tool descriptions — the agent decides which tool to call based solely on the description.
Scope index search tools narrowly (e.g., customer-feedback-* not ).

Weekly Installs

150

Repository

elastic/agent-skills

GitHub Stars

First Seen

11 days ago

Security Audits

Gen Agent Trust HubWarn SocketPass SnykPass

Installed on

cursor133

github-copilot126

opencode125

gemini-cli125

codex125

amp124

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

120,000 周安装

Index search config : Use "pattern", not "index". Using "index" causes a validation error.

PUT restrictions : Only description, configuration, and tags are accepted. Including id or type causes a 400 error — these fields are immutable after creation.

Use KEEP to return only needed columns and reduce token consumption.

Validate ES|QL queries with test-tool before assigning to an agent.

For ES|QL tools with no parameters, still include "params": {}.