Execute a Tool | Kibana Serverless API documentation

Execute a Tool Technical Preview

POST /api/agent_builder/tools/_execute

Execute a tool with parameters. Use this endpoint to run a tool directly with specified inputs and optional external connector integration.

[Required authorization] Route required privileges: read_onechat.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

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 object Required

Parameters to pass to the tool execution. See examples for details

Additional properties are allowed.

Responses

200 application/json

Indicates a successful response

POST /api/agent_builder/tools/_execute

curl \
 --request POST 'https://<KIBANA_URL>/api/agent_builder/tools/_execute' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"tool_id":"platform.core.execute_esql","tool_params":{"query":"FROM financial_trades | LIMIT 3"}}'

Request examples

Example request executing platform.core.execute_esql tool

{
  "tool_id": "platform.core.execute_esql",
  "tool_params": {
    "query": "FROM financial_trades | LIMIT 3"
  }
}

Example request executing platform.core.get_document_by_id tool

{
  "tool_id": "platform.core.get_document_by_id",
  "tool_params": {
    "id": "TRD-20250805-0820a89f",
    "index": "financial_trades"
  }
}

Example request executing custom example-esql-tool tool

{
  "tool_id": "example-esql-tool",
  "tool_params": {
    "limit": 3,
    "startTime": "2024-01-01T00:00:00Z"
  }
}

Example request executing custom example-index-search-tool tool

{
  "tool_id": "example-index-search-tool",
  "tool_params": {
    "nlQuery": "find trades with high execution prices above 100"
  }
}

Response examples (200)

Example response calling built-in platform.core.execute_esql tool

{
  "results": [
    {
      "data": {
        "esql": "FROM financial_trades | LIMIT 3"
      },
      "type": "query"
    },
    {
      "data": {
        "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"
          ]
        ],
        "columns": [
          {
            "name": "account_id",
            "type": "keyword"
          },
          {
            "name": "execution_price",
            "type": "double"
          },
          {
            "name": "symbol",
            "type": "keyword"
          },
          {
            "name": "trade_type",
            "type": "keyword"
          }
        ]
      },
      "type": "tabular_data",
      "tool_result_id": "xTpT"
    }
  ]
}

Example response calling built-in platform.core.get_document_by_id tool

{
  "results": [
    {
      "data": {
        "content": {
          "symbol": "EWL",
          "quantity": 131,
          "trade_id": "TRD-20250805-0820a89f",
          "account_id": "ACC00271-fb5c",
          "order_type": "market",
          "trade_cost": 63998.74,
          "trade_type": "sell",
          "last_updated": "2025-09-15T13:23:36",
          "order_status": "executed",
          "status_reason": "fully_filled",
          "execution_price": 488.54,
          "execution_timestamp": "2025-08-05T08:04:11.649855"
        },
        "partial": false,
        "reference": {
          "id": "TRD-20250805-0820a89f",
          "index": "financial_trades"
        }
      },
      "type": "resource"
    }
  ]
}

Example response calling custom example-esql-tool tool

{
  "results": [
    {
      "data": {
        "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",
        "source": "esql",
        "values": [
          [
            2115,
            89.33911587329621,
            "US_T_BOND_20YR"
          ],
          [
            2112,
            104.2085415594506,
            "INTL_CORP_ASIA_D"
          ],
          [
            2105,
            89.93244177666526,
            "INTL_CORP_EU_B"
          ]
        ],
        "columns": [
          {
            "name": "trade_count",
            "type": "long"
          },
          {
            "name": "avg_price",
            "type": "double"
          },
          {
            "name": "symbol",
            "type": "keyword"
          }
        ]
      },
      "type": "tabular_data",
      "tool_result_id": "Voy8"
    }
  ]
}

Example response calling custom example-index-search-tool tool

{
  "results": [
    {
      "data": {
        "esql": "FROM financial_trades\n| WHERE execution_price > 100\n| LIMIT 100"
      },
      "type": "query"
    },
    {
      "data": {
        "query": "FROM financial_trades\n| WHERE execution_price > 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"
          ]
        ],
        "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"
          }
        ]
      },
      "type": "tabular_data",
      "tool_result_id": "uE8y"
    }
  ]
}