Skip to content

Commit da5b8cc

Browse files
Naarcha-AWSNaarcha-AWS
authored
Merge branch 'main' into rw-separation
2 parents 2b7dbe0 + add4af9 commit da5b8cc

File tree

3 files changed

+348
-18
lines changed

3 files changed

+348
-18
lines changed

‎_ml-commons-plugin/agents-tools/tools/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ Each tool takes a list of parameters specific to that tool. In the preceding exa
4747
|[`SearchMonitorsTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/search-monitors-tool/) | Searches for alerting monitors. |
4848
|[`VectorDBTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/vector-db-tool/) |Performs dense vector retrieval. |
4949
|[`VisualizationTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/visualization-tool/) |Finds visualizations in OpenSearch Dashboards. |
50+
|[`WebSearchTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/web-search-tool/) |Answers a user's question using a web search. |
5051

5152
## Developer information
5253

‎_ml-commons-plugin/agents-tools/tools/web-search-tool.md

+322
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,322 @@
1+
---
2+
layout: default
3+
title: Web search tool
4+
has_children: false
5+
has_toc: false
6+
nav_order: 130
7+
parent: Tools
8+
grand_parent: Agents and tools
9+
---
10+
11+
<!-- vale off -->
12+
# Web search tool
13+
**Introduced 3.0**
14+
{: .label .label-purple }
15+
<!-- vale on -->
16+
17+
The `WebSearchTool` retrieves search results based on a user's question. It supports [Google](#using-google-as-a-search-engine), Bing, and [DuckDuckGo](#using-duckduckgo-as-a-search-engine) as search engines or can use a [custom API](#using-a-custom-api-as-a-search-engine) to perform searches.
18+
19+
## Using DuckDuckGo as a search engine
20+
21+
To use DuckDuckGo as a search engine with the `WebSearchTool`, follow these steps.
22+
23+
### Step 1: Register a flow agent that will run the WebSearchTool
24+
25+
A flow agent runs a sequence of tools in order and returns the last tool's output. To create a flow agent, send the following register agent request:
26+
27+
```json
28+
POST /_plugins/_ml/agents/_register
29+
{
30+
"name": "Test_Agent_For_WebSearch_tool",
31+
"type": "flow",
32+
"description": "this is a test agent for the WebSearchTool",
33+
"tools": [
34+
{
35+
"type": "WebSearchTool",
36+
"name": "DuckduckgoWebSearchTool",
37+
"parameters": {
38+
"engine": "duckduckgo",
39+
"input": "${parameters.question}"
40+
}
41+
}
42+
]
43+
}
44+
```
45+
{% include copy-curl.html %}
46+
47+
For parameter descriptions, see [Register parameters](#register-parameters).
48+
49+
OpenSearch responds with an agent ID:
50+
51+
```json
52+
{
53+
"agent_id": "9X7xWI0Bpc3sThaJdY9i"
54+
}
55+
```
56+
57+
### Step 2: Run the agent
58+
59+
Then, run the agent by sending the following request (DuckDuckGo doesn't require any credentials):
60+
61+
```json
62+
POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute
63+
{
64+
"parameters": {
65+
"question": "How to create a index pattern in OpenSearch?"
66+
}
67+
}
68+
```
69+
{% include copy-curl.html %}
70+
71+
OpenSearch returns the web search results:
72+
73+
```json
74+
{
75+
"inference_results": [
76+
{
77+
"output": [
78+
{
79+
"name": "response",
80+
"result": """
81+
{
82+
"next_page": "https://html.duckduckgo.com/html?q=how+to+create+index+pattern+in+OpenSearch&ia=web&dc=11",
83+
"items": [
84+
{
85+
"url": "http://someurl",
86+
"title": "the page result title",
87+
"content": "the page content..."
88+
},
89+
{
90+
"url": "https://anotherurl",
91+
"title": "the page result title",
92+
"content": "the page content..."
93+
}
94+
...
95+
]
96+
}
97+
"""
98+
}
99+
]
100+
}
101+
]
102+
}
103+
```
104+
105+
## Using Google as a search engine
106+
107+
To use Google as a search engine with the `WebSearchTool`, follow these steps.
108+
109+
### Step 1: Register a flow agent that will run the WebSearchTool
110+
111+
A flow agent runs a sequence of tools in order and returns the last tool's output. To create a flow agent, send the following register agent request:
112+
113+
```json
114+
POST /_plugins/_ml/agents/_register
115+
{
116+
"name": "Test_Agent_For_WebSearch_tool",
117+
"type": "flow",
118+
"description": "this is a test agent for the WebSearchTool",
119+
"tools": [
120+
{
121+
"type": "WebSearchTool",
122+
"name": "GoogleWebSearchTool",
123+
"parameters": {
124+
"engine": "google",
125+
"engine_id": "${your_google_engine_id}",
126+
"api_key": "${your_google_api_key}",
127+
"input": "${parameters.question}"
128+
}
129+
}
130+
]
131+
}
132+
```
133+
{% include copy-curl.html %}
134+
135+
For parameter descriptions, see [Register parameters](#register-parameters).
136+
137+
OpenSearch responds with an agent ID:
138+
139+
```json
140+
{
141+
"agent_id": "9X7xWI0Bpc3sThaJdY9i"
142+
}
143+
```
144+
145+
### Step 2: Run the agent
146+
147+
Before you run the agent, ensure that you have obtained the credentials needed to access Google search programmatically.
148+
149+
Then, run the agent by sending the following request:
150+
151+
```json
152+
POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute
153+
{
154+
"parameters": {
155+
"question": "How to create a index pattern in OpenSearch?"
156+
}
157+
}
158+
```
159+
{% include copy-curl.html %}
160+
161+
OpenSearch returns the web search results:
162+
163+
```json
164+
{
165+
"inference_results": [
166+
{
167+
"output": [
168+
{
169+
"name": "response",
170+
"result": """
171+
{
172+
"next_page": "https://customsearch.googleapis.com/customsearch/v1?q=how+to+create+index+pattern+in+OpenSearch&start=10",
173+
"items": [
174+
{
175+
"url": "http://someurl",
176+
"title": "the page result title",
177+
"content": "the page content..."
178+
},
179+
{
180+
"url": "https://anotherurl",
181+
"title": "the page result title",
182+
"content": "the page content..."
183+
}
184+
...
185+
]
186+
}
187+
"""
188+
}
189+
]
190+
}
191+
]
192+
}
193+
```
194+
195+
## Using a custom API as a search engine
196+
197+
To use a custom API as a search engine with the `WebSearchTool`, follow these steps.
198+
199+
### Step 1: Register a flow agent that will run the WebSearchTool
200+
201+
To use a custom endpoint for search, you need to configure the following parameters:
202+
203+
- `Authorization`: For authentication
204+
- `endpoint`: For the API connection
205+
- `custom_res_url_jsonpath`: For parsing the JSON response and extracting links
206+
207+
Your API must return responses in JSON format. The links returned by the API must be retrievable using [JSONPath](https://en.wikipedia.org/wiki/JSONPath) expressions. Other parameters like `query_key`, `offset_key`, and `limit_key` are optional but should be specified if your API uses different values than the defaults.
208+
209+
To create a flow agent, send the following register agent request:
210+
211+
```json
212+
POST /_plugins/_ml/agents/_register
213+
{
214+
"name": "Test_Agent_For_WebSearch_tool",
215+
"type": "flow",
216+
"description": "this is a test agent for the WebSearchTool",
217+
"tools": [
218+
{
219+
"type": "WebSearchTool",
220+
"name": "CustomWebSearchTool",
221+
"parameters": {
222+
"engine": "custom",
223+
"endpoint": "${your_custom_endpoint}",
224+
"custom_res_url_jsonpath": "$.data[*].link",
225+
"Authorization": "Bearer xxxx",
226+
"query_key": "q",
227+
"offset_key": "offset",
228+
"limit_key": "limit"
229+
}
230+
}
231+
]
232+
}
233+
```
234+
{% include copy-curl.html %}
235+
236+
For parameter descriptions, see [Register parameters](#register-parameters).
237+
238+
OpenSearch responds with an agent ID:
239+
240+
```json
241+
{
242+
"agent_id": "9X7xWI0Bpc3sThaJdY9i"
243+
}
244+
```
245+
246+
### Step 2: Run the agent
247+
248+
Before you run the agent, ensure that you have obtained the credentials needed to access your custom search API programmatically.
249+
250+
Then, run the agent by sending the following request:
251+
252+
```json
253+
POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute
254+
{
255+
"parameters": {
256+
"question": "How to create a index pattern in OpenSearch?"
257+
}
258+
}
259+
```
260+
{% include copy-curl.html %}
261+
262+
OpenSearch returns the web search results:
263+
264+
```json
265+
{
266+
"inference_results": [
267+
{
268+
"output": [
269+
{
270+
"name": "response",
271+
"result": """
272+
{
273+
"next_page": "{your_custom_endpoint}?q=how+to+create+index+pattern+in+OpenSearch&offset=10&limit=10",
274+
"items": [
275+
{
276+
"url": "http://someurl",
277+
"title": "the page result title",
278+
"content": "the page content..."
279+
},
280+
{
281+
"url": "https://anotherurl",
282+
"title": "the page result title",
283+
"content": "the page content..."
284+
}
285+
...
286+
]
287+
}
288+
"""
289+
}
290+
]
291+
}
292+
]
293+
}
294+
```
295+
296+
297+
298+
## Register parameters
299+
300+
The following table lists all tool parameters that are available when registering an agent.
301+
302+
303+
304+
| Parameter | Type | Required/Optional | Description |
305+
|:---|:---|:---|:---|
306+
| `engine` | String | Required | The search engine to use. Valid values are `google`, `bing`, `duckduckgo`, or `custom`. |
307+
| `engine_id` | String | Optional | The Custom Search Engine ID for Google. Required when `engine` is set to `google`. |
308+
| `api_key` | String | Optional | The API key for authentication. Required when `engine` is set to `google` or `bing`. |
309+
| `endpoint` | String | Optional | The URL endpoint for the custom search API. Required when `engine` is set to `custom`. |
310+
| `Authorization` | String | Optional | The authorization header value for the custom API. Required when `engine` is set to `custom`. |
311+
| `query_key` | String | Optional | The parameter name for the search query in the custom API URL (for example, `${endpoint}?my_query_key=${question}`). Default is `q`. |
312+
| `offset_key` | String | Optional | The parameter name for the pagination offset in the custom API URL (for example, `${endpoint}?q=${question}&start=10`). Default is `offset`. |
313+
| `limit_key` | String | Optional | The parameter name for the result limit in the custom API URL (for example, `${endpoint}?q=${question}&start=10&limit=10`). Default is `limit`. |
314+
| `custom_res_url_jsonpath` | String | Optional | The JSONPath expression used to extract URLs from the custom API response (for example, `$[*].link`). Required when `engine` is set to `custom`. |
315+
316+
## Execute parameters
317+
318+
The following table lists all tool parameters that are available when running the agent.
319+
320+
Parameter | Type | Required/Optional | Description
321+
:--- | :--- | :--- | :---
322+
`question` | String | Required | The natural language question to send to the LLM.

0 commit comments

Comments
 (0)