Create a tool
Base URL
https://{kibana_url}
POST
/api/agent_builder/tools
POST
/s/{space_id} /api/agent_builder/tools
Auth
Stack
9.2+
The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.
Availability
Generally available since 9.2
This functionality is generally available and ready for production usage.
Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.
This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.
Create a new tool. Use this endpoint to define a custom tool with specific functionality and configuration for use by agents. To learn more about Agent Builder tools, refer to the tools documentation .
Privileges
agentBuilder:manageTools
Expand all
space_id
string optional
An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.
A required header to protect against CSRF attacks
{
}
configuration
map string to object required
Tool-specific configuration parameters. See examples for details.
confirmation
object
Optional tool call policy to control tool call confirmation behavior
+
Show 1 property
askUser
enum
Values:
once
always
never
description
string
Description of what the tool does.
id
string required
Unique identifier for the tool.
tags
string [] · default: []
Optional tags for categorizing and organizing tools.
type
enum required
The type of tool to create (e.g., esql, index_search).
Values:
esql
index_search
workflow
mcp
200
Indicates a successful response
application/json
Thank you for your feedback.
Base URL
https://{kibana_url}
Examples
Example
languages
Create ES|QL tool
languages
Create index search tool
languages
Request
Console
1 / 2 languages
‹
›
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
POST kbn:/api/agent_builder/tools
{
"id": "example-esql-tool",
"type": "esql",
"description": "An ES|QL query tool for analyzing financial trades with time filtering",
"tags": ["analytics", "finance", "updated"],
"configuration": {
"query": "FROM financial_trades | WHERE execution_timestamp >= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit",
"params": {
"startTime": {
"type": "date",
"description": "Start time for the analysis in ISO format"
},
"limit": {
"type": "integer",
"description": "Maximum number of results to return"
}
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
curl \
-X POST "https://${KIBANA_URL}/api/agent_builder/tools" \
-H "Authorization: ApiKey ${API_KEY}" \
-H "kbn-xsrf: true" \
-H "Content-Type: application/json" \
-d '{
"id": "example-esql-tool",
"type": "esql",
"description": "Example ES|QL query tool for analyzing financial trades with time filtering",
"tags": ["analytics", "finance"],
"configuration": {
"query": "FROM financial_trades | WHERE execution_timestamp >= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit",
"params": {
"startTime": {
"type": "date",
"description": "Start time for the analysis in ISO format"
},
"limit": {
"type": "integer",
"description": "Maximum number of results to return"
}
}
}
}'
Request
Console
1 / 2 languages
‹
›
Example request to create an ESQL query tool with a pre-defined query
Show more
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
POST kbn:/api/agent_builder/tools
{
"configuration": {
"params": {
"limit": {
"description": "Maximum number of results to return",
"type": "integer"
},
"startTime": {
"description": "Start time for the analysis in ISO format",
"type": "date"
}
},
"query": "FROM financial_trades | WHERE execution_timestamp \u003E= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit"
},
"description": "Example ES|QL query tool for analyzing financial trades with time filtering",
"id": "example-esql-tool",
"tags": [
"analytics",
"finance"
],
"type": "esql"
}
Generated from the API spec
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
curl \
-X POST "https://${KIBANA_URL}/api/agent_builder/tools" \
-H "Authorization: ApiKey ${API_KEY}" \
-H "kbn-xsrf: true" \
-H "Content-Type: application/json" \
-d '{
"configuration": {
"params": {
"limit": {
"description": "Maximum number of results to return",
"type": "integer"
},
"startTime": {
"description": "Start time for the analysis in ISO format",
"type": "date"
}
},
"query": "FROM financial_trades | WHERE execution_timestamp \u003E= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit"
},
"description": "Example ES|QL query tool for analyzing financial trades with time filtering",
"id": "example-esql-tool",
"tags": [
"analytics",
"finance"
],
"type": "esql"
}'
Generated from the API spec
Response
Example response returning a definition of ESQL tool created
Show more
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
"configuration": {
"params": {
"limit": {
"description": "Maximum number of results to return",
"type": "integer"
},
"startTime": {
"description": "Start time for the analysis in ISO format",
"type": "date"
}
},
"query": "FROM financial_trades | WHERE execution_timestamp \u003E= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit"
},
"description": "Example ES|QL query tool for analyzing financial trades with time filtering",
"id": "example-esql-tool",
"readonly": false,
"schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Parameters needed to execute the query",
"type": "object",
"properties": {
"limit": {
"description": "Maximum number of results to return",
"type": "integer"
},
"startTime": {
"description": "Start time for the analysis in ISO format",
"format": "date-time",
"type": "string"
}
},
"required": [
"startTime",
"limit"
]
},
"tags": [
"analytics",
"finance"
],
"type": "esql"
}
Request
Console
1 / 2 languages
‹
›
Example request to create an index_search tool with a pre-defined index pattern
Show more
1
2
3
4
5
6
7
8
9
10
11
12
13
POST kbn:/api/agent_builder/tools
{
"configuration": {
"pattern": "financial_*"
},
"description": "Search tool specifically for financial data analysis and reporting",
"id": "example-index-search-tool",
"tags": [
"search",
"finance"
],
"type": "index_search"
}
Generated from the API spec
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl \
-X POST "https://${KIBANA_URL}/api/agent_builder/tools" \
-H "Authorization: ApiKey ${API_KEY}" \
-H "kbn-xsrf: true" \
-H "Content-Type: application/json" \
-d '{
"configuration": {
"pattern": "financial_*"
},
"description": "Search tool specifically for financial data analysis and reporting",
"id": "example-index-search-tool",
"tags": [
"search",
"finance"
],
"type": "index_search"
}'
Generated from the API spec
Response
Example response returning a definition of search tool tool created
Show more
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
"configuration": {
"pattern": "financial_*"
},
"description": "Search tool specifically for financial data analysis and reporting",
"id": "example-index-search-tool",
"readonly": false,
"schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"type": "object",
"properties": {
"nlQuery": {
"description": "A natural language query expressing the search request",
"type": "string"
}
},
"required": [
"nlQuery"
]
},
"tags": [
"search",
"finance"
],
"type": "index_search"
}