🐍 GenAI Agents Infrastructure

This repository provides the complete infrastructure for running GenAI agents, including:

• Backend
• Router
• Master Agents
• PostgreSQL Database
• Frontend
• CLI
• Redis
• Celery

📎 Repository Link

👉 GitHub Repository

🛠️ Readme Files

• CLI
• Backend
• Master Agents
• Router
• Frontend

📄️ License

• MIT

🧠 Supported Agent Types

The system supports multiple kinds of Agents:

Agent Type	Description
GenAI Agents	Connected via genai-protocol library interface.
MCP Servers	MCP (Model Context Protocol) servers can be added by pasting their URL in the UI.
A2A Servers	A2A (Agent to Agent Protocol) servers can be added by pasting their URL in the UI.

---

📦 Prerequisites

Make sure you have the following installed:

• Docker

• Docker Compose

• make (optional)

  • macOS: brew install make
  • Linux: sudo apt-get install make

🚀 Local Setup

1. Clone the repository:

   git clone https://github.com/genai-works-org/genai-agentos.git
   cd genai-agentos/
   

2. Create a .env file by copying the example (can be empty and customized later):

   cp .env-example .env
   

   • A .env file should be present for configuration.
   • All variables in .env-example are commented. Platform starts with an empty .env file. You can customize any environment setting by uncommenting the relevant line and providing a new value.

3. Start Docker desktop and ensure it is running.

4. Start the infrastructure:

   make up
   # or alternatively
   docker compose up
   

5. After startup:

   • Frontend UI: http://localhost:3000/
   • Swagger API Docs: http://localhost:8000/docs#/

👾 Supported Providers and Models

• OpenAI: gpt-4o

🌐 Ngrok Setup (Optional)

Ngrok can be used to expose the local WebSocket endpoint.

1. Install Ngrok:

   • macOS (Homebrew): brew install ngrok/ngrok/ngrok
   • Linux: sudo snap install ngrok

2. Authenticate Ngrok:

   • Sign up or log in at ngrok dashboard.

   • Go to the "Your Authtoken" section and copy the token.

   • Run the command:

     ngrok config add-authtoken <YOUR_AUTH_TOKEN>
     

3. Start a tunnel to local port 8080:

   ngrok http 8080
   

4. Copy the generated WebSocket URL and update the ws_url field in:

   genai_session.session.GenAISession
   

---

🤖GenAI Agent registration quick start (For more data check CLI)

cd cli/

python cli.py signup -u <username> # Register a new user, also available in [UI](http://localhost:3000/)

python cli.py login -u <username> -p <password> # Login to the system, get JWT user token

python cli.py register_agent --name <agent_name> --description <agent_description>

cd agents/

# Run the agent
uv run python <agent_name>.py # or alternatively 
python <agent_name>.py 

💎 Environment Variables

Variable	Description	Example / Default
FRONTEND_PORT	Port to start a frontend	3000 - default. Can be changed by run in terminal source FRONTEND_PORT=<your_port>
ROUTER_WS_URL	WebSocket URL for the router container	ws://genai-router:8080/ws - host is either localhost or router container name
SECRET_KEY	Secret key for cryptographic operations - JWT/ LLM config encryption	$(openssl rand -hex 32)
POSTGRES_HOST	PostgreSQL Host	genai-postgres
POSTGRES_USER	PostgreSQL Username	postgres
POSTGRES_PASSWORD	PostgreSQL Password	postgres
POSTGRES_DB	PostgreSQL Database Name	postgres
POSTGRES_PORT	PostgreSQL Port	5432
DEBUG	Enable/disable debug mode - Server/ ORM logging	True / False
MASTER_AGENT_API_KEY	API key for the Master Agent - internal identifier	e1adc3d8-fca1-40b2-b90a-7b48290f2d6a::master_server_ml
MASTER_BE_API_KEY	API key for the Master Backend - internal identifier	7a3fd399-3e48-46a0-ab7c-0eaf38020283::master_server_be
BACKEND_CORS_ORIGINS	Allowed CORS origins for the backend	["*"], ["http://localhost"]
DEFAULT_FILES_FOLDER_NAME	Default folder for file storage - Docker file volume path	/files
CLI_BACKEND_ORIGIN_URL	backend URL for CLI access	http://localhost:8000

🛠️ Troubleshooting

❓ MCP server or A2A card URL could not be accessed by the genai-backend

✅ If your MCP server or A2A card is hosted on your local machine, make sure to change the host name from http://localhost:<your_port> to http://host.docker.internal:<your_port> and try again.

🔎 Also make sure to pass the full url of your MCP server or A2A card, such as - http://host.docker.internal:8000/mcp for MCP or http://host.docker.internal:10002 for A2A

⚠️ No need to specify /.well-known/agent.json for your A2A card as genai-backend will do it for you!

❓ My MCP server with valid host cannot be accessed by the genai-backend

✅ Make sure your MCP server supports streamable-http protocol and is remotely accessible.Also make sure that you're specifiying full URL of your server, like - http://host.docker.internal:8000/mcp

⚠️ Side note: sse protocol is officially deprecated by MCP protocol devs, stdio protocol is not supported yet, but stay tuned for future announcements!

⚠️ If you encounter Docker issues, follow these steps: Clean Up Docker Assets: Stop and remove all containers. Remove all images. Remove all volumes (caution: this action deletes data). Prune all unused Docker objects, including containers, images, volumes, and networks. These steps typically resolve common issues by providing a clean and refreshed Docker environment.