Run a tool

Base URL: https://{kibana_url}

POST /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.

Required authorization

Privileges agentBuilder:read

Header parameters

kbn-xsrf string required: A required header to protect against CSRF attacks

Request body

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.
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

Response

200

Indicates a successful response

application/json

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

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?"
  }
}

curl Shell

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?"}
   }
 }'

Response

No example

Request Console 1 / 2 languages

Example request executing platform.core.execute_esql tool

Console Kibana Dev Tools

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

curl Shell

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

{
  "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

Console Kibana Dev Tools

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

curl Shell

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

{
  "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

Console Kibana Dev Tools

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

curl Shell

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

{
  "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

Console Kibana Dev Tools

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

curl Shell

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

{
  "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"
    }
  ]
}