ES|QL tools in Elastic Agent Builder

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

While agents can generate ES|QL queries dynamically using index search tools, custom ES|QL tools ensure syntax correctness and enforce critical business rules that an LLM might occasionally miss. For strategies to avoid data retrieval issues, refer to Context length exceeded.

• 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: Must be provided by the agent when calling the tool
• Optional: Can be omitted; uses null if no default is specified

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.

×

FROM finance-orders-*
| WHERE order_status == "completed" AND region == ?region
| STATS total_revenue = SUM(amount) BY quarter
| LIMIT 5
		

• Include LIMIT clauses: Prevent returning excessive results by setting reasonable limits
• Use meaningful parameter names: Choose names that clearly indicate what the parameter represents (e.g., 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

For general guidance on naming tools and writing effective descriptions, refer to Custom tools best practices.

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.