1  ---
  2  title: Research Tools
  3  sidebar_position: 50
  4  ---
  5  
  6  import NetworkAccessRequiredSingleFeature from '@site/docs/partials/network-access-required.mdx';
  7  
  8  # Research Tools
  9  
 10  Agent Mesh provides research tools that enable agents to search the web and conduct comprehensive research on complex topics. These tools give agents access to current information beyond their training data and the ability to synthesize findings from multiple sources into detailed reports.
 11  
 12  ## Overview
 13  
 14  The research tools consist of two categories:
 15  
 16  The web search tools provide direct access to web search engines, allowing agents to retrieve current information, news, and facts. The deep research tool builds on web search to conduct iterative research with LLM-powered reflection and report generation.
 17  
 18  <NetworkAccessRequiredSingleFeature />
 19  
 20  ## Setup and Configuration
 21  
 22  ### Prerequisites
 23  
 24  To use the web search functionality, you need a Google Custom Search API key and a Custom Search Engine ID. You can obtain these from the Google Cloud Console.
 25  
 26  ### Environment Variables
 27  
 28  Set the following environment variables:
 29  
 30  ```bash
 31  export GOOGLE_API_KEY="your_google_api_key_here"
 32  export GOOGLE_CSE_ID="your_custom_search_engine_id_here"
 33  ```
 34  
 35  ### Enabling the Tools
 36  
 37  Enable the research tools in your agent's `app_config.yml`:
 38  
 39  ```yaml
 40  tools:
 41    - tool_type: builtin-group
 42      group_name: "web_search"
 43  
 44    - tool_type: builtin-group
 45      group_name: "research"
 46  ```
 47  
 48  You can also enable individual tools:
 49  
 50  ```yaml
 51  tools:
 52    - tool_type: builtin
 53      tool_name: "web_search_google"
 54    - tool_type: builtin
 55      tool_name: "deep_research"
 56  ```
 57  
 58  ### Tool Configuration
 59  
 60  Both tools accept configuration through the `tool_config` block:
 61  
 62  ```yaml
 63  - tool_type: builtin
 64    tool_name: "web_search_google"
 65    tool_config:
 66      google_search_api_key: ${GOOGLE_API_KEY}
 67      google_cse_id: ${GOOGLE_CSE_ID}
 68  
 69  - tool_type: builtin
 70    tool_name: "deep_research"
 71    tool_config:
 72      google_search_api_key: ${GOOGLE_API_KEY}
 73      google_cse_id: ${GOOGLE_CSE_ID}
 74      max_iterations: 5
 75      max_runtime_seconds: 300
 76      sources:
 77        - web
 78  ```
 79  
 80  ## Web Search Tool
 81  
 82  The `web_search_google` tool searches the web using Google Custom Search API and returns results with source citations.
 83  
 84  ### Parameters
 85  
 86  | Parameter | Type | Description |
 87  |-----------|------|-------------|
 88  | `query` | string | The search query (required) |
 89  | `max_results` | integer | Maximum number of results to return (1-10, default: 5) |
 90  | `search_type` | string | Set to `"image"` for image search |
 91  | `date_restrict` | string | Restrict results by recency (for example, `"d7"` for last 7 days) |
 92  | `safe_search` | string | Safe search level: `"off"`, `"medium"`, or `"high"` |
 93  
 94  ### Usage Examples
 95  
 96  A basic web search:
 97  ```
 98  Search the web for "latest developments in quantum computing"
 99  ```
100  
101  An image search:
102  ```
103  Search for images of "aurora borealis"
104  ```
105  
106  A search with date restriction:
107  ```
108  Search for news about "AI regulations" from the last 7 days
109  ```
110  
111  ### Response Format
112  
113  The tool returns search results with the following information for each result:
114  - Title and URL of the source
115  - A text snippet from the page
116  - Attribution information for citations
117  - Favicon URL for display purposes
118  
119  The results include metadata that enables automatic citation rendering in the UI. Agents should cite sources using the citation format provided in their instructions.
120  
121  :::info
122  Image results are displayed automatically in the UI. Agents should not cite images or mention image URLs in their response text.
123  :::
124  
125  ## Deep Research Tool
126  
127  The `deep_research` tool conducts comprehensive, iterative research across multiple sources. It uses LLM-powered reflection to identify knowledge gaps and refine search queries, then synthesizes findings into a detailed report with proper citations.
128  
129  ### How Deep Research Works
130  
131  The deep research process follows these steps:
132  
133  1. The tool breaks down the research question into multiple search queries using LLM analysis
134  2. It searches across configured sources (currently web search, with knowledge base support planned)
135  3. The LLM reflects on the findings to assess completeness and identify gaps
136  4. Based on the reflection, the tool generates refined queries and conducts additional searches
137  5. The tool selects the most authoritative sources and fetches their full content
138  6. Finally, it synthesizes all findings into a comprehensive report with citations
139  
140  Throughout this process, the tool sends progress updates to the frontend, allowing users to see the current research phase, queries being executed, and sources being analyzed.
141  
142  ### Parameters
143  
144  | Parameter | Type | Description |
145  |-----------|------|-------------|
146  | `research_question` | string | The research question or topic to investigate (required) |
147  | `research_type` | string | `"quick"` (5 min, 3 iterations) or `"in-depth"` (10 min, 10 iterations) |
148  | `max_iterations` | integer | Maximum research iterations (1-10, overrides research_type) |
149  | `max_runtime_minutes` | integer | Maximum runtime in minutes (1-10, overrides research_type) |
150  | `max_runtime_seconds` | integer | Maximum runtime in seconds (60-600) |
151  | `sources` | array | Sources to search: `["web"]` or `["web", "kb"]` |
152  | `kb_ids` | array | Specific knowledge base IDs to search (when `"kb"` is in sources) |
153  
154  ### Configuration Priority
155  
156  The tool resolves configuration in this order (highest to lowest priority):
157  
158  1. Explicit parameters passed to the tool
159  2. Values from `tool_config` in the agent configuration
160  3. Defaults based on `research_type` ("quick" or "in-depth")
161  
162  ### Research Types
163  
164  The `research_type` parameter provides convenient presets:
165  
166  | Type | Duration | Iterations | Use Case |
167  |------|----------|------------|----------|
168  | `quick` | 5 minutes | 3 | Fast answers, simple topics |
169  | `in-depth` | 10 minutes | 10 | Complex topics, comprehensive analysis |
170  
171  ### Advanced Configuration
172  
173  You can configure phase-specific models for cost optimization or quality control:
174  
175  ```yaml
176  - tool_type: builtin
177    tool_name: "deep_research"
178    tool_config:
179      google_search_api_key: ${GOOGLE_API_KEY}
180      google_cse_id: ${GOOGLE_CSE_ID}
181      
182      # Use faster models for query generation and reflection
183      models:
184        query_generation: "gpt-4o-mini"
185        reflection: "gpt-4o-mini"
186        source_selection: "gpt-4o-mini"
187      
188      # Use a more capable model for report generation
189      model_configs:
190        report_generation:
191          model: "claude-3-5-sonnet-20241022"
192          temperature: 0.7
193          max_tokens: 16000
194  ```
195  
196  ### Usage Examples
197  
198  A quick research request:
199  ```
200  Research the current state of renewable energy adoption in Europe
201  ```
202  
203  An in-depth research request:
204  ```
205  Conduct in-depth research on the economic impact of artificial intelligence on the job market over the next decade
206  ```
207  
208  A research request with specific parameters:
209  ```
210  Research quantum computing applications in drug discovery. Use 5 iterations and limit to 3 minutes.
211  ```
212  
213  ### Output
214  
215  The deep research tool produces:
216  
217  1. A comprehensive research report saved as a Markdown artifact
218  2. Metadata with all sources and citations for UI rendering
219  3. Progress updates throughout the research process
220  
221  The report includes:
222  - Executive summary
223  - Introduction with context
224  - Main analysis organized by themes
225  - Comparative analysis of different perspectives
226  - Implications and conclusions
227  - References section with all cited sources
228  - Research methodology section
229  
230  ### Progress Updates
231  
232  During research, the tool sends structured progress updates that include:
233  - Current phase (planning, searching, analyzing, writing)
234  - Progress percentage
235  - Current iteration and total iterations
236  - Number of sources found
237  - Current search query
238  - URLs being fetched
239  
240  These updates enable rich UI visualizations of the research process.
241  
242  ## Required Scopes
243  
244  The research tools require the following scopes for authorization:
245  
246  | Tool | Required Scope |
247  |------|----------------|
248  | `web_search_google` | `tool:web_search:execute` |
249  | `deep_research` | `tool:research:deep_research` |
250  
251  ## Alternative Search Providers
252  
253  The built-in web search uses Google Custom Search API. For other search providers such as Exa, Brave, or Tavily, use the corresponding plugins from the solace-agent-mesh-plugins repository.
254  
255  ## Technical Considerations
256  
257  ### Rate Limits
258  
259  Google Custom Search API has usage limits. Monitor your API usage and implement appropriate rate limiting for production deployments.
260  
261  ### Content Fetching
262  
263  When the deep research tool fetches full content from web pages, some sites may block automated requests or return incomplete content. The tool handles these failures gracefully and continues with available sources.
264  
265  ### Report Quality
266  
267  The quality of research reports depends on:
268  - The quality and relevance of search results
269  - The number of iterations and sources analyzed
270  - The capabilities of the LLM used for report generation
271  
272  For best results, use capable models for the report generation phase and allow sufficient iterations for complex topics.