fullstack-architecture

Full-Stack Multi-Agent Architecture

Directory layout

backend/
├── app/
│   ├── main.py       # FastAPI app — REST endpoints + WebSocket handler
│   ├── agents.py     # AG2 agent team definition and run_team() entry point
│   └── schemas.py    # Pydantic models shared between endpoints and agents
└── tests/
    └── test_api.py

frontend/ ├── src/ │ ├── main.tsx # React entry point │ ├── App.tsx # Root component │ └── components/ │ └── Chat.tsx # WebSocket chat UI ├── index.html ├── vite.config.ts # Vite config with API/WS proxy to backend └── package.json

## Tech stack

- **Backend:** FastAPI, AG2 (multi-agent orchestration), Pydantic, uvicorn
- **Frontend:** React 19, TypeScript, Vite
- **Communication:** WebSocket for real-time agent messages, REST for health/metadata

## Communication protocol

The frontend and backend communicate over a single WebSocket at `/ws/chat`.

### Message format (JSON over WebSocket)

Client → Server:
```json
{"message": "user text here"}

Server → Client (one per agent response):

{"agent": "planner", "content": "...", "type": "agent_message"}

Server → Client (when all agents finish):

{"agent": "", "content": "", "type": "done"}

Message types: agent_message, status, error, done.

REST endpoints

• GET /api/health — returns {"status": "ok", "agents": ["planner", "coder", "reviewer"]}

Agent team

The backend runs a 3-agent team using AG2's RoundRobinPattern:

1. planner — breaks user requests into numbered steps
2. coder — implements the plan in code
3. reviewer — reviews for correctness and security

The run_team(message) function in agents.py is the single entry point. It returns a list of {"agent": name, "content": text} dicts.

Key conventions

• All API models live in schemas.py — import from there, never define inline
• Agent definitions stay in agents.py — main.py only imports run_team and AGENT_NAMES
• The frontend Vite config proxies /api and /ws to the backend in dev — no hardcoded URLs in components
• Pydantic models use model_dump_json() for serialization (v2 API)