🐍 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:

📦 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

🛠️ 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.