Agent Integration

Zoom Search can be used as an evidence-retrieval tool inside an agent loop. The agent calls Zoom Search when it needs grounded web evidence, then consumes a structured response containing the answer draft, source list, warnings, and runtime metrics.

This keeps the core search workflow independent while making it easy to plug into LangGraph, LangChain, or other tool-calling agents.

LangGraph / LangChain Tool

See examples/langgraph_tool.py for a minimal async tool wrapper.

from langchain.tools import tool

from zoom_search import search


@tool
async def zoom_search_evidence(query: str, include_raw_diagnostics: bool = False) -> dict:
    """Search for grounded web evidence and return answer, sources, warnings, and metrics."""

    response = await search(
        question=query,
        output_mode="answer_with_sources",
        include_raw_diagnostics=include_raw_diagnostics,
    )
    payload = {
        "request_id": response.request_id,
        "answer": response.answer,
        "sources": response.results,
        "metrics": response.metrics,
        "warnings": response.warnings,
    }
    if include_raw_diagnostics:
        payload["raw_diagnostics"] = response.raw_diagnostics
    return payload

In production, pass real providers and API keys the same way as the standard Zoom Search API:

response = await search(
    question=query,
    llm_engine="gemini",
    llm_model="gemini-2.5-flash",
    llm_api_key="YOUR_GEMINI_API_KEY",
    search_engine="tavily",
    search_api_key="YOUR_TAVILY_API_KEY",
    output_mode="answer_with_sources",
)

Tool Output Shape

The recommended agent-facing output is JSON-like and reviewable:

{
    "request_id": "...",
    "answer": "...",
    "sources": [
        {
            "title": "...",
            "snippet": "...",
            "url": "...",
            "source_domain": "...",
        }
    ],
    "metrics": {
        "elapsed_ms": 1234,
        "search_requests": {...},
        "llm_usage": {...},
    },
    "warnings": [],
}

Agents can use this output to:

• answer with citations
• inspect source provenance before final response generation
• decide whether to run follow-up searches
• track quality, latency, token use, and search request cost
• expose warnings or low-confidence retrieval paths for human review

Why Use Zoom Search As An Agent Tool

• Query refinement improves source discovery before the agent writes an answer.
• Source-domain zoom-in gives the agent deeper evidence from high-value domains.
• Duplicate provenance and source domains make outputs easier to inspect.
• Metrics make agent behavior easier to evaluate and regress-test.

MCP Server Adapter

Zoom Search also ships an optional stdio MCP server that exposes a zoom_search tool.

Install MCP support:

pip install "zoom-search[mcp]"

Run the server:

zoom-search-mcp

For real providers, pass credentials through environment variables in your MCP client configuration:

{
  "mcpServers": {
    "zoom-search": {
      "command": "zoom-search-mcp",
      "env": {
        "ZOOM_SEARCH_LLM_ENGINE": "gemini",
        "ZOOM_SEARCH_LLM_MODEL": "gemini-2.5-flash",
        "ZOOM_SEARCH_LLM_API_KEY": "YOUR_GEMINI_API_KEY",
        "ZOOM_SEARCH_SEARCH_ENGINE": "tavily",
        "ZOOM_SEARCH_SEARCH_API_KEY": "YOUR_TAVILY_API_KEY"
      }
    }
  }
}

The MCP tool accepts:

{
  "question": "Which vector databases support hybrid search and metadata filtering for Python apps?",
  "previous_conversation": [],
  "output_mode": "answer_with_sources",
  "demo_mode": false,
  "zoomout_num_results": 5,
  "zoomin_num_results": 5,
  "top_k_domains_per_query": 1,
  "include_raw_diagnostics": false
}

For local no-key demos, call the tool with demo_mode: true. For reliability testing, set include_raw_diagnostics: true to include raw LLM response diagnostics for query rewriting and answer synthesis. Keep it disabled for normal agent calls.

The server reads these environment variables:

Variable	Purpose
ZOOM_SEARCH_LLM_ENGINE	Built-in LLM provider engine, e.g. gemini, deepseek, or openai
ZOOM_SEARCH_LLM_MODEL	Provider model name
ZOOM_SEARCH_LLM_API_KEY	LLM provider API key
ZOOM_SEARCH_LLM_BASE_URL	Optional LLM base URL override
ZOOM_SEARCH_SEARCH_ENGINE	Built-in search engine, e.g. tavily, serpapi, or brave
ZOOM_SEARCH_SEARCH_API_KEY	Search provider API key
ZOOM_SEARCH_SEARCH_BASE_URL	Optional search base URL override
ZOOM_SEARCH_DEMO_MODE	Set to true for demo-mode default