Search Template Fill tool
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.
The SearchTemplateFillTool generates an OpenSearch query domain-specific language (DSL) query from a natural language question by filling the parameters of a registered agentic search template. The large language model (LLM) returns only the parameter values, and OpenSearch renders them into the stored Mustache template. The tool falls back to the QueryPlanningTool, which writes the full query, in the following cases:
- No template in
template_idsis usable for the index, for example, because no template is registered for the index or every template’s parameter schema is empty. - The LLM sets
cannot_expressto indicate that no template can express the question or chooses no template. - The LLM response contains no tool call, a value that doesn’t match the parameter schema, or a template that isn’t a candidate.
- The rendered template isn’t a single JSON object.
If reading the registered templates or the LLM call fails, the tool returns the error without falling back.
For a complete example, including how to store and register templates, see Filling search templates.
Prerequisites
Before using the tool, complete the following steps:
- Set
plugins.ml_commons.agentic_search_template_enabledtotrue. The tool isn’t available when multi-tenancy is enabled. - Store one or more search templates and register each one using the Register Agentic Search Template API. For more information, see Register Agentic Search Template API.
- Register an externally hosted model for which the connector
request_bodyincludes${parameters.tool_configs:-},${parameters.system_prompt}, and either${parameters.user_prompt}or${parameters.prompt}.
Step 1: Register a flow agent
The following example registers a flow agent that runs the SearchTemplateFillTool:
POST /_plugins/_ml/agents/_register
{
"name": "template-fill-agent",
"type": "flow",
"tools": [
{
"type": "SearchTemplateFillTool",
"parameters": {
"model_id": "<model_id>",
"_llm_interface": "bedrock/converse/claude",
"response_filter": "$.output.message.content[0].text"
},
"config": {
"template_ids": "[\"product_search\",\"similar_search\"]"
}
}
]
}
Step 2: Execute the agent
Execute the agent by sending the following request:
POST /_plugins/_ml/agents/<agent_id>/_execute
{
"parameters": {
"question": "the 2 most expensive footwear shoes",
"index_name": "products"
}
}
OpenSearch returns the rendered query:
{
"inference_results": [
{
"output": [
{
"name": "response",
"result": "{\"query\":{\"bool\":{\"must\":[{\"match\":{\"title\":\"shoes\"}}],\"filter\":[{\"term\":{\"category\":\"footwear\"}}]}},\"sort\":[{\"price\":\"desc\"}],\"size\":2}"
}
]
}
]
}
Register parameters
The following table lists the parameters that you can set in the tool’s parameters when registering an agent.
| Parameter | Type | Required/Optional | Description |
|---|---|---|---|
model_id | String | Required | The model ID of the LLM that fills the template. The fallback QueryPlanningTool uses the same model. |
_llm_interface | String | Required | The function calling interface of the model. Valid values are bedrock/converse/claude, openai/v1/chat/completions, and gemini/v1beta/generatecontent. |
response_filter | String | Optional | A JSONPath expression that extracts the generated query from the LLM response. Used only by the fallback QueryPlanningTool. See Response filter configuration. |
All other parameters are passed to the fallback QueryPlanningTool. For example, fallback_query and query_planner_system_prompt customize the fallback. For more information, see Query Planning tool register parameters.
The following table lists the fields that you can set in the tool’s config. Execute requests can’t override these fields, so registering an agent with either field in parameters returns an error.
| Field | Type | Required/Optional | Description |
|---|---|---|---|
template_ids | String | Required | The agentic search templates that the agent can fill, as a JSON array of template IDs, for example, "[\"product_search\"]", or as a single template ID. Templates are offered in the listed order. Only templates that are registered for the searched index, have a non-empty parameter schema, and have a stored script that the user can read are used, and at most eight templates are offered. |
fallback_enabled | String | Optional | Whether the tool falls back to the QueryPlanningTool when it can’t fill a template. Valid values are true and false. If false, the tool returns an error instead. Default is true. |
Execute parameters
The following table lists the parameters that you can provide when executing the agent.
| Parameter | Type | Required/Optional | Description |
|---|---|---|---|
question | String | Required | The natural language question. |
index_name | String | Required | The name of the index to search. Templates registered for other indexes are skipped. |
Permissions
When the Security plugin is enabled, the tool reads and renders each stored script as the user running the search, so that user needs the cluster:admin/script/get permission. If the user can’t read a template’s stored script, the tool doesn’t offer that template to the LLM.