Proteus AI

What is Proteus AI about?

Proteus AI provides a flexible platform for constructing and managing complex automation tasks and intelligent agent systems. It combines chain‑of‑thought reasoning, dynamic tool calling, and a visual workflow editor to allow users to design, execute, and monitor multi‑agent pipelines.

How to use Proteus AI?

Prerequisites – Install Docker, Docker‑Compose and OpenSSL.
Build the sandbox – cd sandbox && ./build.sh && cd ...
Build the core agent image – cd proteus && docker build -t proteus-agent ..
Generate SSL certificates – ./bin/generate-ssl-cert.sh inside the proteus directory.
Configure environment variables – copy the .env.example files in docker/volumes/agent and docker/volumes/sandbox to .env and edit as needed.
Start services – cd docker && docker-compose up -d.
Access the web UI at https://localhost (or http://localhost:8000).
Interact via the web UI, CLI (proteus/bin scripts), or the Android client.

Key features of Proteus AI

Intelligent dialogue – Chain‑of‑Thought reasoning, multi‑turn context, file analysis, skill memory.
Dynamic tool invocation – Built‑in nodes for database access, web search, crawling, code execution, browser automation, email, weather, etc.
Visual workflow builder – Drag‑and‑drop node editor with support for loops, nesting, and lifecycle controls (start, pause, resume, cancel).
Real‑time monitoring – SSE‑based streaming of node status, agent thought process, and execution results.
MCP integration – Standardized external tool loading and remote MCP server interaction.
Secure sandbox – Isolated environment for Python and shell execution.
Cross‑platform clients – Web UI, powerful CLI, and Android app with SSE streaming.

Use cases of Proteus AI

Research assistant – Automated literature search, summarization, and multi‑agent deep‑research reports.
Business process automation – Chain database queries, API calls, and email notifications in a single workflow.
Customer support bots – Context‑aware chat agents that can fetch knowledge base articles or execute troubleshooting scripts.
Data enrichment pipelines – Combine web crawling, API queries, and AI summarization to enrich datasets.
DevOps automation – Execute scripts, manage cloud resources, and monitor tasks through visual workflows.

FAQ from the Proteus AI

Q: Do I need to write code to add new node types? A: No. New nodes can be added by creating a Python file under proteus/src/nodes/ and registering it in agent_node_config.yaml.

Q: How is code execution sandboxed? A: The sandbox runs in a separate Docker container built from the sandbox directory, isolating filesystem and network access.

Q: Can I run Proteus AI without Docker? A: It is possible but not recommended; the Docker setup ensures isolation of the sandbox and simplifies service orchestration.

Q: What models are supported? A: Any LLM accessible via the configured model_name (e.g., deepseek-chat). Model endpoints are defined in the configuration files under proteus/conf/.

Q: How do I enable MCP tool integration? A: Define MCP server credentials in the environment variables and use the mcp-agent mode when launching an agent.

Proteus AI：多智能体工作流引擎

Proteus AI 是一个强大的、可扩展的、基于 Python 和 FastAPI 构建的多智能体工作流引擎。它旨在提供一个灵活、高效的平台，用于构建和管理复杂的自动化任务和智能代理系统。

🌊 项目名称由来

Proteus（普罗透斯）源自希腊神话中的海神，他以能够随意改变自己的形态而闻名。这个名字完美契合了本项目的核心特性：

强大的可变性：引擎通过不同节点类型的组合实现各种复杂的工作流
智能适应：Agent 系统能够智能地选择最适合的工具和执行路径
灵活性：引擎能够灵活处理各种任务场景和数据流

✨ 核心特性

🧠 智能对话系统

高级推理能力：基于 Chain-of-Thought (CoT) 推理，支持复杂的任务分解和决策
动态工具调用：智能体能够根据任务需求动态选择并调用内置或外部工具
多轮对话与上下文管理：支持多轮对话，保持上下文连贯性，提升交互体验
技能系统：支持技能调用和技能记忆，可扩展智能体能力
文件分析：支持上传文件并基于文件内容进行问答和分析

🔄 灵活的工作流编排

可视化工作流构建：直观的 Web 界面支持节点和边的拖拽，轻松构建复杂工作流
完整的生命周期管理：支持工作流的创建、启动、暂停、恢复和取消
智能调度：处理节点依赖关系，确保数据流和执行顺序正确
异步执行与实时监控：基于 SSE (Server-Sent Events) 实现实时通信，监控节点执行状态和结果
高级工作流结构：支持循环执行和工作流嵌套，提升复用性和灵活性

🛠️ 丰富的内置节点与可扩展性

内置多种节点类型，涵盖多种操作，并支持轻松扩展：

类别	节点类型	功能描述
数据库操作	`db_query`, `db_execute`, `mysql_node`	数据库查询和执行
信息检索	`duckduckgo_search`, `arxiv_search`, `serper_search`	多种搜索引擎集成
Web 爬虫	`web_crawler`	网页内容抓取
代码与自动化	`python_execute`	Python 代码和 Shell 脚本执行（沙箱环境）
浏览器自动化	`browser_agent`	浏览器操作自动化
交互与通信	`api_call`, `chat`, `email_sender`	API 调用、聊天节点、邮件发送
技能管理	`skills_extract`	技能解析与管理（列出、获取、读取技能文件）
特殊功能	`weather_forecast`	天气预报查询（通过经纬度获取天气数据）

📊 实时监控与可视化

SSE 实时通信：通过 Server-Sent Events 实现前后端实时数据传输
节点状态实时更新：Web 界面实时展示节点执行进度、状态和结果
智能体思考过程可视化：实时显示智能体思考过程和操作，增强可观察性
历史记录管理：支持会话历史的查询、存储、摘要生成和恢复

🔌 MCP (Model Context Protocol) 支持

标准化外部工具集成：支持 MCP 标准，动态加载和管理外部工具和资源
远程 MCP 服务器集成：通过 MCP 客户端节点与外部服务无缝交互
LLM 工具理解：标准化的工具描述便于大型语言模型 (LLM) 理解和使用工具

🛡️ 安全沙箱环境

提供独立的沙箱环境，用于安全地执行 Python 代码和终端命令，隔离潜在风险。

🎨 用户友好的界面与工具

Web 可视化界面：提供直观的 Web 界面进行工作流构建、智能体交互和状态监控
命令行工具 (CLI)：功能强大的 CLI 工具，方便开发者和用户在终端中直接与 Proteus AI 系统交互

📋 实际效果展示

请查看 examples/ 文件夹中的研究报告示例，展示 Proteus 在复杂信息收集和分析方面的能力：

🚀 快速开始

请严格遵循以下流程构建和启动项目。

前提条件

Docker & Docker Compose
OpenSSL (用于生成 SSL 证书)

构建与启动流程

1. 构建 Sandbox 镜像

首先构建用于安全执行代码的沙箱环境镜像。

cd sandbox
./build.sh
cd ..

2. 构建 Proteus 镜像

构建核心 Agent 服务的镜像。

cd proteus
docker build -t proteus-agent .

3. 生成 SSL 证书

为 Nginx 服务生成 SSL 证书，以支持 HTTPS 访问。

# 确保在 proteus 目录下
./bin/generate-ssl-cert.sh

4. 启动服务

进入 Docker 目录并启动所有服务。

cd docker

# 首次启动前，请确保配置了必要的环境变量
# 复制示例配置文件
# cp volumes/agent/.env.example volumes/agent/.env
# cp volumes/sandbox/.env.example volumes/sandbox/.env

# 启动服务
docker-compose up -d

服务启动后：

Web 界面访问地址: https://localhost (通过 Nginx 代理) 或 http://localhost:8000
Sandbox 服务运行在: http://localhost:8000 (容器内部端口)

⚙️ 配置说明

主要配置项位于 proteus/docker/volumes/agent/.env 文件中。您需要从 .env.example 复制并配置：

🤖 智能体模式

Proteus AI 提供多种智能体运行模式，适用于不同场景：

模式	描述
`chat`	纯对话模式，支持工具调用和多轮对话
`task`	任务模式，自动规划并完成复杂任务
`workflow`	工作流模式，执行可视化工作流
`super-agent`	超级智能体，具备更强的规划与执行能力
`mcp-agent`	MCP 模式，通过 Model Context Protocol 调用外部工具
`browser-agent`	浏览器操作模式，支持自动化网页交互
`deep-research`	深度研究模式，对指定主题进行系统性深度研究
`deep-research-multi`	多智能体协作深度研究模式
`codeact-agent`	代码执行智能体，通过编写和运行代码解决问题

🧠 Chat 智能体

Proteus AI 的核心是 Chat 智能体，这是一个功能强大的对话智能体，支持工具调用和上下文管理：

# 使用 Chat 智能体进行对话
chat_agent = ChatAgent(
    stream_manager=stream_manager,
    model_name="deepseek-chat",
    enable_tools=True,
    tool_choices=["serper_search", "web_crawler", "python_execute"],
    max_tool_iterations=5,
    conversation_id=conversation_id,
    conversation_round=5,
    enable_tool_memory=True,
    enable_skills_memory=True,
    user_name=user_name,
    selected_skills=selected_skills,
    workspace_path=workspace_path,  # 可选，工作区路径
)

# 运行智能体
result = await chat_agent.run(
    chat_id=chat_id,
    text="请搜索最新的人工智能发展动态并进行分析",
    file_analysis_context=file_context
)

核心特性：

多轮对话：支持上下文记忆，能够理解对话历史
动态工具调用：根据用户意图自动选择并调用合适的工具（如搜索、代码执行、网页爬取）
文件分析：支持上传文件并基于文件内容进行问答和分析
实时流式响应：通过 SSE 实时输出思考过程和回复内容
技能系统：支持技能调用和技能记忆，可扩展智能体能力
工具记忆：记录工具调用历史，优化后续交互

🛠️ 开发指南

1. 项目结构

proteus-ai/
├── proteus/                 # 主应用目录
│   ├── src/                # 源代码
│   │   ├── agent/          # 智能体系统（chat_agent.py、base_agent.py、prompt/）
│   │   ├── nodes/          # 节点实现（agent_node_config.yaml 及各节点文件）
│   │   ├── api/            # API 接口（stream_manager、llm_api、events 等）
│   │   ├── auth/           # 认证模块
│   │   ├── login/          # 登录模块
│   │   ├── manager/        # 管理器模块（会话、模型等）
│   │   ├── tasks/          # 任务处理器
│   │   └── utils/          # 工具函数
│   ├── static/             # 静态文件（Web 界面）
│   ├── conf/               # 配置文件（压缩策略、模型配置等）
│   ├── docker/             # Docker 配置及 volumes
│   ├── bin/                # 脚本工具（SSL 证书生成等）
│   ├── scripts/            # 辅助脚本
│   ├── tests/              # 测试文件
│   └── requirements.txt    # Python 依赖
├── sandbox/                # 沙箱环境（安全代码执行）
├── app/                    # Android 客户端
│   └── src/                # Kotlin/Compose 源码
├── server/                 # 轻量级 Web 服务器
│   ├── main.py             # FastAPI 主应用
│   ├── requirements.txt    # Python 依赖
│   └── .env.example        # 环境变量示例
├── examples/               # 使用示例
│   ├── deep-research/      # 深度研究报告示例
│   └── self_improving_agent/ # 自我改进智能体示例
├── AGENTS.md               # 智能体详细文档
└── README.md               # 项目说明

2. 添加新节点类型

在 proteus/src/nodes/ 目录下创建新的节点文件
在 proteus/src/nodes/agent_node_config.yaml 中注册 Agent 工具配置

3. 扩展 Agent 功能

在 proteus/src/agent/prompt/ 中添加新的提示词模板
修改 proteus/src/agent/agent.py 实现新的推理方法
注册新的工具到 Agent 系统

4. 前端开发

静态资源位于 proteus/static/ 目录
使用 SSE 接收实时更新

5. 测试指南

# 运行测试
cd proteus
python -m pytest tests/

6. 使用 MCP 功能

配置 MCP 服务器
在代码中使用 MCP 管理器
在 Agent 中使用 MCP 工具

📱 Android 客户端 (app/)

app/ 目录包含 Proteus AI 的官方 Android 客户端，基于 Jetpack Compose + Kotlin + Material Design 3 构建，让你随时随地通过手机使用 AI 智能体服务。详细说明见 app/README.md。

主要功能

实时流式对话：通过 SSE 实时接收 AI 回复，支持 Markdown 渲染和 Mermaid 图表
思考过程可视化：可折叠卡片展示 AI 推理链路和工具调用详情
三种增强模式：深度研究 🌐 / 网络搜索 🔍 / 技能调用 🛠️，按需开启
会话历史管理：侧边栏显示所有历史对话，点击即可加载历史记录
Token 管理：Bearer Token 安全持久化存储
停止任务：AI 回复过程中可随时中断
Material Design 3：支持深色/浅色主题自动切换

快速上手

1. 启动后端服务

按照本 README 上方的"快速开始"章节启动 Proteus AI 后端服务。

2. 编译安装应用

# 进入 app 目录
cd app

# 编译调试版 APK（需已配置 Android SDK 环境变量）
./gradlew assembleDebug

# 安装到已连接的 Android 设备
adb install app/build/outputs/apk/debug/app-debug.apk

推荐使用 Android Studio 2023.3+ 打开 app/ 目录，点击 ▶️ Run 直接安装并运行。

3. 配置服务器地址

场景	配置方式
Android 模拟器访问本机（默认）	无需修改，默认 `http://10.0.2.2:8888/`
真机访问局域网服务器	修改 `app/build.gradle.kts` 中 `defaultConfig` 的 `BASE_URL` 为局域网 IP
生产环境	修改 `buildTypes.release` 中的 `BASE_URL`

4. 首次使用

启动应用，自动弹出 Token 配置对话框
输入 Proteus AI 后端服务的 Bearer Token
确认后自动加载历史会话，即可开始对话

更多详细说明（架构、接口文档、常见问题等）请查看 app/README.md。

🌐 轻量级 Web 服务器 (server/)

server/ 目录包含一个基于 FastAPI 的轻量级 Web 服务器，提供对话管理、模型配置查询、任务队列提交和 SSE 流式重放等接口，详细说明见 server/README.md。

主要接口

方法	路径	说明
`GET`	`/conversations`	获取当前用户的会话列表
`GET`	`/conversations/{id}`	获取指定会话详情
`GET`	`/models`	获取可用模型列表
`GET`	`/replay/stream/{chat_id}`	SSE 流式重放已保存的聊天记录
`POST`	`/submit_task`	提交任务到 Redis 队列
`GET`	`/health`	服务健康检查

快速启动

cd server

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env，填写 Redis 连接信息

# 启动服务
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

服务启动后可访问：

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

认证方式

在请求头中携带 Bearer Token：

Authorization: Bearer <your_token>

🔮 未来计划

我们致力于不断改进 Proteus 引擎，以下是未来可能优先考虑的功能和优化：

核心功能增强

完善工作流的暂停和恢复机制
引入工作流模板系统
实现工作流版本控制
增加节点执行超时机制

节点类型扩展

集成更多主流 AI 模型和第三方服务 API
实现文件格式转换节点
添加邮件和消息通知节点

Agent 系统优化

进一步优化 Chain-of-Thought 推理
增强多智能体协作机制
实现智能体记忆系统和知识共享
增强错误处理和恢复能力

用户体验改进

优化 Web 界面交互
添加工作流调试工具
实现工作流执行日志导出功能
增加性能监控面板

部署和运维

添加集群部署支持
实现自动化测试框架
优化资源使用效率
增加监控告警机制

🤝 贡献指南

欢迎提交 Issue 和 Pull Request 来帮助改进项目。在提交代码前，请确保：

代码符合项目的编码规范
添加了必要的测试用例
更新了相关文档
遵循 Git 提交规范
通过所有 CI 检查

📄 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

🔗 相关资源

💬 支持与反馈

如果您在使用过程中遇到问题或有改进建议，请通过以下方式联系我们：

提交 GitHub Issue
查看项目文档
参与社区讨论

Proteus AI - 让复杂任务变得简单自动化

Proteus AI Overview