references/architecture-guide.md
# Elastic Agent Builder Architecture Guide
Elastic Agent Builder is a framework built into Elasticsearch/Kibana that creates AI agents grounded in your
Elasticsearch data. It combines LLMs with Elasticsearch's search, analytics, and relevance capabilities into a unified
platform — no separate vector database, RAG pipeline, or tool orchestrator needed.
**Docs**: [Elastic Agent Builder](https://www.elastic.co/docs/explore-analyze/ai-features/elastic-agent-builder)
## Core Concepts
### Three Building Blocks
**1. Chat UI** — A real-time conversational interface (in Kibana or via API) to interact with agents.
**2. Agents** — LLM-powered entities that follow custom instructions and use tools to answer questions, run analytics,
or drive workflows. Two flavors:
- **Built-in agents** — Pre-configured, ready to chat with your data immediately
- **Custom agents** — User-defined system prompt + curated toolset + security profile
**3. Tools** — Modular, reusable functions agents invoke to retrieve or manipulate data. Two flavors:
- **Built-in tools** (prefixed `platform.core.*`) — Ship out of the box
- **Custom tools** — ES|QL tools, index search tools, or workflow tools you define
## Built-in Tools Reference
| Tool ID | Purpose |
| ------------------------------------- | ------------------------------------------------------------------- |
| `platform.core.search` | Translates natural language into hybrid/semantic/structured queries |
| `platform.core.list_indices` | Lists available indices |
| `platform.core.get_index_mapping` | Retrieves field mappings for an index |
| `platform.core.get_document_by_id` | Fetches a specific document by ID |
| `platform.core.execute_esql` | Generates and executes ES\|QL from natural language |
| `platform.core.generate_esql` | Generates ES\|QL without executing it |
| `platform.core.index_explorer` | Selects the most relevant index from multiple candidates |
| `platform.core.create_visualization` | Creates Kibana visualizations from ES\|QL |
| `platform.core.integration_knowledge` | Retrieves knowledge from Fleet-installed integrations |
| `platform.core.product_documentation` | Searches Elastic product documentation |
`platform.core.search` is the primary context retrieval tool — it handles hybrid search automatically (lexical +
semantic via ELSER/dense vectors), selecting the right index and query type.
## Elasticsearch as a Context Engine
Agent Builder leverages Elasticsearch natively for three context engineering patterns:
### 1. Improving Context Management
- `platform.core.search` auto-selects the best index and translates natural language into optimized queries, preventing
context window overflow
- Use **index search tools** scoped to specific indices to restrict the agent's surface area and reduce noise
- Use `platform.core.index_explorer` in multi-index environments to route queries to the right data source
- Instruct agents explicitly in their system prompt to use tools rather than rely on training knowledge
### 2. Persistent Memory Layer
Elasticsearch naturally acts as long-term memory:
- **Short-term memory**: Agent Builder's built-in chat session tracks conversation history automatically
- **Long-term memory**: Store agent outputs back to Elasticsearch indices for retrieval in future sessions
- **Cross-session context**: Index tool outputs to a dedicated memory index, then give the agent an index search tool
scoped to that index to retrieve past reasoning
- Elastic Workflows can automate the write-back of outputs to memory indices
### 3. Hybrid Search for Relevance
`platform.core.search` and custom index search tools use Elasticsearch's full hybrid search stack:
- **Lexical** (BM25) for keyword precision
- **Semantic/vector** (ELSER sparse vectors or dense embeddings) for conceptual matching
- **FORK/FUSE** in ES|QL combines multiple search strategies using Reciprocal Rank Fusion (RRF)
- **Reranking** with Elastic Rerank or third-party models (Cohere, Vertex) for final relevance scoring
- Use `semantic_text` field type to enable out-of-the-box semantic search without managing embeddings manually
## Best Practices
### Tool Design
- **Write descriptive tool descriptions** — The agent decides which tool to call based solely on the description. Be
explicit about when to use each tool and include example trigger phrases.
- **Scope index search tools narrowly** — Prefer `customer-feedback-*` over `*` to reduce noise and limit token
consumption from oversized result sets.
- **Include LIMIT in every ES|QL query** — The implicit default is 1000 rows, which consumes tokens rapidly and can
trigger `context_length_exceeded` errors.
- **Validate ES|QL before deploying** — Use the "Infer parameters from query" button in Kibana UI to auto-detect
parameters and test with sample values.
- **Add `_meta.description` to index mappings** — Helps `platform.core.search` and `platform.core.index_explorer` select
the right index without calling `list_indices` first.
### Agent Prompt Design
- **Explicitly instruct tool use** — LLMs sometimes answer from training data instead of calling tools. Add: "Always use
tools to retrieve data. Never answer data questions from memory."
- **Name which tool to use for which intent** — Vague instructions lead to wrong tool selection. Be specific: "For
sentiment trends, use `feedback_sentiment_trend`. For individual feedback, use `customer_feedback_search`."
- **Instruct the agent to ask for clarification** — Prevents broad queries when a targeted tool would suffice: "If the
user's question is ambiguous about time range, ask for clarification before querying."
### Token Optimization
Token costs accumulate from conversation history, tool response payloads, and the number of tool calls per turn.
- **Replace broad built-in tools with focused custom tools** — Custom tools pre-define the query logic and scope, so the
LLM only controls parameters, not the query shape. This produces smaller, more relevant result sets.
- **Limit the toolset assigned to each agent** — Every tool in an agent's toolset is included in the system prompt as a
function definition, consuming input tokens on every call — even unused tools. Design agents with the minimum viable
toolset.
- **Use agent instructions to enforce tool discipline** — Even with a focused toolset, an agent may call tools
redundantly. Use the system prompt to create explicit call rules: "For trend questions, ALWAYS use
billing_complaint_summary. Do NOT call more than one tool per user question unless the question explicitly asks for
two things."
- **Keep tool responses small** — Use `KEEP` to return only needed columns. Prefer aggregations over raw document
retrieval for summary questions.
- **Monitor token usage** — Agent Builder displays input and output token counts after each response in the Chat UI. Use
the "View JSON" button to inspect the raw usage breakdown per tool call.
> **Docs**: [Monitor usage](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/monitor-usage)
> **Troubleshooting**:
> [Context length exceeded](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/troubleshooting/context-length-exceeded)
## Programmatic Access
Agent Builder is accessed through the Kibana Agent Builder HTTP API. In universal skills, cite endpoints with the `kbn:`
prefix (for example `GET kbn:/api/agent_builder/tools`). The [Operations](../SKILL.md#operations) section in `SKILL.md`
maps each shorthand to the `elastic kb agent-builder` CLI command.
### Key Endpoints
| Action | HTTP API (shorthand) |
| ---------------------- | ------------------------------------------------ |
| List tools | `GET kbn:/api/agent_builder/tools` |
| Create tool | `POST kbn:/api/agent_builder/tools` |
| Update tool | `PUT kbn:/api/agent_builder/tools/{toolId}` |
| Delete tool | `DELETE kbn:/api/agent_builder/tools/{toolId}` |
| Execute tool (testing) | `POST kbn:/api/agent_builder/tools/_execute` |
| List agents | `GET kbn:/api/agent_builder/agents` |
| Create agent | `POST kbn:/api/agent_builder/agents` |
| Get agent | `GET kbn:/api/agent_builder/agents/{agentId}` |
| Update agent | `PUT kbn:/api/agent_builder/agents/{agentId}` |
| Delete agent | `DELETE kbn:/api/agent_builder/agents/{agentId}` |
| Chat with agent | `POST kbn:/api/agent_builder/converse/async` |
### MCP & A2A Integration
- **MCP server**: Exposes all built-in and custom tools to any MCP client (Claude Desktop, Cursor, VS Code). Provide
your Kibana URL + API key in the client config.
- **A2A server**: Exposes agents to external agent frameworks, services, and apps — enabling reuse of your Elastic
context engineering logic across integrations.
## Permissions & Security
- Tools and agents respect Elasticsearch RBAC — the API key used scopes what data is accessible
- MCP and A2A support OAuth and custom authentication mechanisms
- Custom ES|QL tools provide guardrails by pre-defining query structure — only parameters are LLM-controlled, not query
logic
references/use-cases.md
# Elastic Agent Builder — Use Case Playbooks
---
## 1. Customer Feedback Analysis Agent
**Goal**: Analyze customer feedback, identify sentiment trends, surface policy-related mentions, and generate analytics.
**Key Tools**:
- `platform.core.search` — semantic search over feedback indices for open-ended queries
- Custom Index Search tool scoped to `customer-feedback-*` — focused retrieval
- Custom ES|QL tool for sentiment aggregations and trend analytics
### Custom Index Search Tool
`POST kbn:/api/agent_builder/tools`
```json
{
"id": "customer_feedback_search",
"type": "index_search",
"description": "Searches customer feedback, support tickets, and NPS responses. Use this to find sentiment, product complaints, praise, or policy mentions. Supports semantic and keyword search.",
"configuration": {
"pattern": "customer-feedback-*"
}
}
```
### Custom ES|QL Tool — Sentiment Trend by Product
`POST kbn:/api/agent_builder/tools`
```json
{
"id": "feedback_sentiment_trend",
"type": "esql",
"description": "Returns a breakdown of positive vs. negative feedback counts by product category over a given number of days. Use for trend analysis, not for reading individual feedback.",
"configuration": {
"query": "FROM customer-feedback-* | WHERE @timestamp >= NOW() - ?lookback_days::integer * 1d | STATS positive = COUNT(*) WHERE sentiment == \"positive\", negative = COUNT(*) WHERE sentiment == \"negative\", total = COUNT(*) 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"
}
}
}
}
```
### Custom ES|QL Tool — Policy Compliance Check
`POST kbn:/api/agent_builder/tools`
```json
{
"id": "policy_mention_search",
"type": "esql",
"description": "Counts how many feedback items mention a specific policy keyword. Use for compliance monitoring or to understand which policies generate the most customer friction.",
"configuration": {
"query": "FROM customer-feedback-* | WHERE MATCH(feedback_text, ?policy_keyword) | STATS mention_count = COUNT(*), avg_sentiment_score = AVG(sentiment_score) BY product_category | SORT mention_count DESC | LIMIT 15",
"params": {
"policy_keyword": {
"type": "string",
"description": "Policy term or keyword to search for, e.g. 'refund policy', 'cancellation', 'data privacy'"
}
}
}
}
```
### Agent Definition
`POST kbn:/api/agent_builder/agents`
```json
{
"id": "customer-feedback-agent",
"name": "Customer Feedback Analyst",
"description": "Analyzes customer sentiment, surfaces policy friction points, and provides product feedback trends.",
"configuration": {
"instructions": "You are a customer intelligence analyst. Always use tools to ground your responses in real data — do not answer from memory. For open questions about specific feedback, use customer_feedback_search. For trend analytics or policy mentions, use the ES|QL tools. When presenting findings, include counts and percentages where available.",
"tools": [
{
"tool_ids": [
"customer_feedback_search",
"feedback_sentiment_trend",
"policy_mention_search",
"platform.core.search"
]
}
]
}
}
```
---
## 2. Marketing Campaign Analysis Agent
**Goal**: Analyze campaign performance, compare results across campaigns, and join campaign metadata with outcome data
using ES|QL LOOKUP JOIN.
**Key Tools**:
- `platform.core.search` — broad semantic retrieval across marketing indices
- Custom Index Search tool scoped to campaign description indices
- Custom ES|QL tools that join campaign description + results indices
### Custom Index Search Tool — Campaign Descriptions
`POST kbn:/api/agent_builder/tools`
```json
{
"id": "campaign_description_search",
"type": "index_search",
"description": "Search marketing campaign descriptions, objectives, target audiences, and creative briefs. Use to understand what a campaign was about or find campaigns matching specific criteria.",
"configuration": {
"pattern": "marketing-campaigns-*"
}
}
```
### Custom ES|QL Tool — Campaign Performance Join
`POST kbn:/api/agent_builder/tools`
```json
{
"id": "campaign_performance_analysis",
"type": "esql",
"description": "Joins campaign descriptions with performance results to analyze ROI, conversion rates, and spend efficiency for campaigns in a given channel over a lookback period. Use when the user asks about campaign effectiveness, ROI, or performance comparisons.",
"configuration": {
"query": "FROM marketing-campaign-results-* | WHERE channel == ?channel AND @timestamp >= NOW() - ?lookback_days::integer * 1d | STATS total_spend = SUM(spend), total_conversions = SUM(conversions), total_impressions = SUM(impressions), avg_ctr = AVG(click_through_rate) BY campaign_id | LOOKUP JOIN marketing-campaigns-* ON campaign_id | EVAL roi = (total_conversions * ?revenue_per_conversion - total_spend) / total_spend * 100 | SORT roi DESC | LIMIT 10",
"params": {
"channel": {
"type": "string",
"description": "Marketing channel, e.g. 'email', 'social', 'paid_search', 'display'"
},
"lookback_days": {
"type": "integer",
"description": "Number of days to look back, e.g. 30, 90, 365"
},
"revenue_per_conversion": {
"type": "float",
"description": "Assumed revenue value per conversion for ROI calculation"
}
}
}
}
```
### Custom ES|QL Tool — Audience Segment Performance
`POST kbn:/api/agent_builder/tools`
```json
{
"id": "audience_segment_performance",
"type": "esql",
"description": "Analyzes which audience segments perform best for a given campaign. Use when the user asks about targeting effectiveness or audience insights.",
"configuration": {
"query": "FROM marketing-campaign-results-* | WHERE campaign_id == ?campaign_id | STATS conversions = SUM(conversions), spend = SUM(spend), impressions = SUM(impressions) BY audience_segment | EVAL cost_per_conversion = spend / conversions | SORT conversions DESC | LIMIT 15",
"params": {
"campaign_id": {
"type": "string",
"description": "The campaign ID to analyze"
}
}
}
}
```
### Agent Definition
`POST kbn:/api/agent_builder/agents`
```json
{
"id": "marketing-campaign-agent",
"name": "Marketing Campaign Analyst",
"description": "Analyzes marketing campaign effectiveness, compares ROI across campaigns and channels, and surfaces audience insights.",
"configuration": {
"instructions": "You are a marketing analytics expert. Always call tools for data — never answer from memory. For qualitative questions about what a campaign was about, use campaign_description_search. For performance metrics and ROI, use campaign_performance_analysis. For audience breakdowns, use audience_segment_performance. When showing results, present a concise summary with the most important metrics highlighted, then offer to drill down further.",
"tools": [
{
"tool_ids": [
"campaign_description_search",
"campaign_performance_analysis",
"audience_segment_performance",
"platform.core.search"
]
}
]
}
}
```
---
## 3. Contract Analysis Agent
**Goal**: Search a large corpus of contracts for specific clause mentions, identify non-standard terms, and surface risk
patterns using hybrid search + ES|QL analytics.
**Key Design**: Hybrid search finds contracts with relevant clauses (using semantic + lexical matching). ES|QL tools
then extract and analyze specific term patterns across the corpus.
### Custom Index Search Tool — Contract Hybrid Search
`POST kbn:/api/agent_builder/tools`
```json
{
"id": "contract_search",
"type": "index_search",
"description": "Searches the full contract corpus using hybrid search (semantic + keyword). Use to find contracts mentioning specific clauses, obligations, parties, or terms.",
"configuration": {
"pattern": "contracts-*"
}
}
```
### Custom ES|QL Tool — Clause Frequency Analysis
`POST kbn:/api/agent_builder/tools`
```json
{
"id": "clause_frequency_analysis",
"type": "esql",
"description": "Counts how many contracts contain a specific clause or term keyword, grouped by contract type or counterparty category. Use for corpus-wide analysis of how common a clause is.",
"configuration": {
"query": "FROM contracts-* | WHERE MATCH(contract_text, ?clause_keyword) | STATS contract_count = COUNT(*), counterparty_types = COUNT_DISTINCT(counterparty_category) BY contract_type | SORT contract_count DESC | LIMIT 20",
"params": {
"clause_keyword": {
"type": "string",
"description": "Clause or term to search for, e.g. 'limitation of liability', 'force majeure', 'auto-renewal'"
}
}
}
}
```
### Custom ES|QL Tool — Liability Cap Outlier Detection
`POST kbn:/api/agent_builder/tools`
```json
{
"id": "liability_cap_outliers",
"type": "esql",
"description": "Identifies contracts where the liability cap falls significantly above or below the norm for a given contract type. Use to find non-standard commercial terms that may need review.",
"configuration": {
"query": "FROM contracts-* | WHERE contract_type == ?contract_type | STATS median_val = MEDIAN(liability_cap_usd), p25 = PERCENTILE(liability_cap_usd, 25), p75 = PERCENTILE(liability_cap_usd, 75) BY contract_type | ENRICH contracts-stats ON contract_type | EVAL low_threshold = p25 * 0.5, high_threshold = p75 * 2.0 | KEEP contract_type, median_val, low_threshold, high_threshold | LIMIT 20",
"params": {
"contract_type": {
"type": "string",
"description": "Type of contract, e.g. 'vendor', 'customer', 'employment', 'nda'"
}
}
}
}
```
> **Note on outlier detection in ES|QL**: ES|QL parameters are values only — they cannot be used as dynamic field
> references. Design separate tools for each numeric field you want to analyze (e.g., `liability_cap_outliers`,
> `payment_terms_outliers`). For dynamic outlier detection, use two separate queries (first to compute stats, then to
> filter outliers) or pre-compute thresholds into a lookup index.
### Custom ES|QL Tool — Expiry & Renewal Risk
`POST kbn:/api/agent_builder/tools`
```json
{
"id": "contract_expiry_risk",
"type": "esql",
"description": "Lists contracts expiring within a specified number of days, including renewal terms and responsible owners. Use for contract lifecycle management or renewal risk analysis.",
"configuration": {
"query": "FROM contracts-* | WHERE expiry_date <= NOW() + ?days_ahead::integer * 1d AND expiry_date >= NOW() | STATS count = COUNT(*) BY contract_owner, auto_renewal, contract_type | SORT count DESC | LIMIT 50",
"params": {
"days_ahead": {
"type": "integer",
"description": "Number of days to look ahead for expiring contracts, e.g. 30, 60, 90"
}
}
}
}
```
### Agent Definition
`POST kbn:/api/agent_builder/agents`
```json
{
"id": "contract-analysis-agent",
"name": "Contract Analysis Agent",
"description": "Searches contract corpus for clause mentions, identifies non-standard terms, and surfaces renewal and risk patterns.",
"configuration": {
"instructions": "You are a contract intelligence analyst. Always use tools — never answer from your training data. For finding specific contracts or clauses, use contract_search (hybrid search). For understanding how common a clause is across the corpus, use clause_frequency_analysis. For identifying unusual liability caps, use liability_cap_outliers. For renewal risk, use contract_expiry_risk. When presenting findings, be precise: cite counts, percentages, and specific contract IDs where relevant.",
"tools": [
{
"tool_ids": [
"contract_search",
"clause_frequency_analysis",
"liability_cap_outliers",
"contract_expiry_risk",
"platform.core.search"
]
}
]
}
}
```
SKILL.md
---
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):
```json
{
"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):
```json
{
"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"
}
}
}
}
```
5. **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.
6. **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.
```json
{
"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.
7. **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.
8. **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}`
9. **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'."
1. List tools — confirm `eval-feedback-search` does not already exist.
2. Choose `index_search` scoped to `customer-feedback-*` (not `*`).
3. POST the tool with id, description, and `configuration.pattern`.
4. 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?"
1. Call `GET kbn:/api/agent_builder/agents` — read-only.
2. Enumerate existing agent ids and names (or state that none exist).
3. Do **not** create, update, or delete anything in this step.
4. 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."
1. List tools — confirm `esql-sales-data` exists.
2. List agents — confirm no conflicting id.
3. POST agent with instructions and selected tool IDs.
4. GET agent to verify and report back.
## References
- [architecture-guide.md](references/architecture-guide.md) — Built-in tools, context engineering, token optimization,
MCP/A2A integration, permissions
- [use-cases.md](references/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>'` |