# SuperAGI Agent Framework

## Overview

[SuperAGI](https://github.com/TransformerOptimus/SuperAGI) is an open-source, developer-first autonomous AI agent framework with 15K+ GitHub stars. Unlike simple chatbots, SuperAGI runs **autonomous agents** — AI systems that independently plan, execute multi-step tasks, use tools, and iterate toward a goal without constant human input.

**Why run SuperAGI on Clore.ai?**

* **GPU-optional with powerful local LLM support** — Run agents backed by local models (Llama, Mistral, etc.) on Clore.ai GPUs for fully private, cost-controlled autonomous AI.
* **Concurrent agent execution** — Run multiple agents in parallel on the same server, each working on different tasks simultaneously.
* **Persistent agent memory** — Agents maintain context, learn from tool outputs, and store long-term memory in vector databases between runs.
* **Tool marketplace** — Pre-built integrations for Google Search, GitHub, Email, Jira, Notion, and more.
* **Clore.ai economics** — At \~$0.20/hr for an RTX 3090, you can run capable autonomous agents at a fraction of cloud AI service costs.

### Key Features

| Feature             | Description                                         |
| ------------------- | --------------------------------------------------- |
| Agent provisioning  | Create, configure, and deploy agents via GUI        |
| Tool marketplace    | 30+ built-in tools (search, code, files, APIs)      |
| Multi-model support | OpenAI, Anthropic, local LLMs via custom endpoint   |
| Concurrent agents   | Run multiple agents simultaneously                  |
| Agent memory        | Short-term (context window) + long-term (vector DB) |
| GUI dashboard       | Full web interface for agent management             |
| Resource manager    | Track token usage and costs per agent               |
| Workflow templates  | Pre-built agent templates for common tasks          |

### Architecture

```
┌────────────────────────────────────────────────────┐
│              SuperAGI Stack                        │
│                                                    │
│  ┌─────────────────────┐   ┌───────────────────┐   │
│  │  Frontend (Port 3000)│   │  API (Port 8001)  │   │
│  │   Next.js UI         │   │  FastAPI Backend   │   │
│  └──────────┬──────────┘   └─────────┬─────────┘   │
│             └──────────┬─────────────┘             │
│                        ▼                           │
│  ┌─────────────────────────────────────────────┐   │
│  │              Agent Executor                 │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  │   │
│  │  │  Agent 1  │  │  Agent 2  │  │  Agent N  │  │   │
│  │  └──────────┘  └──────────┘  └──────────┘  │   │
│  └───────┬─────────────┬─────────────┬─────────┘   │
│          ▼             ▼             ▼             │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐      │
│  │ PostgreSQL │  │  Redis    │  │  Vector   │      │
│  │  (State)  │  │  (Queue)  │  │    DB     │      │
│  └───────────┘  └───────────┘  └───────────┘      │
└────────────────────────────────────────────────────┘
          │
    ┌─────┴──────┐
    ▼            ▼
 OpenAI      Local LLM
 Anthropic   (Ollama/vLLM)
```

***

## Requirements

### Server Specifications

| Component   | Minimum         | Recommended           | Notes                                  |
| ----------- | --------------- | --------------------- | -------------------------------------- |
| **GPU**     | None (API mode) | RTX 3090 (local LLMs) | GPU needed for local model inference   |
| **VRAM**    | —               | 24 GB                 | For running 13B+ local models          |
| **CPU**     | 4 vCPU          | 8 vCPU                | Agent execution is CPU-intensive       |
| **RAM**     | 8 GB            | 16 GB                 | Multiple concurrent agents need memory |
| **Storage** | 20 GB           | 100+ GB               | Agent logs, vector DB, model storage   |

### Clore.ai Pricing Reference

| Server Type         | Approx. Cost    | Use Case                                   |
| ------------------- | --------------- | ------------------------------------------ |
| CPU (8 vCPU, 16 GB) | \~$0.10–0.20/hr | SuperAGI + external API (OpenAI/Anthropic) |
| RTX 3090 (24 GB)    | \~$0.20/hr      | SuperAGI + Ollama 13B local model          |
| RTX 4090 (24 GB)    | \~$0.35/hr      | SuperAGI + Ollama, faster inference        |
| 2× RTX 3090         | \~$0.40/hr      | SuperAGI + 70B model (Q4 quantized)        |
| A100 80 GB          | \~$1.10/hr      | SuperAGI + large models, high concurrency  |
| H100 80 GB          | \~$2.50/hr      | Production-grade autonomous agent systems  |

> 💡 **Cost tip:** For development and testing, use OpenAI or Anthropic APIs (no GPU needed). Switch to a GPU instance only when you need local LLM inference for privacy or cost reasons. See [GPU Comparison Guide](/guides/getting-started/gpu-comparison.md).

### Prerequisites

* Clore.ai server with SSH access
* Docker + Docker Compose (pre-installed on Clore.ai)
* Git (pre-installed)
* 4+ vCPU, 8+ GB RAM (16 GB recommended for concurrent agents)
* OpenAI API key **or** local LLM endpoint (Ollama/vLLM)

***

## Quick Start

### Method 1: Docker Compose (Official — Recommended)

SuperAGI's official deployment uses Docker Compose to manage all services.

**Step 1: Connect to your Clore.ai server**

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

**Step 2: Clone and configure**

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

**Step 3: Edit `config.yaml`**

```bash
nano config.yaml
```

Minimum required configuration:

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

# Database (leave as default for Docker Compose)
POSTGRES_DB: "super_agi"
POSTGRES_USER: "super_agi"
POSTGRES_PASSWORD: "password"

# Vector Database
VECTOR_STORE: "Redis"  # or "Pinecone", "Qdrant", "Weaviate"
REDIS_URL: "redis://super__agi-redis-1:6379/0"

# App settings
ENV: "PROD"
ALLOW_LISTS_CREATION: "true"

# Optional: restrict access
# AUTH_SECRET_KEY: "your-random-secret"
```

**Step 4: Start the stack**

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

The build process downloads dependencies and compiles the frontend (\~5–10 minutes on first run).

**Step 5: Monitor startup**

```bash
# Watch all services come up
docker compose ps

# Follow logs
docker compose logs -f

# Wait for "Application startup complete" in the backend logs
docker compose logs superagi-backend --tail 30
```

**Step 6: Access the dashboard**

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

The API is available at:

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

API documentation:

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

***

### Method 2: Quick Start with Pre-built Images

For faster startup using pre-built images (skip the build step):

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

# Edit config with your API keys
nano config.yaml

# Use pre-built images if available
docker compose -f docker-compose.yaml pull
docker compose up -d
```

***

### Method 3: Minimal Single-Model Setup

A streamlined setup for testing with just OpenAI:

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

# Create minimal config
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

# Monitor build progress
docker compose logs superagi-frontend --tail 5 -f &
docker compose logs superagi-backend --tail 5 -f
```

***

## Configuration

### `config.yaml` Reference

```yaml
# ============================================================
# LLM Providers
# ============================================================
OPENAI_API_KEY: "sk-..."                    # OpenAI GPT models
ANTHROPIC_API_KEY: "sk-ant-..."            # Claude models

# For local models (Ollama or OpenAI-compatible API)
# Set in the UI: Settings → Models → Custom Model
OPENAI_API_BASE: "http://172.17.0.1:11434/v1"  # Ollama on same host
OPENAI_MODEL: "llama3.1:8b"

# ============================================================
# Database
# ============================================================
POSTGRES_DB: "super_agi"
POSTGRES_USER: "super_agi"
POSTGRES_PASSWORD: "your-strong-password"

# ============================================================
# Vector Database (agent long-term memory)
# ============================================================
VECTOR_STORE: "Redis"       # Redis (default, built-in)
# Or use external:
# VECTOR_STORE: "Pinecone"
# PINECONE_API_KEY: "your-key"
# PINECONE_ENVIRONMENT: "us-east-1-aws"

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

# ============================================================
# Tool API Keys (optional, for specific tools)
# ============================================================
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
# ============================================================
STORAGE_TYPE: "File"        # Local file storage
# STORAGE_TYPE: "S3"        # S3-compatible (MinIO, AWS)
# BUCKET_NAME: "superagi"
# AWS_ACCESS_KEY_ID: "..."
# AWS_SECRET_ACCESS_KEY: "..."

# ============================================================
# Security
# ============================================================
JWT_SECRET_KEY: "your-random-secret-key"
```

### Connecting SuperAGI to Tools

Tools are configured through the GUI at **Settings → Toolkit**. Each tool can be enabled/disabled per agent.

**Built-in tools:**

| Tool             | Purpose                    | API Key Needed     |
| ---------------- | -------------------------- | ------------------ |
| Google Search    | Web search                 | Yes (Google API)   |
| DuckDuckGo       | Web search                 | No                 |
| GitHub           | Code repository access     | Yes (GitHub token) |
| Email            | Send/read email            | Yes (SMTP config)  |
| Code Writer      | Write and execute code     | No                 |
| File Manager     | Read/write local files     | No                 |
| Browser          | Headless web browsing      | No                 |
| Jira             | Issue tracking             | Yes                |
| Notion           | Knowledge base             | Yes                |
| Image Generation | DALL-E 3, Stable Diffusion | Yes (OpenAI key)   |

### Creating Your First Agent

Via the GUI (Settings → Agents → Create Agent):

1. **Name** — Give your agent a descriptive name
2. **Description** — What this agent does
3. **Goals** — List the objectives (one per line)
4. **Instructions** — System prompt for behavior
5. **Model** — Select LLM (GPT-4, Claude, or local)
6. **Tools** — Enable relevant tools
7. **Max Iterations** — Safety limit (10–50 typical)

Via the REST API:

```bash
# Create an agent via 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 Acceleration

SuperAGI supports local LLM inference via any OpenAI-compatible endpoint, making it ideal for GPU-backed Clore.ai deployments.

### Setting Up Ollama as Agent LLM Backend

See [Ollama Guide](/guides/language-models/ollama.md) for full Ollama setup. Integration with SuperAGI:

**Step 1: Start Ollama on the same Clore.ai server**

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

# Pull a capable model for agent use (needs good reasoning)
docker exec ollama ollama pull llama3.1:8b        # Fast, good reasoning
docker exec ollama ollama pull mistral:7b-instruct  # Code tasks
docker exec ollama ollama pull deepseek-coder:6.7b # Code-heavy agents
```

**Step 2: Configure SuperAGI to use Ollama**

In `config.yaml`:

```yaml
# Point to Ollama (running on the Docker host)
OPENAI_API_BASE: "http://172.17.0.1:11434/v1"
```

Or configure in the SuperAGI UI:

* **Settings → Models → Add Custom Model**
* Provider: OpenAI-compatible
* Base URL: `http://172.17.0.1:11434/v1`
* API Key: `ollama` (any string)
* Model name: `llama3.1:8b`

### Setting Up vLLM for High-Throughput Agents

For production deployments with many concurrent agents (see [vLLM Guide](/guides/language-models/vllm.md)):

```bash
# Start vLLM on GPU server
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

# In config.yaml:
# OPENAI_API_BASE: "http://172.17.0.1:8000/v1"
```

### GPU Sizing for Agent Workloads

| Use Case        | Model               | GPU         | VRAM  | Concurrent Agents        |
| --------------- | ------------------- | ----------- | ----- | ------------------------ |
| Testing         | GPT-4o-mini (API)   | None        | —     | Unlimited (rate-limited) |
| Light agents    | Llama 3.1 8B        | RTX 3090    | 8 GB  | 2–4                      |
| Reasoning tasks | Mistral 7B Instruct | RTX 3090    | 6 GB  | 3–5                      |
| Complex agents  | Llama 3.1 70B Q4    | 2× RTX 3090 | 48 GB | 1–2                      |
| Production      | Llama 3.1 70B FP16  | A100 80GB   | 80 GB | 3–6                      |

***

## Tips & Best Practices

### Agent Design

* **Be specific with goals** — Vague goals like "do research" cause agents to loop. Use "Research X and write a 500-word summary to file output.txt."
* **Set iteration limits** — Always set `max_iterations` (20–50). Unlimited agents can consume tokens rapidly.
* **Use task queue mode** — For multi-step pipelines, "Task Queue" agents are more reliable than "Don't Limit" mode.
* **Test with cheap models first** — Validate agent logic with GPT-4o-mini or a local 7B model before using expensive models.

### Cost Management on Clore.ai

```bash
# Monitor token usage in real-time from the SuperAGI dashboard
# Settings → Resources → Token Usage

# Set organization-level limits in config.yaml
MAX_BUDGET_TOKENS: 100000  # Soft limit per session
```

Since Clore.ai charges hourly:

```bash
# Save agent configurations before stopping instance
docker compose exec superagi-backend \
  python -c "import json; from superagi.models import Agent; ..."

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

# Copy backup off-server
scp -P <ssh-port> root@<server-ip>:~/SuperAGI/superagi-db-*.sql.gz ./
```

### Securing SuperAGI

```bash
# Enable authentication in config.yaml
AUTH_SECRET_KEY: "your-strong-random-secret"

# Restrict API to localhost (use SSH tunnels)
# Modify docker-compose.yml to remove external port binding:
# ports:
#   - "127.0.0.1:8001:8001"  # API local only
#   - "127.0.0.1:3000:3000"  # UI local only

# Then access via SSH tunnel:
# ssh -L 3000:localhost:3000 -L 8001:localhost:8001 root@<server-ip> -p <port>
```

### Persistent Storage Between Clore.ai Sessions

```bash
# Create full backup script
cat > /root/backup-superagi.sh << 'EOF'
#!/bin/bash
cd ~/SuperAGI

# Backup database
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

# Backup config and workspaces
tar -czf ~/backups/superagi-files-$(date +%Y%m%d-%H%M).tar.gz \
  config.yaml \
  workspace/ \
  .env 2>/dev/null || true

echo "Backup complete: $(ls -lh ~/backups/ | tail -2)"
EOF

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

### Updating SuperAGI

```bash
cd ~/SuperAGI

# Save current config
cp config.yaml config.yaml.backup

# Pull latest changes
git pull origin main

# Rebuild and restart
docker compose down
docker compose up -d --build

# Verify all services are healthy
docker compose ps
docker compose logs superagi-backend --tail 20
```

***

## Troubleshooting

### Build fails during `docker compose up --build`

```bash
# Check build logs in detail
docker compose build superagi-backend --no-cache 2>&1 | tail -50

# Common fix: free up disk space
docker system prune -f
df -h  # Ensure at least 10 GB free

# If npm build fails for frontend
docker compose build superagi-frontend --no-cache

# Check Node.js memory during build
docker compose build superagi-frontend \
  --build-arg NODE_OPTIONS="--max-old-space-size=4096"
```

### Backend crashes on startup

```bash
# Check backend logs
docker compose logs superagi-backend --tail 50

# Common causes:
# 1. Invalid config.yaml syntax
python3 -c "import yaml; yaml.safe_load(open('config.yaml'))" && echo "YAML OK"

# 2. Database not ready
docker compose restart superagi-backend  # Wait for DB to start first

# 3. Missing API key
grep OPENAI_API_KEY config.yaml  # Ensure it's set and not empty
```

### Frontend not loading (port 3000)

```bash
# Check frontend container
docker compose ps superagi-frontend
docker compose logs superagi-frontend --tail 30

# Verify port mapping
ss -tlnp | grep 3000

# Check if API backend is reachable from frontend
docker compose exec superagi-frontend \
  curl -s http://superagi-backend:8001/health
```

### Agents loop indefinitely

```bash
# Check agent logs in the SuperAGI UI:
# Dashboard → Agent → View Logs

# Force-stop a running agent via API
curl -X POST "http://localhost:8001/v1/agent/<agent-id>/stop" \
  -H "Content-Type: application/json"

# Or stop all agents via DB
docker compose exec super__agi-db-1 \
  psql -U super_agi -c "UPDATE agent_executions SET status='COMPLETED' WHERE status='RUNNING';"
```

### Redis connection errors

```bash
# Check Redis status
docker compose ps super__agi-redis-1
docker compose logs super__agi-redis-1

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

# Restart Redis
docker compose restart super__agi-redis-1
```

### Ollama not reachable from SuperAGI container

```bash
# Find Docker bridge IP
docker network inspect bridge | grep Gateway

# Test from backend container
docker compose exec superagi-backend \
  curl -s http://172.17.0.1:11434/v1/models

# If using host networking
docker run -d --network host ...  # Not compatible with docker compose easily

# Alternative: add Ollama to the same compose network
# Add to docker-compose.yml services:
# ollama:
#   image: ollama/ollama
#   deploy:
#     resources:
#       reservations:
#         devices:
#           - driver: nvidia
#             count: all
#             capabilities: [gpu]
```

### Database connection pool exhausted

```bash
# Increase PostgreSQL max connections in docker-compose.yml
# Under the db service:
command: postgres -c max_connections=200

# Restart database
docker compose restart super__agi-db-1
docker compose restart superagi-backend
```

***

## Further Reading

* [SuperAGI Documentation](https://superagi.com/docs) — official guides, API reference
* [SuperAGI GitHub](https://github.com/TransformerOptimus/SuperAGI) — source code, issues, community
* [Running Ollama on Clore.ai](/guides/language-models/ollama.md) — local LLM backend for agents
* [Running vLLM on Clore.ai](/guides/language-models/vllm.md) — high-throughput inference for concurrent agents
* [GPU Comparison Guide](/guides/getting-started/gpu-comparison.md) — choosing the right Clore.ai tier
* [SuperAGI Tool Marketplace](https://superagi.com/marketplace/) — community-built agent tools
* [SuperAGI Discord](https://discord.gg/dXbRe5BHJC) — community support and discussions
* [FastAPI Docs (SuperAGI API)](http://localhost:8001/docs) — interactive API documentation on your instance


---

# 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/ai-platforms-and-agents/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.