# Research Multi-Agent Tool

## Overview
- Coordinates a team of specialized ADK agents to deliver end-to-end research workflows (search ➜ extraction ➜ synthesis)
- Built on Google ADK abstractions (`LlmAgent`, `LiteLlm`, ADK tool contracts) with per-agent instructions and shared error handling
- Designed to run inside an ADK host process with local MCP tooling for web search and Crawl4AI-based content analysis

## Repository Layout
- `researcher/agent_module/agent.py` — Root coordinator agent exposed to ADK
- `researcher/agent_module/search_agent.py` — DuckDuckGo-backed discovery agent provisioned via MCP Toolset
- `researcher/agent_module/content_extractor.py` — Crawl4AI-powered extractor producing structured JSON (Pydantic schema in `schema.py`)
- `researcher/agent_module/writer.py` — Summarization agent that composes short/medium/long writeups from cached content
- `researcher/agent_module/schema.py` — Pydantic models describing extraction payloads for downstream consumers

## Prerequisites
- Python 3.10+ with `uv` available for MCP subprocess execution
- Running ADK host with local VLLM endpoint exposed at `http://localhost:8002/v1`
- Installed dependencies:
  - `google-adk` package and transitive requirements
  - `crawl4ai` with browser backend (Chromium/Playwright) accessible to the runtime
  - `dotenv` for environment configuration

## Environment Configuration
1. Copy `.env.example` (if available) to `.env` and populate required secrets (API keys, MCP credentials, etc.).
2. Ensure supporting environment variables are present when the ADK process starts:
   - Any Crawl4AI / Playwright configuration, e.g., `PLAYWRIGHT_BROWSERS_PATH`
   - DuckDuckGo MCP settings (see the MCP server README)
   - Optional overrides you add for the model endpoint; the current code defaults to `http://localhost:8002/v1`
3. The modules call `load_dotenv()` at import time, so changes to `.env` apply on the next process start.

## How It Works
1. `agent.py` instantiates three specialized agents and wraps them as ADK tools.
2. The root `research_coordinator` agent receives user instructions, decides which tool to invoke, and orchestrates multi-step flows.
3. Error callbacks return degradable messages, keeping the coordinator responsive despite downstream issues.
4. Intermediate state (e.g., extracted markdown or saved content) lives in `ToolContext.state`, enabling later steps to reuse data.

### Agent Responsibilities
- **search_agent**: Crafts queries, uses the DuckDuckGo MCP server via `uv run python google_search_mcp.py`, and returns structured search hit summaries.
- **content_extractor**: Leverages `AsyncWebCrawler` and `LLMExtractionStrategy` to convert a single URL into the schema defined in `schema.py`.
- **writer**: Reads stored content from tool state, choosing summary length (`short`, `medium`, `long`) and formatting the response.

## Running the Agents
1. Start required services (local VLLM, MCP search server, Crawl4AI browser dependencies).
2. Launch the ADK runtime pointing at the `researcher.agent_module.agent.root_agent`.
3. Interact through ADK (CLI, web UI, or API). The coordinator will call subordinate agents as needed.

## Extending the System
- Add new specialists by creating modules that return `LlmAgent` or `FunctionTool` instances and register them in `agent.py`.
- Use the shared `on_tool_error_callback` to keep failure handling consistent.
- Store reusable data in `ToolContext.state` with clear key names to avoid collisions.
- Update `schema.py` to capture additional metadata, ensuring downstream consumers and extractor instructions stay aligned.

## Operational Considerations
- Monitor MCP subprocess lifecycles; long-lived searches should enforce tighter timeouts and retries via `MCPToolset`.
- Crawl4AI can be resource-intensive; consider enabling caching (switch from `CacheMode.BYPASS`) once Stable storage is configured.
- All agents currently share the same LiteLlm settings; parameterize through environment variables if scaling horizontally.

## Testing & Verification
- Unit-test pure utilities (e.g., schema validations) with `pytest`.
- Create integration tests that mock LPC responses to verify multi-agent orchestration.
- Run smoke tests against staging MCP servers before deploying to production ADK hosts.

## Maintenance Checklist
- Keep MCP server scripts (`google_search_mcp.py`) and browser drivers in sync with upstream versions.
- Rotate any API keys or secrets referenced in the `.env`.
- Review tool instructions periodically to maintain alignment with evolving research workflows.

## Security & Hardening Notes
- Ensure MCP servers and VLLM endpoints require authentication when exposed beyond localhost.
- Validate and sanitize URLs before passing them to Crawl4AI to avoid SSRF or local file access.
- Consider rate limiting or sandboxing to mitigate malicious content fetched during extraction.
- Log tool invocations and failures for auditing; redact user-provided secrets from logs.