Content
# GDG-29 A2A Multi-Agent System
A distributed multi-agent system built on the [A2A (Agent-to-Agent) Protocol](https://a2a-protocol.org/) demonstrating orchestrated agent communication with specialized capabilities for web search and Airbnb interactions.
## 🏗️ Architecture
This project implements a multi-agent architecture where:
- **Orchestrator Agent** (`client/`) - Coordinates multiple specialized agents using Google ADK
- **Web Search Agent** (`web-agent-server/`) - Performs web searches using Google Serper API
- **Airbnb Agent** (`airbnb-agent-server/`) - Interacts with Airbnb listings via MCP (Model Context Protocol)
- **API Bridge** (`client/api_server.py`) - FastAPI server connecting React frontend to A2A orchestrator
- **Web Frontend** (`web/`) - React application for user interaction
```
┌─────────────┐
│ Web UI │ (React + TypeScript)
│ (Port 5173)│
└──────┬──────┘
│ HTTP/SSE
┌──────▼──────────┐
│ API Bridge │ (FastAPI)
│ (Port 8000) │
└──────┬──────────┘
│ A2A Protocol
┌──────▼──────────────┐
│ Orchestrator │ (Google ADK)
│ (Port 9999) │
└──────┬─────────────┘
│
├─────────────┬─────────────┐
│ │ │
┌──────▼──────┐ ┌───▼──────┐ ┌───▼──────┐
│ Web Search │ │ Airbnb │ │ ... │
│ Agent │ │ Agent │ │ │
│ (Port 9999) │ │(Port 9998)│ │ │
└─────────────┘ └──────────┘ └──────────┘
```
## 📁 Project Structure
```
gdg-29-a2a/
├── client/ # Orchestrator agent & API bridge
│ ├── orchestrator/
│ │ └── agent.py # Root orchestrator agent
│ ├── api_server.py # FastAPI bridge server
│ ├── client.py # A2A client example
│ └── pyproject.toml # Python dependencies
│
├── web-agent-server/ # Web search agent
│ ├── agents/
│ │ ├── web_search_agent.py
│ │ └── websearch_agent_executor.py
│ ├── main.py # A2A server entry point
│ └── pyproject.toml
│
├── airbnb-agent-server/ # Airbnb agent
│ ├── airbnb/
│ │ └── agent.py # Airbnb agent with MCP tools
│ └── pyproject.toml
│
└── web/ # React frontend
├── src/
│ ├── components/ # UI components
│ ├── services/ # API client
│ └── types/ # TypeScript types
├── package.json
└── README.md # Frontend-specific docs
```
## 🚀 Getting Started
### Prerequisites
- **Python 3.12+** (for orchestrator and agents)
- **Python 3.13+** (for specialized agents)
- **Node.js 18+** and **npm 9+** (for web frontend)
- **Poetry** (for Python dependency management)
- **Google ADK** access (for agent orchestration)
- **Google Serper API Key** (for web search agent)
- **Environment variables** configured (see below)
### Environment Variables
Create `.env` files in each service directory:
#### `client/.env`
```bash
A2A_SERVER_URL=http://localhost:9999
API_PORT=8000
```
#### `web-agent-server/.env`
```bash
SERPER_API_KEY=your_serper_api_key_here
```
#### `web/.env`
```bash
VITE_API_BASE_URL=http://localhost:8000
```
### Installation
#### 1. Install Python Dependencies
```bash
# Orchestrator & API Bridge
cd client
poetry install
# Web Search Agent
cd ../web-agent-server
poetry install
# Airbnb Agent
cd ../airbnb-agent-server
poetry install
```
#### 2. Install Web Frontend Dependencies
```bash
cd web
npm install
```
### Running the System
You need to run all services simultaneously. Use separate terminal windows or a process manager.
#### Terminal 1: Web Search Agent
```bash
cd web-agent-server
poetry run python main.py
```
Agent runs on `http://localhost:9999`
#### Terminal 2: Airbnb Agent
```bash
cd airbnb-agent-server
poetry run python -m airbnb.agent
```
Agent runs on `http://localhost:9998`
#### Terminal 3: Orchestrator & API Bridge
```bash
cd client
poetry run python api_server.py
```
API runs on `http://localhost:8000`
#### Terminal 4: Web Frontend
```bash
cd web
npm run dev
```
Frontend runs on `http://localhost:5173`
### Quick Start Script
Alternatively, use the provided start script:
```bash
cd client
./start.sh
```
## 🔧 Technology Stack
### Backend
- **Google ADK** - Agent Development Kit for orchestration
- **A2A SDK** - Agent-to-Agent protocol implementation
- **FastAPI** - High-performance API framework
- **LangChain** - Agent framework (web search agent)
- **MCP** - Model Context Protocol (Airbnb integration)
- **Uvicorn** - ASGI server
### Frontend
- **React 19** - UI framework
- **TypeScript** - Type safety
- **Vite** - Build tool
- **Tailwind CSS** - Styling
- **shadcn/ui** - UI components
- **React Markdown** - Markdown rendering
### Agents
- **Gemini 2.5 Flash** - LLM for orchestrator and Airbnb agent
- **Kimi K2 Instruct** - LLM for web search agent
- **Google Serper API** - Web search capabilities
## 🎯 Features
### Multi-Agent Orchestration
- Root orchestrator agent coordinates specialized agents
- Plan-ReAct planner for task decomposition
- Dynamic agent selection based on user queries
### Agent Capabilities
#### Web Search Agent
- Performs real-time web searches
- Processes search results with LLM
- Streaming responses for real-time updates
#### Airbnb Agent
- Searches Airbnb listings
- Interacts with Airbnb via MCP tools
- Provides listing details and availability
### Frontend Features
- **Real-time streaming** - SSE (Server-Sent Events) for live responses
- **Rich content rendering** - Text, files, data, and error parts
- **Markdown support** - Formatted text with syntax highlighting
- **Error handling** - Graceful error recovery with retry
- **Type safety** - Full TypeScript coverage
## 📡 API Endpoints
### API Bridge (`http://localhost:8000`)
- `GET /` - Health check
- `GET /api/health` - Detailed health status
- `POST /api/a2a/send` - Send message (non-streaming)
- `POST /api/a2a/send-stream` - Send message (streaming via SSE)
### Agent Endpoints
- `http://localhost:9999/.well-known/agent-card` - Web search agent card
- `http://localhost:9998/.well-known/agent-card` - Airbnb agent card
## 🔍 Development
### Adding a New Agent
1. Create agent server directory
2. Implement agent executor following A2A protocol
3. Register agent card with capabilities
4. Add to orchestrator in `client/orchestrator/agent.py`:
```python
new_agent = RemoteA2aAgent(
name="new_agent",
description="Agent description",
agent_card=f"http://localhost:PORT/.well-known/agent-card",
)
root_agent = LlmAgent(
...
tools=[..., AgentTool(new_agent)]
)
```
### Testing
```bash
# Test orchestrator client
cd client
poetry run python client.py
# Test web search agent
cd web-agent-server
poetry run python main.py
# Test API bridge
curl http://localhost:8000/api/health
```
## 📚 Documentation
- [A2A Protocol Documentation](https://a2a-protocol.org/)
- [Google ADK Documentation](https://github.com/google/generative-ai-python/tree/main/google/adk)
- [Frontend README](./web/README.md) - Detailed frontend documentation
- [Markdown Support](./web/MARKDOWN_SUPPORT.md) - Frontend markdown features
- [Thinking Blocks](./web/THINKING_BLOCKS.md) - Agent thinking visualization
## 🐛 Troubleshooting
### Port Conflicts
Ensure ports 8000, 9999, 9998, and 5173 are available.
### Agent Connection Issues
- Verify all agents are running before starting orchestrator
- Check agent card endpoints are accessible
- Review A2A_SERVER_URL configuration
### API Errors
- Check environment variables are set correctly
- Verify A2A SDK version compatibility
- Review logs for detailed error messages
### Frontend Issues
- Clear browser cache and restart dev server
- Check CORS configuration in `api_server.py`
- Verify `VITE_API_BASE_URL` matches API server port
## 📝 License
MIT
## 👤 Author
**Jérémy Voisin**
- Email: voisin.jeremy@outlook.fr
## 🙏 Acknowledgments
- Google ADK team for the Agent Development Kit
- A2A Protocol community
- LangChain for agent framework
- MCP project for Model Context Protocol
