# SuperAGI 代理框架

## 概览

[SuperAGI](https://github.com/TransformerOptimus/SuperAGI) 是一个开源、面向开发者的自主 AI 代理框架，拥有 15K+ 的 GitHub 收藏。与简单的聊天机器人不同，SuperAGI 运行 **自主代理** —— 能够独立规划、执行多步骤任务、使用工具并在没有持续人工输入的情况下为达成目标进行迭代的 AI 系统。

**为什么在 Clore.ai 上运行 SuperAGI？**

* **可选 GPU，强大的本地 LLM 支持** —— 在 Clore.ai 的 GPU 上运行由本地模型（Llama、Mistral 等）支撑的代理，以实现完全私有、可控成本的自主 AI。
* **并发代理执行** —— 在同一服务器上并行运行多个代理，每个代理同时处理不同任务。
* **持久化代理记忆** —— 代理保持上下文，从工具输出中学习，并在运行间将长期记忆存储在向量数据库中。
* **工具市场** —— 预构建的 Google 搜索、GitHub、电子邮件、Jira、Notion 等集成。
* **Clore.ai 经济性** —— 以 RTX 3090 约 $0.20/小时 的价格，你可以以云 AI 服务费用的一小部分运行功能强大的自主代理。

### 主要特性

| 特性      | 4s                              |
| ------- | ------------------------------- |
| 代理配置    | 通过 GUI 创建、配置和部署代理               |
| 工具市场    | 30+ 内建工具（搜索、代码、文件、API）          |
| 多模型支持   | OpenAI、Anthropic，通过自定义端点的本地 LLM |
| 并发代理    | 同时运行多个代理                        |
| 代理记忆    | 短期（上下文窗口）+ 长期（向量数据库）            |
| GUI 仪表板 | 用于代理管理的完整 Web 界面                |
| 资源管理器   | 跟踪每个代理的令牌使用和成本                  |
| 工作流模板   | 用于常见任务的预构建代理模板                  |

### 架构

```
┌────────────────────────────────────────────────────┐
│              SuperAGI 架构栈                         │
│                                                    │
│  ┌─────────────────────┐   ┌───────────────────┐   │
│  │  前端（端口 3000）  │   │  API（端口 8001） │   │
│  │   Next.js 界面       │   │  FastAPI 后端       │   │
│  └──────────┬──────────┘   └─────────┬─────────┘   │
│             └──────────┬─────────────┘             │
│                        ▼                           │
│  ┌─────────────────────────────────────────────┐   │
│  │              代理执行器                      │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  │   │
│  │  │  代理 1   │  │  代理 2   │  │  代理 N   │  │   │
│  │  └──────────┘  └──────────┘  └──────────┘  │   │
│  └───────┬─────────────┬─────────────┬─────────┘   │
│          ▼             ▼             ▼             │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐      │
│  │ PostgreSQL │  │  Redis    │  │  向量数据库 │      │
│  │  （状态）  │  │  （队列） │  │            │      │
│  └───────────┘  └───────────┘  └───────────┘      │
└────────────────────────────────────────────────────┘
          │
    ┌─────┴──────┐
    ▼            ▼
 OpenAI      本地 LLM
 Anthropic   （Ollama/vLLM）
```

***

## 要求

### 服务器规格

| 组件      | 最低        | 推荐               | 注意事项            |
| ------- | --------- | ---------------- | --------------- |
| **GPU** | 无（API 模式） | RTX 3090（本地 LLM） | 本地模型推理需要 GPU    |
| **显存**  | —         | 24 GB            | 用于运行 13B+ 的本地模型 |
| **CPU** | 4 个 vCPU  | 8 vCPU           | 代理执行对 CPU 资源需求大 |
| **内存**  | 8 GB      | 16 GB            | 多个并发代理需要内存      |
| **存储**  | 20 GB     | 100+ GB          | 代理日志、向量数据库、模型存储 |

### Clore.ai 价格参考

| 服务器类型             | 大致费用            | 模型变体                                |
| ----------------- | --------------- | ----------------------------------- |
| CPU（8 vCPU，16 GB） | 约 $0.10–0.20/小时 | SuperAGI + 外部 API（OpenAI/Anthropic） |
| RTX 3090（24 GB）   | \~$0.20/小时      | SuperAGI + Ollama 13B 本地模型          |
| RTX 4090（24 GB）   | \~$0.35/小时      | SuperAGI + Ollama，更快的推理             |
| 2× RTX 3090       | \~$0.40/小时      | SuperAGI + 70B 模型（Q4 量化）            |
| A100 80 GB        | \~$1.10/小时      | SuperAGI + 大模型，高并发                  |
| H100 80 GB        | 约 $2.50/小时      | 生产级自主代理系统                           |

> 💡 **成本提示：** 对于开发和测试，使用 OpenAI 或 Anthropic API（不需要 GPU）。仅当需要为隐私或成本原因进行本地 LLM 推理时才切换到 GPU 实例。详见 [GPU 比较指南](https://docs.clore.ai/guides/guides_v2-zh/kuai-su-ru-men/gpu-comparison).

### 先决条件

* 带 SSH 访问的 Clore.ai 服务器
* Docker + Docker Compose（Clore.ai 上预装）
* Git（预装）
* 4+ vCPU，8+ GB 内存（并发代理推荐 16 GB）
* OpenAI API 密钥 **或** 本地 LLM 端点（Ollama/vLLM）

***

## 快速开始

### 方法 1：Docker Compose（官方 — 推荐）

SuperAGI 的官方部署使用 Docker Compose 来管理所有服务。

**步骤 1：连接到你的 Clore.ai 服务器**

```bash
ssh root@<your-clore-server-ip> -p <ssh-port>
```

**步骤 2：克隆并配置**

```bash
git clone https://github.com/TransformerOptimus/SuperAGI.git
cd SuperAGI
cp config_template.yaml config.yaml
```

**步骤 3：编辑 `config.yaml`**

```bash
nano config.yaml
```

最低所需配置：

```yaml
# config.yaml
OPENAI_API_KEY: "sk-your-openai-key-here"

# 数据库（对于 Docker Compose 可保留默认）
POSTGRES_DB: "super_agi"
POSTGRES_USER: "super_agi"
POSTGRES_PASSWORD: "password"

# 向量数据库
VECTOR_STORE: "Redis"  # 或 "Pinecone"、"Qdrant"、"Weaviate"
REDIS_URL: "redis://super__agi-redis-1:6379/0"

# 应用设置
ENV: "PROD"
ALLOW_LISTS_CREATION: "true"

# 可选：限制访问
# AUTH_SECRET_KEY: "your-random-secret"
```

**第 4 步：启动堆栈**

```bash
docker compose up -d --build
```

构建过程会下载依赖并编译前端（首次运行大约 5–10 分钟）。

**步骤 5：监控启动**

```bash
# 观察所有服务启动
docker compose ps

# 跟随日志
docker compose logs -f

# 在后端日志中等待 “Application startup complete”
docker compose logs superagi-backend --tail 30
```

**步骤 6：访问仪表板**

```
http://<your-clore-server-ip>:3000
```

API 可访问于：

```
http://<your-clore-server-ip>:8001
```

API 文档：

```
http://<your-clore-server-ip>:8001/docs
```

***

### 方法 2：使用预构建镜像快速上手

使用预构建镜像可以更快启动（跳过构建步骤）：

```bash
git clone https://github.com/TransformerOptimus/SuperAGI.git
cd SuperAGI
cp config_template.yaml config.yaml

# 在配置中填写你的 API 密钥
nano config.yaml

# 如有可用，使用预构建镜像
docker compose -f docker-compose.yaml pull
docker compose up -d
```

***

### 方法 3：最小单模型设置

用于仅使用 OpenAI 的简化测试设置：

```bash
git clone https://github.com/TransformerOptimus/SuperAGI.git
cd SuperAGI

# 创建最小配置
cat > config.yaml << 'EOF'
OPENAI_API_KEY: "sk-your-key-here"
POSTGRES_DB: "super_agi"
POSTGRES_USER: "super_agi"
POSTGRES_PASSWORD: "superagi_password_123"
REDIS_URL: "redis://super__agi-redis-1:6379/0"
ENV: "PROD"
EOF

docker compose up -d --build

# 监控构建进度
docker compose logs superagi-frontend --tail 5 -f &
docker compose logs superagi-backend --tail 5 -f
```

***

## 配置

### `config.yaml` 参考

```yaml
# ============================================================
# LLM 提供商
# ============================================================
OPENAI_API_KEY: "sk-..."                    # OpenAI GPT 模型
ANTHROPIC_API_KEY: "sk-ant-..."            # Claude 模型

# 对于本地模型（Ollama 或与 OpenAI 兼容的 API）
# 在 UI 中设置：Settings → Models → Custom Model
OPENAI_API_BASE: "http://172.17.0.1:11434/v1"  # 与宿主同机的 Ollama
OPENAI_MODEL: "llama3.1:8b"

# ============================================================
# 数据库
# ============================================================
POSTGRES_DB: "super_agi"
POSTGRES_USER: "super_agi"
POSTGRES_PASSWORD: "your-strong-password"

# ============================================================
# 向量数据库（代理长期记忆）
# ============================================================
VECTOR_STORE: "Redis"       # Redis（默认，内置）
# 或使用外部：
# VECTOR_STORE: "Pinecone"
# PINECONE_API_KEY: "your-key"
# PINECONE_ENVIRONMENT: "us-east-1-aws"

# VECTOR_STORE: "Weaviate"
# WEAVIATE_URL: "http://weaviate:8080"

# ============================================================
# 工具 API 密钥（可选，针对特定工具）
# ============================================================
GOOGLE_API_KEY: "your-google-key"
GOOGLE_CUSTOM_SEARCH_ENGINE_ID: "your-cx-id"
GITHUB_TOKEN: "ghp_your-token"
JIRA_EMAIL: "your@email.com"
JIRA_API_TOKEN: "your-jira-token"
JIRA_SERVER_URL: "https://your-org.atlassian.net"

# ============================================================
# 存储
# ============================================================
STORAGE_TYPE: "File"        # 本地文件存储
# STORAGE_TYPE: "S3"        # 兼容 S3（MinIO、AWS）
# BUCKET_NAME: "superagi"
# AWS_ACCESS_KEY_ID: "..."
# AWS_SECRET_ACCESS_KEY: "..."

# ============================================================
# 安全
# ============================================================
JWT_SECRET_KEY: "your-random-secret-key"
```

### 将 SuperAGI 连接到工具

工具可通过 GUI 在以下位置配置： **Settings → Toolkit**。每个工具可针对每个代理启用/禁用。

**内置工具：**

| 工具         | 用途                        | 需要 API 密钥     |
| ---------- | ------------------------- | ------------- |
| Google 搜索  | 网页搜索                      | 是（Google API） |
| DuckDuckGo | 网页搜索                      | 否             |
| GitHub     | 代码仓库访问                    | 是（GitHub 令牌）  |
| 电子邮件       | 发送/读取电子邮件                 | 是（SMTP 配置）    |
| 代码写入器      | 编写并执行代码                   | 否             |
| 文件管理器      | 读取/写入本地文件                 | 否             |
| 浏览器        | 无头网页浏览                    | 否             |
| Jira       | 问题跟踪                      | 是             |
| Notion     | 知识库                       | 是             |
| 图像生成       | DALL-E 3、Stable Diffusion | 是（OpenAI 密钥）  |

### 创建你的第一个代理

通过 GUI（Settings → Agents → Create Agent）：

1. **名称** —— 给你的代理起一个描述性名称
2. **4s** —— 该代理的功能
3. **目标** —— 列出目标（每行一项）
4. **指令** —— 行为的系统提示
5. **A100** —— 选择 LLM（GPT-4、Claude 或 本地）
6. **工具** —— 启用相关工具
7. **最大迭代次数** —— 安全限制（通常 10–50）

通过 REST API：

```bash
# 通过 API 创建代理
curl -X POST "http://localhost:8001/v1/agent" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Agent",
    "description": "Researches topics and writes summaries",
    "goal": [
      "Research the topic provided",
      "Write a comprehensive summary",
      "Save the summary to a file"
    ],
    "agent_type": "Task Queue",
    "constraints": [],
    "tools": ["DuckDuckGoSearch", "WriteFileTool", "ReadFileTool"],
    "exit_criterion": "No exit criterion",
    "max_iterations": 25,
    "user_timezone": "UTC",
    "llm_model_config": {
      "model_name": "gpt-4o-mini",
      "temperature": 0.5,
      "max_new_tokens": 2000
    }
  }'
```

***

## GPU 加速

SuperAGI 支持通过任何与 OpenAI 兼容的端点进行本地 LLM 推理，非常适合使用 GPU 支持的 Clore.ai 部署。

### 将 Ollama 设置为代理的 LLM 后端

参见 [Ollama 指南](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama) 用于完整 Ollama 设置的说明。与 SuperAGI 的集成：

**步骤 1：在相同的 Clore.ai 服务器上启动 Ollama**

```bash
docker run -d \
  --name ollama \
  --gpus all \
  --restart unless-stopped \
  -p 11434:11434 \
  -v ollama_models:/root/.ollama \
  ollama/ollama

# 拉取适合代理使用的强力模型（需要良好的推理能力）
docker exec ollama ollama pull llama3.1:8b        # 快速，推理能力强
docker exec ollama ollama pull mistral:7b-instruct  # 适合代码任务
docker exec ollama ollama pull deepseek-coder:6.7b # 适合代码密集型代理
```

**步骤 2：配置 SuperAGI 使用 Ollama**

在 `config.yaml`:

```yaml
# 指向 Ollama（在 Docker 主机上运行）
OPENAI_API_BASE: "http://172.17.0.1:11434/v1"
```

或在 SuperAGI UI 中配置：

* **Settings → Models → Add Custom Model**
* 提供商：与 OpenAI 兼容
* 基础 URL： `http://172.17.0.1:11434/v1`
* API 密钥： `ollama` （任意字符串）
* 模型名称： `llama3.1:8b`

### 为高吞吐量代理设置 vLLM

对于具有大量并发代理的生产部署（见 [vLLM 指南](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/vllm)):

```bash
# 在 GPU 服务器上启动 vLLM
docker run -d \
  --name vllm \
  --gpus all \
  --restart unless-stopped \
  -p 8000:8000 \
  -v hf_cache:/root/.cache/huggingface \
  -e HF_TOKEN=hf_your-token \
  vllm/vllm-openai:latest \
  --model mistralai/Mistral-7B-Instruct-v0.3 \
  --served-model-name mistral-7b \
  --max-model-len 8192 \
  --enable-prefix-caching

# 在 config.yaml 中：
# OPENAI_API_BASE: "http://172.17.0.1:8000/v1"
```

### 代理工作负载的 GPU 大小建议

| 模型变体  | A100                | GPU         | 显存    | 并发代理      |
| ----- | ------------------- | ----------- | ----- | --------- |
| 测试    | GPT-4o-mini（API）    | 无           | —     | 无限（受速率限制） |
| 轻量级代理 | Llama 3.1 8B        | 速度          | 8 GB  | 2–4       |
| 推理类任务 | Mistral 7B Instruct | 速度          | 6 GB  | 3–5       |
| 复杂代理  | Llama 3.1 70B Q4    | 2× RTX 3090 | 48 GB | 1–2       |
| 生产    | Llama 3.1 70B FP16  | 4 小时会话      | 80 GB | 3–6       |

***

## 提示与最佳实践

### 代理设计

* **对目标要具体** —— 像 “做研究” 这样模糊的目标会导致代理循环。请使用 “研究 X 并写一篇 500 字的总结到输出文件 output.txt。”
* **设置迭代限制** —— 始终设置 `max_iterations` （20–50）。无限制的代理可能会快速消耗令牌。
* **使用任务队列模式** —— 对于多步骤流水线，“Task Queue” 代理比 “Don't Limit” 模式更可靠。
* **先用廉价模型测试** —— 在使用昂贵模型之前，先用 GPT-4o-mini 或本地 7B 模型验证代理逻辑。

### 在 Clore.ai 上的成本管理

```bash
# 在 SuperAGI 仪表板实时监控令牌使用情况
# Settings → Resources → Token Usage

# 在 config.yaml 中设置组织级别限制
MAX_BUDGET_TOKENS: 100000  # 每次会话的软限制
```

由于 Clore.ai 按小时计费：

```bash
# 在停止实例前保存代理配置
docker compose exec superagi-backend \
  python -c "import json; from superagi.models import Agent; ..."

# 备份 PostgreSQL 数据库
docker compose exec super__agi-db-1 \
  pg_dump -U super_agi super_agi | gzip > superagi-db-$(date +%Y%m%d).sql.gz

# 将备份复制到服务器外部
scp -P <ssh-port> root@<server-ip>:~/SuperAGI/superagi-db-*.sql.gz ./
```

### 保护 SuperAGI

```bash
# 在 config.yaml 中启用身份验证
AUTH_SECRET_KEY: "your-strong-random-secret"

# 将 API 限制为本地主机（使用 SSH 隧道）
# 修改 docker-compose.yml 以移除外部端口绑定：
# ports:
#   - "127.0.0.1:8001:8001"  # 仅本地 API
#   - "127.0.0.1:3000:3000"  # 仅本地 UI

# 然后通过 SSH 隧道访问：
# ssh -L 3000:localhost:3000 -L 8001:localhost:8001 root@<server-ip> -p <port>
```

### 在 Clore.ai 会话之间的持久化存储

```bash
# 创建完整备份脚本
cat > /root/backup-superagi.sh << 'EOF'
#!/bin/bash
cd ~/SuperAGI

# 备份数据库
docker compose exec -T super__agi-db-1 \
  pg_dump -U super_agi super_agi | \
  gzip > ~/backups/superagi-db-$(date +%Y%m%d-%H%M).sql.gz

# 备份配置和工作区
tar -czf ~/backups/superagi-files-$(date +%Y%m%d-%H%M).tar.gz \
  config.yaml \
  workspace/ \
  .env 2>/dev/null || true

echo "备份完成：$(ls -lh ~/backups/ | tail -2)"
EOF

chmod +x /root/backup-superagi.sh
mkdir -p ~/backups
```

### 更新 SuperAGI

```bash
cd ~/SuperAGI

# 保存当前配置
cp config.yaml config.yaml.backup

# 拉取最新更改
git pull origin main

# 重新构建并重启
docker compose down
docker compose up -d --build

# 验证所有服务健康状态
docker compose ps
docker compose logs superagi-backend --tail 20
```

***

## # 使用固定种子以获得一致结果

### 构建在以下步骤失败 `docker compose up --build`

```bash
# 详细检查构建日志
docker compose build superagi-backend --no-cache 2>&1 | tail -50

# 常见修复：释放磁盘空间
docker system prune -f
df -h  # 确保至少有 10 GB 可用

# 如果前端 npm 构建失败
docker compose build superagi-frontend --no-cache

# 检查构建期间的 Node.js 内存
docker compose build superagi-frontend \
  --build-arg NODE_OPTIONS="--max-old-space-size=4096"
```

### 后端启动时崩溃

```bash
# 检查后端日志
docker compose logs superagi-backend --tail 50

# 常见原因：
# 1. config.yaml 语法无效
python3 -c "import yaml; yaml.safe_load(open('config.yaml'))" && echo "YAML OK"

# 2. 数据库未就绪
docker compose restart superagi-backend  # 先等待数据库启动

# 3. 缺少 API 密钥
grep OPENAI_API_KEY config.yaml  # 确保已设置且不为空
```

### 前端无法加载（端口 3000）

```bash
# 检查前端容器
docker compose ps superagi-frontend
docker compose logs superagi-frontend --tail 30

# 验证端口映射
ss -tlnp | grep 3000

# 检查前端是否能访问 API 后端
docker compose exec superagi-frontend \
  curl -s http://superagi-backend:8001/health
```

### 代理无限循环

```bash
# 在 SuperAGI UI 中检查代理日志：
# 仪表板 → 代理 → 查看日志

# 通过 API 强制停止正在运行的代理
curl -X POST "http://localhost:8001/v1/agent/<agent-id>/stop" \
  -H "Content-Type: application/json"

# 或通过数据库停止所有代理
docker compose exec super__agi-db-1 \
  psql -U super_agi -c "UPDATE agent_executions SET status='COMPLETED' WHERE status='RUNNING';"
```

### Redis 连接错误

```bash
# 检查 Redis 状态
docker compose ps super__agi-redis-1
docker compose logs super__agi-redis-1

# 测试 Redis 连接
docker compose exec superagi-backend \
  python3 -c "import redis; r=redis.from_url('redis://super__agi-redis-1:6379/0'); print(r.ping())"

# 重启 Redis
docker compose restart super__agi-redis-1
```

### Ollama 无法从 SuperAGI 容器访问

```bash
# 查找 Docker 桥接 IP
docker network inspect bridge | grep Gateway

# 在后端容器中测试
docker compose exec superagi-backend \
  curl -s http://172.17.0.1:11434/v1/models

# 如果使用主机网络
docker run -d --network host ...  # 与 docker compose 不易兼容

# 替代方法：将 Ollama 添加到相同的 compose 网络
# 在 docker-compose.yml 的 services 中添加：
# ollama:
#   image: ollama/ollama
#   deploy:
#     resources:
#       reservations:
#         devices:
#           - driver: nvidia
#             count: all
#             capabilities: [gpu]
```

### 数据库连接池耗尽

```bash
# 在 docker-compose.yml 中增加 PostgreSQL 最大连接数
# 在 db 服务下：
command: postgres -c max_connections=200

# 重启数据库
docker compose restart super__agi-db-1
docker compose restart superagi-backend
```

***

## 延伸阅读

* [SuperAGI 文档](https://superagi.com/docs) —— 官方指南、API 参考
* [SuperAGI GitHub](https://github.com/TransformerOptimus/SuperAGI) —— 源代码、问题、社区
* [在 Clore.ai 上运行 Ollama](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama) —— 作为代理的本地 LLM 后端
* [在 Clore.ai 上运行 vLLM](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/vllm) —— 为并发代理提供高吞吐量推理
* [GPU 比较指南](https://docs.clore.ai/guides/guides_v2-zh/kuai-su-ru-men/gpu-comparison) —— 选择合适的 Clore.ai 等级
* [SuperAGI 工具市场](https://superagi.com/marketplace/) —— 社区构建的代理工具
* [SuperAGI Discord](https://discord.gg/dXbRe5BHJC) —— 社区支持与讨论
* [FastAPI 文档（SuperAGI API）](http://localhost:8001/docs) —— 在你的实例上交互式的 API 文档