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