This project demonstrates how to design, orchestrate, and deploy a safe, tool‑grounded, multi‑agent developer assistant using Google Agent Development Kit (ADK) and Gemini models.
The system implements a strictly routed multi‑agent architecture where a central RootAgent orchestrates specialist agents for:
The result is an opinionated developer‑intelligence toolkit that prioritizes safety, determinism, and architectural clarity, while remaining extensible for real‑world production use. This ADK Toolkit is designed not only for AI developers, since it supports a wide range of technical and non-technical users such as Ready Tensor users, ML Engineers, Researchers, Technical Writers.
google_searchThis toolkit supports a broad range of users across the AI development lifecycle. By combining specialist agents with explicit tool constraints, users can retrieve high‑signal information, execute safe code, and access authoritative references without managing agent complexity directly.
The following table gives an overview of use cases that illustrate how different user roles can leverage the toolkit to address role-specific needs, highlighting its flexibility, practical relevance, and applicability beyond expert AI practitioners.
| User Role | Value Delivered | Example Use Cases |
|---|---|---|
| ML Engineers | AI tooling insights | Compare open‑source models, frameworks |
| Backend Engineers | AI relevance without ML overhead | Identify deployable AI tools |
| MLOps Engineers | Deployment signals | Assess model maturity and ops readiness |
| Tech Leads | Strategic summaries | Weekly AI trend overviews |
| Dev Advocates | Clear narratives | Explain AI articles to non‑experts |
| Product Managers | Competitive insight | Open‑source vs proprietary analysis |
| Researchers | Research‑to‑practice bridge | Discover implementations of papers |
| Students | Guided learning | Learn Python and AI tooling |
The application is built using a state-aware, RootAgent-centric multi-agent architecture powered by Google ADK and Gemini models.
At a high level, the system consists of:
The below table shows the main Agent Responsibilities
| Agent | Purpose | Capabilities | Constraints |
|---|---|---|---|
| RootAgent | Central router and orchestrator | • Intent detection • Deterministic routing • Delegation to specialist agents | • Never answers directly • No tool calls • Delegation only |
| AIDevSearchAgent | AI developer news discovery | • Search AI dev news • Headline extraction • Structured summaries • Uses google_search | • AI content only • Must use google_search• No code execution |
| CodeAgent | Safe Python execution | • Execute Python code • Return raw output or errors | • Python only • No filesystem • No network • No explanations |
| CodeExplainAgent | Explain Python code | • Step-by-step explanation • Highlight logic and pitfalls | • No execution • No code modification |
| HuggingFaceAgent | Canonical HF references | • Validate exact HF IDs • Return official URLs | • Exact IDs only • No guessing • No recommendations |
| GitHubAgent | GitHub repository inspection | • Fetch repo metadata • Stars, issues, PRs • Recent activity via MCP | • Explicit owner/repo required• No discovery • No inference |
This system architecture is intentionally described using two parallel lanes:
Keeping these lanes separate makes authority, responsibility, and trust boundaries explicit.
The Control Flow lane represents decision‑making and orchestration, entirely owned by the RootAgent.
Key rules:
This guarantees a single, auditable decision point and prevents hidden agent autonomy.
╔═══════════════════════════════════════════════════════════════════════════════════════════════════╗ ║ CONTROL FLOW ║ ║ (Decision, routing, orchestration – ADK) ║ ╠═══════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ ┌─────────────────────────────────────────────────────────────────────────────────────┐ ║ ║ │ ADK Web UI │ ║ ║ │ - User prompts │ ║ ║ │ - Headline selection │ ║ ║ └──────────────────────────┬──────────────────────────────────────────────────────────┘ ║ ║ ▼ ║ ║ ┌─────────────────────────────────────────────────────────────────────────────────────┐ ║ ║ │ RootAgent │ ║ ║ │ (Gemini 2.5 Flash – Router / Orchestrator) │ ║ ║ │ │ ║ ║ │ - Intent classification │ ║ ║ │ - Delegation (AgentTool) │ ║ ║ │ - Result aggregation │ ║ ║ └───────┬──────────────┬──────────────┬──────────────┬───────────────────────┬────────┘ ║ ║ │ │ │ │ │ ║ ║ ▼ ▼ ▼ ▼ ▼ ║ ║ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ ║ ║ │ AIDevSearch │ │ CodeAgent │ │ CodeExplain │ │ HuggingFace │ │ GitHub │ ║ ║ │ Agent │ │ │ │ Agent │ │ Agent │ │ Agent │ ║ ║ │ (Gemini Tool)│ │ (Gemini Tool)│ │ (Gemini Tool) │ │ (Gemini Tool) │ │ (Gemini Tool) │ ║ ║ └──────────────┘ └──────────────┘ └────────────────┘ └────────────────┘ └────────────────┘ ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════════════════════════╝
The Data Flow lane represents execution, transport, and I/O paths. These flows may:
Important: transport differences do not imply authority. All flows still originate from RootAgent decisions.
╔════════════════════════════════════════════════════════════════════════════════════════════════════╗ ║ DATA FLOW ║ ║ (Execution, transport, external systems) ║ ╠════════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ ┌─────────────────────┐ ┌──────────────────────────────┐ ┌──────────────────────────────┐ ║ ║ │ google_search (ADK) │ │ BuiltInCodeExecutor │ │ CodeExplain │ ║ ║ └─────────┬───────────┘ │ (Python sandbox, no net/fs) │ │ (Python sandbox, no net/fs) │ ║ ║ │ └─────────┬────────────────────┘ └─────────┬────────────────────┘ ║ ║ ▼ ▼ ▼ ║ ║ External search results Python execution output Python explanation output ║ ║ ║ ║ ┌─────────────────────┐ ┌────────────────────────────────┐ ║ ║ │ HF MCP Server │ │ GitHub MCP Server │ ║ ║ │ (stdio, local proc) │ │ (HTTP, remote Copilot MCP) │ ║ ║ └─────────┬───────────┘ └─────────┬──────────────────────┘ ║ ║ │ │ ║ ║ ▼ ▼ ║ ║ Hugging Face Hub GitHub Platform ║ ║ - models - repos ║ ║ - datasets - issues / PRs ║ ║ - spaces - commits / releases ║ ║ ║ ╚════════════════════════════════════════════════════════════════════════════════════════════════════╝
This section provides a concise, authoritative mapping between agents, tools, and execution backends. It complements the architecture diagrams by making attachments, responsibilities, and transport mechanisms explicit.
| Component | Type | Attached To | Purpose |
|---|---|---|---|
| AIDevSearchAgent | AgentTool | RootAgent | Discover & summarize AI developer news |
| CodeAgent | AgentTool | RootAgent | Execute Python code safely |
| CodeExplainAgent | AgentTool | RootAgent | Explain Python code safely |
| hugging_face_agent | AgentTool + MCP | RootAgent | Hugging Face data (models, datasets, spaces) access |
| github_agent | AgentTool + MCP | RootAgent | GitHub insights |
| google_search | ADK Tool | AIDevSearchAgent | Web discovery |
| BuiltInCodeExecutor | ADK Executor | CodeAgent | Deterministic Python sandbox |
Why this matters:
This pubblication has a GitHub code repository attached also under the Code section.
git clone https://github.com/micag2025/Toolkit_Google_ADK.git cd Toolkit_Google_ADK python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt
Set environment variables (keys) in .env or your environment. See example .env.example.
GEMINI_API_KEY=your_gemini_api_key HF_API_KEY=your_hf_api_key GIT_API_KEY=your_github_api_key ADK_DEV_MODE=true
Start the ADK Web app:
adk web
ADK will provide a local URL. Open it in your browser. From the Google ADK user interface in the left pane, select the app_01 agent. You can now interact with the ADK AI Developer.
Stop the ADK process (if needed):
pkill -f "adk web"
This enhanced instruction pattern includes:
This creates a much more reliable and focused agent behavior.
You can test the enhanced multi-agent system using both valid and invalid prompts. A full set of reproducible test prompts and expected behaviors is provided in the accompanying GitHub repository.
After selecting the appropriate app (app_01) from the dropdown menu from the ADK Web UI, below is a high-signal, comprehensive set of prompt examples designed to systematically test the application end-to-end, aligned with the agent architecture, routing rules, MCP integrations, and UI flows.
Note : Different Run Results: The output generated can vary with each execution due to their dynamic, probabilistic nature.
Some built-in ADK tools (for example google_search and code execution) typically cannot be combined within a single agent instance.
Workaround:
SearchAgent, CodeAgent)AgentTool.create()This preserves architectural clarity while respecting ADK constraints.
LLM responses may vary between runs, even with identical inputs.
Mitigation:
Usage is subject to Vertex AI / Google Cloud quotas and billing limits.
Recommendation:
Contributions are welcomed to improve the ADK Toolkit! Suggested workflow:
git checkout -b feat/your-feature
Please follow the repository code style and add tests for major features.
We actively welcome contributors who want to help extend the system without compromising its architectural guarantees. The following items represent suggested and validated directions for future work.
Intentional Model Selection : The current implementation uses gemini-2.5-flash across agents. A promising improvement is to intentionally mix Gemini models by responsibility. For example, upgrading AIDevSearchAgent to gemini-2.5-pro and evaluating trade-offs enables controlled experimentation around quality vs cost vs latency, while preserving RootAgent orchestration.
Additional AgentTools : Add new AgentTools without destabilizing existing flows, preserving RootAgent-only delegation and avoiding agent-to-agent invocation chains.
Structured Outputs: Produce machine-readable JSON outputs for headlines and summaries . Enable downstream automation and evaluation pipelines.
Session & State Management: Persistent session storage across restarts. Reproducible conversations and debugging support.
Search & Retrieval Refinements : Filters (e.g. only open-source). Date ranges and recency controls. Improved relevance scoring.
UI & Observability : UI buttons for explicit selection and confirmation. Debug / observability modes. Clear visibility into control vs data flow at runtime.
Stronger Execution Guardrails : Tighter resource limits. Enhanced sandbox policies. Explicit failure modes and reporting.
Feel free to suggest more ideas by opening an issue or starting a discussion! For bug reports or feature requests,
open an issue.
This project is licensed under the MIT License. See the LICENSE file for details.
An acknowledgement to Ready Tensor developer community for creating a vibrant ecosystem where AI professionals can share projects, insights, and innovations, playing a meaningful role in accelerating the advancement of AI technology and in shaping practical, real-world developer tools such as this project.