251 lines
7.6 KiB
Markdown
251 lines
7.6 KiB
Markdown
<h1 align="center">Evo AI - AI Agents Platform</h1>
|
|
|
|
<div align="center">
|
|
|
|
[](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)
|
|
|
|
</div>
|
|
|
|
## 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
|
|
|
|
- **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
|
|
- **ReactFlow**: Library for building node-based visual workflows
|
|
|
|
## 📊 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
|
|
|
|
- **Python**: 3.10 or higher
|
|
- **PostgreSQL**: 13.0 or higher
|
|
- **Redis**: 6.0 or higher
|
|
- **Git**: For version control
|
|
- **Make**: For running Makefile commands
|
|
|
|
## 🔧 Installation
|
|
|
|
1. Clone the repository:
|
|
|
|
```bash
|
|
git clone https://github.com/EvolutionAPI/evo-ai.git
|
|
cd evo-ai
|
|
```
|
|
|
|
2. Create a virtual environment and install dependencies:
|
|
|
|
```bash
|
|
make venv
|
|
source venv/bin/activate # Linux/Mac
|
|
make install-dev # For development dependencies
|
|
```
|
|
|
|
3. Set up environment variables:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit the .env file with your settings
|
|
```
|
|
|
|
4. Initialize the database and seed data:
|
|
|
|
```bash
|
|
make alembic-upgrade
|
|
make seed-all
|
|
```
|
|
|
|
## 🖥️ Frontend Installation
|
|
|
|
1. Clone the frontend repository:
|
|
|
|
```bash
|
|
git clone https://github.com/EvolutionAPI/evo-ai-frontend.git
|
|
cd evo-ai-frontend
|
|
```
|
|
|
|
2. Follow the installation instructions in the frontend repository's README.
|
|
|
|
## 🚀 Getting Started
|
|
|
|
After installation, start by configuring your MCP server, creating a client, and setting up your agents.
|
|
|
|
### 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"
|
|
```
|
|
|
|
> **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
|
|
|
|
## 🚀 Running the Project
|
|
|
|
```bash
|
|
make run # For development with automatic reload
|
|
make run-prod # For production with multiple workers
|
|
```
|
|
|
|
The API will be available at `http://localhost:8000`
|
|
|
|
## 👨💻 Development 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
|
|
```
|
|
|
|
## 🐳 Running with Docker
|
|
|
|
1. Configure the `.env` file
|
|
2. Start the services:
|
|
|
|
```bash
|
|
make docker-build
|
|
make docker-up
|
|
make docker-seed
|
|
```
|
|
|
|
## 📚 API Documentation
|
|
|
|
The interactive API documentation is available at:
|
|
|
|
- Swagger UI: `http://localhost:8000/docs`
|
|
- ReDoc: `http://localhost:8000/redoc`
|
|
|
|
## ⭐ 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).
|