From 96ca610a789c51684a387ac41fbcea6b22c7ed1b Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 30 Dec 2025 15:21:11 +0100 Subject: [PATCH 1/4] [agent builder] Document default values for optional params in ESQL tools --- solutions/search/agent-builder/kibana-api.md | 90 ++++++++++++++++++- .../search/agent-builder/tools/esql-tools.md | 45 ++++++++-- 2 files changed, 128 insertions(+), 7 deletions(-) diff --git a/solutions/search/agent-builder/kibana-api.md b/solutions/search/agent-builder/kibana-api.md index ddfe4ef52e..2cd40901ec 100644 --- a/solutions/search/agent-builder/kibana-api.md +++ b/solutions/search/agent-builder/kibana-api.md @@ -12,7 +12,7 @@ applies_to: This page provides a quick overview of the main {{kib}} API endpoints for {{agent-builder}}. For complete details including all available parameters, request/response schemas, and error handling, refer to the [{{kib}} API reference](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-agent-builder). -These APIs allow you to programmatically work with the {{agent-builder}} abstractions. +These APIs enable you to programmatically work with the {{agent-builder}} abstractions. ## Using the APIs @@ -147,6 +147,94 @@ curl -X POST "https://${KIBANA_URL}/api/agent_builder/tools" \ } }' ``` +::: + +:::: + +**Example:** Create a tool with default values for optional parameters {applies_to}`stack: ga 9.3` + +This example creates an ES|QL tool with optional parameters that have default values, which are automatically used when the agent doesn't provide them. + +::::{tab-set} +:group: api-examples-defaults + +:::{tab-item} Console +:sync: console-defaults +```console +POST kbn://api/agent_builder/tools +{ + "id": "sales-analysis-tool", + "type": "esql", + "description": "Analyze sales data with optional time filtering and automatic defaults for unspecified parameters", + "tags": ["analytics", "sales"], + "configuration": { + "query": "FROM sales | WHERE timestamp >= ?start_date AND region == ?region | STATS total_sales=SUM(amount) BY product | LIMIT ?limit", + "params": { + "start_date": { + "type": "date", + "description": "Start date for analysis. When not provided by the agent, defaults to '2024-01-01T00:00:00Z'", + "optional": true, + "defaultValue": "2024-01-01T00:00:00Z" + }, + "region": { + "type": "keyword", + "description": "Sales region to filter by. If omitted, defaults to 'ALL' to include all regions", + "optional": true, + "defaultValue": "ALL" + }, + "limit": { + "type": "integer", + "description": "Maximum results to return. When not specified, automatically limits to 50 results", + "optional": true, + "defaultValue": 50 + } + } + } +} +``` +::: + +:::{tab-item} curl +:sync: curl-defaults +```bash +curl -X POST "https://${KIBANA_URL}/api/agent_builder/tools" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "id": "sales-analysis-tool", + "type": "esql", + "description": "Analyze sales data with optional time filtering and automatic defaults for unspecified parameters", + "tags": ["analytics", "sales"], + "configuration": { + "query": "FROM sales | WHERE timestamp >= ?start_date AND region == ?region | STATS total_sales=SUM(amount) BY product | LIMIT ?limit", + "params": { + "start_date": { + "type": "date", + "description": "Start date for analysis. When not provided by the agent, defaults to \"2024-01-01T00:00:00Z\"", + "optional": true, + "defaultValue": "2024-01-01T00:00:00Z" + }, + "region": { + "type": "keyword", + "description": "Sales region to filter by. If omitted, defaults to \"ALL\" to include all regions", + "optional": true, + "defaultValue": "ALL" + }, + "limit": { + "type": "integer", + "description": "Maximum results to return. When not specified, automatically limits to 50 results", + "optional": true, + "defaultValue": 50 + } + } + } + }' +``` +::: + +:::: + :::{include} _snippets/spaces-api-note.md ::: ::: diff --git a/solutions/search/agent-builder/tools/esql-tools.md b/solutions/search/agent-builder/tools/esql-tools.md index 2a82027b4e..ad933121c7 100644 --- a/solutions/search/agent-builder/tools/esql-tools.md +++ b/solutions/search/agent-builder/tools/esql-tools.md @@ -8,8 +8,6 @@ applies_to: security: unavailable --- - - # {{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. @@ -43,8 +41,42 @@ Use custom **{{esql}} tools** when: 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 +* **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 + + ::::{applies-switch} + + :::{applies-item} { "stack": "ga 9.3" } + + * You must specify a [default value](#default-values-for-optional-parameters) for optional parameters to prevent query errors when agents don't provide them + + ::: + + :::{applies-item} { "stack": "preview 9.2" } + + * You don't need to specify a default value, the agent uses `null` when not provided + + ::: + + :::: + + + +### Default values for optional parameters +```{applies_to} +stack: ga 9.3 +``` + +:::{important} +Support for optional parameters with default values in {{esql}} tools is an API-only feature initially. Default values are required for all optional parameters to prevent query syntax errors. +::: + +Optional parameters must 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 will automatically use the defaults. +When the agent provides a value, it overrides the default. + +Refer to the [API documentation](https://www.elastic.co/docs/api/doc/kibana/operation/operation-post-agent-builder-tools) for details about the {{esql}} tools API. ## Query syntax @@ -70,9 +102,10 @@ You can ask the LLM to infer the parameters for the query or add them manually. ## Best practices - **Include [`LIMIT`](elasticsearch://reference/query-languages/esql/commands/limit.md) 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`) +- **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](#default-values-for-optional-parameters)** for optional parameters: Set sensible defaults for optional parameters to reduce complexity for agents and ensure consistent behavior when parameters are omitted {applies_to}`stack: ga 9.3` ## Limitations @@ -80,4 +113,4 @@ You can ask the LLM to infer the parameters for the query or add them manually. ## {{esql}} documentation -To learn more about the language, refer to the [{{esql}} docs](elasticsearch://reference/query-languages/esql.md). +To learn more about the language, refer to the [{{esql}} docs](elasticsearch://reference/query-languages/esql.md). \ No newline at end of file From 7b65a10f6c7c18bfc2bb2751816e16940c4380d2 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 30 Dec 2025 15:27:25 +0100 Subject: [PATCH 2/4] add cross-refs and links --- solutions/search/agent-builder/kibana-api.md | 2 +- solutions/search/agent-builder/tools/esql-tools.md | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/solutions/search/agent-builder/kibana-api.md b/solutions/search/agent-builder/kibana-api.md index 2cd40901ec..d138326d3a 100644 --- a/solutions/search/agent-builder/kibana-api.md +++ b/solutions/search/agent-builder/kibana-api.md @@ -151,7 +151,7 @@ curl -X POST "https://${KIBANA_URL}/api/agent_builder/tools" \ :::: -**Example:** Create a tool with default values for optional parameters {applies_to}`stack: ga 9.3` +**Example:** Create a tool with [default values](/solutions/search/agent-builder/tools/esql-tools.md#default-values-for-optional-parameters) for optional parameters {applies_to}`stack: ga 9.3` This example creates an ES|QL tool with optional parameters that have default values, which are automatically used when the agent doesn't provide them. diff --git a/solutions/search/agent-builder/tools/esql-tools.md b/solutions/search/agent-builder/tools/esql-tools.md index ad933121c7..2007cb2144 100644 --- a/solutions/search/agent-builder/tools/esql-tools.md +++ b/solutions/search/agent-builder/tools/esql-tools.md @@ -99,6 +99,10 @@ You can ask the LLM to infer the parameters for the query or add them manually. :alt: Creating an ES|QL tool with a parameterized query ::: +:::{note} +For API examples, refer to [](/solutions/search/agent-builder/kibana-api.md#tools) +::: + ## Best practices - **Include [`LIMIT`](elasticsearch://reference/query-languages/esql/commands/limit.md) clauses**: Prevent returning excessive results by setting reasonable limits From 6a50a6ec2917e5fcaea3902778b1df857069d59b Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 30 Dec 2025 15:31:32 +0100 Subject: [PATCH 3/4] use present tense --- 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 2007cb2144..6aee06c775 100644 --- a/solutions/search/agent-builder/tools/esql-tools.md +++ b/solutions/search/agent-builder/tools/esql-tools.md @@ -73,7 +73,7 @@ Support for optional parameters with default values in {{esql}} tools is an API- Optional parameters must 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 will automatically use the defaults. +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](https://www.elastic.co/docs/api/doc/kibana/operation/operation-post-agent-builder-tools) for details about the {{esql}} tools API. From ff0f95f7906ffdea574e992e356fd4b0ec286b2f Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Wed, 31 Dec 2025 10:19:41 +0100 Subject: [PATCH 4/4] setting a default value isn't enforced --- solutions/search/agent-builder/tools/esql-tools.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/solutions/search/agent-builder/tools/esql-tools.md b/solutions/search/agent-builder/tools/esql-tools.md index 6aee06c775..da6f70098a 100644 --- a/solutions/search/agent-builder/tools/esql-tools.md +++ b/solutions/search/agent-builder/tools/esql-tools.md @@ -48,7 +48,7 @@ Parameters can be configured as: :::{applies-item} { "stack": "ga 9.3" } - * You must specify a [default value](#default-values-for-optional-parameters) for optional parameters to prevent query errors when agents don't provide them + * You can specify a [default value](#default-values-for-optional-parameters) for optional parameters to prevent query errors when agents don't provide them ::: @@ -68,10 +68,10 @@ stack: ga 9.3 ``` :::{important} -Support for optional parameters with default values in {{esql}} tools is an API-only feature initially. Default values are required for all optional parameters to prevent query syntax errors. +Support for optional parameters with default values in {{esql}} 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 must have default values that are automatically applied when the agent doesn't provide a value. This ensures valid query syntax and consistent behavior. +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.