Agent Builder is a set of AI-powered capabilities for developing and interacting with agents that work with your Elasticsearch data. Most users will probably want to integrate with Agent Builder using MCP or A2A, but you can also work programmatically with tools, agents, and conversations using these Kibana APIs. **Elastic Agent Builder requires an Enterprise subscription.**
openapi: 3.0.3
info:
contact:
name: Kibana Team
description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
The API calls are stateless.
Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the
request.
API requests return JSON output, which is a format that is machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- PATCH: Applies partial modifications to the existing information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.
For example:
```
GET kbn:/api/data_views
```
For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).
NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.
## Documentation source and versions
This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.
It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
This documentation contains work-in-progress information for future Elastic Stack releases.
'
title: Kibana APIs Actions agent builder API
version: ''
x-doc-license:
name: Attribution-NonCommercial-NoDerivatives 4.0 International
url: https://creativecommons.org/licenses/by-nc-nd/4.0/
x-feedbackLink:
label: Feedback
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
variables:
kibana_url:
default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- name: agent builder
description: 'Agent Builder is a set of AI-powered capabilities for developing and interacting with agents that work with your Elasticsearch data.
Most users will probably want to integrate with Agent Builder using MCP or A2A, but you can also work programmatically with tools, agents, and conversations using these Kibana APIs.
**Elastic Agent Builder requires an Enterprise subscription.**
'
externalDocs:
description: Agent Builder docs
url: https://www.elastic.co/docs/solutions/search/agent-builder/programmatic-access
x-displayName: Agent Builder
paths:
/api/agent_builder/a2a/{agentId}:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/agent_builder/a2a/{agentId}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
> warn
> This endpoint is designed for A2A protocol clients and should not be used directly via REST APIs. Use an A2A SDK or A2A Inspector instead.<br/><br/>[Required authorization] Route required privileges: agentBuilder:read.'
operationId: post-agent-builder-a2a-agentid
parameters:
- description: The unique identifier of the agent to send the A2A task to.
in: path
name: agentId
required: true
schema:
type: string
requestBody:
content:
application/json:
examples:
a2aTaskRequestExample:
description: 'WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with A2A using an A2A SDK or A2A Inspector instead.'
value:
id: task-123
jsonrpc: '2.0'
method: complete
params:
messages:
- content: Hello from A2A protocol
role: user
schema: {}
responses:
'200':
content:
application/json:
examples:
a2aTaskResponseExample:
description: Example response from A2A Task Endpoint with results of task execution
value:
id: task-123
jsonrpc: '2.0'
result:
conversation_id: conv-456
response:
message: Hello! How can I help you today?
type: response
description: Indicates a successful response
summary: Send A2A task
tags:
- agent builder
x-state: Technical Preview; added in 9.2.0
x-metaTags:
- content: Kibana
name: product_name
/api/agent_builder/a2a/{agentId}.json:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/agent_builder/a2a/{agentId}.json</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get agent discovery metadata in JSON format. Use this endpoint to provide agent information for A2A protocol integration and discovery.<br/><br/>[Required authorization] Route required privileges: agentBuilder:read.'
operationId: get-agent-builder-a2a-agentid.json
parameters:
- description: The unique identifier of the agent to get A2A metadata for.
in: path
name: agentId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
a2aAgentCardResponseExample:
description: Example response card of Elastic AI Agent
value:
capabilities:
pushNotifications: false
stateTransitionHistory: false
streaming: false
defaultInputModes:
- text/plain
defaultOutputModes:
- text/plain
description: Elastic AI Agent
name: Elastic AI Agent
protocolVersion: 0.3.0
provider:
organization: Elastic
url: https://elastic.co
securitySchemes:
authorization:
description: Authentication token
in: header
name: Authorization
type: apiKey
skills:
- description: A powerful tool for searching and analyzing data within your Elasticsearch cluster.
examples: []
id: platform.core.search
inputModes:
- text/plain
- application/json
name: platform.core.search
outputModes:
- text/plain
- application/json
tags:
- tool
supportsAuthenticatedExtendedCard: false
url: http://localhost:5601/api/agent_builder/a2a/elastic-ai-agent
version: 0.1.0
description: Indicates a successful response
summary: Get A2A agent card
tags:
- agent builder
x-codeSamples:
- lang: curl
source: "curl \\\n -X GET \"${KIBANA_URL}/api/agent_builder/a2a/{agentId}.json\" \\\n -H \"Authorization: ApiKey ${API_KEY}\"\n"
- lang: Console
source: 'GET kbn://api/agent_builder/a2a/{agentId}.json
'
x-state: Technical Preview; added in 9.2.0
x-metaTags:
- content: Kibana
name: product_name
/api/agent_builder/agents:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/agent_builder/agents</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
List all available agents. Use this endpoint to retrieve complete agent information including their current configuration and assigned tools. To learn more, refer to the [agents documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/agent-builder-agents).<br/><br/>[Required authorization] Route required privileges: agentBuilder:read.'
operationId: get-agent-builder-agents
parameters: []
responses:
'200':
content:
application/json:
examples:
listAgentsResponseExample:
description: Example response that returns one built-in Elastic agent and one created by the user
value:
results:
- configuration:
tools:
- tool_ids:
- platform.core.search
- platform.core.list_indices
- platform.core.get_index_mapping
- platform.core.get_document_by_id
description: Elastic AI Agent
id: elastic-ai-agent
name: Elastic AI Agent
type: chat
- avatar_color: '#BFDBFF'
avatar_symbol: SI
configuration:
instructions: You are a custom agent that wants to help searching data using all indices starting with prefix "content-".
tools:
- tool_ids:
- platform.core.search
- platform.core.list_indices
- platform.core.get_index_mapping
- platform.core.get_document_by_id
description: Hi! I can help you search the data within the indices starting with "content-" prefix.
id: created-agent-id
labels:
- custom-indices
- department-search
name: Search Index Helper
type: chat
description: Indicates a successful response
summary: List agents
tags:
- agent builder
x-codeSamples:
- lang: curl
source: "curl \\\n -X GET \"${KIBANA_URL}/api/agent_builder/agents\" \\\n -H \"Authorization: ApiKey ${API_KEY}\"\n"
- lang: Console
source: 'GET kbn://api/agent_builder/agents
'
x-state: Added in 9.2.0
x-metaTags:
- content: Kibana
name: product_name
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/agent_builder/agents</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Create a new agent. Use this endpoint to define the agent''s behavior, appearance, and capabilities through comprehensive configuration options. To learn more, refer to the [agents documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/agent-builder-agents).<br/><br/>[Required authorization] Route required privileges: agentBuilder:manageAgents.'
operationId: post-agent-builder-agents
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
createAgentRequestExample:
description: Example request for creating a custom agent with special prompt and tools
value:
avatar_color: '#BFDBFF'
avatar_symbol: SI
configuration:
instructions: You are a custom agent that wants to help searching data using all indices starting with prefix "content-".
tools:
- tool_ids:
- platform.core.search
- platform.core.list_indices
- platform.core.get_index_mapping
- platform.core.get_document_by_id
description: Hi! I can help you search the data within the indices starting with "content-" prefix.
id: created-agent-id
labels:
- custom-indices
- department-search
name: Search Index Helper
schema:
additionalProperties: false
type: object
properties:
avatar_color:
description: Optional hex color code for the agent avatar.
type: string
avatar_symbol:
description: Optional symbol/initials for the agent avatar.
type: string
configuration:
additionalProperties: false
description: Configuration settings for the agent.
type: object
properties:
enable_elastic_capabilities:
description: When true, enables built-in Elastic capabilities for the agent.
type: boolean
instructions:
description: Optional system instructions that define the agent behavior.
type: string
plugin_ids:
description: Array of plugin IDs to assign to the agent.
items:
description: Plugin ID to assign to the agent.
type: string
maxItems: 100
type: array
skill_ids:
description: Array of skill IDs to be available to the agent.
items:
description: Skill ID to be available to the agent.
type: string
maxItems: 100
type: array
tools:
items:
additionalProperties: false
description: Tool selection configuration for the agent.
type: object
properties:
tool_ids:
description: Array of tool IDs that the agent can use.
items:
description: Tool ID to be available to the agent.
type: string
type: array
required:
- tool_ids
type: array
workflow_ids:
items:
description: Optional list of workflow IDs. When set, these workflows run before every agent execution, in order.
type: string
maxItems: 100
type: array
required:
- tools
description:
description: Description of what the agent does.
type: string
id:
description: Unique identifier for the agent.
type: string
labels:
description: Optional labels for categorizing and organizing agents.
items:
description: Label for categorizing the agent.
type: string
type: array
name:
description: Display name for the agent.
type: string
visibility:
description: '**Technical Preview; added in 9.4.0.** Optional visibility setting: `public` (any privileged user can read/write), `shared` (any privileged user can read, only owner can write), `private` (only owner can read/write).'
enum:
- public
- shared
- private
type: string
required:
- id
- name
- description
- configuration
responses:
'200':
content:
application/json:
examples:
createAgentResponseExample:
description: Example response returning the definition of an agent created as a result of the request
value:
avatar_color: '#BFDBFF'
avatar_symbol: SI
configuration:
instructions: You are a custom agent that wants to help searching data using all indices starting with prefix "content-".
tools:
- tool_ids:
- platform.core.search
- platform.core.list_indices
- platform.core.get_index_mapping
- platform.core.get_document_by_id
description: Hi! I can help you search the data within the indices starting with "content-" prefix.
id: created-agent-id
labels:
- custom-indices
- department-search
name: Search Index Helper
type: chat
description: Indicates a successful response
summary: Create an agent
tags:
- agent builder
x-codeSamples:
- lang: curl
source: "curl \\\n -X POST \"${KIBANA_URL}/api/agent_builder/agents\" \\\n -H \"Authorization: ApiKey ${API_KEY}\" \\\n -H \"kbn-xsrf: true\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"new-agent-id\",\n \"name\": \"Search Index Helper\",\n \"description\": \"Hi! I can help you search the data within the indices starting with \\\"content-\\\" prefix.\",\n \"labels\": [\"custom-indices\", \"department-search\"],\n \"avatar_color\": \"#BFDBFF\",\n \"avatar_symbol\": \"SI\",\n \"configuration\": {\n \"instructions\": \"You are a custom agent that wants to help searching data using all indices starting with prefix \\\"content-\\\".\",\n \"tools\": [\n {\n \"tool_ids\": [\n \"platform.core.search\",\n \"platform.core.list_indices\",\n \"platform.core.get_index_mapping\",\n \"platform.core.get_document_by_id\"\n ]\n }\n ]\n }\n}'\n"
- lang: Console
source: "POST kbn://api/agent_builder/agents\n{\n \"id\": \"new-agent-id\",\n \"name\": \"Search Index Helper\",\n \"description\": \"Hi! I can help you search the data within the indices starting with \\\"content-\\\" prefix.\",\n \"labels\": [\"custom-indices\", \"department-search\"],\n \"avatar_color\": \"#BFDBFF\",\n \"avatar_symbol\": \"SI\",\n \"configuration\": {\n \"instructions\": \"You are a custom agent that wants to help searching data using all indices starting with prefix \\\"content-\\\".\",\n \"tools\": [\n {\n \"tool_ids\": [\n \"platform.core.search\",\n \"platform.core.list_indices\",\n \"platform.core.get_index_mapping\",\n \"platform.core.get_document_by_id\"\n ]\n }\n ]\n }\n}\n"
x-state: Added in 9.2.0
x-metaTags:
- content: Kibana
name: product_name
/api/agent_builder/agents/{agent_id}/consumption:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/agent_builder/agents/{agent_id}/consumption</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Returns paginated, per-conversation token consumption data for a given agent. Includes input/output token counts, round counts, LLM call counts, and warnings for conversations with high token usage. Requires the manageAgents privilege.<br/><br/>[Required authorization] Route required privileges: agentBuilder:manageAgents.'
operationId: post-agent-builder-agents-agent-id-consumption
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: The unique identifier of the agent.
in: path
name: agent_id
required: true
schema:
type: string
requestBody:
content:
application/json:
examples:
consumptionDefaultExample:
description: Get consumption data for an agent with default pagination
value:
size: 25
sort_field: updated_at
sort_order: desc
consumptionFilteredExample:
description: Get consumption data filtered by username with warnings
value:
has_warnings: true
size: 10
sort_field: total_tokens
sort_order: desc
usernames:
- elastic
- admin
schema:
additionalProperties: false
type: object
properties:
has_warnings:
description: Filter to conversations with or without high-token warnings.
type: boolean
search:
description: Free-text search filter on conversation title.
type: string
search_after:
description: Cursor for pagination. Pass the search_after value from the previous response.
items:
nullable: true
maxItems: 10000
type: array
size:
default: 25
description: Number of results per page.
maximum: 100
minimum: 1
type: number
sort_field:
default: updated_at
description: Field to sort results by.
enum:
- updated_at
- total_tokens
- round_count
type: string
sort_order:
default: desc
description: Sort direction.
enum:
- asc
- desc
type: string
usernames:
description: Filter results to conversations by these usernames.
items:
type: string
maxItems: 10000
type: array
responses:
'200':
content:
application/json:
examples:
consumptionResponseExample:
description: Example response with per-conversation token usage data
value:
aggregations:
total_with_warnings: 0
usernames:
- elastic
- admin
results:
- conversation_id: conv-abc123
created_at: '2025-03-01T10:00:00Z'
llm_calls: 8
round_count: 5
title: Help me search my data
token_usage:
input_tokens: 15000
output_tokens: 3000
total_tokens: 18000
updated_at: '2025-03-01T10:15:00Z'
user:
id: uid-1
username: elastic
warnings: []
- conversation_id: conv-def456
created_at: '2025-03-02T14:00:00Z'
llm_calls: 20
round_count: 12
title: Analyze server logs
token_usage:
input_tokens: 250000
output_tokens: 8000
total_tokens: 258000
updated_at: '2025-03-02T14:30:00Z'
user:
id: uid-2
username: admin
warnings:
- input_tokens: 250000
round_id: round-7
type: high_input_tokens
search_after:
- 1709391000000
- '2025-03-02T14:30:00Z'
total: 2
description: Indicates a successful response
summary: Get agent consumption data
tags:
- agent builder
x-codeSamples:
- lang: curl
source: "curl \\\n -X POST \"${KIBANA_URL}/api/agent_builder/agents/elastic-ai-agent/consumption\" \\\n -H \"Authorization: ApiKey ${API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -H \"elastic-api-version: 2023-10-31\" \\\n -d '{\"size\": 25, \"sort_field\": \"updated_at\", \"sort_order\": \"desc\"}'\n"
- lang: Console
source: 'POST kbn://api/agent_builder/agents/elastic-ai-agent/consumption
{"size": 25, "sort_field": "updated_at", "sort_order": "desc"}
'
x-state: Technical Preview; added in 9.4.0
x-metaTags:
- content: Kibana
name: product_name
/api/agent_builder/agents/{id}:
delete:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb delete">delete</span> <span class="operation-path">/s/{space_id}/api/agent_builder/agents/{id}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Delete an agent by ID. This action cannot be undone. To learn more, refer to the [agents documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/agent-builder-agents).<br/><br/>[Required authorization] Route required privileges: agentBuilder:manageAgents.'
operationId: delete-agent-builder-agents-id
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: The unique identifier of the agent to delete.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
deleteAgentResponseExample:
description: Example response showing that deletion of the agent has been successful
value:
success: true
description: Indicates a successful response
summary: Delete an agent
tags:
- agent builder
x-codeSamples:
- lang: curl
source: "curl \\\n -X DELETE \"${KIBANA_URL}/api/agent_builder/agents/{id}\" \\\n -H \"Authorization: ApiKey ${API_KEY}\" \\\n -H \"kbn-xsrf: true\"\n"
- lang: Console
source: 'DELETE kbn://api/agent_builder/agents/{id}
'
x-state: Added in 9.2.0
x-metaTags:
- content: Kibana
name: product_name
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/agent_builder/agents/{id}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get a specific agent by ID. Use this endpoint to retrieve the complete agent definition including all configuration details and tool assignments. To learn more, refer to the [agents documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/agent-builder-agents).<br/><br/>[Required authorization] Route required privileges: agentBuilder:read.'
operationId: get-agent-builder-agents-id
parameters:
- description: The unique identifier of the agent to retrieve.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
getAgentByIdResponseExample:
description: Example response that an agent created by the user that will query elasticsearch indices starting with 'content-' prefix to answer the questions.
value:
avatar_color: '#BFDBFF'
avatar_symbol: SI
configuration:
instructions: You are a custom agent that wants to help searching data using all indices starting with prefix "content-".
tools:
- tool_ids:
- platform.core.search
- platform.core.list_indices
- platform.core.get_index_mapping
- platform.core.get_document_by_id
description: Hi! I can help you search the data within the indices starting with "content-" prefix.
id: created-agent-id
labels:
- custom-indices
- department-search
name: Search Index Helper
type: chat
description: Indicates a successful response
summary: Get an agent by ID
tags:
- agent builder
x-codeSamples:
- lang: curl
source: "curl \\\n -X GET \"${KIBANA_URL}/api/agent_builder/agents/{id}\" \\\n -H \"Authorization: ApiKey ${API_KEY}\"\n"
- lang: Console
source: 'GET kbn://api/agent_builder/agents/{id}
'
x-state: Added in 9.2.0
x-metaTags:
- content: Kibana
name: product_name
put:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb put">put</span> <span class="operation-path">/s/{space_id}/api/agent_builder/agents/{id}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Update an existing agent configuration. Use this endpoint to modify any aspect of the agent''s behavior, appearance, or capabilities. To learn more, refer to the [agents documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/agent-builder-agents).<br/><br/>[Required authorization] Route required privileges: agentBuilder:manageAgents.'
operationId: put-agent-builder-agents-id
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: The unique identifier of the agent to update.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
examples:
createAgentRequestExample:
description: Example request for updating custom agent
value:
avatar_color: '#BFDBFF'
avatar_symbol: SI
configuration:
instructions: You are a custom agent that wants to help searching data us
# --- truncated at 32 KB (158 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kibana/refs/heads/main/openapi/kibana-agent-builder-api-openapi.yml