How genai-works-org/genai-agentos works
Project type and purpose
• This is a full-stack, microservices-style monorepo that provisions a GenAI Agents Infrastructure.
• Key goals:
• Provide a React-based frontend UI for user/agent management, chat, flows, settings.
• Expose a FastAPI backend (REST + WebSocket) to handle authentication, agent registration, chats, flows, file storage.
• Use Celery + Redis for asynchronous LLM/agent calls and background jobs.
• Offer a dedicated Router microservice for WebSocket routing.
• Offer a Master-Agent microservice for advanced agent orchestration.
• Provide a CLI for scripting user/agent registration.
• Persist state in PostgreSQL and coordinate containerized deployment via Docker Compose.
File structure analysis
• Top-level dirs:
• backend/ → FastAPI app, Alembic migrations, Celery tasks, database models, HTTP & WS routes.
• frontend/ → React + Vite + TypeScript UI, REST & WebSocket clients, pages, components, services.
• cli/ → Python CLI tool for signup/login/register_agent, uses backend API.
• router/ → Python microservice set up as a standalone WebSocket gateway.
• master-agent/ → Python microservice implementing “master” orchestration logic, LLM connectors.
• genai_agents_example/ → sample agent implementations.
• tests/ → HTTP client tests for backend API and agent integration tests.
• Root contains docker-compose.yml (orchestrates containers), Makefile, .env-example, GitHub workflows.
README insights
• Confirms architecture: Backend, Router, Master-Agents, PostgreSQL, Frontend, CLI, Redis, Celery.
• Describes how to make up the full stack.
• Lists environment variables for inter-container hostnames/ports.
• Mentions supported provider types (OpenAI, MCP, A2A).
Components
a. User’s Browser (Frontend UI)
b. Backend API
– REST endpoints (HTTP 8000)
– WebSocket endpoint (over HTTP 8080 or via Router)
c. Router service
– WebSocket gateway at ws://…/ws
d. Celery system
– Redis broker
– Celery workers (tasks.py)
e. PostgreSQL database
f. Master-Agent microservice
g. CLI tool (external client)
h. External Agent Protocol endpoints
– GenAI Agents (genai-protocol)
– MCP servers
– A2A servers
Interactions & data flows
1. Browser ←→ REST API (user login, CRUD on agents, flows, files)
2. Browser ←→ Router (WebSocket) ←→ Backend WebSocket route (real-time chat, flow updates)
3. Backend → Celery (enqueue long-running tasks: LLM calls, file I/O, agent-to-agent)
4. Celery workers → External LLM/agent endpoints via HTTP/streamable-HTTP
5. Celery workers → write results back to Backend (DB or publish to WebSocket)
6. Master-Agent microservice ←→ Router or Backend (specialized orchestration calls, tracing)
7. CLI → REST API (signup, login, register_agent)
Architectural patterns & principles
• Microservices: Backend, Router, Master-Agent, CLI are separate deployables.
• Asynchronous/event-driven: Celery tasks + Redis broker handle heavy LLM calls.
• REST + WebSocket Hybrid: Synchronous resource ops vs. real-time streaming.
• Containerization: Each component runs in its own Docker container, networked via Docker Compose.
• Separation of concerns: UI vs. API vs. background processing vs. orchestration.
Detail checklist
• Environment variable links (e.g., ROUTER_WS_URL in frontend).
• Alembic migrations → PostgreSQL path for schema evolution.
• Celery broker (Redis) as central message bus.