Create a tool
Base URL
https://{kibana_url}
POST
/api/agent_builder/tools
POST
/s/{space_id} /api/agent_builder/tools
Auth
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"
}