Content
# Multi-Agent System with OAuth2 + RBAC
**Microsoft Agent Framework + Google A2A Protocol + OAuth2 Authentication + Role-Based Tool Gateway**
## Architecture
### Tech Stack
- **Authentication**: OAuth2 Bearer Token
- **Authorization**: Role-Based Access Control (RBAC)
- **A2A Protocol**: Google Agent-to-Agent (v0.2.5)
- **Agent Framework**: Microsoft Agent Framework
- **LLM**: Azure OpenAI (GPT-4.1)
- **Web Framework**: FastAPI
- **Database**: PostgreSQL 16
- **State Store**: Redis 7
- **Container**: Docker / Docker Compose
- **MCP**: Tavily (Web Search), Context7 (Documentation)
### System Architecture
```
┌──────────────────────────────────┐
│ User Request (OAuth Token) │
└────────────────┬─────────────────┘
↓
┌──────────────────────┐
│ API Gateway :8100 │ ← OAuth2 Authentication
│ - Token Validation │ Role Resolution
└──────────┬───────────┘
↓
┌──────────────────────┐
│ Orchestrator :8000 │ ← Agent Selection
│ - Skill Matching │ & Routing
└──────────┬───────────┘
↓
┌────────┴────────┐
↓ ↓
┌───────────────┐ ┌──────────────────┐
│ Agent Services│ │ Tool Gateway │
│ :8001-8003 │───→ :8200 │ ← RBAC Check
├───────────────┤ │ - Permission │ Tool Execution
│ DataAnalyst │ │ - Execution │
│ BusinessAdv. │ └──────────────────┘
│ TechnicalExp. │
└───────┬───────┘
↓
┌───────────────┐ ┌──────────────────┐
│ Registry :8080│ │ PostgreSQL :5432 │
│ - Agent Cards │ │ - Users/Roles │
│ - Discovery │ │ - Permissions │
└───────────────┘ └──────────────────┘
┌──────────────────┐
│ Redis :6379 │
│ - Conversations │
└──────────────────┘
```
**Core Features**:
- **OAuth2 Authentication**: Secure user authentication with Bearer tokens
- **RBAC**: Role-based tool access control (admin, researcher, analyst, user)
- **A2A Protocol**: Agent-to-agent collaboration and delegation
- **Tool Gateway**: Centralized tool execution with permission enforcement
- **Agent Discovery**: Capability-based agent selection via Registry
## Key Features
### 1. Container-Based Architecture
- **Docker/Docker Compose**: Standard containerization
- **Each Agent = Independent Container**: Complete isolation and scalability
- **Health Checks**: Automatic monitoring and restart
- **Bridge Network**: Secure inter-container communication
### 2. FastAPI-Based Services
- **RESTful API**: Standard HTTP communication
- **Auto Documentation**: Swagger UI (`/docs`)
- **Async Processing**: High-performance async/await
- **Type Safety**: Pydantic models
### 3. Intelligent Routing
- **Router Agent**: LLM-based agent selection
- **Capability Matching**: Automatic skill-based matching
- **Cost Optimization**: Only necessary agents invoked
## Services
| Service | Port | Role | Container Name |
|---------|------|------|----------------|
| API Gateway | 8100 | OAuth2 authentication | api-gateway |
| Tool Gateway | 8200 | RBAC tool execution | tool-gateway |
| Orchestrator | 8000 | Agent orchestration | orchestrator |
| Data Analyst | 8001 | Data analysis expert | data-analyst |
| Business Advisor | 8002 | Business strategy | business-advisor |
| Technical Expert | 8003 | Technical consultant | technical-expert |
| Registry | 8080 | Agent registry | registry |
| PostgreSQL | 5432 | User/role database | postgres |
| Redis | 6379 | Conversation store | redis |
## Requirements
- **Docker** 20.10+
- **Docker Compose** 2.0+
- **Python** 3.12+ (for local development)
- **uv** (Python package manager)
### Installation
```bash
# Docker installation (macOS)
brew install docker
# Docker Compose installation
brew install docker-compose
```
## Getting Started
### 1. Environment Setup
Create `.env` file:
```env
# Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_DEPLOYMENT=gpt-4.1
AZURE_OPENAI_API_VERSION=2024-12-01-preview
# Redis
REDIS_URL=redis://redis:6379
# PostgreSQL
DATABASE_URL=postgresql+asyncpg://postgres:postgres@postgres:5432/agent_gateway
# Services
REGISTRY_URL=http://registry:8080
# OAuth
TOKEN_EXPIRE_HOURS=24
# MCP
TAVILY_API_KEY=your-tavily-api-key
```
### 2. Start System
```bash
# Start all services
docker-compose up -d
# View logs
docker-compose logs -f
# Check service health
docker-compose ps
```
Startup process:
1. PostgreSQL container starts
2. Redis container starts
3. API Gateway starts and initializes database schema
4. Tool Gateway starts
5. Registry service starts
6. Agent services start and register
7. Orchestrator starts
8. Health checks complete
### 4. Initialize Database
```bash
# Install dependencies
uv sync
# Run database initialization script
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/agent_gateway \
uv run python scripts/init_db.py
```
This creates sample users:
- `admin / admin123` (all tools)
- `researcher / researcher123` (time, search)
- `analyst / analyst123` (time, search, query)
- `user / user123` (time only)
### 3. Test System
```bash
# Health check
curl http://localhost:8080/health
# Query orchestrator
curl -X POST http://localhost:8000/orchestrate \
-H 'Content-Type: application/json' \
-d '{
"query": "How to build a data analysis platform?"
}'
```
### 4. Stop System
```bash
# Stop all services
docker-compose down
# Stop and remove volumes
docker-compose down -v
```
## API Usage
### Orchestrator API
**Endpoint**: `POST http://localhost:8000/orchestrate`
**Request**:
```json
{
"query": "What strategy can increase our company revenue?",
"conversation_id": "optional-conversation-id"
}
```
**Response**:
```json
{
"query": "What strategy can increase our company revenue?",
"selected_agents": ["BusinessAdvisor", "DataAnalyst"],
"responses": [
{
"agent_name": "BusinessAdvisor",
"response": "Based on market analysis...",
"conversation_id": "uuid",
"delegated_to": ["DataAnalyst"]
}
],
"conversation_id": "uuid"
}
```
### Registry API
```bash
# List all registered agents
curl http://localhost:8080/agents
# Get specific agent card
curl http://localhost:8080/agents/DataAnalyst/card
# Find agents by skill
curl http://localhost:8080/agents/skill/data-analysis
```
### Individual Agent API
```bash
# Direct query to Data Analyst
curl -X POST http://localhost:8001/a2a/query \
-H 'Content-Type: application/json' \
-d '{
"query": "How to analyze time series data?",
"conversation_id": "optional-id"
}'
```
## Development Mode
### Local Development
```bash
# Install dependencies
uv sync
# Run single service
REDIS_URL=redis://localhost:6379 \
REGISTRY_URL=http://localhost:8080 \
uv run python -m src.services.registry
# Run all services locally (separate terminals)
uv run python -m src.services.registry
uv run python -m src.services.data_analyst
uv run python -m src.services.business_advisor
uv run python -m src.services.technical_expert
uv run python -m src.services.orchestrator
```
### View Logs
```bash
# All logs
docker-compose logs -f
# Specific service logs
docker-compose logs -f orchestrator
docker-compose logs -f data-analyst
```
### Container Management
```bash
# Running containers
docker-compose ps
# Resource usage
docker stats
# Rebuild specific service
docker-compose build orchestrator
docker-compose up -d orchestrator
# Full rebuild
docker-compose build --no-cache
docker-compose up -d
```
## Troubleshooting
### Container won't start
```bash
# Check logs
docker-compose logs registry
# Check container status
docker-compose ps -a
# Restart service
docker-compose restart registry
```
### Health check fails
```bash
# Manual health check
curl http://localhost:8080/health
# Check container health
docker inspect registry | grep -A 10 Health
```
### Network issues
```bash
# List networks
docker network ls
# Inspect network
docker network inspect ktds_default
# Recreate network
docker-compose down
docker-compose up -d
```
## Project Structure
```
multi-agent-system/
├── src/
│ ├── core/
│ │ ├── agent_base.py # Base agent class
│ │ ├── a2a_client.py # A2A client
│ │ ├── conversation.py # Conversation store
│ │ ├── config.py # Configuration
│ │ ├── mcp_manager.py # MCP server manager
│ │ └── tools.py # Agent tools
│ ├── services/
│ │ ├── registry.py # Registry service
│ │ ├── data_analyst.py # Data analyst agent
│ │ ├── business_advisor.py # Business advisor agent
│ │ ├── technical_expert.py # Technical expert agent
│ │ └── orchestrator.py # Orchestrator service
│ └── models/
│ ├── agent_card.py # A2A agent card models
│ ├── requests.py # Request models
│ └── responses.py # Response models
├── docker-compose.yml # Docker Compose config
├── Dockerfile # Docker image
├── pyproject.toml # Python dependencies
├── uv.lock # Lock file
├── mcp.json # MCP server config
├── .env # Environment variables
└── README.md
```
## Adding New Agent
### 1. Create Service Code
```python
# src/services/new_agent.py
from fastapi import FastAPI, HTTPException
from ..core.agent_base import BaseAgent
from ..core.conversation import ConversationStore
from ..core.config import settings
conversation_store = ConversationStore(
redis_url=settings.redis_url,
db=settings.redis_db
)
agent = BaseAgent(
name="NewAgent",
instructions="You are a new specialized agent...",
skills=[...],
conversation_store=conversation_store,
enable_a2a=True
)
app = FastAPI(title="New Agent")
@app.post("/a2a/query")
async def a2a_query(request: AgentRequest) -> AgentResponse:
response = await agent.run(
query=request.query,
conversation_id=request.conversation_id
)
return response
```
### 2. Add to docker-compose.yml
```yaml
new-agent:
build:
context: .
dockerfile: Dockerfile
container_name: new-agent
command: ["python", "-m", "uvicorn", "src.services.new_agent:app", "--host", "0.0.0.0", "--port", "8004"]
ports:
- "8004:8004"
networks:
- network
depends_on:
redis:
condition: service_healthy
registry:
condition: service_healthy
environment:
- REDIS_URL=redis://redis:6379
- REGISTRY_URL=http://registry:8080
```
### 3. Restart
```bash
docker-compose up -d new-agent
```
## Performance Optimization
### Intelligent Routing Benefits
**Example**: "How to optimize Python performance?"
- ❌ **Broadcast**: All 3 agents called
- ✅ **Smart Routing**: Only Technical Expert called
→ **66% cost reduction!**
### Resource Limits
```yaml
# Add to docker-compose.yml
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
```
## Tech Stack
| Layer | Technology | Description |
|-------|------------|-------------|
| Container | **Docker** | Standard containerization |
| Orchestration | **Docker Compose** | Multi-container management |
| API Framework | **FastAPI** | High-performance async web framework |
| AI Agent | **Microsoft Agent Framework** | Agent creation and LLM integration |
| LLM Backend | **Azure OpenAI** | GPT-4.1 model |
| Language | **Python 3.12** | Modern Python |
| Package Manager | **uv** | Fast package manager |
| MCP Servers | **Tavily, Context7** | Web search and documentation |
## References
- [Docker Documentation](https://docs.docker.com/)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [Microsoft Agent Framework](https://github.com/microsoft/agent-framework)
- [Azure OpenAI Service](https://azure.microsoft.com/products/ai-services/openai-service)
- [Google A2A Protocol](https://github.com/google/a2a)
## License
MIT License
