Evo AI - 人工智能代理平台

Evo AI - 人工智能代理平台

Evo AI 是一个用于创建和管理人工智能代理的开源平台，支持与不同的人工智能模型和服务集成。

🚀 概述

Evo AI 平台允许：

• 创建和管理人工智能代理
• 与不同的语言模型集成
• 客户管理和 MCP 服务器配置
• 自定义工具管理
• Google 代理开发工具包 (ADK)：代理开发的基础框架
• CrewAI 支持：代理开发的替代框架（正在开发中）
• 基于电子邮件验证的 JWT 认证
• Agent 2 Agent (A2A) 协议支持：人工智能代理之间的互操作性
• 使用 LangGraph 的工作流代理：构建复杂代理工作流
• 安全的 API 密钥管理：加密存储 API 密钥
• 代理组织：按类别组织代理的文件夹结构

🤖 代理类型

Evo AI 支持多种类型的代理，可以灵活组合：

1. LLM 代理（语言模型）

基于 GPT-4、Claude 等语言模型的代理。可配置工具、MCP 服务器和子代理。

2. A2A 代理（代理间）

实现 Google A2A 协议以实现代理间互操作性的代理。

3. 顺序代理

按特定顺序执行一系列子代理。

4. 并行代理

同时执行多个子代理。

5. 循环代理

以循环方式执行子代理，设定最大迭代次数。

6. 工作流代理

使用 LangGraph 定义的图结构，在自定义的工作流中执行子代理。

7. 任务代理

使用目标代理和结构化任务指令执行特定任务。

🛠️ 技术栈

后端

• FastAPI：用于构建 API 的 Web 框架
• SQLAlchemy：用于数据库交互的 ORM
• PostgreSQL：主数据库
• Alembic：迁移系统
• Pydantic：数据验证和序列化
• Uvicorn：ASGI 服务器
• Redis：缓存和会话管理
• JWT：安全令牌认证
• SendGrid/SMTP：用于通知的邮件服务（可配置）
• Jinja2：用于渲染邮件的模板引擎
• Bcrypt：密码哈希和安全性
• LangGraph：用于构建有状态多代理工作流的框架

前端

• Next.js 15：带有 App Router 的 React 框架
• React 18：用户界面库
• TypeScript：类型安全的 JavaScript
• Tailwind CSS：实用优先的 CSS 框架
• shadcn/ui：现代组件库
• React Hook Form：表单管理
• Zod：模式验证
• ReactFlow：基于节点的可视化工作流
• React Query：服务器状态管理

📊 Langfuse 集成（追踪与可观性）

Evo AI 平台原生支持与 Langfuse 集成，利用 OpenTelemetry (OTel) 标准对代理执行、提示、模型响应和工具调用进行详细追踪。

如何配置

1. 在你的 .env 文件中设置环境变量：

   LANGFUSE_PUBLIC_KEY="pk-lf-..."
   LANGFUSE_SECRET_KEY="sk-lf-..."
   OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel"
   

2. 在 Langfuse 控制台查看

   • 访问你的 Langfuse 控制台，查看实时追踪信息。

🤖 Agent 2 Agent (A2A) 协议支持

Evo AI 实现了 Google 的 Agent 2 Agent (A2A) 协议，实现了人工智能代理之间的无缝通信和互操作性。

有关 A2A 协议的更多信息，请访问 Google 的 A2A 协议文档。

📋 先决条件

后端

• Python：3.10 或更高版本
• PostgreSQL：13.0 或更高版本
• Redis：6.0 或更高版本
• Git：用于版本控制
• Make：用于运行 Makefile 命令

前端

• Node.js：18.0 或更高版本
• pnpm：推荐的包管理器，或 npm/yarn

🔧 安装

1. 克隆仓库

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

2. 后端设置

虚拟环境和依赖

# 创建并激活虚拟环境
make venv
source venv/bin/activate  # Linux/Mac
# 或在 Windows 上：venv\Scripts\activate

# 安装开发依赖
make install-dev

环境配置

# 复制并配置后端环境
cp .env.example .env
# 编辑 .env 文件，填写你的数据库、Redis 等设置

数据库设置

# 初始化数据库并应用迁移
make alembic-upgrade

# 种植初始数据（管理员用户、示例客户等）
make seed-all

3. 前端设置

安装依赖

# 进入前端目录
cd frontend

# 使用 pnpm 安装依赖（推荐）
pnpm install

# 或使用 npm
# npm install

# 或使用 yarn
# yarn install

前端环境配置

# 复制并配置前端环境
cp .env.example .env
# 编辑 .env 文件，填写你的 API 地址（默认：http://localhost:8000）

前端 .env 应包含：

NEXT_PUBLIC_API_URL=http://localhost:8000

🚀 运行应用

开发模式

启动后端（终端 1）

# 从项目根目录
make run
# 后端将在 http://localhost:8000 可用

启动前端（终端 2）

# 从前端目录
cd frontend
pnpm dev

# 或使用 npm/yarn
# npm run dev
# yarn dev

# 前端将在 http://localhost:3000 可用

生产模式

后端

make run-prod    # 多个工作进程的生产环境

前端

cd frontend
pnpm build && pnpm start

# 或使用 npm/yarn
# npm run build && npm start
# yarn build && yarn start

🐳 Docker 安装

使用 Docker Compose 的全栈部署

# 构建并启动所有服务（后端 + 数据库 + Redis）
make docker-build
make docker-up

# 初始化数据库并种植种子数据
make docker-seed

使用 Docker 的前端部署

# 从前端目录
cd frontend

# 构建前端镜像
docker build -t evo-ai-frontend .

# 运行前端容器
docker run -p 3000:3000 -e NEXT_PUBLIC_API_URL=http://localhost:8000 evo-ai-frontend

或者使用提供的 docker-compose：

# 从前端目录进入
cd frontend
docker-compose up -d

🎯 快速入门

安装完成后，请按照以下步骤操作：

1. 访问前端界面：打开 http://localhost:3000
2. 创建管理员账号：使用预置的管理员凭据，或注册新账号
3. 配置 MCP 服务器：设置您的第一个 MCP 服务器连接
4. 创建客户：添加一个客户以管理您的智能体
5. 构建首个智能体：创建并配置您的 AI 智能体
6. 测试智能体：通过聊天界面与您的智能体进行交互

默认管理员凭据

运行种子数据后，您可以使用以下信息登录：

• 邮箱：请查看种子数据输出中的生成管理员邮箱
• 密码：请查看种子数据输出中的生成密码

🖥️ API 文档

交互式 API 文档可在以下地址访问：

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

👨‍💻 开发命令

后端命令

# 数据库迁移
make alembic-upgrade            # 将数据库更新到最新版本
make alembic-revision message="description"  # 创建新的迁移文件

# 种子数据
make seed-all                   # 运行所有种子数据脚本

# 代码检查
make lint                       # 使用 flake8 检查代码风格
make format                     # 使用 black 格式化代码

前端命令

# 从前端目录进入
cd frontend

# 开发模式
pnpm dev                        # 启动开发服务器
pnpm build                      # 构建生产环境代码
pnpm start                      # 启动生产环境服务器
pnpm lint                       # 运行 ESLint 检查

🚀 配置

后端配置（.env 文件）

关键配置项包括：

# 数据库配置
POSTGRES_CONNECTION_STRING="postgresql://postgres:root@localhost:5432/evo_ai"

# Redis 配置
REDIS_HOST="localhost"
REDIS_PORT=6379

# AI 引擎配置
AI_ENGINE="adk"  # 可选值："adk"（Google Agent Development Kit）或 "crewai"（CrewAI 框架）

# JWT 配置
JWT_SECRET_KEY="your-jwt-secret-key"

# 邮件服务提供商配置
EMAIL_PROVIDER="sendgrid"  # 可选值："sendgrid" 或 "smtp"

# API 密钥加密密钥
ENCRYPTION_KEY="your-encryption-key"

前端配置（.env 文件）

# API 配置
NEXT_PUBLIC_API_URL="http://localhost:8000"  # 后端 API 地址

注意：虽然 Google ADK 已完全支持，但 CrewAI 引擎选项目前仍在积极开发中。在生产环境中，建议使用默认的 "adk" 引擎。

🔐 认证

API 使用 JWT（JSON Web Token）进行认证，支持以下功能：

• 用户注册与邮箱验证
• 登录获取 JWT 令牌
• 密码找回流程
• 多次登录失败后锁定账户

🚀 在 GitHub 上为我们点赞

如果您觉得 EvoAI 很有用，请为我们点亮一颗星！您的支持将帮助我们壮大社区，并持续改进产品。

🤝 贡献

我们欢迎社区的贡献！请阅读我们的 贡献指南 以了解详细信息。

📄 许可证

本项目采用 Apache License 2.0 许可证。

Evo AI 快速上手指南

Evo AI 是一个开源的 AI 智能体（Agent）平台，支持多种大语言模型集成、MCP 服务器配置以及复杂的智能体工作流编排。本指南将帮助中国开发者快速在本地搭建并运行该平台。

环境准备

在开始之前，请确保您的开发环境满足以下最低要求：

系统依赖

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)
• Git: 用于代码版本控制
• Make: 用于执行自动化命令

后端环境

• Python: 3.10 或更高版本
• PostgreSQL: 13.0 或更高版本
• Redis: 6.0 或更高版本

前端环境

• Node.js: 18.0 或更高版本
• 包管理器: 推荐使用 pnpm (也可使用 npm 或 yarn)

国内加速建议：

• Python 依赖：建议使用清华或阿里镜像源安装 (pip install -i https://pypi.tuna.tsinghua.edu.cn/simple ...)
• Node 依赖：配置 .npmrc 使用淘宝镜像 (registry=https://registry.npmmirror.com)

---

安装步骤

1. 克隆项目

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

2. 后端设置

创建虚拟环境并安装依赖

# 创建并激活虚拟环境
make venv
source venv/bin/activate  # Linux/Mac
# Windows 用户请使用: venv\Scripts\activate

# 安装开发依赖
make install-dev

配置环境变量

cp .env.example .env
# 请使用编辑器修改 .env 文件，配置数据库连接、Redis 地址及 JWT 密钥等

初始化数据库

# 执行数据库迁移
make alembic-upgrade

# 植入初始数据（包含管理员账号、示例客户端等）
make seed-all

注意：执行 make seed-all 后，终端会输出生成的默认管理员邮箱和密码，请务必记录。

3. 前端设置

进入前端目录并安装依赖

cd frontend

# 推荐使用 pnpm 安装
pnpm install

# 若使用 npm: npm install
# 若使用 yarn: yarn install

配置前端环境变量

cp .env.example .env

确保 frontend/.env 中包含以下内容（默认无需修改）：

NEXT_PUBLIC_API_URL=http://localhost:8000

---

基本使用

完成安装后，您可以按照以下步骤启动服务并开始创建第一个 AI 智能体。

1. 启动应用

您需要开启两个终端窗口分别运行后端和前端。

终端 1：启动后端

# 在项目根目录下
make run
# 后端服务将运行在 http://localhost:8000

终端 2：启动前端

# 进入 frontend 目录
cd frontend
pnpm dev
# 前端服务将运行在 http://localhost:3000

(可选) Docker 一键启动 如果您希望使用 Docker 运行全套服务（含数据库和 Redis）：

make docker-build
make docker-up
make docker-seed

2. 登录与初始化

1. 打开浏览器访问 http://localhost:3000。
2. 使用之前在 make seed-all 步骤中生成的管理员邮箱和密码登录。
3. 若无记录，可尝试注册新账号（需配置邮件服务，开发环境建议直接使用 Seeder 生成的账号）。

3. 创建您的第一个智能体

登录成功后，按以下流程操作：

1. 配置 MCP 服务器：在设置中添加您的第一个 MCP (Model Context Protocol) 服务器连接。
2. 创建客户端 (Client)：新建一个客户端用于归类管理智能体。
3. 构建智能体：
   • 选择智能体类型（如 LLM Agent, Sequential Agent, Workflow Agent 等）。
   • 配置使用的模型（支持 GPT-4, Claude 等）及工具。
   • 保存配置。
4. 测试交互：进入聊天界面，发送消息与您创建的 AI 智能体进行对话测试。

4. API 文档查看

开发者可直接访问交互式 API 文档进行调试：

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

---

提示：目前平台默认推荐使用 Google ADK 引擎 (AI_ENGINE="adk")，CrewAI 引擎尚在开发中，生产环境建议保持默认配置。