AgentSphere

A dynamic AI platform enabling users to interact with agents individually or in groups, create workflows, and integrate MCP tools for seamless task automation.

🌟 Features

• 🤖 AI Agents: Create and manage AI agents with customizable system prompts
• 🔄 LLM Integration: Connect to various LLM providers (Only Gemini for Now!)
• 🏢 Organizations: Create and manage organizations with multiple members
• 🔧 MCP Tools: Integrate external tools via MCP servers
• 👥 Multi-User: Collaborative environment with user management
• 🔒 Secure: API keys stored securely in HashiCorp Vault
• 📊 API Documentation: Comprehensive API documentation with Swagger/ReDoc
• 🚀 Scalable: Built with Docker for easy deployment and scaling

🛠️ Tech Stack

• Backend: Django 5.0, Django REST Framework
• Database: PostgreSQL
• Cache & Message Broker: Redis
• Task Queue: Celery
• Secret Management: HashiCorp Vault
• Storage: MinIO (S3-compatible)
• Containerization: Docker, Docker Compose
• Documentation: drf-spectacular (OpenAPI)
• Monitoring: Sentry, Django Silk
• Email: Mailpit (development)

📋 Prerequisites

• Docker and Docker Compose
• Git

🚀 Getting Started

Clone the repository

git clone https://github.com/DataRohit/AgentSphere.git
cd AgentSphere

Environment Setup

• Copy the example environment files:

cp .envs/.django.env.example .envs/.django.env
cp .envs/.postgres.env.example .envs/.postgres.env
cp .envs/.minio.env.example .envs/.minio.env
cp .envs/.vault.env.example .envs/.vault.env
cp .envs/.pgadmin.env.example .envs/.pgadmin.env

• Update the environment files with your settings

Start the Application

make up

This will start all services defined in the docker-compose.yml file.

Access the Application

• Django Admin: http://localhost:8080/admin/
• API Documentation:
  • Swagger UI: http://localhost:8080/api/v1/swagger/ui/
  • ReDoc: http://localhost:8080/api/v1/swagger/redoc/
• PgAdmin: http://localhost:8080/pgadmin/
• Mailpit: http://localhost:8080/mailpit/
• Vault UI: http://localhost:8080/vault/ui/
• Flower (Celery monitoring): http://localhost:8080/flower/

🧰 Development Commands

AgentSphere comes with a colorful Makefile that provides convenient commands for development:

# Docker Commands
make help              # 🔍 Show help message
make up                # 🚀 Start all containers
make down              # 🛑 Stop all containers
make infra-up          # 🏗️ Start infrastructure services only
make app-up            # 📱 Start application services only
make ps                # 📋 List running containers
make logs              # 📜 View logs from all containers
make logs-app          # 📜 View logs from application containers
make logs-infra        # 📜 View logs from infrastructure containers
make build             # 🔨 Build all containers
make clean             # 🧹 Remove all containers, networks, and volumes
make restart           # 🔄 Restart all containers
make restart-app       # 🔄 Restart application containers
make restart-infra     # 🔄 Restart infrastructure containers

# Python Code Quality Commands
make lint              # 🔎 Run ruff linter on Python code
make format            # 💅 Format Python code with ruff
make fix               # 🔧 Fix auto-fixable issues with ruff

🏗️ Project Structure

AgentSphere/
├── .envs/                 # Environment variable files
├── backend/               # Django backend code
│   ├── apps/              # Django applications
│   │   ├── agents/        # AI agents functionality
│   │   ├── chats/         # Chat management (single & group)
│   │   ├── common/        # Shared utilities and models
│   │   ├── contrib/       # Contributed Django extensions
│   │   ├── conversation/  # Conversation sessions & websockets
│   │   ├── llms/          # LLM configurations & integrations
│   │   ├── organization/  # Organization management
│   │   ├── templates/     # Email and HTML templates
│   │   ├── tools/         # MCP tools integration
│   │   └── users/         # User management & authentication
│   ├── config/           # Django settings and configuration
│   └── requirements.txt  # Python dependencies
├── compose/               # Docker compose configuration
│   ├── django/           # Django service configuration
│   ├── nginx/            # Nginx service configuration
│   └── postgres/         # PostgreSQL service configuration
├── docker-compose.yml     # Docker compose services definition
└── makefile               # Development commands

🔑 Key Concepts

Agents

AI agents are the core of AgentSphere. Each agent has:

• A name and description
• A system prompt that defines its behavior
• A connection to an LLM for generating responses
• An automatically generated avatar using DiceBear
• Public or private visibility within an organization
• A limit of 5 agents per user per organization

LLMs

Language Model configurations that can be connected to agents:

• Support for multiple API providers (Currently Gemini 2.5 Pro/Flash)
• Secure API key storage in HashiCorp Vault
• Configurable token limits
• Organization-based access control

Chats

AgentSphere supports two types of chat interactions:

• Single Chats: One-to-one conversations between a user and an agent
• Group Chats: Multi-agent conversations where a user can interact with multiple agents
• Both chat types support message history, editing, and deletion

Conversation Sessions

Conversation sessions manage the flow of interactions:

• Link to either single or group chats
• Track active/inactive status
• Can use a selector prompt for routing to appropriate agents/tools
• Associate with specific LLM models for processing

Organizations

Organizations provide a way to group users and resources:

• Each user can create up to 3 organizations
• Organizations can have up to 8 members
• Resources (Agents, LLMs, MCP tools) are associated with organizations
• Public/private visibility controls for resources

MCP Tools

MCP (Multi-Agent Communication Protocol) tools allow integration with external services:

• Each user can add up to 5 MCP tools per organization
• Tools are defined by name, description, URL, and optional tags
• Secure authentication with external services

📚 API Documentation

The API is documented using OpenAPI 3.0 (via drf-spectacular). You can explore the API using:

• Swagger UI: http://localhost:8080/api/v1/swagger/ui/
• ReDoc: http://localhost:8080/api/v1/swagger/redoc/

🔒 Security

• User authentication via JWT tokens
• API keys stored securely in HashiCorp Vault
• CSRF protection
• Secure cookie settings

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Contact

Rohit Ingole - rohit.vilas.ingole@gmail.com

Project Link: https://github.com/DataRohit/AgentSphere

🔄 CI/CD Pipeline

AgentSphere uses a robust CI/CD pipeline to ensure code quality and automated deployments:

• Linting: Automated code quality checks using Ruff
• Testing: Automated tests run on each pull request
• Docker: Containerized builds for consistent deployment
• Deployment: Automated deployment to staging and production environments

📊 Project Status

AgentSphere is currently in active development. The core functionality is implemented, but we're continuously adding new features and improvements.

🌐 Supported LLM Providers

• Gemini (Currently supported)
• OpenAI (Coming soon)
• Anthropic (Coming soon)

💬 Getting Help

If you need help with AgentSphere, you can:

• Open an Issue: For bugs or feature requests
• Discussions: For general questions and discussions
• Email: Contact the maintainer directly at rohit.vilas.ingole@gmail.com

We welcome all feedback and contributions!