Evo AI - AI Agents Platform
[](https://evolution-api.com/whatsapp)
[](https://evolution-api.com/discord)
[](https://evolution-api.com/postman)
[](https://doc.evolution-api.com)
[](./LICENSE)
[](https://app.picpay.com/user/davidsongomes1998)
[](https://github.com/sponsors/EvolutionAPI)
## Evo AI - AI Agents Platform
Evo AI is an open-source platform for creating and managing AI agents, enabling integration with different AI models and services.
## 🚀 Overview
The Evo AI platform allows:
- Creation and management of AI agents
- Integration with different language models
- Client management and MCP server configuration
- Custom tools management
- **[Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/)**: Base framework for agent development
- **[CrewAI Support](https://github.com/crewAI/crewAI)**: Alternative framework for agent development (in development)
- JWT authentication with email verification
- **[Agent 2 Agent (A2A) Protocol Support](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/)**: Interoperability between AI agents
- **[Workflow Agent with LangGraph](https://www.langchain.com/langgraph)**: Building complex agent workflows
- **Secure API Key Management**: Encrypted storage of API keys
- **Agent Organization**: Folder structure for organizing agents by categories
## 🤖 Agent Types
Evo AI supports different types of agents that can be flexibly combined:
### 1. LLM Agent (Language Model)
Agent based on language models like GPT-4, Claude, etc. Can be configured with tools, MCP servers, and sub-agents.
### 2. A2A Agent (Agent-to-Agent)
Agent that implements Google's A2A protocol for agent interoperability.
### 3. Sequential Agent
Executes a sequence of sub-agents in a specific order.
### 4. Parallel Agent
Executes multiple sub-agents simultaneously.
### 5. Loop Agent
Executes sub-agents in a loop with a defined maximum number of iterations.
### 6. Workflow Agent
Executes sub-agents in a custom workflow defined by a graph structure using LangGraph.
### 7. Task Agent
Executes a specific task using a target agent with structured task instructions.
## 🛠️ Technologies
### Backend
- **FastAPI**: Web framework for building the API
- **SQLAlchemy**: ORM for database interaction
- **PostgreSQL**: Main database
- **Alembic**: Migration system
- **Pydantic**: Data validation and serialization
- **Uvicorn**: ASGI server
- **Redis**: Cache and session management
- **JWT**: Secure token authentication
- **SendGrid/SMTP**: Email service for notifications (configurable)
- **Jinja2**: Template engine for email rendering
- **Bcrypt**: Password hashing and security
- **LangGraph**: Framework for building stateful, multi-agent workflows
### Frontend
- **Next.js 15**: React framework with App Router
- **React 18**: User interface library
- **TypeScript**: Type-safe JavaScript
- **Tailwind CSS**: Utility-first CSS framework
- **shadcn/ui**: Modern component library
- **React Hook Form**: Form management
- **Zod**: Schema validation
- **ReactFlow**: Node-based visual workflows
- **React Query**: Server state management
## 📊 Langfuse Integration (Tracing & Observability)
Evo AI platform natively supports integration with [Langfuse](https://langfuse.com/) for detailed tracing of agent executions, prompts, model responses, and tool calls, using the OpenTelemetry (OTel) standard.
### How to configure
1. **Set environment variables in your `.env`:**
```env
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_SECRET_KEY="sk-lf-..."
OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel"
```
2. **View in the Langfuse dashboard**
- Access your Langfuse dashboard to see real-time traces.
## 🤖 Agent 2 Agent (A2A) Protocol Support
Evo AI implements the Google's Agent 2 Agent (A2A) protocol, enabling seamless communication and interoperability between AI agents.
For more information about the A2A protocol, visit [Google's A2A Protocol Documentation](https://google.github.io/A2A/).
## 📋 Prerequisites
### Backend
- **Python**: 3.10 or higher
- **PostgreSQL**: 13.0 or higher
- **Redis**: 6.0 or higher
- **Git**: For version control
- **Make**: For running Makefile commands
### Frontend
- **Node.js**: 18.0 or higher
- **pnpm**: Package manager (recommended) or npm/yarn
## 🔧 Installation
### 1. Clone the Repository
```bash
git clone https://github.com/EvolutionAPI/evo-ai.git
cd evo-ai
```
### 2. Backend Setup
#### Virtual Environment and Dependencies
```bash
# Create and activate virtual environment
make venv
source venv/bin/activate # Linux/Mac
# or on Windows: venv\Scripts\activate
# Install development dependencies
make install-dev
```
#### Environment Configuration
```bash
# Copy and configure backend environment
cp .env.example .env
# Edit the .env file with your database, Redis, and other settings
```
#### Database Setup
```bash
# Initialize database and apply migrations
make alembic-upgrade
# Seed initial data (admin user, sample clients, etc.)
make seed-all
```
### 3. Frontend Setup
#### Install Dependencies
```bash
# Navigate to frontend directory
cd frontend
# Install dependencies using pnpm (recommended)
pnpm install
# Or using npm
# npm install
# Or using yarn
# yarn install
```
#### Frontend Environment Configuration
```bash
# Copy and configure frontend environment
cp .env.example .env
# Edit .env with your API URL (default: http://localhost:8000)
```
The frontend `.env` should contain:
```env
NEXT_PUBLIC_API_URL=http://localhost:8000
```
## 🚀 Running the Application
### Development Mode
#### Start Backend (Terminal 1)
```bash
# From project root
make run
# Backend will be available at http://localhost:8000
```
#### Start Frontend (Terminal 2)
```bash
# From frontend directory
cd frontend
pnpm dev
# Or using npm/yarn
# npm run dev
# yarn dev
# Frontend will be available at http://localhost:3000
```
### Production Mode
#### Backend
```bash
make run-prod # Production with multiple workers
```
#### Frontend
```bash
cd frontend
pnpm build && pnpm start
# Or using npm/yarn
# npm run build && npm start
# yarn build && yarn start
```
## 🐳 Docker Installation
### Full Stack with Docker Compose
```bash
# Build and start all services (backend + database + redis)
make docker-build
make docker-up
# Initialize database with seed data
make docker-seed
```
### Frontend with Docker
```bash
# From frontend directory
cd frontend
# Build frontend image
docker build -t evo-ai-frontend .
# Run frontend container
docker run -p 3000:3000 -e NEXT_PUBLIC_API_URL=http://localhost:8000 evo-ai-frontend
```
Or using the provided docker-compose:
```bash
# From frontend directory
cd frontend
docker-compose up -d
```
## 🎯 Getting Started
After installation, follow these steps:
1. **Access the Frontend**: Open `http://localhost:3000`
2. **Create Admin Account**: Use the seeded admin credentials or register a new account
3. **Configure MCP Server**: Set up your first MCP server connection
4. **Create Client**: Add a client to organize your agents
5. **Build Your First Agent**: Create and configure your AI agent
6. **Test Agent**: Use the chat interface to interact with your agent
### Default Admin Credentials
After running the seeders, you can login with:
- **Email**: Check the seeder output for the generated admin email
- **Password**: Check the seeder output for the generated password
## 🖥️ API Documentation
The interactive API documentation is available at:
- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`
## 👨💻 Development Commands
### Backend Commands
```bash
# Database migrations
make alembic-upgrade # Update database to latest version
make alembic-revision message="description" # Create new migration
# Seeders
make seed-all # Run all seeders
# Code verification
make lint # Verify code with flake8
make format # Format code with black
```
### Frontend Commands
```bash
# From frontend directory
cd frontend
# Development
pnpm dev # Start development server
pnpm build # Build for production
pnpm start # Start production server
pnpm lint # Run ESLint
```
## 🚀 Configuration
### Backend Configuration (.env file)
Key settings include:
```bash
# Database settings
POSTGRES_CONNECTION_STRING="postgresql://postgres:root@localhost:5432/evo_ai"
# Redis settings
REDIS_HOST="localhost"
REDIS_PORT=6379
# AI Engine configuration
AI_ENGINE="adk" # Options: "adk" (Google Agent Development Kit) or "crewai" (CrewAI framework)
# JWT settings
JWT_SECRET_KEY="your-jwt-secret-key"
# Email provider configuration
EMAIL_PROVIDER="sendgrid" # Options: "sendgrid" or "smtp"
# Encryption for API keys
ENCRYPTION_KEY="your-encryption-key"
```
### Frontend Configuration (.env file)
```bash
# API Configuration
NEXT_PUBLIC_API_URL="http://localhost:8000" # Backend API URL
```
> **Note**: While Google ADK is fully supported, the CrewAI engine option is still under active development. For production environments, it's recommended to use the default "adk" engine.
## 🔐 Authentication
The API uses JWT (JSON Web Token) authentication with:
- User registration and email verification
- Login to obtain JWT tokens
- Password recovery flow
- Account lockout after multiple failed login attempts
## 🚀 Star Us on GitHub
If you find EvoAI useful, please consider giving us a star! Your support helps us grow our community and continue improving the product.
[](https://www.star-history.com/#EvolutionAPI/evo-ai&Date)
## 🤝 Contributing
We welcome contributions from the community! Please read our [Contributing Guidelines](CONTRIBUTING.md) for more details.
## 📄 License
This project is licensed under the [Apache License 2.0](./LICENSE).