/kibana-agent-builder

name: kibana-agent-builder
description: >
  Create and manage Kibana Agent Builder agents and custom tools. Use when asked to
  create, update, delete, test, or inspect agents or tools in Agent Builder, or when
  the user wants to understand what agents or tools already exist.
metadata:
  author: elastic
  version: 0.3.0
  universal: true

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.

<!-- begin-partial: preamble -->

Environment Configuration

This skill executes Elasticsearch operations through the `elastic` CLI. If the [`elastic` CLI](https://github.com/elastic/cli#configuration) 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](#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.

<!-- end-partial: preamble -->

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](references/architecture-guide.md) for built-in tool inventory, context engineering, and security notes.

Process

1. **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.

2. **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.

3. **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.

4. **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",