Run a tool
Base URL
https://{kibana_url}
POST
/api/agent_builder/tools/_execute
POST
/s/{space_id} /api/agent_builder/tools/_execute
Auth
Run a tool with parameters. Use this endpoint to run a tool directly with specified inputs and optional external connector integration. To learn more about Agent Builder tools, refer to the tools documentation .
Privileges
agentBuilder:read
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
{
}
approvals
object
Actions the tool run may take that would otherwise need a live user to approve them. Applies to this run and any sub-agents it spawns.
+
Show 1 property
auto_approved_apis
object
Destructive Elasticsearch or Kibana APIs the tool may call without a user confirmation, keyed by backend. A tool run has no live user to answer the confirmation prompt, so a destructive API is refused unless it is listed here.
+
Show 2 properties
elasticsearch
string [] · max items: 100
Elasticsearch APIs pre-approved for this run. Each entry is an exact identifier formed from the namespace and name (for example indices.create), a namespace wildcard (for example indices.*), or * for every Elasticsearch API.
kibana
string [] · max items: 100
Kibana APIs pre-approved for this run. Each entry is an exact identifier formed from the namespace and name (for example alerting.delete-alerting-rule-id), a namespace wildcard (for example alerting.*), or * for every Kibana API.
connector_id
string
Optional connector ID for tools that require external integrations.
tool_id
string required
The ID of the tool to execute.
tool_params
map string to object required
Parameters to pass to the tool execution. See examples for details
200
Indicates a successful response
application/json
Thank you for your feedback.
Base URL
https://{kibana_url}
Examples
Example
languages
Execute builtin ES|QL tool
languages
Execute builtin tool
languages
Execute custom ES|QL tool
languages
Execute index search tool
languages
Request
Console
1 / 2 languages
‹
›
1
2
3
4
5
6
7
POST kbn:/api/agent_builder/tools/_execute
{
"tool_id": "platform.core.search",
"tool_params": {
"query": "can you find john doe's email from the employee index?"
}
}
1
2
3
4
5
6
7
8
9
10
11
curl \
-X POST "https://${KIBANA_URL}/api/agent_builder/tools/_execute" \
-H "Authorization: ApiKey ${API_KEY}" \
-H "kbn-xsrf: true" \
-H "Content-Type: application/json" \
-d '{
"tool_id": "platform.core.search",
"tool_params": {
"query": "can you find john doe's email from the employee index?"}
}
}'
Request
Console
1 / 2 languages
‹
›
Example request executing platform.core.execute_esql tool
Show more
1
2
3
4
5
6
7
POST kbn:/api/agent_builder/tools/_execute
{
"tool_id": "platform.core.execute_esql",
"tool_params": {
"query": "FROM financial_trades | LIMIT 3"
}
}
Generated from the API spec
1
2
3
4
5
6
7
8
9
10
11
12
13
curl \
-X POST "https://${KIBANA_URL}/api/agent_builder/tools/_execute" \
-H "Authorization: ApiKey ${API_KEY}" \
-H "kbn-xsrf: true" \
-H "Content-Type: application/json" \
-d '{
"tool_id": "platform.core.execute_esql",
"tool_params": {
"query": "FROM financial_trades | LIMIT 3"
}
}'s email from the employee index?"}
}
}'
Generated from the API spec
Response
Example response calling built-in platform.core.execute_esql tool
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
45
46
47
48
49
50
51
52
53
54
55
56
{
"results": [
{
"data": {
"esql": "FROM financial_trades | LIMIT 3"
},
"type": "query"
},
{
"data": {
"columns": [
{
"name": "account_id",
"type": "keyword"
},
{
"name": "execution_price",
"type": "double"
},
{
"name": "symbol",
"type": "keyword"
},
{
"name": "trade_type",
"type": "keyword"
}
],
"query": "FROM financial_trades | LIMIT 3",
"source": "esql",
"values": [
[
"ACC00179-1f91",
43.77000045776367,
"CVX",
"sell"
],
[
"ACC00407-0bbb",
660.4199829101562,
"V",
"buy"
],
[
"ACC00179-1f91",
440.3599853515625,
"KO",
"buy"
]
]
},
"tool_result_id": "xTpT",
"type": "esql_results"
}
]
}
Request
Console
1 / 2 languages
‹
›
Example request executing platform.core.get_document_by_id tool
Show more
1
2
3
4
5
6
7
8
POST kbn:/api/agent_builder/tools/_execute
{
"tool_id": "platform.core.get_document_by_id",
"tool_params": {
"id": "TRD-20250805-0820a89f",
"index": "financial_trades"
}
}
Generated from the API spec
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl \
-X POST "https://${KIBANA_URL}/api/agent_builder/tools/_execute" \
-H "Authorization: ApiKey ${API_KEY}" \
-H "kbn-xsrf: true" \
-H "Content-Type: application/json" \
-d '{
"tool_id": "platform.core.get_document_by_id",
"tool_params": {
"id": "TRD-20250805-0820a89f",
"index": "financial_trades"
}
}'s email from the employee index?"}
}
}'
Generated from the API spec
Response
Example response calling built-in platform.core.get_document_by_id tool
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
{
"results": [
{
"data": {
"content": {
"account_id": "ACC00271-fb5c",
"execution_price": 488.54,
"execution_timestamp": "2025-08-05T08:04:11.649855",
"last_updated": "2025-09-15T13:23:36",
"order_status": "executed",
"order_type": "market",
"quantity": 131,
"status_reason": "fully_filled",
"symbol": "EWL",
"trade_cost": 63998.74,
"trade_id": "TRD-20250805-0820a89f",
"trade_type": "sell"
},
"partial": false,
"reference": {
"id": "TRD-20250805-0820a89f",
"index": "financial_trades"
}
},
"type": "resource"
}
]
}
Request
Console
1 / 2 languages
‹
›
Example request executing custom example-esql-tool tool
Show more
1
2
3
4
5
6
7
8
POST kbn:/api/agent_builder/tools/_execute
{
"tool_id": "example-esql-tool",
"tool_params": {
"limit": 3,
"startTime": "2024-01-01T00:00:00Z"
}
}
Generated from the API spec
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl \
-X POST "https://${KIBANA_URL}/api/agent_builder/tools/_execute" \
-H "Authorization: ApiKey ${API_KEY}" \
-H "kbn-xsrf: true" \
-H "Content-Type: application/json" \
-d '{
"tool_id": "example-esql-tool",
"tool_params": {
"limit": 3,
"startTime": "2024-01-01T00:00:00Z"
}
}'s email from the employee index?"}
}
}'
Generated from the API spec
Response
Example response calling custom example-esql-tool tool
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
{
"results": [
{
"data": {
"columns": [
{
"name": "trade_count",
"type": "long"
},
{
"name": "avg_price",
"type": "double"
},
{
"name": "symbol",
"type": "keyword"
}
],
"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",
"source": "esql",
"values": [
[
2115,
89.33911587329621,
"US_T_BOND_20YR"
],
[
2112,
104.20854155945055,
"INTL_CORP_ASIA_D"
],
[
2105,
89.93244177666526,
"INTL_CORP_EU_B"
]
]
},
"tool_result_id": "Voy8",
"type": "esql_results"
}
]
}
Request
Console
1 / 2 languages
‹
›
Example request executing custom example-index-search-tool tool
Show more
1
2
3
4
5
6
7
POST kbn:/api/agent_builder/tools/_execute
{
"tool_id": "example-index-search-tool",
"tool_params": {
"nlQuery": "find trades with high execution prices above 100"
}
}
Generated from the API spec
1
2
3
4
5
6
7
8
9
10
11
12
13
curl \
-X POST "https://${KIBANA_URL}/api/agent_builder/tools/_execute" \
-H "Authorization: ApiKey ${API_KEY}" \
-H "kbn-xsrf: true" \
-H "Content-Type: application/json" \
-d '{
"tool_id": "example-index-search-tool",
"tool_params": {
"nlQuery": "find trades with high execution prices above 100"
}
}'s email from the employee index?"}
}
}'
Generated from the API spec
Response
Example response calling custom example-index-search-tool tool
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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
{
"results": [
{
"data": {
"esql": "FROM financial_trades\n| WHERE execution_price \u003E 100\n| LIMIT 100"
},
"type": "query"
},
{
"data": {
"columns": [
{
"name": "account_id",
"type": "keyword"
},
{
"name": "execution_price",
"type": "double"
},
{
"name": "execution_timestamp",
"type": "date"
},
{
"name": "symbol",
"type": "keyword"
},
{
"name": "trade_type",
"type": "keyword"
}
],
"query": "FROM financial_trades\n| WHERE execution_price \u003E 100\n| LIMIT 100",
"source": "esql",
"values": [
[
"ACC00407-0bbb",
660.4199829101562,
"2020-09-25T11:06:08.687Z",
"V",
"buy"
],
[
"ACC00179-1f91",
440.3599853515625,
"2025-08-07T21:56:45.377Z",
"KO",
"buy"
],
[
"ACC00407-0bbb",
132.8800048828125,
"2020-11-19T04:39:13.655Z",
"JAP_JGB_10YR",
"sell"
]
]
},
"tool_result_id": "uE8y",
"type": "esql_results"
}
]
}