# 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 比较指南](/guides/guides_v2-zh/ru-men/gpu-comparison.md).

### 先决条件

* 带 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 指南](/guides/guides_v2-zh/yu-yan-mo-xing/ollama.md) 用于完整 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 指南](/guides/guides_v2-zh/yu-yan-mo-xing/vllm.md)):

```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](/guides/guides_v2-zh/yu-yan-mo-xing/ollama.md) —— 作为代理的本地 LLM 后端
* [在 Clore.ai 上运行 vLLM](/guides/guides_v2-zh/yu-yan-mo-xing/vllm.md) —— 为并发代理提供高吞吐量推理
* [GPU 比较指南](/guides/guides_v2-zh/ru-men/gpu-comparison.md) —— 选择合适的 Clore.ai 等级
* [SuperAGI 工具市场](https://superagi.com/marketplace/) —— 社区构建的代理工具
* [SuperAGI Discord](https://discord.gg/dXbRe5BHJC) —— 社区支持与讨论
* [FastAPI 文档（SuperAGI API）](http://localhost:8001/docs) —— 在你的实例上交互式的 API 文档


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/ai-ping-tai-yu-zhi-neng-ti/superagi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.