Filling search templates
Introduced 3.10
This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated GitHub issue.
By default, agentic search asks a large language model (LLM) to write the entire query in query domain-specific language (DSL). With agentic search templates, the LLM fills the parameters of a search template that you register in advance, and OpenSearch renders the stored Mustache template into the query.
Filling templates compared to using them as examples
The following table compares filling search templates with using search templates as examples.
| Using search templates as examples | Filling search templates | |
|---|---|---|
| Configuration | List the stored templates and their descriptions in the search_templates parameter of the QueryPlanningTool. | Register each stored template as an agentic search template. OpenSearch derives a parameter schema from the template. |
| LLM input | The templates, as examples in the prompt | The parameter schema and the question |
| LLM output | The full query DSL | Only the parameter values |
| Query construction | The LLM writes the query and can follow, change, or ignore a template. | OpenSearch renders the stored template using the parameter values. |
| Query structure | Not guaranteed | Always the template structure |
| Value validation | None | OpenSearch checks each value against the type and allowed values in the parameter schema. |
| Output size | A full query, about 300 tokens | A few values, about 5–30 tokens |
| When no template fits | The LLM writes the query without a template. | The LLM declines to fill a template, and the request falls back to an LLM-written query. |
Choosing an approach to filling templates
You can fill templates in either of the following ways:
- In OpenSearch: Register a flow agent with the
SearchTemplateFillTool. The LLM call and rendering run in the cluster. - In the OpenSearch Agent Server: Register a flow agent with a
ConnectorToolthat calls theagentic_searchagent of the OpenSearch Agent Server. The agent server calls its own LLM and renders the template using the cluster’s Render Template API.
Both approaches use the same registered templates and the same search pipeline. Complete the following steps for either approach, and then continue on the page for the approach that you choose.
Agentic search templates are not supported when multi-tenancy is enabled.
Prerequisites
To enable the agentic search template APIs and the SearchTemplateFillTool, update the following cluster setting:
PUT _cluster/settings
{
"persistent": {
"plugins.ml_commons.agentic_search_template_enabled": true
}
}
Step 1: Create an index
Create an index for product data:
PUT /products
{
"mappings": {
"properties": {
"title": { "type": "text" },
"category": { "type": "keyword" },
"price": { "type": "float" }
}
}
}
Ingest sample products into the index:
POST /_bulk
{ "index": { "_index": "products", "_id": "1" } }
{ "title": "leather dress shoes", "category": "footwear", "price": 210.0 }
{ "index": { "_index": "products", "_id": "2" } }
{ "title": "trail running shoes", "category": "footwear", "price": 120.0 }
{ "index": { "_index": "products", "_id": "3" } }
{ "title": "canvas shoes", "category": "footwear", "price": 45.0 }
{ "index": { "_index": "products", "_id": "4" } }
{ "title": "wool hiking socks", "category": "apparel", "price": 18.0 }
Step 2: Store a search template
Store the query structure as a Mustache search template. Write each optional clause as a Mustache section ({{#param}}...{{/param}}) so that the query stays valid when the LLM omits that parameter. The following template requires query_text and size and adds an optional category filter and an optional descending sort:
PUT _scripts/product_search
{
"script": {
"lang": "mustache",
"source": "{\"query\":{\"bool\":{\"must\":[{\"match\":{\"title\":\"{{query_text}}\"}}],\"filter\":[{{#category}}{\"term\":{\"category\":\"{{category}}\"}}{{/category}}]}},{{#sort_by}}\"sort\":[{\"{{sort_by}}\":\"desc\"}],{{/sort_by}}\"size\":{{size}}}"
}
}
Step 3: Register the template for agentic search
Register the stored template as an agentic search template. Specify the index that it searches, and describe what it searches:
POST _plugins/_ml/agentic_search_templates
{
"template_id": "product_search",
"index": "products",
"description": "Product search by title with an optional category filter and an optional descending sort"
}
The response contains the template ID and the registration status:
{
"template_id": "product_search",
"status": "created"
}
During registration, OpenSearch reads the stored template and the index mapping, derives a parameter schema, and verifies that the template renders valid JSON both with all parameters filled and with only the required parameters filled. OpenSearch rejects a template that fails this validation. For more information about the parameter schema, see Register Agentic Search Template API.
OpenSearch derives the allowed values of sort_by from the index mapping fields that can be sorted on, so the LLM can sort by category or price. The title field is a text field, which can’t be used for sorting, so it isn’t listed. To review the derived schema, use the Get Agentic Search Template API. To allow sorting only by price, narrow the sort_by enum using the Update Agentic Search Template API:
PUT _plugins/_ml/agentic_search_templates/product_search
{
"param_schema": {
"sort_by": {
"enum": ["price"]
}
}
}
Step 4: Fill the registered template
To fill the registered template, choose one of the following options:
Managing agentic search templates
To register, retrieve, list, update, or delete agentic search templates, see Agentic search template APIs.
Related documentation
- Search Template Fill tool
- Agentic search template APIs
- Using search templates as examples
- Using flow agents for agentic search
- Search templates