diff --git a/solutions/search/agent-builder/kibana-api.md b/solutions/search/agent-builder/kibana-api.md index ddfe4ef52e..d138326d3a 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](/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. + +::::{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..da6f70098a 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 can 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. 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](https://www.elastic.co/docs/api/doc/kibana/operation/operation-post-agent-builder-tools) for details about the {{esql}} tools API. ## Query syntax @@ -67,12 +99,17 @@ 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 -- **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 +117,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