Create a tool Technical Preview; added in 9.2.0

POST /api/agent_builder/tools
Api key auth Basic auth

Spaces method and path for this operation:

post /s/{space_id}/api/agent_builder/tools

Refer to Spaces for more information.

Create a new tool. Use this endpoint to define a custom tool with specific functionality and configuration for use by agents.

[Required authorization] Route required privileges: manage_onechat.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

  • configuration object Required

    Tool-specific configuration parameters. See examples for details.

    Additional properties are allowed.

  • description string

    Description of what the tool does.

    Default value is empty.

  • id string Required

    Unique identifier for the tool.

  • tags array[string]

    Optional tags for categorizing and organizing tools.

    Default value is [] (empty).

  • type string Required

    The type of tool to create (e.g., esql, index_search).

    Values are esql, index_search, or workflow.

Responses

  • 200 application/json

    Indicates a successful response

POST /api/agent_builder/tools 
curl \ --request POST 'https://localhost:5601/api/agent_builder/tools' \ --header "Authorization: $API_KEY" \ --header "Content-Type: application/json" \ --header "kbn-xsrf: true" \ --data '{"id":"example-esql-tool","tags":["analytics","finance"],"type":"esql","description":"Example ES|QL query tool for analyzing financial trades with time filtering","configuration":{"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","params":{"limit":{"type":"integer","description":"Maximum number of results to return"},"startTime":{"type":"date","description":"Start time for the analysis in ISO format"}}}}'
Request examples
Example request to create an ESQL query tool with a pre-defined query 
{ "id": "example-esql-tool", "tags": [ "analytics", "finance" ], "type": "esql", "description": "Example ES|QL query tool for analyzing financial trades with time filtering", "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": { "limit": { "type": "integer", "description": "Maximum number of results to return" }, "startTime": { "type": "date", "description": "Start time for the analysis in ISO format" } } } }
Example request to create an index_search tool with a pre-defined index pattern 
{ "id": "example-index-search-tool", "tags": [ "search", "finance" ], "type": "index_search", "description": "Search tool specifically for financial data analysis and reporting", "configuration": { "pattern": "financial_*" } }
Response examples (200)
Example response returning a definition of ESQL tool created 
{ "id": "example-esql-tool", "tags": [ "analytics", "finance" ], "type": "esql", "schema": { "type": "object", "$schema": "http://json-schema.org/draft-07/schema#", "required": [ "startTime", "limit" ], "properties": { "limit": { "type": "integer", "description": "Maximum number of results to return" }, "startTime": { "type": "string", "format": "date-time", "description": "Start time for the analysis in ISO format" } }, "description": "Parameters needed to execute the query", "additionalProperties": false }, "readonly": false, "description": "Example ES|QL query tool for analyzing financial trades with time filtering", "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": { "limit": { "type": "integer", "description": "Maximum number of results to return" }, "startTime": { "type": "date", "description": "Start time for the analysis in ISO format" } } } }
Example response returning a definition of search tool tool created 
{ "id": "example-index-search-tool", "tags": [ "search", "finance" ], "type": "index_search", "schema": { "type": "object", "$schema": "http://json-schema.org/draft-07/schema#", "required": [ "nlQuery" ], "properties": { "nlQuery": { "type": "string", "description": "A natural language query expressing the search request" } }, "additionalProperties": false }, "readonly": false, "description": "Search tool specifically for financial data analysis and reporting", "configuration": { "pattern": "financial_*" } }