{"id":28100151,"url":"https://github.com/evolutionapi/evo-ai","last_synced_at":"2025-06-13T10:36:17.585Z","repository":{"id":293052552,"uuid":"982711664","full_name":"EvolutionAPI/evo-ai","owner":"EvolutionAPI","description":"Evo AI is an open-source platform for creating and managing AI agents, enabling integration with different AI models and services.","archived":false,"fork":false,"pushed_at":"2025-06-02T21:59:04.000Z","size":111685,"stargazers_count":334,"open_issues_count":15,"forks_count":111,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-06-10T01:48:03.204Z","etag":null,"topics":["a2a-protocol","adk","agent","agentic-ai","agentic-workflow","ai","crewai","langgraph","mcp","python"],"latest_commit_sha":null,"homepage":"https://evo-ai.co","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EvolutionAPI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-13T09:45:28.000Z","updated_at":"2025-06-09T15:48:01.000Z","dependencies_parsed_at":"2025-05-31T15:44:27.566Z","dependency_job_id":"4a3125e7-c86d-4e30-b48e-caa3bd86fc2e","html_url":"https://github.com/EvolutionAPI/evo-ai","commit_stats":null,"previous_names":["evolutionapi/evo-ai"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/EvolutionAPI/evo-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvolutionAPI%2Fevo-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvolutionAPI%2Fevo-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvolutionAPI%2Fevo-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvolutionAPI%2Fevo-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EvolutionAPI","download_url":"https://codeload.github.com/EvolutionAPI/evo-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvolutionAPI%2Fevo-ai/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259627934,"owners_count":22886949,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a-protocol","adk","agent","agentic-ai","agentic-workflow","ai","crewai","langgraph","mcp","python"],"created_at":"2025-05-13T18:30:45.651Z","updated_at":"2025-06-13T10:36:17.573Z","avatar_url":"https://github.com/EvolutionAPI.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003eEvo AI - AI Agents Platform\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Whatsapp Group](https://img.shields.io/badge/Group-WhatsApp-%2322BC18)](https://evolution-api.com/whatsapp)\n[![Discord Community](https://img.shields.io/badge/Discord-Community-blue)](https://evolution-api.com/discord)\n[![Postman Collection](https://img.shields.io/badge/Postman-Collection-orange)](https://evolution-api.com/postman)\n[![Documentation](https://img.shields.io/badge/Documentation-Official-green)](https://doc.evolution-api.com)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)\n[![Support](https://img.shields.io/badge/Donation-picpay-green)](https://app.picpay.com/user/davidsongomes1998)\n[![Sponsors](https://img.shields.io/badge/Github-sponsor-orange)](https://github.com/sponsors/EvolutionAPI)\n\n\u003c/div\u003e\n\n## Evo AI - AI Agents Platform\n\nEvo AI is an open-source platform for creating and managing AI agents, enabling integration with different AI models and services.\n\n## 🚀 Overview\n\nThe Evo AI platform allows:\n\n- Creation and management of AI agents\n- Integration with different language models\n- Client management and MCP server configuration\n- Custom tools management\n- **[Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/)**: Base framework for agent development\n- **[CrewAI Support](https://github.com/crewAI/crewAI)**: Alternative framework for agent development (in development)\n- JWT authentication with email verification\n- **[Agent 2 Agent (A2A) Protocol Support](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/)**: Interoperability between AI agents\n- **[Workflow Agent with LangGraph](https://www.langchain.com/langgraph)**: Building complex agent workflows\n- **Secure API Key Management**: Encrypted storage of API keys\n- **Agent Organization**: Folder structure for organizing agents by categories\n\n## 🤖 Agent Types\n\nEvo AI supports different types of agents that can be flexibly combined:\n\n### 1. LLM Agent (Language Model)\n\nAgent based on language models like GPT-4, Claude, etc. Can be configured with tools, MCP servers, and sub-agents.\n\n### 2. A2A Agent (Agent-to-Agent)\n\nAgent that implements Google's A2A protocol for agent interoperability.\n\n### 3. Sequential Agent\n\nExecutes a sequence of sub-agents in a specific order.\n\n### 4. Parallel Agent\n\nExecutes multiple sub-agents simultaneously.\n\n### 5. Loop Agent\n\nExecutes sub-agents in a loop with a defined maximum number of iterations.\n\n### 6. Workflow Agent\n\nExecutes sub-agents in a custom workflow defined by a graph structure using LangGraph.\n\n### 7. Task Agent\n\nExecutes a specific task using a target agent with structured task instructions.\n\n## 🛠️ Technologies\n\n### Backend\n- **FastAPI**: Web framework for building the API\n- **SQLAlchemy**: ORM for database interaction\n- **PostgreSQL**: Main database\n- **Alembic**: Migration system\n- **Pydantic**: Data validation and serialization\n- **Uvicorn**: ASGI server\n- **Redis**: Cache and session management\n- **JWT**: Secure token authentication\n- **SendGrid/SMTP**: Email service for notifications (configurable)\n- **Jinja2**: Template engine for email rendering\n- **Bcrypt**: Password hashing and security\n- **LangGraph**: Framework for building stateful, multi-agent workflows\n\n### Frontend\n- **Next.js 15**: React framework with App Router\n- **React 18**: User interface library\n- **TypeScript**: Type-safe JavaScript\n- **Tailwind CSS**: Utility-first CSS framework\n- **shadcn/ui**: Modern component library\n- **React Hook Form**: Form management\n- **Zod**: Schema validation\n- **ReactFlow**: Node-based visual workflows\n- **React Query**: Server state management\n\n## 📊 Langfuse Integration (Tracing \u0026 Observability)\n\nEvo 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.\n\n### How to configure\n\n1. **Set environment variables in your `.env`:**\n\n   ```env\n   LANGFUSE_PUBLIC_KEY=\"pk-lf-...\"\n   LANGFUSE_SECRET_KEY=\"sk-lf-...\"\n   OTEL_EXPORTER_OTLP_ENDPOINT=\"https://cloud.langfuse.com/api/public/otel\"\n   ```\n\n2. **View in the Langfuse dashboard**\n   - Access your Langfuse dashboard to see real-time traces.\n\n## 🤖 Agent 2 Agent (A2A) Protocol Support\n\nEvo AI implements the Google's Agent 2 Agent (A2A) protocol, enabling seamless communication and interoperability between AI agents.\n\nFor more information about the A2A protocol, visit [Google's A2A Protocol Documentation](https://google.github.io/A2A/).\n\n## 📋 Prerequisites\n\n### Backend\n- **Python**: 3.10 or higher\n- **PostgreSQL**: 13.0 or higher\n- **Redis**: 6.0 or higher\n- **Git**: For version control\n- **Make**: For running Makefile commands\n\n### Frontend\n- **Node.js**: 18.0 or higher\n- **pnpm**: Package manager (recommended) or npm/yarn\n\n## 🔧 Installation\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/EvolutionAPI/evo-ai.git\ncd evo-ai\n```\n\n### 2. Backend Setup\n\n#### Virtual Environment and Dependencies\n\n```bash\n# Create and activate virtual environment\nmake venv\nsource venv/bin/activate  # Linux/Mac\n# or on Windows: venv\\Scripts\\activate\n\n# Install development dependencies\nmake install-dev\n```\n\n#### Environment Configuration\n\n```bash\n# Copy and configure backend environment\ncp .env.example .env\n# Edit the .env file with your database, Redis, and other settings\n```\n\n#### Database Setup\n\n```bash\n# Initialize database and apply migrations\nmake alembic-upgrade\n\n# Seed initial data (admin user, sample clients, etc.)\nmake seed-all\n```\n\n### 3. Frontend Setup\n\n#### Install Dependencies\n\n```bash\n# Navigate to frontend directory\ncd frontend\n\n# Install dependencies using pnpm (recommended)\npnpm install\n\n# Or using npm\n# npm install\n\n# Or using yarn\n# yarn install\n```\n\n#### Frontend Environment Configuration\n\n```bash\n# Copy and configure frontend environment\ncp .env.example .env\n# Edit .env with your API URL (default: http://localhost:8000)\n```\n\nThe frontend `.env` should contain:\n\n```env\nNEXT_PUBLIC_API_URL=http://localhost:8000\n```\n\n## 🚀 Running the Application\n\n### Development Mode\n\n#### Start Backend (Terminal 1)\n```bash\n# From project root\nmake run\n# Backend will be available at http://localhost:8000\n```\n\n#### Start Frontend (Terminal 2)\n```bash\n# From frontend directory\ncd frontend\npnpm dev\n\n# Or using npm/yarn\n# npm run dev\n# yarn dev\n\n# Frontend will be available at http://localhost:3000\n```\n\n### Production Mode\n\n#### Backend\n```bash\nmake run-prod    # Production with multiple workers\n```\n\n#### Frontend\n```bash\ncd frontend\npnpm build \u0026\u0026 pnpm start\n\n# Or using npm/yarn\n# npm run build \u0026\u0026 npm start\n# yarn build \u0026\u0026 yarn start\n```\n\n## 🐳 Docker Installation\n\n### Full Stack with Docker Compose\n\n```bash\n# Build and start all services (backend + database + redis)\nmake docker-build\nmake docker-up\n\n# Initialize database with seed data\nmake docker-seed\n```\n\n### Frontend with Docker\n\n```bash\n# From frontend directory\ncd frontend\n\n# Build frontend image\ndocker build -t evo-ai-frontend .\n\n# Run frontend container\ndocker run -p 3000:3000 -e NEXT_PUBLIC_API_URL=http://localhost:8000 evo-ai-frontend\n```\n\nOr using the provided docker-compose:\n\n```bash\n# From frontend directory\ncd frontend\ndocker-compose up -d\n```\n\n## 🎯 Getting Started\n\nAfter installation, follow these steps:\n\n1. **Access the Frontend**: Open `http://localhost:3000`\n2. **Create Admin Account**: Use the seeded admin credentials or register a new account\n3. **Configure MCP Server**: Set up your first MCP server connection\n4. **Create Client**: Add a client to organize your agents\n5. **Build Your First Agent**: Create and configure your AI agent\n6. **Test Agent**: Use the chat interface to interact with your agent\n\n### Default Admin Credentials\n\nAfter running the seeders, you can login with:\n- **Email**: Check the seeder output for the generated admin email\n- **Password**: Check the seeder output for the generated password\n\n## 🖥️ API Documentation\n\nThe interactive API documentation is available at:\n\n- Swagger UI: `http://localhost:8000/docs`\n- ReDoc: `http://localhost:8000/redoc`\n\n## 👨‍💻 Development Commands\n\n### Backend Commands\n```bash\n# Database migrations\nmake alembic-upgrade            # Update database to latest version\nmake alembic-revision message=\"description\"  # Create new migration\n\n# Seeders\nmake seed-all                   # Run all seeders\n\n# Code verification\nmake lint                       # Verify code with flake8\nmake format                     # Format code with black\n```\n\n### Frontend Commands\n```bash\n# From frontend directory\ncd frontend\n\n# Development\npnpm dev                        # Start development server\npnpm build                      # Build for production\npnpm start                      # Start production server\npnpm lint                       # Run ESLint\n```\n\n## 🚀 Configuration\n\n### Backend Configuration (.env file)\n\nKey settings include:\n\n```bash\n# Database settings\nPOSTGRES_CONNECTION_STRING=\"postgresql://postgres:root@localhost:5432/evo_ai\"\n\n# Redis settings\nREDIS_HOST=\"localhost\"\nREDIS_PORT=6379\n\n# AI Engine configuration\nAI_ENGINE=\"adk\"  # Options: \"adk\" (Google Agent Development Kit) or \"crewai\" (CrewAI framework)\n\n# JWT settings\nJWT_SECRET_KEY=\"your-jwt-secret-key\"\n\n# Email provider configuration\nEMAIL_PROVIDER=\"sendgrid\"  # Options: \"sendgrid\" or \"smtp\"\n\n# Encryption for API keys\nENCRYPTION_KEY=\"your-encryption-key\"\n```\n\n### Frontend Configuration (.env file)\n\n```bash\n# API Configuration\nNEXT_PUBLIC_API_URL=\"http://localhost:8000\"  # Backend API URL\n```\n\n\u003e **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.\n\n## 🔐 Authentication\n\nThe API uses JWT (JSON Web Token) authentication with:\n\n- User registration and email verification\n- Login to obtain JWT tokens\n- Password recovery flow\n- Account lockout after multiple failed login attempts\n\n## 🚀 Star Us on GitHub\n\nIf you find EvoAI useful, please consider giving us a star! Your support helps us grow our community and continue improving the product.\n\n[![Star History Chart](https://api.star-history.com/svg?repos=EvolutionAPI/evo-ai\u0026type=Date)](https://www.star-history.com/#EvolutionAPI/evo-ai\u0026Date)\n\n## 🤝 Contributing\n\nWe welcome contributions from the community! Please read our [Contributing Guidelines](CONTRIBUTING.md) for more details.\n\n## 📄 License\n\nThis project is licensed under the [Apache License 2.0](./LICENSE).\n","funding_links":["https://github.com/sponsors/EvolutionAPI"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevolutionapi%2Fevo-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevolutionapi%2Fevo-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevolutionapi%2Fevo-ai/lists"}