Skip to content

Commit 5ab4593

Browse files
owaiskazi19kolchfa-awsnatebower
authored
Add documentation for agentic search processors (#11117)
* Add documentation for agentic search processors Signed-off-by: Owais <owaiskazi19@gmail.com> * Doc review and add agentic query Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Fix links Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Addressed PR comments Signed-off-by: Owais <owaiskazi19@gmail.com> * Apply suggestions from code review Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: Nathan Bower <nbower@amazon.com> --------- Signed-off-by: Owais <owaiskazi19@gmail.com> Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Nathan Bower <nbower@amazon.com> Co-authored-by: Fanit Kolchina <kolchfa@amazon.com> Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Nathan Bower <nbower@amazon.com>
1 parent e005909 commit 5ab4593

File tree

8 files changed

+304
-6
lines changed

8 files changed

+304
-6
lines changed

‎_query-dsl/specialized/agentic.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
layout: default
3+
title: Agentic
4+
parent: Specialized queries
5+
nav_order: 2
6+
---
7+
8+
# Agentic query
9+
**Introduced 3.2**
10+
{: .label .label-purple }
11+
12+
Use the `agentic` query to ask questions in natural language and have OpenSearch automatically plan and execute the retrieval. The `agentic` query works in conjunction with a preconfigured agent that reads the question, plans the search, and returns relevant results. For more information about agentic search, see [Agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/).
13+
14+
**Prerequisite**<br>
15+
Before using an `agentic` query, you must configure an agent with the [`QueryPlanningTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/query-planning-tool/) and create a search pipeline with an `agentic_query_translator` search request processor.
16+
{: .note}
17+
18+
## Request body fields
19+
20+
The `agentic` query accepts the following fields.
21+
22+
Field | Data type | Required/Optional | Description
23+
:--- | :--- | :--- | :---
24+
`query_text` | String | Required | The natural language question or request.
25+
`query_fields` | Array | Optional | A list of fields that the agent should consider when generating the search query. If not provided, the agent considers all available fields in the index mapping.
26+
27+
## Example
28+
29+
The following example uses an `agentic` query that asks a natural language question about flowers in an `iris` dataset. In this example, `query_text` contains the natural language question, `query_fields` specifies the fields to use when generating the query, and the `search-pipeline` query parameter specifies the search pipeline containing the agentic query translator processor:
30+
31+
```json
32+
GET /iris-index/_search?search_pipeline=agentic-pipeline
33+
{
34+
"query": {
35+
"agentic": {
36+
"query_text": "List all the flowers present",
37+
"query_fields": ["species", "petal_length_in_cm"]
38+
}
39+
}
40+
}
41+
```
42+
{% include copy-curl.html %}
43+
44+
When executed, the agentic search request performs the following steps:
45+
46+
1. Sends the natural language question, along with the index mapping and a default prompt, to a large language model (LLM).
47+
2. The LLM generates a query domain-specific language (DSL) query based on the input.
48+
3. The generated DSL query is executed as a search request in OpenSearch.
49+
4. Returns the search results based on the generated query.
50+
51+
For a complete example, see [Agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/).
52+
53+
## Next steps
54+
55+
- Learn how to set up agentic search in [Agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/).
56+
- Learn about configuring agents in [Agents]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/).
57+
- Learn about the [QueryPlanningTool]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/query-planning-tool/).

‎_query-dsl/specialized/index.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,14 @@ redirect_from:
1212

1313
OpenSearch supports the following specialized queries:
1414

15-
- `distance_feature`: Calculates document scores based on the dynamically calculated distance between the origin and a document's `date`, `date_nanos`, or `geo_point` fields. This query can skip non-competitive hits.
15+
- [`agentic`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/agentic/): Uses natural language questions that are automatically planned and executed by an agent with a large language model.
1616

17-
- [`more_like_this`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/more-like-this/): Finds documents similar to the provided text, document, or collection of documents.
17+
- [`distance_feature`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/distance-feature/): Calculates document scores based on the dynamically calculated distance between the origin and a document's `date`, `date_nanos`, or `geo_point` fields. This query can skip non-competitive hits.
1818

1919
- [`knn`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/k-nn/): Used for searching raw vectors during [vector search]({{site.url}}{{site.baseurl}}/vector-search/).
2020

21+
- [`more_like_this`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/more-like-this/): Finds documents similar to the provided text, document, or collection of documents.
22+
2123
- [`neural`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/neural/): Used for searching by text or image in [vector search]({{site.url}}{{site.baseurl}}/search-plugins/neural-search/).
2224

2325
- [`neural_sparse`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/neural-sparse/): Used for vector field search in [sparse neural search]({{site.url}}{{site.baseurl}}/search-plugins/neural-sparse-search/).
@@ -30,4 +32,6 @@ OpenSearch supports the following specialized queries:
3032

3133
- [`script_score`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/script-score/): Calculates a custom score for matching documents using a script.
3234

35+
- [`template`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/template/): Allows you to use Mustache templating in queries.
36+
3337
- [`wrapper`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/wrapper/): Accepts other queries as JSON or YAML strings.

‎_query-dsl/specialized/k-nn/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ layout: default
33
title: k-NN
44
parent: Specialized queries
55
has_children: true
6-
nav_order: 10
6+
nav_order: 15
77
redirect_from:
88
- /query-dsl/specialized/k-nn/
99
---

‎_search-plugins/search-pipelines/agentic-context-processor.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
layout: default
3+
title: Agentic context
4+
nav_order: 2
5+
has_children: false
6+
parent: Search processors
7+
grand_parent: Search pipelines
8+
---
9+
10+
# Agentic context processor
11+
**Introduced 3.3**
12+
{: .label .label-purple }
13+
14+
The `agentic_context` search response processor adds agent execution context information to search response extensions. This processor works in conjunction with the [agentic query translator]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/agentic-query-translator-processor/) to expose the agent's query translation process and maintain conversation continuity:
15+
16+
1. The processor retrieves agent context information from the pipeline processing context.
17+
2. Based on the processor configuration, it selectively includes the agent steps summary and the query domain-specific language (DSL) query in the response.
18+
3. The memory ID is always included, when available, for conversation continuity.
19+
4. The context information is added to the search response extensions.
20+
5. Type validation ensures that all context attributes are strings.
21+
22+
## Request body fields
23+
24+
The following table lists all available request fields.
25+
26+
Field | Data type | Description
27+
:--- | :--- | :---
28+
`agent_steps_summary` | Boolean | Whether to include the agent's execution steps summary in the response. Default is `false`. Optional.
29+
`dsl_query` | Boolean | Whether to include the generated DSL query in the response. Default is `false`. Optional.
30+
31+
## Response fields
32+
33+
When enabled, the processor adds the following fields to the search response extensions.
34+
35+
Field | Description
36+
:--- | :---
37+
`agent_steps_summary` | A summary of the steps that the agent took to translate the natural language query (included when `agent_steps_summary` is `true`).
38+
`memory_id` | The conversation memory ID for maintaining context across queries. Only provide this in the `agentic` query if you want to continue the previous conversation.
39+
`dsl_query` | The generated DSL query that was executed (included when `dsl_query` is `true`).
40+
41+
## Example
42+
43+
The following example request creates a search pipeline with an `agentic_context` response processor:
44+
45+
```json
46+
PUT /_search/pipeline/agentic_pipeline
47+
{
48+
"request_processors": [
49+
{
50+
"agentic_query_translator": {
51+
"agent_id": "your-agent-id"
52+
}
53+
}
54+
],
55+
"response_processors": [
56+
{
57+
"agentic_context": {
58+
"agent_steps_summary": true,
59+
"dsl_query": true
60+
}
61+
}
62+
]
63+
}
64+
```
65+
{% include copy-curl.html %}
66+
67+
Perform a search using the configured pipeline:
68+
69+
```json
70+
POST /your-index/_search?search_pipeline=agentic_search_pipeline
71+
{
72+
"query": {
73+
"agentic": {
74+
"query_text": "Show me shoes in white color",
75+
"memory_id": "your memory id"
76+
}
77+
}
78+
}
79+
```
80+
{% include copy-curl.html %}
81+
82+
The response contains the steps taken by the agent to translate the query, the memory ID, and the rewritten DSL query:
83+
84+
```json
85+
{
86+
"took": 15,
87+
"hits": {
88+
"_shards": {...},
89+
"hits": [...]
90+
},
91+
"ext": {
92+
"agent_steps_summary": "I have these tools available: [ListIndexTool, IndexMappingTool, query_planner_tool]\\nFirst I used: ListIndexTool — input: \"\"; context gained: \"Discovered products-index which seems relevant for products and pricing context\"\\nSecond I used: IndexMappingTool — input: \"products-index\"; context gained: \"Confirmed presence of category and price fields in products-index\"\\nThird I used: query_planner_tool — qpt.question: \"Show me shoes that cost exactly 100 dollars.\"; index_name_provided: \"products-index\"\\nValidation: qpt output is valid and accurately reflects the request for shoes priced at 100 dollars.",
93+
"memory_id": "WVhHiJkBnqovov2plcDH",
94+
"dsl_query": "{\"query\":{\"bool\":{\"filter\":[{\"term\":{\"category\":\"shoes\"}},{\"term\":{\"price\":100.0}}]}}}"
95+
}
96+
}
97+
```
98+
99+
## Related pages
100+
101+
- [Agentic search queries]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search)
102+
- [Agents]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/index/)
103+
- [Agentic query translator processor]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/agentic-query-translator-processor/)

‎_search-plugins/search-pipelines/agentic-query-translator-processor.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
layout: default
3+
title: Agentic query translator
4+
nav_order: 5
5+
has_children: false
6+
parent: Search processors
7+
grand_parent: Search pipelines
8+
---
9+
10+
# Agentic query translator processor
11+
**Introduced 3.2**
12+
{: .label .label-purple }
13+
14+
The `agentic_query_translator` search request processor enables natural language search by translating user queries into OpenSearch query domain-specific language (DSL) queries using machine learning (ML) agents. It works with [agentic search queries]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search) to provide conversational search capabilities:
15+
16+
1. The processor sends the user's natural language query to the specified ML agent.
17+
2. The agent translates the query into OpenSearch DSL.
18+
3. The original query is replaced with the generated DSL query.
19+
20+
This processor only works with the `agentic` query type as the top-level query.
21+
{: .note}
22+
23+
## Prerequisites
24+
25+
Before using the `agentic_query_translator` processor, you must have either a conversational or flow agent configured. For more information, see [Agents]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/index/).
26+
27+
## Request body fields
28+
29+
The following table lists all available request fields.
30+
31+
Field | Data type | Description
32+
:--- | :--- | :---
33+
`agent_id` | String | The ID of the ML agent that will translate natural language queries into DSL queries. Required.
34+
35+
36+
## Example
37+
38+
The following example request creates a search pipeline with an `agentic_query_translator` processor:
39+
40+
```json
41+
PUT /_search/pipeline/agentic_search_pipeline
42+
{
43+
"request_processors": [
44+
{
45+
"agentic_query_translator": {
46+
"agent_id": "your-agent-id-here"
47+
}
48+
}
49+
]
50+
}
51+
```
52+
{% include copy-curl.html %}
53+
54+
## Usage
55+
56+
To use the processor, run an `agentic` query:
57+
58+
```json
59+
POST /your-index/_search?search_pipeline=agentic_search_pipeline
60+
{
61+
"query": {
62+
"agentic": {
63+
"query_text": "Show me shoes in white color"
64+
}
65+
}
66+
}
67+
```
68+
{% include copy-curl.html %}
69+
70+
The response contains the matching documents:
71+
72+
```json
73+
{
74+
"took": 6031,
75+
"timed_out": false,
76+
"_shards": {
77+
"total": 8,
78+
"successful": 8,
79+
"skipped": 0,
80+
"failed": 0
81+
},
82+
"hits": {
83+
"total": {
84+
"value": 8,
85+
"relation": "eq"
86+
},
87+
"max_score": 0.0,
88+
"hits": [
89+
{
90+
"_index": "products-index",
91+
"_id": "43",
92+
"_score": 0.0,
93+
"_source": {
94+
"product_name": "Nike Air Max white",
95+
"description": "Red cushioned sneakers",
96+
"price": 140.0,
97+
"currency": "USD",
98+
"in_stock": true,
99+
"color": "white",
100+
"size": "10",
101+
"product_id": "P6001",
102+
"category": "shoes",
103+
"brand": "Nike"
104+
}
105+
},
106+
{
107+
"_index": "products-index",
108+
"_id": "45",
109+
"_score": 0.0,
110+
"_source": {
111+
"product_name": "Adidas Superstar white",
112+
"description": "Classic black sneakers",
113+
"price": 100.0,
114+
"currency": "USD",
115+
"in_stock": true,
116+
"color": "white",
117+
"size": "8",
118+
"product_id": "P6003",
119+
"category": "shoes",
120+
"brand": "Adidas"
121+
}
122+
}
123+
]
124+
}
125+
}
126+
```
127+
128+
## Related pages
129+
130+
- [Agentic search queries]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search)
131+
- [Agents]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/index/)
132+
- [Agentic context processor]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/agentic-context-processor/)

‎_search-plugins/search-pipelines/search-processors.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ The following table lists all supported search request processors.
2222

2323
Processor | Description | Earliest available version
2424
:--- | :--- | :---
25+
[`agentic_query_translator`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/agentic-query-translator-processor/) | Translates `agentic` queries into OpenSearch query domain-specific language (DSL) and executes an agent to process the query. | 3.2
2526
[`filter_query`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/filter-query-processor/) | Adds a filtering query that is used to filter requests. | 2.8
2627
[`ml_inference`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/ml-inference-search-request/) | Invokes registered machine learning (ML) models in order to rewrite queries. | 2.16
2728
[`neural_query_enricher`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/neural-query-enricher/) | Sets a default model for neural search and neural sparse search at the index or field level. | 2.11 (neural), 2.13 (neural sparse)
@@ -37,6 +38,7 @@ The following table lists all supported search response processors.
3738

3839
Processor | Description | Earliest available version
3940
:--- | :--- | :---
41+
[`agentic_context`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/agentic-context-processor/)| Returns the agent summary, generated query, and memory ID for an `agentic` query. | 3.3
4042
[`collapse`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/collapse-processor/)| Deduplicates search hits based on a field value, similarly to `collapse` in a search request. | 2.12
4143
[`hybrid_score_explanation`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/explanation-processor/)| Adds detailed scoring information to search results when the `explain` parameter is enabled, providing information about score normalization, combination techniques, and individual score calculations in hybrid queries. | 2.19
4244
[`ml_inference`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/ml-inference-search-response/) | Invokes registered machine learning (ML) models in order to incorporate model output as additional search response fields. | 2.16
@@ -48,7 +50,6 @@ Processor | Description | Earliest available version
4850
[`split`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/split-processor/)| Splits a string field into an array of substrings based on a specified delimiter. | 2.17
4951
[`truncate_hits`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/truncate-hits-processor/)| Discards search hits after a specified target count is reached. Can undo the effect of the `oversample` request processor. | 2.12
5052

51-
5253
## Search phase results processors
5354

5455
A search phase results processor runs between search phases at the coordinating node level. It intercepts the results retrieved from one search phase and transforms them before passing them to the next search phase.

‎_vector-search/ai-search/agentic-search.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,11 @@ has_children: false
77
---
88

99
# Agentic search
10+
1011
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, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/).
1112
{: .warning}
1213

13-
Introduced 3.2
14+
**Introduced 3.2**
1415
{: .label .label-purple }
1516

1617
Agentic search lets users ask questions in natural language and have OpenSearch plan and execute the retrieval automatically. A preconfigured **agent** reads the question, plans the search, and returns relevant results.

‎_vector-search/api/neural.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ By default, the Neural Search Stats API is disabled through a cluster setting. T
2020
PUT /_cluster/settings
2121
{
2222
"persistent": {
23-
"plugins.neural_search.stats_enabled": "true"
23+
"plugins.neural_search.stats_enabled": true
2424
}
2525
}
2626
```

0 commit comments

Comments
 (0)