kibana-agent-builder

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:

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:

1. Name (required) — The agent's display name. Default: $ARGUMENTS.
2. Description (optional) — Brief description of what the agent does. Default: same as name.
3. 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 \

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

Update an Agent

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

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

Chat with an Agent

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.

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.

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

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

Tool Script Commands

List all tools

Get a specific tool

Create a tool

For index search tools:

For workflow tools:

Update a tool

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

Delete a tool

Test a tool

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

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

Update an agent's instructions

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

Chat with an agent

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

Create an ES|QL tool with parameters

1. Consult the elasticsearch-esql skill for ES|QL syntax

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

3. 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 kibana-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 *).
• 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": {}.