AI AgentForge Documentation

Quick Start

Get started with AI AgentForge in 3 simple steps.

Tips to Get the Most Out of AI AgentForge

🏗️ Architecture

How the system is organized.

Project Structure

LLM Providers

AI AgentForge is model-agnostic — use cloud APIs, local models, or self-hosted inference servers. All providers use the OpenAI-compatible API format.

Supported Providers

Privacy Comparison

Configuration

All providers are configured in config/config.json. Add, remove, or modify providers as needed:

{
  "providers": {
    "openrouter": {
      "api_key": "${OPENROUTER_API_KEY}",
      "base_url": "https://openrouter.ai/api/v1"
    },
    "ollama": {                             // No real API key needed
      "api_key": "ollama",
      "base_url": "http://localhost:11434/v1"
    },
    "vllm": {                               // No real API key needed
      "api_key": "not-needed",
      "base_url": "http://localhost:8001/v1"
    },
    "nvidia": {
      "api_key": "${NVIDIA_API_KEY}",
      "base_url": "https://integrate.api.nvidia.com/v1"
    }
  }
}

Using a Provider per Agent

Each agent can use a different provider/model. Just set the model with the provider prefix:

// Cloud model via OpenRouter
"model": "meta-llama/llama-3.3-70b-instruct:free"

// Local model via Ollama
"model": "ollama/llama3.2"

// Self-hosted model via vLLM
"model": "vllm/mistral-7b-instruct"

// Direct OpenAI
"model": "openai/gpt-4o-mini"

// NVIDIA NIM cloud inference
"model": "nvidia/llama-3.1-nemotron-ultra-253b-v1"

Setup Guides

Ollama Setup (5 minutes)

# 1. Install Ollama (https://ollama.com)
# 2. Pull a model
ollama pull llama3.2

# 3. Ollama runs automatically at http://localhost:11434
# 4. Set agent model to "ollama/llama3.2" — done!

vLLM Setup

# 1. Install vLLM (requires NVIDIA GPU)
pip install vllm

# 2. Start the server
vllm serve mistral-7b-instruct --port 8001

# 3. Set agent model to "vllm/mistral-7b-instruct" — done!

Agents

An agent is an AI personality with a specific role, model, and tools. All agents are defined in config/agents.json.

Agent Parameter Reference

Each agent has tunable parameters that control its behavior. These can be adjusted per-agent via the Config Editor.

Sub-Agent Delegation

How to Use an Agent

⤵ Sub-Agent Delegation

Agents can intelligently delegate tasks to specialized sub-agents at runtime using LLM function calling. This enables a meta-agent architecture where a general assistant routes complex tasks to domain experts.

How It Works

Configuration

Add sub_agents to any agent in config/agents.json or via the Config Editor:

{
  "id": "general",
  "name": "General Assistant",
  "sub_agents": ["researcher", "coder", "analyst"],
  "max_delegation_depth": 3,
  "delegation_strategy": "supervised"
}

Configuration Fields

Delegation Strategies

Safety Guards

Live Progress

When delegation happens, the chat UI shows real-time status updates via WebSocket:

• "⤵ Delegating to Research Agent..." — toast notification when delegation starts
• Purple delegation card — shows the full delegation chain with nested sub-tool calls
• Sidebar badge — agents with sub-agents show a purple "⤵ N sub-agents" pill

Example: General Assistant with Supervisor

User: "Find the top 5 AI breakthroughs of 2026"

1. General Assistant receives the prompt
2. LLM calls delegate_to_agent(agent_id="researcher", task="Find top 5 AI...")
3. Toast: "⤵ Delegating to Research Agent..."
4. Research Agent runs web_search → read_url → synthesizes results
5. [SUPERVISOR] General Assistant evaluates the response
6. If quality is good → presents to user
7. If incomplete → retries with refined instructions

Connectors

Connect the AI to your databases and external REST APIs — with encrypted credentials, SSH tunnelling, and SSRF-hardened HTTP connectors. Managed at /connectors.

Supported Database Engines

Setup Workflow

SSH Authentication

Security Model

DB Query Agent

The ️ DB Query Agent is a pre-built agent that uses the three connector tools to answer natural-language questions about your database data.

Agent Workflow (enforced by system prompt)

1. [Optional shortcut] If a connector is pre-selected via the ️ Connector chip, skip step 2 and go straight to schema_connector.
2. Call list_db_connectors to discover available databases. The returned connectors[] list defines the only valid connector IDs the agent may use.
3. Call schema_connector on exactly one connector — the one the user wants to query. Never called on all connectors, and never called on an ID not in the list.
4. Read the returned compact TOML schema to get exact table and column names.
5. Explain the planned SQL in plain English before executing.
6. Call query_connector to run the SELECT statement.
7. Present results as a markdown table with key insights.
8. Optionally call generate_chart for numeric data.

Example Prompts

Connector Agent Tools

Connector REST API

All endpoints require a valid Bearer token (JWT). All data is scoped to the authenticated user.

Connector Data Model

SSH Connector

Database Connector

LLM Token Budget & CSV Export

Without limits, a 50,000-row query result would be ~2.5 MB of JSON — exhausting any LLM context window. Two mechanisms protect against this:

Compact TOML Schema Format

Since April 2026, schema_connector returns database schema in a compact TOML-style string instead of verbose JSON, reducing token usage by ~70–77% for large schemas.

TOML Schema Output Example

[Alarms]
Id:uuid, UserId:uuid, CreatedAt:timestamp without time zone, IsRead:boolean

[Orders]
Id:uuid, CustomerId:uuid, Total:numeric, Status:character varying, CreatedAt:timestamp without time zone

[Users]
Id:uuid, Email:character varying, Name:character varying, Role:character varying

The agent reads the schema field (a string) from the tool response. The schema_hint field in the response reminds the LLM to use exact names when writing SQL.

HTTP API Connectors

HTTP API Connectors let agents call any REST API securely — credentials are Fernet-encrypted and injected server-side; the LLM never sees them. Configure at /connectors → HTTP API tab.

HTTP API Setup Workflow

Authentication Types

Security Model — HTTP Connectors

Endpoint Hints & Context Chips

Each saved endpoint hint (method + path + name) becomes a clickable context chip in the Chat UI when the matching API Agent is selected.

[connector:<id> endpoint:GET /objects] your message here

Create API Agent

Clicking Agent on a connector card triggers a one-click agent creation flow:

1. The backend generates a fully configured agent JSON — model, system prompt, tools, context chips.
2. The frontend fetches the user's existing agent list, merges the new agent (prompts to overwrite if an agent with the same ID already exists).
3. The three HTTP tools (list_http_connectors, describe_http_connector, call_http_connector) are automatically added to the user's tool list if not already present.
4. The agent list is saved and the orchestrator is reloaded — the agent is live immediately.
5. A prompt offers to navigate directly to Chat with the new agent selected.

HTTP Connector Agent Tools

HTTP Connector REST API

HTTP Connector Data Model

Tools

Tools give agents the ability to perform real actions. Defined in config/tools.json.

Core Tools

Communication & Web

Files & Database

Data & Documents

Security

Presentations

️ DB Query Agent — Token Budget & CSV Export

Large query results can exhaust the LLM's context window. The system protects against this at two layers:

Map Search — Details

The search_map tool supports two search modes:

Parameters

BrowseForge — Browser Automation

🏗️ Agent Builder

️ Security & Guardrails

Multi-layered safety system that protects against malicious code execution, accidental file overwrites, and unauthorized access to sensitive resources.

Defense in Depth

Guardrails are enforced at two layers: prompt-level (instructs the LLM) and code-level (blocks even if the LLM ignores instructions).

Code Executor Guardrails

The code_executor tool scans all code for 30+ dangerous patterns before execution. If any pattern is detected, execution is blocked entirely.

File Write Protection

The write_file tool implements a smart auto-versioning strategy to prevent accidental data loss:

File Deletion

The delete_file function is completely disabled. All delete attempts return an error asking the user to delete files manually. This prevents any agent from accidentally or maliciously removing workspace files.

Protected Directories

Agents can only write files inside the workspace/ directory. Writes to the following paths are blocked:

Session Tracking

Every browser tab generates a unique session ID (via sessionStorage) that is sent with each message and stored in the database. This enables:

Workflows

Workflows let multiple agents collaborate on a task. Defined in config/workflows.json.

Workflow Patterns

1. Sequential — Agent A → Agent B

Multiple agents run in order. Each agent's output is passed to the next as input. Great for tasks that need different skills in sequence.

2. Router — Auto-pick Best Agent

An LLM reads your message and automatically picks the best agent to handle it. You don't need to choose!

Available Workflows

How to Use a Workflow

⌨️ Chat Input Features

Power-user shortcuts and smart features built into the message input area.

Keyboard Shortcuts

#Tags — Message Tagging

Add hashtags anywhere in your message to categorize it. Tags are extracted, displayed as purple pills on the message, and stored in the tags column in the database for filtering and analytics.

What are the best practices for REST API design? #followup #backend #learning

The clean message (without tags) is sent to the agent, while the tags are stored separately in the database for later filtering.

Presentations & Themes

SlideForge creates professional slide deck presentations using Marp and a built-in theme catalog.

SlideForge Agent

SlideForge is a specialist agent that converts topics and content into stunning Marp Markdown presentations. It outputs real slide deck files (HTML, PDF, or PPTX) — not just raw Markdown.

Theme System Overview

Instead of embedding hundreds of lines of CSS in the agent prompt, themes are stored as standalone CSS files and injected automatically at build time by the create_presentation tool.

Built-in Themes

8 professional themes are included out of the box. Each is a complete CSS file (~100 lines) covering headings, backgrounds, tables, code blocks, and per-slide class overrides.

Presentation Tools

Adding Custom Themes

Theme Architecture

config/marp_themes/
├── _index.json          ← Theme registry (id, name, description, tags)
├── corporate-dark.css   ← Full CSS theme (~100 lines each)
├── corporate-light.css
├── modern-gradient.css
├── minimal-clean.css
├── academic.css
├── creative-neon.css
├── nature-earth.css
└── elegant-gold.css

Context Chips System

When you select SlideForge in the chat, a row of theme chips appears above the input box. This is powered by the generic Context Chips system — any agent can have its own contextual quick-option chips.

How It Works

Each agent can define a context_chips field in its configuration. When the agent is selected in the chat, the UI reads this config and renders clickable chips above the input area.

Example: Static Options (Tone Selector)

{
  "label": "️ Tone",
  "options": [
    {"name": "Professional", "value": "professional", "color": "#0f3460"},
    {"name": "Casual", "value": "casual", "color": "#06b6d4"},
    {"name": "Fun & Playful", "value": "fun", "color": "#f59e0b"}
  ],
  "inject_as": "[tone: {value}]"
}

Example: Dynamic API Source (SlideForge Themes)

{
  "label": " Themes",
  "source": "api:/api/config/marp-themes|themes",
  "display": "name",
  "value": "id",
  "color_map": {
    "corporate-dark": "#e94560",
    "modern-gradient": "#667eea",
    "elegant-gold": "#d4af37"
  },
  "inject_as": "[theme: {value}]"
}

Built-in Agent Chips

The following 8 agents come pre-configured with context chips out of the box:

BrowseForge

AI-powered browser automation — navigate, interact, extract, and screenshot real web pages with a full Chromium browser. Managed at /browser.

How It Works

Page Representation

When the agent navigates to a page, content is returned in a token-efficient format with numbered interactive elements:

=== PAGE ===
Title: GitHub Login
URL: https://github.com/login

=== CONTENT ===
Sign in to GitHub
To continue to GitHub

=== INTERACTIVE ELEMENTS ===
[1: input "Username or email address" type=text]
[2: input "Password" type=password]
[3: button "Sign in"]
[4: link "Forgot password?"]
[5: link "Create an account"]

The agent uses numeric IDs to reference elements — no CSS selectors or XPath needed:

browse_interact(action="type", element_id=1, value="user@example.com")
browse_interact(action="type", element_id=2, value="***")  ← from credential vault
browse_interact(action="click", element_id=3)

BrowseForge Tools

Session Lifecycle

Browser sessions are named (e.g., "default", "github") and scoped per-user.

Credential Vault

Store website credentials securely — the AI agent references them by name and never sees raw passwords.

Domain Rules

Per-user allowlist and blocklist for controlling which websites the agent can visit.

Security

Configuration

BrowseForge settings are in the browseforge section of config/config.json:

Browser Agent

The BrowseForge agent is a pre-built agent optimised for web browsing tasks.

Example Prompts

⏰ Triggers & Automation

Run workflows automatically via webhooks or cron schedules — no manual chat interaction needed.

Trigger Types

Setup Workflow

Webhook Details

Cron Expressions

Standard 5-field cron syntax (validated by APScheduler):

Run Log & Trace

Every trigger execution is logged with:

Security

Trigger REST API

All endpoints except the webhook receiver require a valid Bearer token (JWT).

JSON Configuration

Everything is controlled by 4 JSON files in the config/ folder. Your personal customisations are stored per-user in the database and merged with global defaults at runtime.

config/config.json — Global Settings

Controls API providers, defaults, global fallback models, and retry settings. API keys use ${ENV_VAR} syntax — they're read from your .env file. Local providers like Ollama and vLLM also accept an optional API key for cloud-hosted or secured deployments.

{

  "default_provider": "openrouter",

  "providers": {

    "openrouter": {                         // Default — 100+ models, free tier

      "api_key": "${OPENROUTER_API_KEY}",

      "base_url": "https://openrouter.ai/api/v1"

    },

    "openai": {                             // Direct OpenAI (GPT-4o, etc.)

      "api_key": "${OPENAI_API_KEY}",

      "base_url": "https://api.openai.com/v1"

    },

    "ollama": {                             // Local OR cloud (e.g. Anyscale, Together AI)

      "api_key": "${OLLAMA_API_KEY}",         // "ollama" for local; real key for cloud

      "base_url": "http://localhost:11434/v1" // Or your cloud endpoint URL

    },

    "vllm": {                               // Self-hosted OR cloud GPU inference

      "api_key": "${VLLM_API_KEY}",           // "not-needed" for local; real key for cloud

      "base_url": "http://localhost:8001/v1"  // Or your cloud endpoint URL

    }

  },

  "defaults": {

    "model": "meta-llama/llama-3.3-70b-instruct:free",

    "temperature": 0.7,

    "max_tokens": 2048

  },

  "fallback_models": [                      // Tried in order if primary fails

    "openrouter/free",

    "meta-llama/llama-3.2-3b-instruct:free",

    "qwen/qwen3-14b:free"

  ],

  "retry": {

    "max_retries": 3,

    "base_delay_seconds": 2

  },

  "server": {

    "host": "0.0.0.0",

    "port": 8000

  }

}

config/agents.json — Agent Definitions

Each agent has an id, name, model, system prompt, tools, temperature, max_tokens, max_tool_iterations, timeout, use_memory, and short_term_memory_window. Agents can optionally override global fallback_models and retry settings. Each user's model choices are saved to the database and merged on top of the global file.

{

  "id": "coder",

  "name": "Code Agent",

  "description": "Specializes in writing and reviewing code",

  "model": "meta-llama/llama-3.3-70b-instruct:free",

  "system_prompt": "You are an expert software engineer...",

  "tools": [
    {"id": "web_search", "max_calls": 3},  // Max 3 searches per request
    {"id": "get_current_time", "max_calls": 1},
    "code_executor",                            // No limit (plain string)
    "calculator"
  ],

  "fallback_models": [                      // Optional: overrides global

    "qwen/qwen3-14b:free",

    "meta-llama/llama-3.2-3b-instruct:free"

  ],

  "retry": {                                 // Optional: overrides global

    "max_retries": 5,

    "base_delay_seconds": 3

  },

  "temperature": 0.2,             // 0.1–0.7 (lower = precise, higher = creative)

  "max_tokens": 8192,               // Max output tokens (2048–16384)

  "max_tool_iterations": 5,          // LLM→tool round-trips per request (2–8),

  "timeout": 180,                      // Soft timeout in seconds (30–600). Default: 120

  "sub_agents": ["researcher", "analyst"],  // Optional: agents this one can delegate to

  "max_delegation_depth": 3,                  // Optional: max nesting depth (default: 3)

  "use_memory": false,              // Inject long-term facts into prompt (default: false)

  "short_term_memory_window": 20,        // Recent message history window (default: 20, use 0-6 for data agents)

  "keep_history": true,               // Store turns in short-term memory (default: true, set false for stateless agents)

  "delegation_strategy": "supervised"         // Optional: auto | supervised | consensus

}

config/tools.json — Tool Definitions

Maps tool IDs to their module, function name, and parameter schema. Your personal tool overrides are stored per-user in the database and merged with global tools at runtime.

{

  "id": "calculator",

  "name": "Calculator",

  "description": "Evaluates math expressions",

  "module": "tools.calculator",       // module path

  "function": "calculate",             // Function to call

  "parameters": {

    "expression": {

      "type": "string",

      "required": true

    }

  }

}

config/workflows.json — Workflow Definitions

Defines multi-agent workflows with steps and context passing. During onboarding, users choose which workflows to enable — those choices are saved to the database. Editable any time via Config Editor.

{

  "id": "research_and_code",

  "pattern": "sequential",

  "steps": [

    {

      "agent_id": "researcher",

      "instruction": "Research: {user_input}",  // {user_input} = your message

      "output_key": "research"               // saves output as "research"

    },

    {

      "agent_id": "coder",

      "instruction": "Code based on: {research}" // uses previous output

    }

  ]

}

️ Resilience & Fallback

Built-in retry logic with exponential backoff, automatic model fallback, and per-agent soft timeouts for graceful partial results.

How It Works

When a model returns a 429 rate-limit error, the system automatically:

Configuration Hierarchy

Retry and fallback settings can be configured at two levels. Per-agent settings always take priority over global settings.

Example: Per-Agent Override

The Code Agent gets more retries and longer delays, while other agents use the global defaults:

{
  "id": "coder",
  "model": "meta-llama/llama-3.3-70b-instruct:free",
  "fallback_models": ["qwen/qwen3-14b:free", "meta-llama/llama-3.2-3b-instruct:free"],
  "retry": { "max_retries": 5, "base_delay_seconds": 3 }
}

Soft Timeout & Partial Results

Complex agents (e.g. Travel Planner with 8 tool iterations) can take several minutes. Instead of a hard timeout that kills the request mid-call and wastes billed tokens, each agent has a soft timeout that checks elapsed time between LLM iterations.

API Reference

All endpoints are available at http://localhost:8000.

New Features

How to Extend

Add new agents, tools, and workflows without writing core code.

Add a New Agent

Add a New Tool

Add a New Workflow

Frequently Asked Questions

Common questions about setup, configuration, and usage.

POST /api/reload

"meta-llama/llama-3.3-70b-instruct:free"  // OpenRouter (default)
"ollama/llama3.2"                          // Local Ollama
"vllm/mistral-7b-instruct"                 // Self-hosted vLLM
"openai/gpt-4o-mini"                       // Direct OpenAI
"nvidia/llama-3.1-nemotron-ultra-253b-v1"  // NVIDIA NIM