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..61c45922af --- /dev/null +++ b/solutions/search/agent-builder/tools/esql-tools.md @@ -0,0 +1,64 @@ +--- +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}}](elasticsearch://reference/query-languages/esql.md) 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 + +## {{esql}} documentation + +To learn more about the language, refer to the [{{esql}} docs](elasticsearch://reference/query-languages/esql.md). 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..fc6fb8cae5 --- /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](/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 + +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-*` +* **All resources**: `*` diff --git a/solutions/toc.yml b/solutions/toc.yml index 325671d671..421471886f 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,8 @@ toc: - hidden: search/agent-builder/chat.md - hidden: search/agent-builder/agent-builder-agents.md - hidden: search/agent-builder/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 @@ -458,13 +460,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 +747,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