Kibana Agent Builder
Create, inspect, update, delete, and test Agent Builder tools and agents. Ground LLM responses in Elasticsearch
data through scoped search tools, parameterized ES|QL, and workflow integrations.
Environment Configuration
This skill executes Elasticsearch operations through the elastic CLI. If the
elastic CLI is not installed, tell the user what it is needed for. Do
not guess credentials, call the HTTP API directly, or attempt other workarounds.
This skill references operations in HTTP-shorthand form (e.g., GET /, GET /_cat/indices, GET /{index}/_mapping,
GET /{index}/_settings/index.mode, POST /_query). The Operations table at the end of this document
maps each shorthand to the equivalent elastic CLI command — always use the CLI rather than calling the HTTP API
directly.
Resource model
Agent Builder exposes three distinct resource kinds — do not conflate them:
| Kind |
Purpose |
Typical API |
| Tool |
Reusable function an agent invokes to retrieve or act on data (index_search, esql, workflow) |
POST kbn:/api/agent_builder/tools |
| Agent |
LLM entity with instructions and a curated toolset |
POST kbn:/api/agent_builder/agents |
| Chat / conversation |
Ephemeral messaging session with an existing agent |
POST kbn:/api/agent_builder/converse/async |
Creating a tool does not create an agent. Listing or chatting with an agent does not create a tool. When the
user asks to "create an agent" or "create a tool," identify which resource they mean before calling a write API.
Built-in tools use the platform.core.* prefix (for example platform.core.search). Custom tools and agents are
user-defined. Read architecture-guide.md for built-in tool inventory, context
engineering, and security notes.
Process
Classify the task. Decide whether the user needs a tool, an agent, or chat with an existing agent. If
they ask what already exists ("what agents are there?", "list agents"), treat the request as read-only discovery
— answer from live data before proposing any create, update, or delete.
Discover existing resources before any write. When creating or updating:
- Call
GET kbn:/api/agent_builder/tools to list available tools (built-in and custom). Do not invent tool IDs.
- Call
GET kbn:/api/agent_builder/agents to list existing agents and avoid duplicate IDs or names.
When the user only asks what agents exist, stop after GET kbn:/api/agent_builder/agents. Enumerate each agent's id
and name. If the list is empty, say so plainly — do not fabricate agents. Only proceed to creation when the user
explicitly asks to create one and you have confirmed the target id is unused.
Choose the tool type (for tool tasks). Match intent to the narrowest tool type:
- Open-ended search over a known index pattern →
index_search with a specific pattern (for example
customer-feedback-*), never * or all-indices scope unless the user explicitly requires it.
- Fixed analytics, aggregations, or parameterized queries →
esql with ?param placeholders and a params
object (use {} when there are no parameters).
- Multi-step automation beyond retrieval →
workflow referencing an existing workflow id.
For ES|QL syntax and query design, follow the elasticsearch-esql skill. For workflow YAML, follow the
kibana-workflows skill.
Build the tool payload. Required fields: id, type, description, configuration. Optional: tags.
API constraints (violations return 400):
- POST accepts only
id, type, description, configuration, tags. name is not valid on tools.
- Index search configuration uses
"pattern", not "index".
- ES|QL tools require
"params" even when empty: "params": {}.
- Each param accepts only
type and description — not default or optional. Hard-code defaults in the query.
- PUT on tools accepts only
description, configuration, and tags. id and type are immutable.
Index search example (scoped pattern):
{
"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 example (parameterized, with 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"
}
}
}
}
Create and verify the tool. Call POST kbn:/api/agent_builder/tools with the payload. Confirm success by calling
GET kbn:/api/agent_builder/tools/{toolId} and reporting the created id, type, description, and configuration back
to the user — do not claim success without a live API response.
Optionally validate ES|QL tools with POST kbn:/api/agent_builder/tools/_execute, passing tool_id and
tool_params. Always include | LIMIT N in ES|QL queries to control token use.
Build the agent payload (for agent tasks). Required fields: id, name, description, configuration.
Configuration must include instructions and a tools array with tool_ids drawn from Step 2 — only IDs returned
by GET kbn:/api/agent_builder/tools.
Derive a stable id from the name (lowercase, hyphens, alphanumeric). Check Step 2's agent list for conflicts before
posting.
{
"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 update constraints: PUT accepts only description, configuration, and tags (plus avatar/labels when
applicable). Do not send immutable fields like id, name, or type on update — they cause 400 errors.
Create and verify the agent. Call POST kbn:/api/agent_builder/agents. Confirm with
GET kbn:/api/agent_builder/agents or GET kbn:/api/agent_builder/agents/{agentId}. Report the live response.
Update or delete (when requested). Confirm destructive actions with the user first.
- Update tool:
PUT kbn:/api/agent_builder/tools/{toolId}
- Delete tool:
DELETE kbn:/api/agent_builder/tools/{toolId}
- Update agent:
PUT kbn:/api/agent_builder/agents/{agentId}
- Delete agent:
DELETE kbn:/api/agent_builder/agents/{agentId}
Chat (when requested). Chat is not agent or tool creation. Use POST kbn:/api/agent_builder/converse/async with
an existing agent_id and user input. Expect multi-step reasoning and tool calls; allow sufficient time for
streaming completion.
Guidelines
- Discover before create. Always list agents (and tools when relevant) before creating resources. When asked "what
agents exist?", answer that question first — read-only — even if the user also mentions wanting a new agent later.
- Scope index search narrowly. Prefer
customer-feedback-* over *. Broad patterns increase noise, token cost, and
RBAC surface area.
- Write descriptive tool descriptions. The agent selects tools based on descriptions alone — include when to use
each tool and example trigger phrases.
- Minimize toolsets. Every assigned tool adds tokens to the agent system prompt on every turn.
- Validate ES|QL before deployment. Execute the tool after creation when parameters or query shape are non-trivial.
- Use aggregations and KEEP. Prefer summary stats over raw document dumps for analytics questions.
Examples
Create an index search tool (eval pattern)
User: "Create a custom Agent Builder tool that searches the customer-feedback-* index. Use the tool id
'eval-feedback-search'."
- List tools — confirm
eval-feedback-search does not already exist.
- Choose
index_search scoped to customer-feedback-* (not *).
- POST the tool with id, description, and
configuration.pattern.
- GET the tool by id and confirm creation to the user.
Answer "what agents already exist?" before creating
User: "I want to create a new agent in Kibana Agent Builder. What agents already exist?"
- Call
GET kbn:/api/agent_builder/agents — read-only.
- Enumerate existing agent ids and names (or state that none exist).
- Do not create, update, or delete anything in this step.
- Only if the user then asks to create, pick an unused id informed by the list above.
Create an agent after discovery
User: "Create a sales-helper agent using the esql-sales-data tool."
- List tools — confirm
esql-sales-data exists.
- List agents — confirm no conflicting id.
- POST agent with instructions and selected tool IDs.
- GET agent to verify and report back.
References
- architecture-guide.md — Built-in tools, context engineering, token optimization,
MCP/A2A integration, permissions
- use-cases.md — Playbooks for customer feedback, marketing campaign, and contract analysis
agents with example tool and agent payloads
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>' |
1---
2name: kibana-agent-builder
3description: >
4 Create and manage Kibana Agent Builder agents and custom tools. Use when asked to
5 create, update, delete, test, or inspect agents or tools in Agent Builder, or when
6 the user wants to understand what agents or tools already exist.
7metadata:
8 source: https://skillmd.com/skills/elastic/kibana-agent-builder
9 author: elastic
10 version: 0.3.0
11 universal: true
12---
13
14# Kibana Agent Builder
15
16Create, inspect, update, delete, and test Agent Builder **tools** and **agents**. Ground LLM responses in Elasticsearch
17data through scoped search tools, parameterized ES|QL, and workflow integrations.
18
19<!-- begin-partial: preamble -->
20
21## Environment Configuration
22
23This skill executes Elasticsearch operations through the `elastic` CLI. If the
24[`elastic` CLI](https://github.com/elastic/cli#configuration) is not installed, tell the user what it is needed for. Do
25not guess credentials, call the HTTP API directly, or attempt other workarounds.
26
27This skill references operations in HTTP-shorthand form (e.g., `GET /`, `GET /_cat/indices`, `GET /{index}/_mapping`,
28`GET /{index}/_settings/index.mode`, `POST /_query`). The [Operations](#operations) table at the end of this document
29maps each shorthand to the equivalent `elastic` CLI command — always use the CLI rather than calling the HTTP API
30directly.
31
32<!-- end-partial: preamble -->
33
34## Resource model
35
36Agent Builder exposes three distinct resource kinds — do not conflate them:
37
38| Kind | Purpose | Typical API |
39| ----------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------- |
40| **Tool** | Reusable function an agent invokes to retrieve or act on data (`index_search`, `esql`, `workflow`) | `POST kbn:/api/agent_builder/tools` |
41| **Agent** | LLM entity with instructions and a curated toolset | `POST kbn:/api/agent_builder/agents` |
42| **Chat / conversation** | Ephemeral messaging session with an existing agent | `POST kbn:/api/agent_builder/converse/async` |
43
44Creating a tool does **not** create an agent. Listing or chatting with an agent does **not** create a tool. When the
45user asks to "create an agent" or "create a tool," identify which resource they mean before calling a write API.
46
47Built-in tools use the `platform.core.*` prefix (for example `platform.core.search`). Custom tools and agents are
48user-defined. Read [architecture-guide.md](references/architecture-guide.md) for built-in tool inventory, context
49engineering, and security notes.
50
51## Process
52
531. **Classify the task.** Decide whether the user needs a **tool**, an **agent**, or **chat** with an existing agent. If
54 they ask what already exists ("what agents are there?", "list agents"), treat the request as **read-only discovery**
55 — answer from live data before proposing any create, update, or delete.
56
572. **Discover existing resources before any write.** When creating or updating:
58 - Call `GET kbn:/api/agent_builder/tools` to list available tools (built-in and custom). Do not invent tool IDs.
59 - Call `GET kbn:/api/agent_builder/agents` to list existing agents and avoid duplicate IDs or names.
60
61 When the user only asks what agents exist, stop after `GET kbn:/api/agent_builder/agents`. Enumerate each agent's id
62 and name. If the list is empty, say so plainly — do not fabricate agents. Only proceed to creation when the user
63 explicitly asks to create one and you have confirmed the target id is unused.
64
653. **Choose the tool type (for tool tasks).** Match intent to the narrowest tool type:
66 - **Open-ended search over a known index pattern** → `index_search` with a **specific pattern** (for example
67 `customer-feedback-*`), never `*` or all-indices scope unless the user explicitly requires it.
68 - **Fixed analytics, aggregations, or parameterized queries** → `esql` with `?param` placeholders and a `params`
69 object (use `{}` when there are no parameters).
70 - **Multi-step automation beyond retrieval** → `workflow` referencing an existing workflow id.
71
72 For ES|QL syntax and query design, follow the `elasticsearch-esql` skill. For workflow YAML, follow the
73 `kibana-workflows` skill.
74
754. **Build the tool payload.** Required fields: `id`, `type`, `description`, `configuration`. Optional: `tags`.
76
77 **API constraints** (violations return 400):
78 - POST accepts only `id`, `type`, `description`, `configuration`, `tags`. **`name` is not valid** on tools.
79 - Index search configuration uses `"pattern"`, **not** `"index"`.
80 - ES|QL tools require `"params"` even when empty: `"params": {}`.
81 - Each param accepts only `type` and `description` — not `default` or `optional`. Hard-code defaults in the query.
82 - PUT on tools accepts only `description`, `configuration`, and `tags`. `id` and `type` are immutable.
83
84 **Index search example** (scoped pattern):
85
86 ```json
87 {
88 "id": "customer_feedback_search",
89 "type": "index_search",
90 "description": "Searches customer feedback and support tickets in the customer-feedback indices.",
91 "configuration": {
92 "pattern": "customer-feedback-*"
93 }
94 }
95 ```
96
97 **ES|QL example** (parameterized, with LIMIT):
98
99 ```json
100 {
101 "id": "feedback_sentiment_trend",
102 "type": "esql",
103 "description": "Returns positive vs negative feedback counts by product category over a lookback window.",
104 "configuration": {
105 "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",
106 "params": {
107 "lookback_days": {
108 "type": "integer",
109 "description": "Number of days to look back, e.g. 7, 30, 90"
110 }
111 }
112 }
113 }
114 ```
115
1165. **Create and verify the tool.** Call `POST kbn:/api/agent_builder/tools` with the payload. Confirm success by calling
117 `GET kbn:/api/agent_builder/tools/{toolId}` and reporting the created id, type, description, and configuration back
118 to the user — do not claim success without a live API response.
119
120 Optionally validate ES|QL tools with `POST kbn:/api/agent_builder/tools/_execute`, passing `tool_id` and
121 `tool_params`. Always include `| LIMIT N` in ES|QL queries to control token use.
122
1236. **Build the agent payload (for agent tasks).** Required fields: `id`, `name`, `description`, `configuration`.
124 Configuration must include `instructions` and a `tools` array with `tool_ids` drawn from Step 2 — only IDs returned
125 by `GET kbn:/api/agent_builder/tools`.
126
127 Derive a stable `id` from the name (lowercase, hyphens, alphanumeric). Check Step 2's agent list for conflicts before
128 posting.
129
130 ```json
131 {
132 "id": "customer-feedback-agent",
133 "name": "Customer Feedback Analyst",
134 "description": "Analyzes customer sentiment and feedback trends.",
135 "configuration": {
136 "instructions": "Always use tools to retrieve data. Never answer data questions from memory.",
137 "tools": [
138 {
139 "tool_ids": ["customer_feedback_search", "platform.core.search"]
140 }
141 ]
142 }
143 }
144 ```
145
146 **Agent update constraints:** PUT accepts only `description`, `configuration`, and `tags` (plus avatar/labels when
147 applicable). Do not send immutable fields like `id`, `name`, or `type` on update — they cause 400 errors.
148
1497. **Create and verify the agent.** Call `POST kbn:/api/agent_builder/agents`. Confirm with
150 `GET kbn:/api/agent_builder/agents` or `GET kbn:/api/agent_builder/agents/{agentId}`. Report the live response.
151
1528. **Update or delete (when requested).** Confirm destructive actions with the user first.
153 - Update tool: `PUT kbn:/api/agent_builder/tools/{toolId}`
154 - Delete tool: `DELETE kbn:/api/agent_builder/tools/{toolId}`
155 - Update agent: `PUT kbn:/api/agent_builder/agents/{agentId}`
156 - Delete agent: `DELETE kbn:/api/agent_builder/agents/{agentId}`
157
1589. **Chat (when requested).** Chat is not agent or tool creation. Use `POST kbn:/api/agent_builder/converse/async` with
159 an existing `agent_id` and user input. Expect multi-step reasoning and tool calls; allow sufficient time for
160 streaming completion.
161
162## Guidelines
163
164- **Discover before create.** Always list agents (and tools when relevant) before creating resources. When asked "what
165 agents exist?", answer that question first — read-only — even if the user also mentions wanting a new agent later.
166- **Scope index search narrowly.** Prefer `customer-feedback-*` over `*`. Broad patterns increase noise, token cost, and
167 RBAC surface area.
168- **Write descriptive tool descriptions.** The agent selects tools based on descriptions alone — include when to use
169 each tool and example trigger phrases.
170- **Minimize toolsets.** Every assigned tool adds tokens to the agent system prompt on every turn.
171- **Validate ES|QL before deployment.** Execute the tool after creation when parameters or query shape are non-trivial.
172- **Use aggregations and KEEP.** Prefer summary stats over raw document dumps for analytics questions.
173
174## Examples
175
176### Create an index search tool (eval pattern)
177
178User: "Create a custom Agent Builder tool that searches the customer-feedback-\* index. Use the tool id
179'eval-feedback-search'."
180
1811. List tools — confirm `eval-feedback-search` does not already exist.
1822. Choose `index_search` scoped to `customer-feedback-*` (not `*`).
1833. POST the tool with id, description, and `configuration.pattern`.
1844. GET the tool by id and confirm creation to the user.
185
186### Answer "what agents already exist?" before creating
187
188User: "I want to create a new agent in Kibana Agent Builder. What agents already exist?"
189
1901. Call `GET kbn:/api/agent_builder/agents` — read-only.
1912. Enumerate existing agent ids and names (or state that none exist).
1923. Do **not** create, update, or delete anything in this step.
1934. Only if the user then asks to create, pick an unused id informed by the list above.
194
195### Create an agent after discovery
196
197User: "Create a sales-helper agent using the esql-sales-data tool."
198
1991. List tools — confirm `esql-sales-data` exists.
2002. List agents — confirm no conflicting id.
2013. POST agent with instructions and selected tool IDs.
2024. GET agent to verify and report back.
203
204## References
205
206- [architecture-guide.md](references/architecture-guide.md) — Built-in tools, context engineering, token optimization,
207 MCP/A2A integration, permissions
208- [use-cases.md](references/use-cases.md) — Playbooks for customer feedback, marketing campaign, and contract analysis
209 agents with example tool and agent payloads
210
211## Operations
212
213| HTTP API (shorthand) | `elastic` CLI command |
214| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
215| `GET kbn:/api/agent_builder/tools` | `elastic kb agent-builder get-agent-builder-tools` |
216| `POST kbn:/api/agent_builder/tools` | `elastic kb agent-builder post-agent-builder-tools --id '<id>' --type '<type>' --description '<desc>' --configuration '<json>'` |
217| `GET kbn:/api/agent_builder/tools/{toolId}` | `elastic kb agent-builder get-agent-builder-tools-toolid --tool-id '<toolId>'` |
218| `PUT kbn:/api/agent_builder/tools/{toolId}` | `elastic kb agent-builder put-agent-builder-tools-toolid --tool-id '<toolId>' [--description '<desc>'] [--configuration '<json>']` |
219| `DELETE kbn:/api/agent_builder/tools/{toolId}` | `elastic kb agent-builder delete-agent-builder-tools-toolid --tool-id '<toolId>' [--force]` |
220| `POST kbn:/api/agent_builder/tools/_execute` | `elastic kb agent-builder post-agent-builder-tools-execute --tool-id '<toolId>' --tool-params '<json>'` |
221| `GET kbn:/api/agent_builder/agents` | `elastic kb agent-builder get-agent-builder-agents` |
222| `POST kbn:/api/agent_builder/agents` | `elastic kb agent-builder post-agent-builder-agents --id '<id>' --name '<name>' --description '<desc>' --configuration '<json>'` |
223| `GET kbn:/api/agent_builder/agents/{agentId}` | `elastic kb agent-builder get-agent-builder-agents-id --id '<agentId>'` |
224| `PUT kbn:/api/agent_builder/agents/{agentId}` | `elastic kb agent-builder put-agent-builder-agents-id --id '<agentId>' [--description '<desc>'] [--configuration '<json>']` |
225| `DELETE kbn:/api/agent_builder/agents/{agentId}` | `elastic kb agent-builder delete-agent-builder-agents-id --id '<agentId>'` |
226| `POST kbn:/api/agent_builder/converse/async` | `elastic kb agent-builder post-agent-builder-converse-async --agent-id '<agentId>' --input '<message>'` |