Better Answers, Bounded Extra CostDirect search baseline vs Zoom Search workflow |
||
Useful results |
Answer quality |
Extra budget |
1-5 -> 4-12more good sources |
2.0-7.2 -> 7.8-8.7stronger final answers |
+5.9s to +12.2s+2.3k to +5.1k tokens |
Quickstart · Agent Tool · Agents · Benchmarks · Advanced Configuration
Zoom Search is a search and evidence tool for AI agents. It helps agents rewrite search questions, gather broader web evidence, zoom into high-value source domains, and return sourced answers with metrics. It is built for agentic applications that need stronger source discovery, traceability, and answer grounding than a single search call. ## Why Zoom Search - **Agent search tool**: expose structured answers, sources, warnings, and metrics for tool-calling agents. - **Better evidence gathering**: rewrite agent questions into stronger search variants. - **Source-domain zoom-in**: search broadly first, then focus on high-value domains. - **Traceable outputs**: preserve source domains, duplicate provenance, warnings, and runtime metrics. - **MCP/LangGraph ready**: use Zoom Search through MCP or LangGraph integrations. - **Provider-flexible**: use built-in engines or custom OpenAI-compatible and native HTTP providers. ## Install ```bash pip install zoom-search ``` ## Quickstart Run a deterministic local demo without API keys: ```python import asyncio from zoom_search import search async def main() -> None: response = await search( question="What hotels in Shenzhen have rooms with exercise bikes?", demo_mode=True, output_mode="answer_with_sources", seed=7, ) print(response.answer) print(response.results) asyncio.run(main()) ``` ## Agent Tool Example Install the MCP extra: ```bash pip install "zoom-search[mcp]" ``` Add Zoom Search to your MCP client: ```json { "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" } } } } ``` Your agent can then call the `zoom_search` tool with a `question` argument: ```json { "question": "Which vector databases support hybrid search and metadata filtering for Python apps?", "output_mode": "answer_with_sources" } ``` The tool returns sourced answers, source-domain zoom-in, warnings, and runtime metrics. Or wrap it as a LangGraph/LangChain tool: ```python import os from langchain.tools import tool from zoom_search import search @tool async def zoom_search_evidence(query: str) -> dict: response = await search( question=query, llm_engine=os.environ["ZOOM_SEARCH_LLM_ENGINE"], llm_model=os.environ["ZOOM_SEARCH_LLM_MODEL"], llm_api_key=os.environ["ZOOM_SEARCH_LLM_API_KEY"], search_engine=os.environ["ZOOM_SEARCH_SEARCH_ENGINE"], search_api_key=os.environ["ZOOM_SEARCH_SEARCH_API_KEY"], output_mode="answer_with_sources", ) return response.to_dict() ``` See [`docs/agent-integration.md`](./docs/agent-integration.md) for MCP client configuration and provider environment variables. ## Benchmarks Historical evaluations compare direct search against the Zoom Search agent workflow, showing better useful result coverage and stronger final answers with bounded extra time and token cost. | Case | Good results | Answer quality | Extra time | Extra tokens | |---|---:|---:|---:|---:| | Playwright authentication reuse | 5 -> 7 | 6.6 -> 8.7 | +5.89s | +2,324 | | GitHub Actions secrets inherit | 1 -> 4 | 2.0 -> 7.8 | +8.93s | +2,936 | | Hydrangea pruning comparison | 4 -> 12 | 7.2 -> 8.4 | +12.17s | +5,073 | See the full benchmark notes in [`docs/benchmarks.md`](./docs/benchmarks.md). Runnable examples for demo mode, streaming, conversation history, and LangGraph are available in the `examples/` directory. ## Documentation - Advanced configuration: https://github.com/goofrey/zoom-search/blob/main/docs/advanced-configuration.md - Agent integration: https://github.com/goofrey/zoom-search/blob/main/docs/agent-integration.md - Development checks: https://github.com/goofrey/zoom-search/blob/main/docs/development.md - Benchmarks: https://github.com/goofrey/zoom-search/blob/main/docs/benchmarks.md ## License Zoom Search is open source under the [MIT License](./LICENSE).