Skip to content

Commit 6ac3aaf

Browse files
owaiskazi19owaiskazi19
committed
Add documentation for agentic search processors
Signed-off-by: Owais <[email protected]>
1 parent 949fe90 commit 6ac3aaf

File tree

4 files changed

+228
-1
lines changed

4 files changed

+228
-1
lines changed

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

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
layout: default
3+
title: Agentic context
4+
nav_order: 70
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/agentic-query-translator/) to provide transparency into the agent's query translation process and maintain conversation continuity.
15+
16+
## Request body fields
17+
18+
The following table lists all available request fields.
19+
20+
Field | Data type | Description
21+
:--- | :--- | :---
22+
`agent_steps_summary` | Boolean | Whether to include the agent's execution steps summary in the response. Default is `false`. Optional.
23+
`dsl_query` | Boolean | Whether to include the generated DSL query in the response. Default is `false`. Optional.
24+
25+
## Response fields
26+
27+
When enabled, the processor adds the following fields to the search response extensions:
28+
29+
Field | Description
30+
:--- | :---
31+
`agent_steps_summary` | A summary of the steps the agent took to translate the natural language query (included when `agent_steps_summary` is `true`)
32+
`dsl_query` | The generated DSL query that was executed (included when `dsl_query` is `true`)
33+
34+
## Example
35+
36+
The following example request creates a search pipeline with an `agentic_context` response processor:
37+
38+
```json
39+
PUT /_search/pipeline/agentic_pipeline
40+
{
41+
"request_processors": [
42+
{
43+
"agentic_query_translator": {
44+
"agent_id": "your-agent-id"
45+
}
46+
}
47+
],
48+
"response_processors": [
49+
{
50+
"agentic_context": {
51+
"agent_steps_summary": true,
52+
"dsl_query": true
53+
}
54+
}
55+
]
56+
}
57+
```
58+
{% include copy-curl.html %}
59+
60+
## Usage
61+
62+
When you perform a search with the configured pipeline, the response will include agent context information:
63+
64+
```json
65+
POST /your-index/_search?search_pipeline=agentic_search_pipeline
66+
{
67+
"query": {
68+
"agentic": {
69+
"query_text": "Show me shoes in white color",
70+
"memory_id": "your memory id"
71+
}
72+
}
73+
}
74+
```
75+
{% include copy-curl.html %}
76+
77+
### Example response
78+
79+
```json
80+
{
81+
"took": 15,
82+
"hits": {
83+
"_shards": {...},
84+
"hits": [...]
85+
},
86+
"ext": {
87+
"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.",
88+
"memory_id": "WVhHiJkBnqovov2plcDH",
89+
"dsl_query": "{\"query\":{\"bool\":{\"filter\":[{\"term\":{\"category\":\"shoes\"}},{\"term\":{\"price\":100.0}}]}}}"
90+
}
91+
}
92+
```
93+
94+
## How it works
95+
96+
1. The processor retrieves agent context information from the pipeline processing context
97+
2. Based on configuration, it selectively includes agent steps summary and DSL query
98+
3. Memory ID is always included when available for conversation continuity
99+
4. The context information is added to the search response extensions
100+
5. Type validation ensures all context attributes are strings

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

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

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ Processor | Description | Earliest available version
2828
[`neural_sparse_two_phase_processor`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/neural-sparse-query-two-phase-processor/) | Accelerates the neural sparse query. | 2.15
2929
[`oversample`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/oversample-processor/) | Increases the search request `size` parameter, storing the original value in the pipeline state. | 2.12
3030
[`script`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/script-processor/) | Adds a script that is run on newly indexed documents. | 2.8
31+
[`agentic_query_translator`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/agentic-query-translator-processor/) | Executes agent for agentic query | 3.2
3132

3233
## Search response processors
3334

@@ -47,6 +48,7 @@ Processor | Description | Earliest available version
4748
[`sort`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/sort-processor/)| Sorts an array of items in either ascending or descending order. | 2.16
4849
[`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
4950
[`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
51+
[`agentic_context`]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/agentic-context-processor/)| Used for agentic query to return agent summary, generated query and memory id | 3.3
5052

5153

5254
## Search phase results processors

‎_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)