kibana-agent-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Manage Agent Builder Agents and Tools in Kibana

在Kibana中管理Agent Builder代理与工具

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.

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

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

KIBANA_USERNAME

KIBANA_PASSWORD

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

变量名称	是否必填	描述
`KIBANA_URL`	是	Kibana基础URL（例如： `https://my-deployment.kb.us-east-1.aws.elastic.cloud` ）
`KIBANA_API_KEY`	否	用于身份验证的API密钥（推荐使用）
`KIBANA_USERNAME`	否	基础认证的用户名（默认使用 `ELASTICSEARCH_USERNAME` ）
`KIBANA_PASSWORD`	否	基础认证的密码（默认使用 `ELASTICSEARCH_PASSWORD` ）
`KIBANA_SPACE_ID`	否	Kibana空间ID（默认空间可省略）
`KIBANA_INSECURE`	否	设置为 `true` 可跳过TLS验证

需提供

KIBANA_API_KEY

或

KIBANA_USERNAME

KIBANA_PASSWORD

其中一组。

Agent Management

代理管理

Create an Agent

创建代理

Step 1: List available tools

步骤1：列出可用工具

bash

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.

bash

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

如果脚本报告连接错误，请停止操作并告知用户验证其

KIBANA_URL

和身份验证环境变量。

查看可用工具列表。前缀为

platform.core.

的工具是内置工具，其他工具为自定义或连接器提供的工具。

Step 2: List existing agents

步骤2：列出已有代理

bash

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

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

bash

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

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

Step 3: Gather agent details

步骤3：收集代理详情

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.

默认使用

$ARGUMENTS

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

名称（必填）—— 代理的显示名称。默认值：
```
$ARGUMENTS
```
。
描述（可选）—— 代理功能的简要说明。默认值与名称相同。
系统指令（可选）—— 代理的自定义系统提示词。默认值：无。

Step 4: Select tools

步骤4：选择工具

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.

展示步骤1中的可用工具，询问用户要包含哪些工具。根据代理用途建议合理的默认工具列表，允许用户添加或移除工具。

Step 5: Create the agent

步骤5：创建代理

bash

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

bash

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
```
若用户未提供可省略

Step 6: Verify creation

步骤6：验证创建结果

bash

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.

bash

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

向用户展示新创建的代理条目。如果条目存在，则报告创建成功；如果不存在，则展示步骤5中的错误输出。

Get an Agent

获取代理信息

bash

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

bash

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

Update an Agent

更新代理

bash

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.

bash

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错误。

Delete an Agent

删除代理

bash

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

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

bash

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

删除前务必与用户确认，删除操作不可恢复。

Chat with an Agent

与代理对话

bash

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.

bash

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

。当事件到达时，输出会显示

[Reasoning]

、

[Tool Call]

、

[Tool Result]

和

[Response]

。传递

--conversation-id

可继续现有对话。

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

Tool Management

工具管理

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

自定义工具可扩展代理的功能，超出平台内置工具的范围。

Tool Types

工具类型

ES|QL Tools

ES|QL工具

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

json

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

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

参数语法：在查询中使用

?param_name

。仅需为每个参数定义

type

和

description

。有效类型包括：

string

、

integer

、

float

、

boolean

、

date

、

array

。

json

{
  "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.

json

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

将内置搜索能力限定在特定索引模式下。LLM会决定查询方式，而您可以控制可访问的索引。

json

{
  "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).

json

{
  "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.

将代理与Elastic Workflow（YAML定义的多步骤自动化流程）连接。适用于代理需要执行数据检索之外的操作（发送通知、创建工单、调用外部API）的场景。

json

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

参数会从工作流的

inputs

部分自动检测。

Tool API Constraints

工具API限制

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.
```
default
```
and
```
optional
```
are not valid and cause 400 errors. Hard-code sensible defaults in the query instead.
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.

创建工具前请阅读以下内容——违反限制会导致400错误。

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

Tool Script Commands

工具脚本命令

List all tools

列出所有工具

bash

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

bash

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

Get a specific tool

获取特定工具信息

bash

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

bash

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

Create a tool

创建工具

bash

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:

bash

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:

bash

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

bash

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

对于索引搜索工具：

bash

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

对于工作流工具：

bash

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

更新工具

bash

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.

bash

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

不可修改。

Delete a tool

删除工具

bash

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

bash

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

Test a tool

测试工具

bash

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.

bash

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结果的列名和行数。

Examples

示例

Create an agent

创建代理

text

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

text

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"

验证——代理出现在列表中

Update an agent's instructions

更新代理指令

text

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

text

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"
```
确认新指令已生效

Chat with an agent

与代理对话

text

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

text

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

对话——运行

chat --id "sales-helper" --message "What are the top revenue products?"

显示代理的回复

Create an ES|QL tool with parameters

创建带参数的ES|QL工具

text

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:

bash

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

text

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

参考
```
elasticsearch-esql
```
技能获取ES|QL语法

创建工具：

bash

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

Create an index search tool

创建索引搜索工具

text

User: Create a tool to search support transcripts

bash

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"

text

User: Create a tool to search support transcripts

bash

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.

以下资料提供详细指导：

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

如需ES|QL语法、函数、运算符和参数规则，请使用

elasticsearch-esql

技能。如需工作流YAML结构、触发器类型、步骤类型和代理-工作流模式，请使用

security-workflows

技能。

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
```
*
```
).
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": {}
```
.

创建代理前始终运行
```
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": {}
```
。