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.

Required privileges

Privileges agentBuilder:manageTools

Path parameters

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.

Header parameters

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

Request body

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

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

curl Shell

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

Response

No example

Request Console 1 / 2 languages

Example request to create an ESQL query tool with a pre-defined query

Console Kibana Dev Tools

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

curl Shell

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

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

Console Kibana Dev Tools

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

curl Shell

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

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

Required privileges

Path parameters

Header parameters

Request body { }

Response

Request body