From b6770c3109470ee33cd399d80c5f7cde4cf4086e Mon Sep 17 00:00:00 2001 From: Jedr Blaszyk Date: Fri, 10 Oct 2025 13:31:49 +0200 Subject: [PATCH 1/8] [Agent Builder] Provide tools docs --- solutions/search/agent-builder/tools.md | 9 +-- .../search/agent-builder/tools/esql-tools.md | 60 ++++++++++++++++ .../agent-builder/tools/index-search-tools.md | 69 +++++++++++++++++++ 3 files changed, 134 insertions(+), 4 deletions(-) create mode 100644 solutions/search/agent-builder/tools/esql-tools.md create mode 100644 solutions/search/agent-builder/tools/index-search-tools.md diff --git a/solutions/search/agent-builder/tools.md b/solutions/search/agent-builder/tools.md index a1e0c88b9c..d01f15d643 100644 --- a/solutions/search/agent-builder/tools.md +++ b/solutions/search/agent-builder/tools.md @@ -68,8 +68,9 @@ Tool namespacing helps organize and identify tools by their source. Built-in too You can extend the built-in tool catalog with your own custom tool definitions. Custom tools offer flexibility in how they interact with your data: -- **Scoped tools**: Define tools that are scoped to a specific index or pattern, allowing the LLM to decide how to query those indices based on the user's request -- **Explicit query tools**: Define tools with explicit {{esql}} queries for precise, pre-defined data retrieval operations +- **[Index search tools](tools/index-search-tools.md)**: Define tools that are scoped to a specific index or pattern, allowing the LLM to decide how to query those indices based on the user's request +- **[ES|QL tools](tools/esql-tools.md)**: Define tools with explicit {{esql}} queries for precise, pre-defined data retrieval operations + This flexibility allows you to create tools that match your specific use cases and data access patterns. @@ -110,7 +111,7 @@ You can create custom tools to help agents interact with your data in specific w 4. Fill in the required fields: - **Name**: Enter a descriptive name for your tool - **Description**: Write a clear explanation of what the tool does and when it should be used - - **Tool type**: Choose either **{{esql}}** query or **Index search** + - **Tool type**: Choose either **[{{esql}}](tools/esql-tools.md)** or **[Index search](tools/index-search-tools.md)** - **Parameters**: For tools with {{esql}} queries, define any parameters your query needs - **Tags**: (Optional) Add labels to categorize and organize your tools 5. Choose how to save your tool: @@ -211,4 +212,4 @@ The **Tools** UI provides a **Copy your MCP server URL** button for easy access. :width: 250px ::: -For detailed MCP server configuration, refer to [MCP server](mcp-server.md). \ No newline at end of file +For detailed MCP server configuration, refer to [MCP server](mcp-server.md). diff --git a/solutions/search/agent-builder/tools/esql-tools.md b/solutions/search/agent-builder/tools/esql-tools.md new file mode 100644 index 0000000000..061c17ee40 --- /dev/null +++ b/solutions/search/agent-builder/tools/esql-tools.md @@ -0,0 +1,60 @@ +--- +navigation_title: "ES|QL tools" +applies_to: + stack: preview 9.2 + serverless: + elasticsearch: preview +--- + +:::{warning} +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. + +**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).** +::: + +# {{esql}} tools + +{{esql}} query tools enable you to create parameterized queries that execute directly against your {{es}} data. These custom tools provide precise control over data retrieval through templated {{esql}} statements. + +## When to use {{esql}} tools + +Use custom **{{esql}} 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 + +## Key characteristics + +* Execute pre-defined {{esql}} queries with dynamic parameters +* Support typed parameters +* Return results in tabular format for structured data analysis +* Ideal for repeatable analytical queries with variable inputs + +## Parameter types + +{{esql}} tools support the following parameter types: + +* **String types**: `text`, `keyword` +* **Numeric types**: `long`, `integer`, `double`, `float` +* **Other types**: `boolean`, `date`, `object`, `nested` + +## Parameter options + +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 + +## Query syntax + +In your {{esql}} query, reference parameters using the `?parameter_name` syntax. The agent will automatically interpolate parameter values when executing the query. + + +## Best practices + +- **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`) +- **Provide clear descriptions**: Help agents understand when and how to use each parameter diff --git a/solutions/search/agent-builder/tools/index-search-tools.md b/solutions/search/agent-builder/tools/index-search-tools.md new file mode 100644 index 0000000000..5dd70a43df --- /dev/null +++ b/solutions/search/agent-builder/tools/index-search-tools.md @@ -0,0 +1,69 @@ +--- +navigation_title: "Index search tools" +applies_to: + stack: preview 9.2 + serverless: + elasticsearch: preview +--- + +:::{warning} +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. + +**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).** +::: + +# Index search tools + +Index search tools provide intelligent, natural language-driven search over specified {{es}} resources. Instead of defining explicit queries, you specify a pattern of indices, aliases, or data streams, and the tool uses a combination of built-in capabilities to intelligently interpret and execute search requests. + +## When to use index search tools + +Use custom **Index search tools** when: + +* You want agents to handle diverse, exploratory queries +* The search intent varies significantly across requests +* Users need flexible, ad-hoc search functionality +* You want to scope general search capabilities to specific indices + +## Key characteristics + +* Accept natural language queries from the agent +* Automatically determine optimal search strategy (full-text, semantic) +* Leverage built-in tools like index exploration, query generation, and semantic search +* Ideal for flexible, user-driven exploratory searches +* No need to pre-define query logic + +## Configuration + +Index search tools require only a single configuration parameter: + +* **`pattern`**: An index pattern string (e.g., `logs-*`, `my-index`, `.alerts-*`) specifying which indices, aliases, or data streams to search + +## How it works + +When an agent calls an index search tool: + +1. The agent provides a natural language query (e.g., "find recent errors related to authentication") +2. The tool analyzes the query intent and available indices +3. It automatically orchestrates built-in tools to: + - Explore the index structure and mappings + - Generate appropriate queries ({{esql}} or query DSL) + - Execute semantic search if relevant + - Rank and format results +4. Returns results in a format the agent can interpret and present + + +## Best practices + +- **Use specific patterns**: Scope tools to relevant index patterns rather than broad wildcards (e.g., `logs-myapp-*` instead of `logs-*`) +- **Write descriptive tool names**: Help agents select the right tool for the query (e.g., "Search Security Alerts" vs. "Search Tool") +- **Provide context in descriptions**: Explain what data the indices contain and what types of questions the tool can answer +- **Create domain-specific tools**: Build separate tools for different data domains (logs, metrics, alerts) rather than one general-purpose tool + + +## Common patterns + +* **Wildcard patterns**: `logs-*`, `metrics-*`, `events-*` +* **Specific indices**: `products`, `users`, `orders` +* **System indices**: `.alerts-security-*`, `.ml-anomalies-*` +* **Date-based patterns**: `logs-2024-*`, `events-2024.01.*` From b341073603bcfcc35f069e7771e511e2e33cc413 Mon Sep 17 00:00:00 2001 From: Jedr Blaszyk Date: Fri, 10 Oct 2025 13:34:12 +0200 Subject: [PATCH 2/8] update index search docs --- solutions/search/agent-builder/tools/index-search-tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/agent-builder/tools/index-search-tools.md b/solutions/search/agent-builder/tools/index-search-tools.md index 5dd70a43df..31cb0987d3 100644 --- a/solutions/search/agent-builder/tools/index-search-tools.md +++ b/solutions/search/agent-builder/tools/index-search-tools.md @@ -66,4 +66,4 @@ When an agent calls an index search tool: * **Wildcard patterns**: `logs-*`, `metrics-*`, `events-*` * **Specific indices**: `products`, `users`, `orders` * **System indices**: `.alerts-security-*`, `.ml-anomalies-*` -* **Date-based patterns**: `logs-2024-*`, `events-2024.01.*` +* **All resources**: `*` From e91cfaea98b5b5bb6c72ea592d28e84595799fc1 Mon Sep 17 00:00:00 2001 From: Jedr Blaszyk Date: Fri, 10 Oct 2025 13:37:12 +0200 Subject: [PATCH 3/8] try adding to toc --- solutions/toc.yml | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/solutions/toc.yml b/solutions/toc.yml index 325671d671..1403f6df80 100644 --- a/solutions/toc.yml +++ b/solutions/toc.yml @@ -1,4 +1,4 @@ -project: 'Solutions and use cases' +project: "Solutions and use cases" toc: - file: index.md - file: search.md @@ -50,6 +50,9 @@ toc: - hidden: search/agent-builder/chat.md - hidden: search/agent-builder/agent-builder-agents.md - hidden: search/agent-builder/tools.md + children: + - hidden: search/agent-builder/tools/esql-tools.md + - hidden: search/agent-builder/tools/index-search-tools.md - hidden: search/agent-builder/programmatic-access.md - hidden: search/agent-builder/kibana-api.md - hidden: search/agent-builder/mcp-server.md @@ -458,13 +461,13 @@ toc: - file: observability/logs/logs-index-template-defaults.md - file: observability/streams/streams.md children: - - file: observability/streams/management/extract.md - children: - - file: observability/streams/management/extract/date.md - - file: observability/streams/management/extract/dissect.md - - file: observability/streams/management/extract/grok.md - - file: observability/streams/management/retention.md - - file: observability/streams/management/advanced.md + - file: observability/streams/management/extract.md + children: + - file: observability/streams/management/extract/date.md + - file: observability/streams/management/extract/dissect.md + - file: observability/streams/management/extract/grok.md + - file: observability/streams/management/retention.md + - file: observability/streams/management/advanced.md - file: observability/incident-management.md children: - file: observability/incident-management/alerting.md @@ -745,4 +748,4 @@ toc: - file: security/advanced-entity-analytics/privileged-user-monitoring-setup.md - file: security/advanced-entity-analytics/monitor-privileged-user-activitites.md - file: security/asset-management.md - - file: security/apis.md \ No newline at end of file + - file: security/apis.md From 8da1f4c3b8ba80c33ec94b609e438314cf81d182 Mon Sep 17 00:00:00 2001 From: Jedr Blaszyk Date: Fri, 10 Oct 2025 13:40:43 +0200 Subject: [PATCH 4/8] try again --- solutions/toc.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/solutions/toc.yml b/solutions/toc.yml index 1403f6df80..421471886f 100644 --- a/solutions/toc.yml +++ b/solutions/toc.yml @@ -50,9 +50,8 @@ toc: - hidden: search/agent-builder/chat.md - hidden: search/agent-builder/agent-builder-agents.md - hidden: search/agent-builder/tools.md - children: - - hidden: search/agent-builder/tools/esql-tools.md - - hidden: search/agent-builder/tools/index-search-tools.md + - hidden: search/agent-builder/tools/esql-tools.md + - hidden: search/agent-builder/tools/index-search-tools.md - hidden: search/agent-builder/programmatic-access.md - hidden: search/agent-builder/kibana-api.md - hidden: search/agent-builder/mcp-server.md From 0a589f11c0a612a03d888b1dc60b4b415dea82cc Mon Sep 17 00:00:00 2001 From: Jedr Blaszyk Date: Fri, 10 Oct 2025 16:55:39 +0200 Subject: [PATCH 5/8] Update solutions/search/agent-builder/tools/esql-tools.md Co-authored-by: Liam Thompson --- solutions/search/agent-builder/tools/esql-tools.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/solutions/search/agent-builder/tools/esql-tools.md b/solutions/search/agent-builder/tools/esql-tools.md index 061c17ee40..0bb511c231 100644 --- a/solutions/search/agent-builder/tools/esql-tools.md +++ b/solutions/search/agent-builder/tools/esql-tools.md @@ -58,3 +58,7 @@ In your {{esql}} query, reference parameters using the `?parameter_name` syntax. - **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`) - **Provide clear descriptions**: Help agents understand when and how to use each parameter + +## {{esql}} documentation + +To learn more about the language, refer to the [{{esql}} docs](elasticsearch://reference/query-languages/esql.md). From db47d7a6e63a05d97045c6892f14cb6408328c94 Mon Sep 17 00:00:00 2001 From: Jedr Blaszyk Date: Fri, 10 Oct 2025 16:55:45 +0200 Subject: [PATCH 6/8] Update solutions/search/agent-builder/tools/index-search-tools.md Co-authored-by: Liam Thompson --- solutions/search/agent-builder/tools/index-search-tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/agent-builder/tools/index-search-tools.md b/solutions/search/agent-builder/tools/index-search-tools.md index 31cb0987d3..e726850a88 100644 --- a/solutions/search/agent-builder/tools/index-search-tools.md +++ b/solutions/search/agent-builder/tools/index-search-tools.md @@ -14,7 +14,7 @@ These pages are currently hidden from the docs TOC and have `noindexed` meta hea # Index search tools -Index search tools provide intelligent, natural language-driven search over specified {{es}} resources. Instead of defining explicit queries, you specify a pattern of indices, aliases, or data streams, and the tool uses a combination of built-in capabilities to intelligently interpret and execute search requests. +Index search tools provide intelligent, natural language-driven search over specified {{es}} resources. Instead of defining explicit queries, you specify a pattern of [indices](/manage-data/data-store/index-basics.md), [aliases](/manage-data/data-store/aliases), or [data streams](/manage-data/data-store/data-streams.md), and the tool uses a combination of built-in capabilities to intelligently interpret and execute search requests. ## When to use index search tools From d2457568e1328c6cf40699c38bbd84fe5ba5786a Mon Sep 17 00:00:00 2001 From: Jedr Blaszyk Date: Fri, 10 Oct 2025 16:55:57 +0200 Subject: [PATCH 7/8] Update solutions/search/agent-builder/tools/esql-tools.md Co-authored-by: Liam Thompson --- solutions/search/agent-builder/tools/esql-tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/agent-builder/tools/esql-tools.md b/solutions/search/agent-builder/tools/esql-tools.md index 0bb511c231..61c45922af 100644 --- a/solutions/search/agent-builder/tools/esql-tools.md +++ b/solutions/search/agent-builder/tools/esql-tools.md @@ -14,7 +14,7 @@ These pages are currently hidden from the docs TOC and have `noindexed` meta hea # {{esql}} tools -{{esql}} query tools enable you to create parameterized queries that execute directly against your {{es}} data. These custom tools provide precise control over data retrieval through templated {{esql}} statements. +{{esql}} query tools enable you to create parameterized queries that execute directly against your {{es}} data. These custom tools provide precise control over data retrieval through templated [{{esql}}](elasticsearch://reference/query-languages/esql.md) statements. ## When to use {{esql}} tools From c4695b1bf7cb1ad997b3c31eabbc1fae91b5d93f Mon Sep 17 00:00:00 2001 From: Jedr Blaszyk Date: Mon, 13 Oct 2025 15:53:14 +0200 Subject: [PATCH 8/8] Update solutions/search/agent-builder/tools/index-search-tools.md Co-authored-by: Liam Thompson --- solutions/search/agent-builder/tools/index-search-tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/agent-builder/tools/index-search-tools.md b/solutions/search/agent-builder/tools/index-search-tools.md index e726850a88..fc6fb8cae5 100644 --- a/solutions/search/agent-builder/tools/index-search-tools.md +++ b/solutions/search/agent-builder/tools/index-search-tools.md @@ -14,7 +14,7 @@ These pages are currently hidden from the docs TOC and have `noindexed` meta hea # Index search tools -Index search tools provide intelligent, natural language-driven search over specified {{es}} resources. Instead of defining explicit queries, you specify a pattern of [indices](/manage-data/data-store/index-basics.md), [aliases](/manage-data/data-store/aliases), or [data streams](/manage-data/data-store/data-streams.md), and the tool uses a combination of built-in capabilities to intelligently interpret and execute search requests. +Index search tools provide intelligent, natural language-driven search over specified {{es}} resources. Instead of defining explicit queries, you specify a pattern of [indices](/manage-data/data-store/index-basics.md), [aliases](/manage-data/data-store/aliases.md), or [data streams](/manage-data/data-store/data-streams.md), and the tool uses a combination of built-in capabilities to intelligently interpret and execute search requests. ## When to use index search tools