Skip to main content

# Research Tools

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.

## Overview​

The research tools consist of two categories:

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.

## Setup and Configuration​

### Prerequisites​

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.

### Environment Variables​

Set the following environment variables:

    export GOOGLE_API_KEY="your_google_api_key_here"
    export GOOGLE_CSE_ID="your_custom_search_engine_id_here"

### Enabling the Tools​

Enable the research tools in your agent's `app_config.yml`:

    tools:
      - tool_type: builtin-group
        group_name: "web_search"

      - tool_type: builtin-group
        group_name: "research"

You can also enable individual tools:

    tools:
      - tool_type: builtin
        tool_name: "web_search_google"
      - tool_type: builtin
        tool_name: "deep_research"

### Tool Configuration​

Both tools accept configuration through the `tool_config` block:

    - tool_type: builtin
      tool_name: "web_search_google"
      tool_config:
        google_search_api_key: ${GOOGLE_API_KEY}
        google_cse_id: ${GOOGLE_CSE_ID}

    - tool_type: builtin
      tool_name: "deep_research"
      tool_config:
        google_search_api_key: ${GOOGLE_API_KEY}
        google_cse_id: ${GOOGLE_CSE_ID}
        max_iterations: 5
        max_runtime_seconds: 300
        sources:
          - web

## Web Search Tool​

The `web_search_google` tool searches the web using Google Custom Search API and returns results with source citations.

### Parameters​

Parameter | Type | Description
--- | --- | ---
`query` | string | The search query (required)
`max_results` | integer | Maximum number of results to return (1-10, default: 5)
`search_type` | string | Set to `"image"` for image search
`date_restrict` | string | Restrict results by recency (for example, `"d7"` for last 7 days)
`safe_search` | string | Safe search level: `"off"`, `"medium"`, or `"high"`

### Usage Examples​

A basic web search:

    Search the web for "latest developments in quantum computing"

An image search:

    Search for images of "aurora borealis"

A search with date restriction:

    Search for news about "AI regulations" from the last 7 days

### Response Format​

The tool returns search results with the following information for each result:

- Title and URL of the source
- A text snippet from the page
- Attribution information for citations
- Favicon URL for display purposes

The results include metadata that enables automatic citation rendering in the UI. Agents should cite sources using the citation format provided in their instructions.

info

Image results are displayed automatically in the UI. Agents should not cite images or mention image URLs in their response text.

## Deep Research Tool​

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.

### How Deep Research Works​

The deep research process follows these steps:

1. The tool breaks down the research question into multiple search queries using LLM analysis
2. It searches across configured sources (currently web search, with knowledge base support planned)
3. The LLM reflects on the findings to assess completeness and identify gaps
4. Based on the reflection, the tool generates refined queries and conducts additional searches
5. The tool selects the most authoritative sources and fetches their full content
6. Finally, it synthesizes all findings into a comprehensive report with citations

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.

### Parameters​

Parameter | Type | Description
--- | --- | ---
`research_question` | string | The research question or topic to investigate (required)
`research_type` | string | `"quick"` (5 min, 3 iterations) or `"in-depth"` (10 min, 10 iterations)
`max_iterations` | integer | Maximum research iterations (1-10, overrides research_type)
`max_runtime_minutes` | integer | Maximum runtime in minutes (1-10, overrides research_type)
`max_runtime_seconds` | integer | Maximum runtime in seconds (60-600)
`sources` | array | Sources to search: `["web"]` or `["web", "kb"]`
`kb_ids` | array | Specific knowledge base IDs to search (when `"kb"` is in sources)

### Configuration Priority​

The tool resolves configuration in this order (highest to lowest priority):

1. Explicit parameters passed to the tool
2. Values from `tool_config` in the agent configuration
3. Defaults based on `research_type` ("quick" or "in-depth")

### Research Types​

The `research_type` parameter provides convenient presets:

Type | Duration | Iterations | Use Case
--- | --- | --- | ---
`quick` | 5 minutes | 3 | Fast answers, simple topics
`in-depth` | 10 minutes | 10 | Complex topics, comprehensive analysis

### Advanced Configuration​

You can configure phase-specific models for cost optimization or quality control:

    - tool_type: builtin
      tool_name: "deep_research"
      tool_config:
        google_search_api_key: ${GOOGLE_API_KEY}
        google_cse_id: ${GOOGLE_CSE_ID}

        # Use faster models for query generation and reflection
        models:
          query_generation: "gpt-4o-mini"
          reflection: "gpt-4o-mini"
          source_selection: "gpt-4o-mini"

        # Use a more capable model for report generation
        model_configs:
          report_generation:
            model: "claude-3-5-sonnet-20241022"
            temperature: 0.7
            max_tokens: 16000

### Usage Examples​

A quick research request:

    Research the current state of renewable energy adoption in Europe

An in-depth research request:

    Conduct in-depth research on the economic impact of artificial intelligence on the job market over the next decade

A research request with specific parameters:

    Research quantum computing applications in drug discovery. Use 5 iterations and limit to 3 minutes.

### Output​

The deep research tool produces:

1. A comprehensive research report saved as a Markdown artifact
2. Metadata with all sources and citations for UI rendering
3. Progress updates throughout the research process

The report includes:

- Executive summary
- Introduction with context
- Main analysis organized by themes
- Comparative analysis of different perspectives
- Implications and conclusions
- References section with all cited sources
- Research methodology section

### Progress Updates​

During research, the tool sends structured progress updates that include:

- Current phase (planning, searching, analyzing, writing)
- Progress percentage
- Current iteration and total iterations
- Number of sources found
- Current search query
- URLs being fetched

These updates enable rich UI visualizations of the research process.

## Required Scopes​

The research tools require the following scopes for authorization:

Tool | Required Scope
--- | ---
`web_search_google` | `tool:web_search:execute`
`deep_research` | `tool:research:deep_research`

## Alternative Search Providers​

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.

## Technical Considerations​

### Rate Limits​

Google Custom Search API has usage limits. Monitor your API usage and implement appropriate rate limiting for production deployments.

### Content Fetching​

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.

### Report Quality​

The quality of research reports depends on:

- The quality and relevance of search results
- The number of iterations and sources analyzed
- The capabilities of the LLM used for report generation

For best results, use capable models for the report generation phase and allow sufficient iterations for complex topics.