|
1 | | -<h1 align="center">Evo AI - Agent Processor</h1> |
| 1 | +<p align="center"> |
| 2 | + <a href="https://evolutionfoundation.com.br"> |
| 3 | + <img src="./public/hover-evolution.png" alt="Evolution Foundation" /> |
| 4 | + </a> |
| 5 | +</p> |
2 | 6 |
|
3 | | -<div align="center"> |
| 7 | +<h1 align="center">Evo CRM Agent Processor</h1> |
4 | 8 |
|
5 | | -[](https://evolution-api.com/whatsapp) |
6 | | -[](https://evolution-api.com/discord) |
7 | | -[](https://evolution-api.com/postman) |
8 | | -[](https://doc.evolution-api.com) |
9 | | -[](./LICENSE) |
10 | | -[](https://app.picpay.com/user/davidsongomes1998) |
11 | | -[](https://github.com/sponsors/EvolutionAPI) |
| 9 | +<p align="center"> |
| 10 | + Agent execution, session orchestration, and knowledge search service for the Evo CRM Community. |
| 11 | +</p> |
12 | 12 |
|
13 | | -</div> |
| 13 | +<p align="center"> |
| 14 | + <a href="https://github.com/EvolutionAPI/evo-ai-processor-community/releases/latest"><img src="https://img.shields.io/github/v/release/EvolutionAPI/evo-ai-processor-community?include_prereleases&label=version&color=00ffa7" alt="Latest version" /></a> |
| 15 | + <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0" /></a> |
| 16 | + <a href="https://docs.evolutionfoundation.com.br"><img src="https://img.shields.io/badge/Docs-evolutionfoundation.com.br-00ffa7" alt="Documentation" /></a> |
| 17 | + <a href="https://evolutionfoundation.com.br/community"><img src="https://img.shields.io/badge/Community-Join%20us-white" alt="Community" /></a> |
| 18 | +</p> |
14 | 19 |
|
15 | | -## Overview |
| 20 | +<p align="center"> |
| 21 | + <a href="https://evolutionfoundation.com.br">Website</a> · |
| 22 | + <a href="https://docs.evolutionfoundation.com.br">Documentation</a> · |
| 23 | + <a href="https://evolutionfoundation.com.br/community">Community</a> · |
| 24 | + <a href="mailto:suporte@evofoundation.com.br">Support</a> |
| 25 | +</p> |
16 | 26 |
|
17 | | -Evo AI Agent Processor is the core microservice of the Evo AI platform, responsible for orchestrating intelligent workflows between multiple agents, processing sessions, storing and searching knowledge in vector databases, and integrating with modern AI services. It provides: |
| 27 | +--- |
| 28 | + |
| 29 | +## About |
| 30 | + |
| 31 | +**Evo CRM Agent Processor** is the AI execution core of the Evo CRM Community. It orchestrates intelligent workflows between multiple agents, manages sessions and artifacts, executes Google ADK agents, and integrates with vector databases for semantic knowledge search. |
| 32 | + |
| 33 | +Built with FastAPI, it provides: |
18 | 34 |
|
19 | 35 | - Workflow orchestration between agents using LangGraph |
20 | | -- Execution of ADK agents (Google ADK) and integration with Google GenAI |
| 36 | +- Execution of Google ADK agents and integration with Google GenAI |
21 | 37 | - Session, event, and artifact processing |
22 | 38 | - Knowledge search and storage in vector databases (Pinecone, Qdrant, OpenSearch) |
23 | 39 | - JWT authentication for protected endpoints |
24 | 40 | - Redis caching for performance |
25 | | -- OpenAI integration for embeddings (optional) |
| 41 | +- OpenAI and provider-neutral integrations for embeddings |
26 | 42 | - RESTful API with FastAPI |
| 43 | +- Observability via OpenTelemetry |
27 | 44 |
|
28 | | -## Technologies |
| 45 | +## Part of the Evo CRM Community |
29 | 46 |
|
30 | | -- **FastAPI**: Web framework for building the API |
31 | | -- **SQLAlchemy**: ORM for database interaction |
32 | | -- **PostgreSQL**: Main database |
33 | | -- **Pydantic**: Data validation |
34 | | -- **Uvicorn**: ASGI server |
35 | | -- **Redis**: Cache and queues |
36 | | -- **JWT (python-jose, pyjwt)**: Authentication and authorization |
37 | | -- **Pinecone / Qdrant / OpenSearch**: Vector databases for semantic search |
38 | | -- **OpenAI**: Embeddings and LLMs (optional) |
39 | | -- **Google ADK**: Execution and management of Google agents |
40 | | -- **LangGraph**: Workflow orchestration between agents |
41 | | -- **MinIO**: Artifact storage |
42 | | -- **Opentelemetry**: Observability and tracing |
43 | | -- **a2a-sdk, mcp**: Integrations and extensions for agents |
44 | | -- **Alembic**: Database schema migration tool for SQLAlchemy |
| 47 | +Evo CRM Agent Processor is part of the [Evo CRM Community](https://github.com/EvolutionAPI/evo-crm-community) ecosystem maintained by Evolution Foundation. To use the full stack, clone the umbrella repository with submodules: |
45 | 48 |
|
46 | | -## Prerequisites |
| 49 | +```bash |
| 50 | +git clone --recurse-submodules git@github.com:EvolutionAPI/evo-crm-community.git |
| 51 | +``` |
47 | 52 |
|
48 | | -- **Python**: 3.10 or higher |
49 | | -- **PostgreSQL**: 13.0 or higher |
50 | | -- **Redis**: 6.0 or higher |
51 | | -- **Git**: For version control |
52 | | -- **Make**: For running Makefile commands |
| 53 | +The Community Edition is **single-tenant** by design — one account, no multi-tenancy overhead, no super-admin, no billing or plans. All limits are removed and features are unlocked by default. |
53 | 54 |
|
54 | | -## 🔧 Installation |
| 55 | +--- |
55 | 56 |
|
56 | | -1. Clone the repository: |
| 57 | +## Tech Stack |
57 | 58 |
|
58 | | -```bash |
59 | | -git clone https://github.com/EvolutionAPI/evo-ai-agent-processor.git |
60 | | -cd evo-ai-agent-processor |
61 | | -``` |
| 59 | +| Component | Technology | |
| 60 | +|---|---| |
| 61 | +| Web framework | FastAPI | |
| 62 | +| ORM | SQLAlchemy | |
| 63 | +| Database | PostgreSQL 13+ | |
| 64 | +| Cache | Redis 6+ | |
| 65 | +| ASGI server | Uvicorn | |
| 66 | +| Authentication | JWT (python-jose, pyjwt) | |
| 67 | +| Vector databases | Pinecone, Qdrant, OpenSearch | |
| 68 | +| Agents | Google ADK, LangGraph | |
| 69 | +| Artifact storage | MinIO | |
| 70 | +| Observability | OpenTelemetry | |
| 71 | +| Migrations | Alembic | |
| 72 | + |
| 73 | +--- |
| 74 | + |
| 75 | +## Quick Start |
62 | 76 |
|
63 | | -2. Create a virtual environment and install dependencies: |
| 77 | +### Prerequisites |
| 78 | + |
| 79 | +- **Python** 3.10+ |
| 80 | +- **PostgreSQL** 13.0+ |
| 81 | +- **Redis** 6.0+ |
| 82 | +- **uv** package manager: `curl -LsSf https://astral.sh/uv/install.sh | sh` |
| 83 | +- **Make** |
| 84 | + |
| 85 | +### Installation |
64 | 86 |
|
65 | 87 | ```bash |
| 88 | +git clone git@github.com:EvolutionAPI/evo-ai-processor-community.git |
| 89 | +cd evo-ai-processor-community |
| 90 | + |
| 91 | +# Create virtual environment and install dependencies |
66 | 92 | make venv |
67 | 93 | source venv/bin/activate # Linux/Mac |
68 | | -make install-dev # For development dependencies |
| 94 | +make install-dev |
| 95 | + |
| 96 | +# Configure environment |
| 97 | +cp .env.example .env |
| 98 | +# Edit .env with your settings |
69 | 99 | ``` |
70 | 100 |
|
71 | | -3. Set up environment variables: |
| 101 | +### Running |
72 | 102 |
|
73 | 103 | ```bash |
74 | | -cp .env.example .env |
75 | | -# Edit the .env file with your settings |
| 104 | +make run # Development with hot reload |
| 105 | +make run-prod # Production |
76 | 106 | ``` |
77 | 107 |
|
78 | | -## Running the Service |
| 108 | +The API will be available at `http://localhost:8000`. |
| 109 | + |
| 110 | +### Docker |
79 | 111 |
|
80 | 112 | ```bash |
81 | | -make run # Development |
82 | | -make run-prod # Production |
| 113 | +make docker-build |
| 114 | +make docker-up |
| 115 | +make docker-seed |
83 | 116 | ``` |
84 | 117 |
|
85 | | -The API will be available at `http://localhost:8000` |
| 118 | +--- |
86 | 119 |
|
87 | | -## 👨💻 Development Commands |
| 120 | +## Development |
88 | 121 |
|
89 | 122 | ```bash |
90 | | -# Code verification |
91 | | -make lint # Verify code with flake8 |
92 | | -make format # Format code with black |
| 123 | +# Code quality |
| 124 | +make lint # Verify with flake8 |
| 125 | +make format # Format with black |
93 | 126 |
|
94 | 127 | # Cache management |
95 | | -make clear-cache # Clean basic cache files |
96 | | -make clear-python-cache # Clean Python cache files (.pyc, __pycache__) |
97 | | -make clear-uv-cache # Clean UV package manager cache |
98 | | -make clear-all-cache # Clean all caches (comprehensive) |
99 | | - |
100 | | -# Environment management |
101 | | -make reset-venv # Reset virtual environment |
102 | | -make refresh-env # Reset environment and reinstall dependencies |
| 128 | +make clear-python-cache # Remove .pyc and __pycache__ |
| 129 | +make clear-uv-cache # Clean UV cache |
| 130 | +make clear-all-cache # Comprehensive cleanup |
| 131 | + |
| 132 | +# Environment |
| 133 | +make reset-venv # Recreate virtual environment |
| 134 | +make refresh-env # Reset and reinstall dependencies |
103 | 135 | ``` |
104 | 136 |
|
105 | | -### 🧹 Cache Management |
| 137 | +--- |
106 | 138 |
|
107 | | -When you encounter issues with cached environment variables or Python imports, use these commands: |
| 139 | +## Architecture |
108 | 140 |
|
109 | | -- **`make clear-python-cache`**: Removes Python bytecode files and `__pycache__` directories |
110 | | -- **`make clear-uv-cache`**: Cleans UV package manager cache |
111 | | -- **`make clear-all-cache`**: Comprehensive cache cleanup including system cache |
112 | | -- **`make reset-venv`**: Recreates the virtual environment |
113 | | -- **`make refresh-env`**: Complete environment refresh (recommended for persistent issues) |
| 141 | +The processor sits between the bot runtime and the agent execution layer: |
114 | 142 |
|
115 | | -## 🐳 Running with Docker |
| 143 | +``` |
| 144 | +Evo Bot Runtime |
| 145 | + ↓ |
| 146 | +Evo CRM Agent Processor ← (you are here) |
| 147 | + ↓ |
| 148 | +Google ADK / LangGraph + Vector DBs (Pinecone/Qdrant/OpenSearch) |
| 149 | + ↓ |
| 150 | +Evo CRM Backend (persistence) |
| 151 | +``` |
116 | 152 |
|
117 | | -1. Configure the `.env` file |
118 | | -2. Start the services: |
| 153 | +Key responsibilities: |
| 154 | +- **Session management**: per-conversation agent state |
| 155 | +- **Artifact storage**: stores intermediate results in MinIO |
| 156 | +- **Vector search**: semantic retrieval over knowledge bases |
| 157 | +- **Workflow orchestration**: LangGraph-based multi-agent flows |
| 158 | +- **Event processing**: emits events for downstream services |
119 | 159 |
|
120 | | -```bash |
121 | | -make docker-build |
122 | | -make docker-up |
123 | | -make docker-seed |
124 | | -``` |
| 160 | +--- |
| 161 | + |
| 162 | +## Documentation |
| 163 | + |
| 164 | +| Resource | Link | |
| 165 | +|---|---| |
| 166 | +| Website | [evolutionfoundation.com.br](https://evolutionfoundation.com.br) | |
| 167 | +| Documentation | [docs.evolutionfoundation.com.br](https://docs.evolutionfoundation.com.br) | |
| 168 | +| Community | [evolutionfoundation.com.br/community](https://evolutionfoundation.com.br/community) | |
| 169 | +| Changelog | [CHANGELOG.md](./CHANGELOG.md) | |
| 170 | +| Contributing | [CONTRIBUTING.md](./CONTRIBUTING.md) | |
| 171 | +| Security | [SECURITY.md](./SECURITY.md) | |
| 172 | + |
| 173 | +--- |
| 174 | + |
| 175 | +## Contributing |
| 176 | + |
| 177 | +Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to submit issues, propose features, and open pull requests. |
| 178 | + |
| 179 | +Join our [community](https://evolutionfoundation.com.br/community) to discuss ideas and collaborate. |
| 180 | + |
| 181 | +--- |
| 182 | + |
| 183 | +## Security |
| 184 | + |
| 185 | +For security issues, **do not open a public issue**. Email **suporte@evofoundation.com.br** or use GitHub's private vulnerability reporting. See [SECURITY.md](./SECURITY.md) for details. |
| 186 | + |
| 187 | +--- |
| 188 | + |
| 189 | +## Acknowledgments |
| 190 | + |
| 191 | +This service builds on excellent open-source software: |
| 192 | +- [FastAPI](https://fastapi.tiangolo.com/) — web framework |
| 193 | +- [LangGraph](https://github.com/langchain-ai/langgraph) — agent workflow orchestration |
| 194 | +- [Google ADK](https://github.com/google/adk-python) — agent execution |
| 195 | +- [Pinecone](https://www.pinecone.io/), [Qdrant](https://qdrant.tech/), [OpenSearch](https://opensearch.org/) — vector databases |
| 196 | +- [Alembic](https://alembic.sqlalchemy.org/) — database migrations |
| 197 | + |
| 198 | +--- |
| 199 | + |
| 200 | +## License |
| 201 | + |
| 202 | +Evo CRM Agent Processor is licensed under the Apache License 2.0. See [LICENSE](./LICENSE) for details. |
| 203 | + |
| 204 | +## Trademarks |
125 | 205 |
|
126 | | -## 🤝 Contributing |
| 206 | +"Evolution Foundation", "Evolution" and "Evo CRM Agent Processor" are trademarks of Evolution Foundation. See [TRADEMARKS.md](./TRADEMARKS.md) for the brand assets policy. |
127 | 207 |
|
128 | | -We welcome contributions from the community! Please read our [Contributing Guidelines](CONTRIBUTING.md) for more details. |
| 208 | +Third-party attributions are documented in [NOTICE](./NOTICE). |
129 | 209 |
|
130 | | -## 📄 License |
| 210 | +--- |
131 | 211 |
|
132 | | -This project is licensed under the [Apache License 2.0](./LICENSE). |
| 212 | +<p align="center"> |
| 213 | + Made by <a href="https://evolutionfoundation.com.br">Evolution Foundation</a> · © 2026 |
| 214 | +</p> |
0 commit comments