Content
# ADK MCP A2A - Agent Development Kit with MCP and A2A Integration
This project demonstrates the integration of **Google Agent Development Kit (ADK)**, **Model Context Protocol (MCP)**, and **Agent2Agent (A2A)** protocol to create a sophisticated multi-agent system with web search capabilities.
## 🏗️ Architecture Overview
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MCP Server │ │ A2A Agent │ │ Search Client │
│ (Web Search) │◄───┤ (ADK) │◄───┤ Agent │
│ │ │ │ │ (A2A Client) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
▲ ▲ ▲
│ │ │
Google Custom Gemini API A2A Protocol
Search API
```
## 🚀 Features
- **🔍 Web Search**: Google Custom Search API integration via MCP
- **🤝 A2A Protocol**: Agent-to-agent communication
- **🧠 ADK Integration**: Google Agent Development Kit powered agents
- **📡 Callback System**: Before/after agent callbacks for extensibility
- **🌊 Streaming Support**: Real-time streaming responses
- **🔄 Multi-turn Conversations**: Context-aware interactions
## 📋 Prerequisites
### 1. Python Environment
- Python 3.10 or higher
- `uv` package manager (recommended) or `pip`
### 2. API Credentials
#### Google API Setup
1. **Gemini API Key**:
- Visit [Google AI Studio](https://aistudio.google.com/)
- Create an API key for Gemini models
2. **Google Custom Search**:
- Get API key from [Google Developers Console](https://developers.google.com/custom-search/v1/introduction)
- Create Custom Search Engine at [Google CSE](https://cse.google.com/cse/)
- Configure to search the entire web
## ⚙️ Installation
### 1. Clone and Setup
```bash
git clone <repository-url>
cd adk_mcp_a2a
```
### 2. Install Dependencies
```bash
# Using uv (recommended)
uv sync
# Or using pip
pip install -e .
```
### 3. Environment Configuration
Create a `.env` file in the project root:
```env
# Required: Gemini API access
GOOGLE_API_KEY=your_gemini_api_key_here
# Required: Google Custom Search
GOOGLE_SEARCH_ENGINE_ID=your_search_engine_id_here
# Optional: A2A agent URL (default: http://localhost:10000)
AGENT_URL=http://localhost:10000
# Optional: MCP server port (default: 8080)
PORT=8080
```
## 🚀 Running the Application
### Step 1: Start the MCP Server
The MCP server provides web search capabilities via Google Custom Search API.
```bash
# Terminal 1: Start MCP server
python mcp-server/server.py
```
**Expected output:**
```
[INFO]: 🚀 MCP server started on port 8080
[INFO]: ✅ Web search tool loaded
```
**Test the MCP server:**
```bash
# In another terminal
python mcp-server/test_server.py
```
### Step 2: Start an A2A Agent Server (Optional)
If you have an A2A agent server, start it on port 10000:
```bash
# Terminal 2: Start your A2A agent server
# (This depends on your specific A2A agent implementation)
```
### Step 3: Run the Search Client Agent
The Search Client Agent connects to A2A agents and provides callback-driven interactions.
```bash
# Terminal 3: Run search client agent examples
python search_client_agent/run_search_agent.py
# Or run in interactive mode
python search_client_agent/run_search_agent.py interactive
# Or test streaming functionality
python search_client_agent/run_search_agent.py streaming
# Or demo custom callbacks
python search_client_agent/run_search_agent.py custom-callbacks
```
### Step 4: Test A2A Client Functionality
Test the basic A2A client functionality:
```bash
# Terminal 4: Test A2A client
python search_client_agent/test_client.py
```
## 🧪 Testing & Examples
### 1. MCP Server Tests
```bash
# Test web search functionality
python mcp-server/test_server.py
```
### 2. Search Client Agent Tests
```bash
# Run all examples with callbacks
python search_client_agent/run_search_agent.py examples
# Interactive mode
python search_client_agent/run_search_agent.py interactive
# Streaming search
python search_client_agent/run_search_agent.py streaming
# Custom callbacks demonstration
python search_client_agent/run_search_agent.py custom-callbacks
```
### 3. Direct A2A Testing
```bash
# Test A2A protocol directly
python search_client_agent/test_client.py
```
## 📁 Project Structure
```
adk_mcp_a2a/
├── README.md # This file
├── .env # Environment configuration
├── .gitignore # Git ignore rules
├── pyproject.toml # Python project configuration
├── uv.lock # Dependency lock file
│
├── mcp-server/ # MCP Server Implementation
│ ├── server.py # Main MCP server with web search
│ ├── test_server.py # MCP server tests
│ └── Dockerfile # Docker configuration
│
└── search_client_agent/ # A2A Search Client Agent
├── __init__.py # Package initialization
├── search_client_agent.py # Main search client agent
├── test_client.py # A2A client tests
└── run_search_agent.py # Agent runner with multiple modes
```
## 🔧 Configuration
### Environment Variables
| Variable | Required | Description | Default |
|----------|----------|-------------|---------|
| `GOOGLE_API_KEY` | ✅ | Gemini API key | - |
| `GOOGLE_SEARCH_ENGINE_ID` | ✅ | Google Custom Search Engine ID | - |
| `AGENT_URL` | ❌ | A2A agent server URL | `http://localhost:10000` |
| `PORT` | ❌ | MCP server port | `8080` |
### MCP Server Configuration
The MCP server (`mcp-server/server.py`) provides:
- `get_exchange_rate`: Currency conversion tool
- `search_web`: Web search via Google Custom Search API
- `save_to_audit_db`: Audit logging functionality
### Search Client Agent Configuration
The Search Client Agent supports:
- **Before Agent Callbacks**: Execute logic before sending requests
- **After Agent Callbacks**: Process responses after receiving them
- **Error Callbacks**: Handle failures and errors
- **Session Management**: Multi-turn conversation support
## 💡 Usage Examples
### Interactive Web Search
```bash
python search_client_agent/run_search_agent.py interactive
```
Example interaction:
```
💬 Search query: Who is the Miss Universe 2025 winner?
🔍 Processing your request...
✅ Search completed!
📋 Response: [Detailed search results with current information]
```
### Custom Callbacks
```python
# Example custom callback
async def my_before_agent_callback(query: str, context: dict) -> dict:
print(f"Processing query: {query}")
context['enhanced'] = True
return context
# Add to agent
agent = SearchClientAgent()
agent.add_before_agent_callback(my_before_agent_callback)
```
## 🐛 Troubleshooting
### Common Issues
1. **"Google API credentials not configured"**
```bash
# Check your .env file
cat .env
# Verify GOOGLE_API_KEY and GOOGLE_SEARCH_ENGINE_ID are set
```
2. **MCP connection failed**
```bash
# Check if MCP server is running
curl http://localhost:8080/health
# Restart MCP server
python mcp-server/server.py
```
3. **A2A agent not responding**
```bash
# Check if A2A agent is running on the specified port
curl http://localhost:10000
# Verify AGENT_URL in .env
```
4. **Import errors**
```bash
# Reinstall dependencies
uv sync
# Or with pip
pip install -e .
```
### Debug Mode
Enable detailed logging by modifying the agents:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
## 🔗 API References
- [Google ADK Documentation](https://google.github.io/adk-docs/)
- [A2A Samples Repository](https://github.com/google-a2a/a2a-samples)
- [Model Context Protocol](https://github.com/modelcontextprotocol)
- [Google Custom Search API](https://developers.google.com/custom-search/v1/introduction)
## 🚀 Advanced Usage
### Docker Deployment
```bash
# Build MCP server
cd mcp-server
docker build -t mcp-server .
docker run -p 8080:8080 --env-file ../.env mcp-server
```
### Custom Agent Development
Extend the search client agent:
```python
from search_client_agent import SearchClientAgent
class MyCustomAgent(SearchClientAgent):
async def custom_search_logic(self, query: str):
# Your custom logic here
return await self.search_web(query, num_results=10)
```
### Multi-Agent Orchestration
Create complex workflows:
```python
# Coordinate multiple agents
agent1 = SearchClientAgent(agent_url="http://localhost:10001")
agent2 = SearchClientAgent(agent_url="http://localhost:10002")
# Parallel searches
results = await asyncio.gather(
agent1.search_web("AI news"),
agent2.search_web("Tech trends")
)
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Update documentation
6. Submit a pull request
## 📄 License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
## 🙏 Acknowledgments
- Google ADK Team for the Agent Development Kit
- A2A Protocol contributors
- Model Context Protocol community
- FastMCP library authors
---
**Happy Agent Building! 🤖✨**
