Repository files navigation

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

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): Base framework for agent development
• CrewAI Support: Alternative framework for agent development (in development)
• JWT authentication with email verification
• Agent 2 Agent (A2A) Protocol Support: Interoperability between AI agents
• Workflow Agent with LangGraph: Building complex agent workflows
• Secure API Key Management: Encrypted storage of API keys
• Agent Organization: Folder structure for organizing agents by categories

Evo AI supports different types of agents that can be flexibly combined:

Agent based on language models like GPT-4, Claude, etc. Can be configured with tools, MCP servers, and sub-agents.

Agent that implements Google's A2A protocol for agent interoperability.

Executes a sequence of sub-agents in a specific order.

Executes multiple sub-agents simultaneously.

Executes sub-agents in a loop with a defined maximum number of iterations.

Executes sub-agents in a custom workflow defined by a graph structure using LangGraph.

Executes a specific task using a target agent with structured task instructions.

• 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

• 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

Evo AI platform natively supports integration withLangfuse for detailed tracing of agent executions, prompts, model responses, and tool calls, using the OpenTelemetry (OTel) standard.

1. Set environment variables in your.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.

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, visitGoogle's A2A Protocol Documentation.

• Python: 3.10 or higher
• PostgreSQL: 13.0 or higher
• Redis: 6.0 or higher
• Git: For version control
• Make: For running Makefile commands

• Node.js: 18.0 or higher
• pnpm: Package manager (recommended) or npm/yarn

git clone https://github.com/EvolutionAPI/evo-ai.gitcd evo-ai

# Create and activate virtual environmentmake venvsource venv/bin/activate# Linux/Mac# or on Windows: venv\Scripts\activate# Install development dependenciesmake install-dev

# Copy and configure backend environmentcp .env.example .env# Edit the .env file with your database, Redis, and other settings

# Initialize database and apply migrationsmake alembic-upgrade# Seed initial data (admin user, sample clients, etc.)make seed-all

# Navigate to frontend directorycd frontend# Install dependencies using pnpm (recommended)pnpm install# Or using npm# npm install# Or using yarn# yarn install

# Copy and configure frontend environmentcp .env.example .env# Edit .env with your API URL (default: http://localhost:8000)

The frontend.env should contain:

NEXT_PUBLIC_API_URL=http://localhost:8000

# From project rootmake run# Backend will be available at http://localhost:8000

# From frontend directorycd frontendpnpm dev# Or using npm/yarn# npm run dev# yarn dev# Frontend will be available at http://localhost:3000

make run-prod# Production with multiple workers

cd frontendpnpm build&& pnpm start# Or using npm/yarn# npm run build && npm start# yarn build && yarn start

# Build and start all services (backend + database + redis)make docker-buildmake docker-up# Initialize database with seed datamake docker-seed

# From frontend directorycd frontend# Build frontend imagedocker build -t evo-ai-frontend.# Run frontend containerdocker run -p 3000:3000 -e NEXT_PUBLIC_API_URL=http://localhost:8000 evo-ai-frontend

Or using the provided docker-compose:

# From frontend directorycd frontenddocker-compose up -d

After installation, follow these steps:

1. Access the Frontend: Openhttp://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

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

The interactive API documentation is available at:

• Swagger UI:http://localhost:8000/docs
• ReDoc:http://localhost:8000/redoc

# Database migrationsmake alembic-upgrade# Update database to latest versionmake alembic-revision message="description"# Create new migration# Seedersmake seed-all# Run all seeders# Code verificationmake lint# Verify code with flake8make format# Format code with black

# From frontend directorycd frontend# Developmentpnpm dev# Start development serverpnpm build# Build for productionpnpm start# Start production serverpnpm lint# Run ESLint

Key settings include:

# Database settingsPOSTGRES_CONNECTION_STRING="postgresql://postgres:root@localhost:5432/evo_ai"# Redis settingsREDIS_HOST="localhost"REDIS_PORT=6379# AI Engine configurationAI_ENGINE="adk"# Options: "adk" (Google Agent Development Kit) or "crewai" (CrewAI framework)# JWT settingsJWT_SECRET_KEY="your-jwt-secret-key"# Email provider configurationEMAIL_PROVIDER="sendgrid"# Options: "sendgrid" or "smtp"# Encryption for API keysENCRYPTION_KEY="your-encryption-key"

# API ConfigurationNEXT_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.

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

If you find EvoAI useful, please consider giving us a star! Your support helps us grow our community and continue improving the product.

We welcome contributions from the community! Please read ourContributing Guidelines for more details.

This project is licensed under theApache License 2.0.