Evo AI

repository·main·Indexed 20 days ago

https://github.com/evolution-foundation/evo-ai

An open-source platform for creating, managing, and orchestrating AI agents. Evo AI supports multiple agent architectures—including Sequential, Parallel, Loop, and Workflow (via LangGraph)—and integrates with LLMs and frameworks such as Google's ADK. The platform includes a FastAPI backend and a Next.js frontend, featuring native Langfuse integration for tracing and observability via OpenTelemetry.

Tokens: 10.1K
Snippets: 38
Records: 48
Agent score: 69%

What's inside evo-ai

Understand the different Agent Types in Evo AI
main
Evo AI supports several agent architectures that can be combined to build complex systems:
1. LLM Agent (Language Model): The base agent powered by models like GPT-4 or Claude. It can be equipped with tools, MCP servers, and sub-agents.
2. A2A Agent (Agent-to-Agent): Implements Google's A2A protocol for interoperability between different AI agents.
3. Sequential Agent: Executes a list of sub-agents in a strict, predefined order.
4. Parallel Agent: Executes multiple sub-agents simultaneously.
5. Loop Agent: Executes sub-agents repeatedly until a maximum number of iterations is reached.
6. Workflow Agent: Uses LangGraph to execute sub-agents based on a custom graph structure (stateful workflows).
7. Task Agent: Executes a specific task by targeting a specific agent with structured instructions.
https://github.com/evolution-foundation/evo-ai/blob/main/README.md

Install and run Evo AI (Full Stack)

main

To set up the Evo AI platform locally, follow these steps to install both the backend and frontend components.

1. Clone and Backend Setup

# Clone the repository
git clone https://github.com/EvolutionAPI/evo-ai.git
cd evo-ai

# Setup virtual environment and dependencies
make venv
source venv/bin/activate  # Linux/Mac
# or on Windows: venv\Scripts\activate

make install-dev

# Configure environment
cp .env.example .env

# Initialize database and seed data
make alembic-upgrade
make seed-all

2. Frontend Setup

cd frontend

# Install dependencies
pnpm install

# Configure environment
cp .env.example .env
# Ensure NEXT_PUBLIC_API_URL is set to your backend URL (e.g., http://localhost:8000)

3. Running in Development Mode

Open two terminals:

Terminal 1 (Backend): From the project root, run make run.
Terminal 2 (Frontend): From the frontend directory, run pnpm dev.

# From project root
make run

# From frontend directory
cd frontend
pnpm dev

Install Evo AI using Docker Compose
main
For a containerized deployment of the full stack (backend, database, and redis), use the provided Docker commands.
```
# Build and start all services
make docker-build
make docker-up

# Initialize database with seed data
make docker-seed
```
```
make docker-build
make docker-up
make docker-seed
```
https://github.com/evolution-foundation/evo-ai/blob/main/README.md

Configure the Backend environment

main

The backend requires several key settings in the .env file to function correctly.

Key	Description
`POSTGRES_CONNECTION_STRING`	Connection string for PostgreSQL (e.g., `postgresql://postgres:root@localhost:5432/evo_ai`)
`REDIS_HOST`	Host for Redis
`REDIS_PORT`	Port for Redis
`AI_ENGINE`	The agent framework to use. Options: `adk` (Google Agent Development Kit - recommended) or `crewai` (in development)
`JWT_SECRET_KEY`	Secret key for JWT authentication
`EMAIL_PROVIDER`	Email service provider. Options: `sendgrid` or `smtp`
`ENCRYPTION_KEY`	Key used for secure storage of API keys

Note: For production, it is recommended to use the adk engine as crewai is still under development.

POSTGRES_CONNECTION_STRING="postgresql://postgres:root@localhost:5432/evo_ai"
REDIS_HOST="localhost"
REDIS_PORT=6379
AI_ENGINE="adk"
JWT_SECRET_KEY="your-jwt-secret-key"
EMAIL_PROVIDER="sendgrid"
ENCRYPTION_KEY="your-encryption-key"

Configure Langfuse for Tracing and Observability
main
Evo AI supports native integration with Langfuse using the OpenTelemetry (OTel) standard to trace agent executions, prompts, model responses, and tool calls. To enable this, add the following environment variables to your backend .env file:
```
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_SECRET_KEY="sk-lf-..."
OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel"
```
```
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_SECRET_KEY="sk-lf-..."
OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel"
```
https://github.com/evolution-foundation/evo-ai/blob/main/README.md

Configure agent types and requirements

main

When creating or updating agents via create_agent or update_agent, the config object must adhere to specific requirements based on the agent's type:

Agent Type	Required Config Keys / Behavior
`a2a`	Requires `agent_card_url`. The service will fetch the agent card from this URL (which must end in `/.well-known/agent.json`) to populate name and description.
`workflow`	Automatically generates an `api_key` in the config if not provided.
`task`	Requires a `tasks` list. Each task in the list must contain an `agent_id` pointing to a valid existing agent.
`sequential`, `parallel`, `loop`	Requires a `sub_agents` list containing valid agent IDs.
`llm`	Standard LLM configuration.

Common Config Keys:

api_key: A unique identifier for the agent (automatically generated if missing).
tools: A list of tool objects: [{"id": "tool_id", "envs": {}}].
agent_tools: A list of agent IDs that serve as tools.
mcp_servers: A list of configured MCP servers.
custom_mcp_servers: A list of custom MCP server URLs and headers: [{"url": "...", "headers": {}}].

Authenticate with the Evo AI API
main
To access protected API routes, you must use JWT authentication. The initial step is to authenticate via the login endpoint located at /api/v1/auth/login.
https://github.com/evolution-foundation/evo-ai/blob/main/src/main.py
Run the Evo AI Frontend via Docker Compose
main
You can deploy the Evo AI frontend using Docker Compose. The service runs on port 3000 by default and requires the NEXT_PUBLIC_API_URL environment variable to connect to the backend API.
To run the service, ensure you have a docker-compose.yml configured as shown below and execute docker-compose up.
```
version: '3.8'

services:
  frontend:
    image: evoapicloud/evo-ai-frontend:latest
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_URL=https://api-teste.evoapicloud.com
    volumes:
      - ./docker-entrypoint.sh:/docker-entrypoint.sh
    restart: unless-stopped
```
https://github.com/evolution-foundation/evo-ai/blob/main/frontend/docker-compose.yml
Configure the Frontend API URL
main
The frontend service uses the NEXT_PUBLIC_API_URL environment variable to determine the endpoint for backend API requests. This must be set in the environment section of your Docker configuration.
Environment Variable:
- NEXT_PUBLIC_API_URL: The full URL of the Evo AI backend API (e.g., https://api-teste.evoapicloud.com).
https://github.com/evolution-foundation/evo-ai/blob/main/frontend/docker-compose.yml
Configure Evo AI API via environment variables
main
The api service (image evoapicloud/evo-ai:latest) is the core of the Evo AI platform. It requires several environment variables for database connectivity, caching, security, and email services.
Database & Cache
- POSTGRES_CONNECTION_STRING: Connection URI for PostgreSQL. Defaults to postgresql://postgres:${POSTGRES_PASSWORD:-postgres}@postgres:5432/evo_ai.
- REDIS_HOST: Host for Redis (defaults to redis).
- REDIS_PORT: Port for Redis (defaults to 6379).
- REDIS_PASSWORD: Password for Redis (defaults to empty string).
- REDIS_SSL: Set to "false" for non-SSL connections.
- REDIS_KEY_PREFIX: Prefix for Redis keys (defaults to a2a:).
- REDIS_TTL: Time-to-live for Redis keys in seconds (defaults to 3600).
Security & Application
- JWT_SECRET_KEY: Required. Secret key used for signing JSON Web Tokens.
- APP_URL: The base URL of the application.
- LOG_LEVEL: Logging verbosity (e.g., INFO, DEBUG). Defaults to INFO.
- DEBUG: Enables debug mode. Defaults to false.
Email Services
- SENDGRID_API_KEY: API key for SendGrid.
- EMAIL_FROM: The email address used as the sender.
```
# Example environment configuration
JWT_SECRET_KEY: "your-super-secret-key"
APP_URL: "http://localhost:8000"
SENDGRID_API_KEY: "SG.your_key"
EMAIL_FROM: "noreply@example.com"
POSTGRES_PASSWORD: "securepassword"
```
https://github.com/evolution-foundation/evo-ai/blob/main/docker-compose.yml
Configure the PostgreSQL connection string
main
The Evo AI API uses a PostgreSQL database. You can configure the connection by setting the POSTGRES_CONNECTION_STRING environment variable. If not provided, it defaults to postgresql://postgres:root@localhost:5432/evo_ai.
On startup, the application automatically creates the necessary database tables using SQLAlchemy's Base.metadata.create_all.
```
export POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/dbname"
```
https://github.com/evolution-foundation/evo-ai/blob/main/src/main.py

Configure Redis via environment variables

main

Evo AI uses environment variables to configure its Redis connection. You can set these variables in a .env file or your system environment. If a variable is not provided, the system uses the default values listed below.

Environment Variable	Default Value	Description
`REDIS_HOST`	`localhost`	The hostname or IP address of the Redis server
`REDIS_PORT`	`6379`	The port number for the Redis connection
`REDIS_DB`	`0`	The database index to use
`REDIS_PASSWORD`	`None`	The password for authentication
`REDIS_SSL`	`false`	Set to `true` to enable SSL/TLS connection
`REDIS_KEY_PREFIX`	`a2a:`	A prefix applied to keys to prevent collisions
`REDIS_TTL`	`3600`	The default Time-To-Live (in seconds) for keys

Evo AI

What's inside evo-ai

1. Clone and Backend Setup

2. Frontend Setup

3. Running in Development Mode

Database & Cache

Security & Application

Email Services