Loading

ES|QL tools

Serverless Elasticsearch Preview Serverless Observability Unavailable Serverless Security Unavailable Stack Preview 9.2.0

ES|QL query tools enable you to create parameterized queries that execute directly against your Elasticsearch data. These custom tools provide precise control over data retrieval through templated ES|QL statements.

Use custom ES|QL tools when:

  • You need precise control over the query logic
  • Your use case involves repeatable analytical patterns
  • You want to expose specific, parameterized queries to agents
  • Results should be in a predictable tabular format
  • You have well-defined data retrieval requirements
  • Execute pre-defined ES|QL queries with dynamic parameters
  • Support typed parameters
  • Return results in tabular format for structured data analysis
  • Ideal for repeatable analytical queries with variable inputs

ES|QL tools support the following parameter types:

  • String types: text, keyword
  • Numeric types: long, integer, double, float
  • Other types: boolean, date, object, nested

Parameters can be configured as:

  • Required: The agent must provide a value when calling the tool

  • Optional: The agent doesn't need to provide a value when calling the tool

    • You can specify a default value for optional parameters to prevent query errors when agents don't provide them
    • You don't need to specify a default value, the agent uses null when not provided

Stack Planned

Important

Support for optional parameters with default values in ES|QL tools is an API-only feature initially. While default values are not required by the API, they are strongly recommended for all optional parameters to prevent query syntax errors.

Optional parameters can have default values that are automatically applied when the agent doesn't provide a value. This ensures valid query syntax and consistent behavior.

When an agent calls a tool without specifying parameters, it automatically uses the defaults. When the agent provides a value, it overrides the default.

Refer to the API documentation for details about the ES|QL tools API.

In your ES|QL query, reference parameters using the ?parameter_name syntax. The agent will automatically interpolate parameter values when executing the query.

Here's an example ES|QL tool that searches for books using full-text search. ?search_terms is a named parameter that the agent will provide when executing the query.

FROM books
| WHERE MATCH(title, ?search_terms)
| KEEP title, author, year
| LIMIT 10

You can ask the LLM to infer the parameters for the query or add them manually.

Creating an ES|QL tool with a parameterized query
Note

For API examples, refer to Work with Elastic Agent Builder using the APIs > Tools

  • Include LIMIT clauses: Prevent returning excessive results by setting reasonable limits
  • Use meaningful parameter names: Choose names that clearly indicate what the parameter represents (for example, start_date instead of date1)
  • Define parameter types: Ensure parameters have the correct type to avoid runtime errors
  • Provide clear descriptions: Help agents understand when and how to use each parameter
  • Use default values for optional parameters: Set sensible defaults for optional parameters to reduce complexity for agents and ensure consistent behavior when parameters are omitted Stack Planned

ES|QL tools are subject to the current limitations of the ES|QL language itself. For more information, refer to ES|QL tool limitations.

To learn more about the language, refer to the ES|QL docs.