Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/evolutionapi/evo-ai

Evo AI is an open-source platform for creating and managing AI agents, enabling integration with different AI models and services.
https://github.com/evolutionapi/evo-ai

a2a-protocol adk agent agentic-ai agentic-workflow ai crewai langgraph mcp python

Last synced: 9 days ago
JSON representation

Evo AI is an open-source platform for creating and managing AI agents, enabling integration with different AI models and services.

Awesome Lists containing this project

README 

        
Evo AI - AI Agents Platform






[![Whatsapp Group](https://img.shields.io/badge/Group-WhatsApp-%2322BC18)](https://evolution-api.com/whatsapp)

[![Discord Community](https://img.shields.io/badge/Discord-Community-blue)](https://evolution-api.com/discord)

[![Postman Collection](https://img.shields.io/badge/Postman-Collection-orange)](https://evolution-api.com/postman)

[![Documentation](https://img.shields.io/badge/Documentation-Official-green)](https://doc.evolution-api.com)

[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)

[![Support](https://img.shields.io/badge/Donation-picpay-green)](https://app.picpay.com/user/davidsongomes1998)

[![Sponsors](https://img.shields.io/badge/Github-sponsor-orange)](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.



[![Star History Chart](https://api.star-history.com/svg?repos=EvolutionAPI/evo-ai&type=Date)](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).