Content
# A2A Weather Assistant Project
A complete front-end and back-end separated project demonstrating how to build intelligent Agent applications using the Agent2Agent (A2A) protocol.
## 📚 Documentation
**📖 For complete documentation, please refer to the [docs directory](./docs/README.md)**
## 🆕 Latest Updates
### 🎨 Weather Poster Generation Feature (2025-10-09)
The Weather Assistant now supports intelligent generation of beautiful weather posters!
**New Features**:
- ✅ Integrated VEADK image generation tool
- ✅ Sub-agent architecture design
- ✅ Customizable poster styles and designs
- ✅ Support for poster modification and optimization
- ✅ Complete usage documentation and examples
**Quick Experience**:
```
Query the weather in Beijing and generate a poster
Generate a weather poster for Shanghai with a blue theme and minimalist style
Change the poster to warm tones
```
**Technical Highlights**:
- 🏗️ Modular sub-agent architecture
- 🤖 Main agent automatically determines when to call sub-agents
- 🎯 Specialized division of labor, independent encapsulation for poster generation
- 📚 Complete development documentation and usage examples
**Related Documentation**:
- 📖 [Weather Poster Feature Documentation](./backend/docs/WEATHER_POSTER_FEATURE.md)
- 💡 [Usage Examples](./backend/docs/WEATHER_POSTER_USAGE_EXAMPLES.md)
- 🚀 [Quick Start](./backend/docs/QUICK_START_WEATHER_POSTER.md)
### ⚡ Task Queue Mode (2025-10-08)
Now supports **two message processing modes**:
| Mode | Features | Applicable Scenarios |
|------|----------|----------------------|
| 🌊 **Streaming Response Mode** | Real-time streaming, instant feedback | Interactive conversations, short tasks |
| 📋 **Task Queue Mode** | Send and forget, background asynchronous processing | Long-running tasks, batch processing |
**New Features**:
- ✅ Asynchronous task submission and execution
- ✅ Task progress tracking and polling
- ✅ Task history querying and management
- ✅ Task cancellation feature
- ✅ Visual task list interface
**Quick Experience**:
1. Start the server (the task manager will start automatically)
2. Toggle the "Task Queue Mode" switch in the front-end interface
3. After sending a message, you can continue to submit new tasks without waiting
4. View the status of all tasks in the task list on the right
**Detailed Documentation**:
- 📖 [Task Queue User Guide](./docs/TASK_QUEUE_GUIDE.md) - Complete usage documentation
- 📝 [Update Notes](./docs/TASK_QUEUE_UPDATE.md) - Detailed update content
- 🧪 Test command: `python backend/test_task_queue.py`
## 🚀 Quick Start
**New user?** We offer two options:
- **Option 2 (Recommended)**: [Quick Start - Unified Server](./docs/快速启动-方案2.md) - Single server with dropdown menu switching
- **Option 1**: [Quick Start - Multi-Port](./docs/QUICKSTART.md) - Multiple independent servers with card-style switching
### Option 2 (Recommended): Unified Server + Dropdown Menu
```bash
# 1. Install dependencies
pip install -r backend/requirements.txt
cd frontend && npm install && cd ..
# 2. Configure API key
cd backend && cp .env.example .env
# Edit the .env file to set MODEL_AGENT_API_KEY
# 3. Start the unified server (including all agents)
cd backend && ./start_multi_agent_server.sh
# 4. Start the front-end
cd frontend && npm run dev
```
### Option 1: Multi-Port + Card Selection
```bash
# Start all agents (each on an independent port)
cd backend && ./start_all_agents.sh
# Or start a single agent
cd backend && ./start_single_agent.sh weather_reporter 8001
# Start the front-end
cd frontend && npm run dev
```
## Project Overview
This project includes:
- **Back-end**: A Python-based A2A multi-agent server (supports Weather Assistant, Translation Assistant, Code Reviewer, Data Analyst, etc.)
- **Front-end**: A desktop application client based on Electron + React + Bootstrap, supporting multi-agent switching
### 🤖 Multi-Agent Support
This project demonstrates how to build and manage multiple agents, providing two options:
#### Option Comparison
| Feature | Option 1 (Multi-Port) | Option 2 (Unified Server) ⭐ Recommended |
|---------|-----------------------|------------------------------------------|
| Number of Servers | 4 independent servers | 1 unified server |
| Ports | 8001-8004 | 8000 |
| Resource Usage | Higher | Lower |
| Front-end UI | Card selector | Dropdown menu |
| Applicable Scenarios | Development and debugging | Production environment |
#### Available Agents
| Agent | Option 1 Port | Option 2 Path | Function Description |
|-------|---------------|---------------|----------------------|
| 🤖 Personal Assistant | - | `/personal_assistant` | Provides personalized services |
| 🌤️ Weather Assistant | 8001 | `/weather` | Queries city weather information + 🎨**Generates weather posters** |
| 🌐 Translation Assistant | 8002 | `/translator` | Multi-language translation services |
| 💻 Code Reviewer | 8003 | `/code_reviewer` | Code quality analysis |
| 📊 Data Analyst | 8004 | `/data_analyst` | Data analysis and visualization |
**Detailed Usage Instructions**:
- [Option 2 User Guide](./docs/方案2使用指南.md) - Unified server option (recommended)
- [Multi-Agent User Guide](./docs/多智能体使用指南.md) - Multi-port option
- [Option Comparison](./docs/方案对比.md) - Detailed option comparison analysis
## Technical Architecture
### Back-end
- Python 3.11+
- veadk (Vertex AI Agent Development Kit)
- Google ADK A2A tools
- Agent2Agent protocol
### Front-end
- Electron (Cross-platform desktop application)
- React 18 + TypeScript
- Bootstrap 5 + React Bootstrap
- Vite (Build tool)
- @a2a-js/sdk (A2A client SDK)
## Project Structure
```
a2a_server/
├── backend/ # Back-end directory
│ ├── multi_agent_server.py # Multi-agent unified server
│ ├── requirements.txt # Python dependencies
│ ├── start_multi_agent_server.sh # Startup script
│ └── .env # Environment variable configuration
│
├── frontend/ # Front-end directory
│ ├── electron/ # Electron main process
│ ├── src/ # React application source code
│ │ ├── components/ # UI components
│ │ │ ├── AgentDropdown.tsx # Agent dropdown selection
│ │ │ ├── ConnectionStatus.tsx
│ │ │ ├── TaskStatusDisplay.tsx
│ │ │ └── ChatBox.tsx # Chat interface
│ │ ├── services/ # A2A client services
│ │ │ └── A2AClientService.ts
│ │ ├── types/ # Type definitions
│ │ │ └── agent.ts # Agent configuration
│ │ └── App.tsx # Main application
│ ├── package.json # Node.js dependencies
│ └── start_frontend.sh # Front-end startup script
│
├── docs/ # 📚 Documentation directory
│ ├── backend/ # Detailed back-end documentation
│ ├── frontend/ # Detailed front-end documentation
│ ├── QUICKSTART.md # Quick start guide
│ ├── 多智能体使用指南.md # Detailed multi-agent documentation
│ ├── 方案2使用指南.md # Unified server option guide
│ └── 方案对比.md # Option comparison analysis
├── start_all.sh # One-click startup script
└── README.md # Project main documentation (current file)
```
## Quick Start
### 1. Environment Preparation
Ensure you have installed:
- Python 3.11 or higher
- Node.js 18 or higher
- npm or yarn
### 2. Back-end Setup
#### Install Dependencies
```bash
cd backend
pip install -r requirements.txt
```
#### Configure Environment Variables
Create a `.env` file:
```bash
cd backend
cp .env.example .env
# Edit the .env file to set your API key
nano .env
```
Set in the `.env` file:
```bash
MODEL_AGENT_API_KEY=your_api_key_here
```
#### Start the Back-end Server
**Method 1: Start All Agents (Recommended)**
```bash
cd backend
chmod +x start_all_agents.sh
./start_all_agents.sh
```
This will start 4 agent servers (ports 8001-8004), with logs saved in the `backend/logs/` directory.
**Method 2: Start a Single Agent**
```bash
cd backend
chmod +x start_single_agent.sh
./start_single_agent.sh weather_reporter 8001
```
Available agent names:
- `weather_reporter` - Weather Assistant
- `translator` - Translation Assistant
- `code_reviewer` - Code Reviewer
- `data_analyst` - Data Analyst
**Method 3: Manual Start**
```bash
cd backend
# Weather Assistant
uvicorn server_agent:app --host 0.0.0.0 --port 8001 --reload
# Translation Assistant
uvicorn server_agent_translator:app --host 0.0.0.0 --port 8002 --reload
# Code Reviewer
uvicorn server_agent_code_reviewer:app --host 0.0.0.0 --port 8003 --reload
# Data Analyst
uvicorn server_agent_data_analyst:app --host 0.0.0.0 --port 8004 --reload
```
**Stop All Agents**
```bash
cd backend
./stop_all_agents.sh
```
### 3. Front-end Setup
#### Install Dependencies
```bash
cd frontend
npm install
```
#### Start Development Environment
```bash
npm run dev
```
This will:
1. Start the Vite development server (http://localhost:5173)
2. Automatically open the Electron desktop application
## User Guide
### Basic Operations
1. **Select Agent**
- After starting the application, you will see the agent selector at the top
- Click on the card to select the agent you want to use (Weather Assistant, Translation Assistant, Code Reviewer, Data Analyst)
- Each agent has different icons and colors
2. **Connect to Server**
- After selecting an agent, the system will automatically connect to the corresponding server
- You can also manually modify the server address and click "Reconnect"
- Check the connection status indicator (green = connected, red = not connected)
3. **Submit Tasks**
- Enter the task content in the input box on the left
- For the Weather Assistant: Enter the city name (e.g., Beijing, Shanghai, Guangzhou)
- For the Translation Assistant: Enter the text to be translated
- For the Code Reviewer: Paste the code snippet
- For the Data Analyst: Describe the data analysis requirements
- Click the "Query" or "Submit" button
4. **View Results**
- The right panel displays the task status in real-time
- View execution logs and final results
- You can clear the current task and submit a new one
### Feature Highlights
✅ **Multi-Agent Support**: Supports switching between different agents (Weather, Translation, Code Review, Data Analysis) in the front-end
✅ **Agent Visualization**: Card-style interface displays all available agents
✅ **Real-Time Communication**: Uses A2A protocol for streaming, receiving task updates in real-time
✅ **Status Visualization**: Clearly displays each stage of task execution
✅ **Error Handling**: Friendly error prompts and exception handling
✅ **Modern UI**: Aesthetic interface based on Bootstrap 5
✅ **Cross-Platform**: Supports Windows, macOS, Linux
✅ **Easily Extendable**: New agents can be easily added
## Development Instructions
### Back-end Development
**Add New Tools**
Define new tool functions in `backend/server_agent.py`:
```python
from veadk.tools import tool
@tool
def get_city_temperature(city: str) -> str:
"""Get city temperature"""
# Implement logic
return f"The temperature in {city} is 25°C"
```
Then register it to the Agent:
```python
agent = Agent(
name="weather_reporter",
tools=[get_city_weather, get_city_temperature],
model_api_key=api_key
)
```
**Modify Port**
Change in the startup command:
```bash
cd backend
python3.11 -m uvicorn server_agent:app --host 0.0.0.0 --port 9000
```
### Front-end Development
**Add New Components**
Create new components in `frontend/src/components/`:
```typescript
import React from 'react'
import { Card } from 'react-bootstrap'
const MyComponent: React.FC = () => {
return <Card>...</Card>
}
export default MyComponent
```
**Modify A2A Client**
Edit `frontend/src/services/A2AClientService.ts` to add new methods.
**Custom Styles**
- Global styles: `frontend/src/index.css`
- Application styles: `frontend/src/App.css`
## Build Production Version
### Front-end Build
```bash
cd frontend
# Build Web application
npm run build
# Build Electron application (will generate installation packages for corresponding platforms)
npm run build:electron
```
Output locations:
- Web application: `frontend/dist/`
- Electron application: `frontend/build/`
## API Documentation
### A2A Protocol Endpoints
The back-end server provides the following A2A protocol endpoints:
- `GET /.well-known/agent-card.json` - Get Agent Card
- `POST /tasks` - Create new task
- `GET /tasks/:taskId` - Query task status
- `POST /tasks/:taskId/cancel` - Cancel task
- `GET /tasks/:taskId/stream` - Stream task updates
### Agent Card Example
```json
{
"id": "weather_reporter",
"name": "Weather Reporter",
"description": "A weather reporting agent",
"capabilities": {
"streaming": true,
"cancellation": true
},
"endpoints": {
"tasks": "http://localhost:4000/tasks"
}
}
```
## Troubleshooting
### Common Issues
**1. Back-end Startup Failure**
```bash
# Check environment variables
cat .env
# Reinstall dependencies
pip install -r requirements.txt --force-reinstall
```
**2. Front-end Connection Failure**
- Ensure the back-end server is running
- Check if the server address is correct (default http://localhost:4000)
- View network requests in the browser console
**3. Electron Application Fails to Start**
```bash
cd frontend
rm -rf node_modules dist
npm install
npm run dev
```
**4. Task Execution Failure**
- Check back-end log output
- Confirm API key configuration is correct
- Validate tool function implementation
## Testing
### Back-end Testing
```bash
# Test Agent Card
curl http://localhost:4000/.well-known/agent-card.json
# Test Task Creation
curl -X POST http://localhost:4000/tasks \
-H "Content-Type: application/json" \
-d '{"message": "Query the weather in Beijing"}'
```
### Front-end Testing
Check in the browser developer tools:
- Network requests
- Console logs
- React component states
## Learning Resources
- [Agent2Agent Protocol Specification](https://a2a-protocol.org)
- [a2a-js SDK Documentation](https://github.com/a2aproject/a2a-js)
- [veadk Documentation](https://github.com/google/veadk)
- [Electron Tutorial](https://www.electronjs.org/docs/latest/tutorial/quick-start)
- [React Official Tutorial](https://react.dev/learn)
## Contribution
Feel free to submit Issues and Pull Requests!
## License
MIT License
## Contact
If you have any questions or suggestions, please create an Issue.
