AutoGPT Framework Deep-Dive

Comprehensive source-code analysis of the AutoGPT platform — from the new visual-builder architecture to the classic agent system

Overview

AutoGPT has evolved from a single-agent CLI tool into a full-stack platform for building AI-powered agentic workflows. The repository now contains two distinct architectures living side-by-side:

Version: 0.6.22 (platform backend). The project targets Python 3.10–3.13 and has 96+ built-in blocks covering integrations from Airtable to YouTube.

Architecture

Repository Structure

Platform Architecture — High Level

Block System

The platform's core abstraction is the Block — a self-contained processing unit with typed inputs and outputs. Blocks are the building blocks of agent graphs.

Block Base Class

class BlockType(str, Enum):
    STANDARD = "Standard"
    INPUT = "Input"
    OUTPUT = "Output"
    NOTE = "Note"
    WEBHOOK = "Webhook"
    AGENT = "Agent"
    AI = "AI"
    ITERATE = "Iterate"
    SUBGRAPH = "Subgraph"

class BlockCategory(str, Enum):
    AI = "AI"
    SOCIAL = "Social"
    CODING = "Coding"
    DATA = "Data"
    SEARCH = "Search"
    MEDIA = "Media"
    COMMUNICATION = "Communication"
    PRODUCTIVITY = "Productivity"
    FINANCE = "Finance"
    # ... 15+ categories

class Block(ABC):
    id: str                           # UUID
    description: str
    input_schema: type[BlockSchemaInput]  # Pydantic model
    output_schema: type[BlockSchemaOutput]
    block_type: BlockType = BlockType.STANDARD
    category: BlockCategory

    @abstractmethod
    async def run(self, input_data: Input, **kwargs) -> BlockOutput:
        """Yield (output_name, value) tuples."""
        ...

Block I/O Schema

Each block declares Pydantic schemas for inputs and outputs. This enables the visual builder to render connection points and validate graphs before execution.

class BlockSchemaInput(BaseModel):
    """Base for block inputs — extend with SchemaField declarations."""

class SchemaField(FieldInfo):
    """Extended pydantic Field with UI metadata:
       - description, placeholder, advanced (bool)
       - discriminator (for union types)
    """

96+ Built-In Blocks

The block registry spans 96 modules covering:

Graph / Flow Model

Agents in the platform are directed graphs of blocks connected by Link objects. A graph is stored as AgentGraph in Prisma with AgentNode and AgentNodeLink records.

class Link(BaseDbModel):
    source_id: str        # Source node UUID
    sink_id: str          # Sink node UUID
    source_name: str      # Output pin name on source
    sink_name: str        # Input pin name on sink
    is_static: bool = False  # Static links carry constant values

class Node(BaseDbModel):
    block_id: str         # Which block type this node instantiates
    input_default: dict   # Default values for unconnected inputs
    metadata: dict        # UI position, etc.

class GraphModel:
    """In-memory representation of a complete agent graph."""
    nodes: list[Node]
    links: list[Link]
    version: int
    settings: GraphSettings  # HITL safe mode, sensitive action mode, etc.

Graph Settings

class GraphSettings(BaseModel):
    human_in_the_loop_safe_mode: bool = True
    sensitive_action_safe_mode: bool = False
    builder_chat_session_id: str | None = None

Executor Engine

The executor is a production-grade system with thread pooling, Prometheus metrics, RabbitMQ queuing, and graceful shutdown:

# Prometheus metrics
active_runs_gauge = Gauge("execution_manager_active_runs", "Number of active graph runs")
pool_size_gauge = Gauge("execution_manager_pool_size", "Maximum number of graph workers")
utilization_gauge = Gauge("execution_manager_utilization_ratio", ...)

class ExecutionProcessor:
    """Processes a single graph execution to completion."""
    # Thread-local storage for per-thread processor instances
    # Handles: node scheduling, input resolution, block execution,
    #          output routing, error recovery, cost tracking

Execution Context

class ExecutionContext(BaseModel):
    """Carries execution-level data throughout the flow."""
    user_id: Optional[str] = None
    graph_id: Optional[str] = None
    graph_exec_id: Optional[str] = None
    node_exec_id: Optional[str] = None

    # Safety settings
    human_in_the_loop_safe_mode: bool = True
    sensitive_action_safe_mode: bool = False
    dry_run: bool = False  # LLM-simulated, no real execution

Execution Flow

Orchestrator Block

The OrchestratorBlock is the heart of the platform's agent capability. It implements a tool-call loop where an LLM reasons over available blocks and executes them iteratively.

Execution Modes

class ExecutionMode(str, Enum):
    BUILT_IN = "built_in"
    """Default built-in tool-call loop (supports all LLM providers)."""

    EXTENDED_THINKING = "extended_thinking"
    """Delegate to an external Agent SDK for richer reasoning.
    Currently supports Anthropic-compatible providers via Claude Agent SDK."""

Tool-Call Loop Integration

The orchestrator uses the shared tool_call_loop utility — a provider-agnostic async generator that:

1. Calls the LLM with tool definitions
2. Extracts tool calls from the response
3. Executes tools via a caller-supplied callback
4. Appends results to the conversation
5. Repeats until no more tool calls or max iterations reached

async def tool_call_loop(
    *,
    messages: list[dict[str, Any]],
    tools: Sequence[Any],
    llm_call: LLMCaller,
    execute_tool: ToolExecutor,
    update_conversation: ConversationUpdater,
    max_iterations: int = -1,
    parallel_tool_calls: bool = True,  # asyncio.gather for multiple calls
) -> AsyncGenerator[ToolCallLoopResult, None]:

Tool Registration

Connected blocks become "tools" in the LLM's tool schema. The orchestrator dynamically builds tool definitions from the graph's connected nodes:

class ToolInfo(BaseModel):
    tool_call: Any         # Original tool call from LLM response
    tool_name: str         # The function name
    tool_def: dict         # The tool definition (OpenAI format)
    input_data: dict       # Processed input ready for execution
    field_mapping: dict    # Field name mapping for the tool

AutoPilot Block

The AutoPilotBlock enables sub-agent patterns — an autonomous agent-within-an-agent that can manage agents, access workspace files, run blocks, and more.

class AutoPilotBlock(Block):
    """Execute tasks using AutoGPT AutoPilot with full access to platform tools.

    The autopilot can manage agents, access workspace files, fetch web content,
    run blocks, and more. This block enables sub-agent patterns (autopilot calling
    autopilot) and scheduled autopilot execution via the agent executor.
    """

    execution_timeout_seconds: int | None = None  # No leaf-block cap

    class Input(BlockSchemaInput):
        prompt: str = SchemaField(
            description="The task or instruction for the autopilot to execute.",
            placeholder="Find my agents and list them",
        )
        system_context: str = SchemaField(
            description="Additional context for the autopilot's system prompt.",
        )

Recursion Guard

class SubAgentRecursionError(BlockExecutionError):
    """Raised when the AutoPilot sub-agent nesting depth limit is exceeded."""
    def __init__(self, message: str) -> None:
        super().__init__(
            message=message,
            block_name="AutoPilotBlock",
            block_id=AUTOPILOT_BLOCK_ID,
        )

The AutoPilot coordinates with the CoPilot system for tool discovery, turn management, and rate limiting. It uses running_turn_limit_message and CopilotPermissions to enforce safety.

LLM Integration

The LLM block is one of the most sophisticated pieces — supporting 6 providers with 80+ models and tool calling.

Supported Providers

Model Metadata System

class ModelMetadata(NamedTuple):
    provider: str
    context_window: int
    max_output_tokens: int | None
    display_name: str
    provider_name: str
    creator_name: str
    price_tier: Literal[1, 2, 3]  # Cost classification

class LlmModel(str, Enum, metaclass=LlmModelMeta):
    # OpenAI
    GPT5_2 = "gpt-5.2-2025-12-11"
    O3 = "o3-2025-04-16"
    # Anthropic
    CLAUDE_4_7_OPUS = "claude-opus-4-7"
    CLAUDE_4_6_SONNET = "claude-sonnet-4-6"
    # OpenRouter (70+ models)
    GROK_4 = "x-ai/grok-4"
    KIMI_K2_6 = "moonshotai/kimi-k2.6"
    ZAI_GLM_5 = "z-ai/glm-5"
    # ... 80+ models total

Provider Dispatch

The LLM block dispatches to the correct provider based on LlmModel.metadata.provider:

# Simplified dispatch logic:
if provider == "openai":
    response = await openai.ChatCompletion.acreate(...)
elif provider == "anthropic":
    response = await anthropic.Messages.create(...)
elif provider == "groq":
    response = await AsyncGroq().chat.completions.create(...)
elif provider == "ollama":
    response = await ollama.chat(...)
elif provider == "open_router":
    # Uses openai SDK with OPENROUTER_BASE_URL
    response = await openai.ChatCompletion.acreate(
        base_url=OPENROUTER_BASE_URL, ...
    )

Context Compression

The platform includes a sophisticated context compression system that trims conversation history when it exceeds the model's context window:

MAIN_OBJECTIVE_PREFIX = "[Main Objective Prompt]: "

def _tok_len(text: str, enc) -> int:
    """True token length using tiktoken."""
    return len(enc.encode(str(text)))

def _msg_tokens(msg: dict, enc) -> int:
    """Count tokens for any message format:
       - OpenAI Chat Completions
       - Anthropic Messages
       - OpenAI Responses API (function_call / function_call_output)
    """

Messages prefixed with [Main Objective Prompt] are protected from compression, ensuring the agent's core directive is never lost.

Memory System

The platform integrates with Mem0 as its persistent memory layer. Four block types provide memory operations:

Memory Scoping

# Every memory operation supports scoping:
params = {
    "user_id": user_id,
    "metadata": input_data.metadata,
}
if input_data.limit_memory_to_run:
    params["run_id"] = graph_exec_id
if input_data.limit_memory_to_agent:
    params["agent_id"] = graph_id

Additional memory integrations: Pinecone block (pinecone.py), FalkorDB (graph database), and Graphiti (knowledge graph via graphiti-core).

REST API & Backend

The backend is a FastAPI application with a modular feature-based route structure:

# Feature modules registered as routers:
backend.api.features.admin.*        # Block cost, credit, diagnostics, analytics
backend.api.features.builder.*      # Visual builder endpoints
backend.api.features.chat.routes    # Agent chat / CoPilot
backend.api.features.library.*      # Agent library / marketplace
backend.api.features.mcp.routes     # MCP server integration
backend.api.features.otto.routes    # Otto (automation)
backend.api.features.store.*        # Agent store / marketplace
backend.api.features.v1.*           # V1 API compatibility
backend.api.features.integrations.* # OAuth webhook management
backend.api.features.analytics.*    # Usage analytics

Infrastructure

@asynccontextmanager
async def lifespan_context(app: fastapi.FastAPI):
    verify_auth_settings()
    await backend.data.db.connect()       # Prisma → PostgreSQL
    await backend.data.redis_client.get_redis_async()  # Fail-fast check

    # Thread pool for sync endpoints (default 40 → configurable)
    config = Config()
    anyio.to_thread.current_default_thread_limiter().total_tokens = (
        config.fastapi_thread_pool_size
    )

Key infrastructure choices:

• Prisma ORM → PostgreSQL (schema in autogpt_platform/db/)
• RabbitMQ → Graph execution queue (GRAPH_EXECUTION_QUEUE_NAME)
• Redis → Event bus (AsyncRedisEventBus), caching, locks
• Sentry → Error tracking (with Anthropic/OpenAI/FastAPI integrations)
• LaunchDarkly → Feature flags (non-local environments)
• Prometheus → Metrics (execution_manager_active_runs, etc.)
• Stripe → Billing / credits

Classic Agent

The original AutoGPT agent uses a component architecture where functionality is composed from pluggable components:

class Agent(BaseAgent):
    """The original AutoGPT agent with 15+ components."""

    # Core components
    action_history: ActionHistoryComponent
    context: ContextComponent
    system: SystemComponent
    watchdog: WatchdogComponent

    # File & code
    file_manager: FileManagerComponent
    code_executor: CodeExecutorComponent
    git_ops: GitOperationsComponent

    # Web & search
    web_search: WebSearchComponent
    web_playwright: WebPlaywrightComponent
    http_client: HTTPClientComponent

    # AI features
    image_gen: ImageGeneratorComponent
    skills: SkillComponent

    # Utilities
    user_interaction: UserInteractionComponent
    todo: TodoComponent
    clipboard: ClipboardComponent
    math_utils: MathUtilsComponent
    text_utils: TextUtilsComponent
    archive_handler: ArchiveHandlerComponent
    data_processor: DataProcessorComponent
    platform_blocks: PlatformBlocksComponent  # Bridge to new platform!

Component Protocols

class DirectiveProvider(Protocol):
    """Provides directives for the system prompt."""

class MessageProvider(Protocol):
    """Provides messages for the LLM conversation."""

class CommandProvider(Protocol):
    """Provides commands that the agent can execute."""

class AfterParse(Protocol):
    """Hook after parsing LLM response."""

class AfterExecute(Protocol):
    """Hook after executing an action."""

Components implement one or more protocols, and the base agent aggregates them into a unified prompt and command set.

Prompt Strategies

The classic agent ships with 7 prompt strategies, each implementing a different reasoning approach:

One-Shot Prompt Template (Default)

DEFAULT_BODY_TEMPLATE = (
    "## Constraints\n"
    "You operate within the following constraints:\n"
    "{constraints}\n"
    "\n"
    "## Resources\n"
    "You can leverage access to the following resources:\n"
    "{resources}\n"
    "\n"
    "## Commands\n"
    "These are the ONLY commands you can use."
    " Any action you perform must be possible through one of these commands:\n"
    "{commands}\n"
    "\n"
    "## Best practices\n"
    "{best_practices}\n"
    "\n"
    "## Efficiency Guidelines\n"
    "You have LIMITED steps. Be efficient:\n"
    "1. UNDERSTAND BEFORE ACTING\n"
    "2. PARALLEL EXECUTION\n"
    "3. WRITE COMPLETE CODE\n"
    "4. VERIFY AFTER CHANGES\n"
    "5. FIX ROOT CAUSE\n"
    "6. CODE STYLE\n"
    "7. SECURITY"
)

DEFAULT_CHOOSE_ACTION_INSTRUCTION = (
    "Determine exactly one command to use next based on the given goals "
    "and the progress you have made so far, "
    "and respond using the JSON schema specified previously."
)

Response Schema

class AssistantThoughts(ModelWithSummary):
    observations: str  # "Relevant observations from your last action"
    reasoning: str     # "Reasoning behind choosing this action"
    self_criticism: str  # "Constructive self-criticism"
    plan: list[str]    # "Short list that conveys the long-term plan"

class OneShotAgentActionProposal(ActionProposal):
    thoughts: AssistantThoughts

Forge Agent (SDK)

Forge is the agent SDK / template — a minimal, extensible agent base that implements the Agent Protocol API:

class ForgeAgent(ProtocolAgent, BaseAgent):
    """The goal of the Forge is to take care of the boilerplate code,
    so you can focus on agent design."""

    def __init__(self, database: AgentDB, workspace: FileStorage):
        state = BaseAgentSettings(
            name="Forge Agent",
            ai_profile=AIProfile(
                ai_name="ForgeAgent",
                ai_role="Generic Agent",
                ai_goals=["Solve tasks"]
            ),
        )
        ProtocolAgent.__init__(self, database, workspace)
        BaseAgent.__init__(self, state)

        # Built-in components (minimal set)
        self.system = SystemComponent()
        self.todo = TodoComponent()
        self.archive_handler = ArchiveHandlerComponent(workspace)
        self.clipboard = ClipboardComponent()
        # ... (fewer components than original_autogpt Agent)

ForgeAgent implements the Agent Protocol — a standardized API for agent communication:

async def create_task(self, task_request: TaskRequestBody) -> Task:
    """Create a task (Agent Protocol)."""

async def execute_step(self, task: Task, step_request: StepRequestBody) -> Step:
    """Execute a single step — override this to implement your agent logic."""

Classic vs Platform Comparison

Prompt Analysis

Platform — CoPilot System Prompt

The CoPilot system prompt is extensive (~500+ lines) and covers:

• File sharing — Markdown embedding with workspace://file_id URIs
• Binary data handling — Never inline base64; save to workspace first
• Large data passing — @@agptfile: references between tools
• Large file writing — Compose from file refs or write section-by-section (avoid token limits)
• Tool discovery — find_block MANDATORY before claiming "no integration"
• Credentials — Eager sign-in card surfacing; prefer tool calls over verbal coaching
• Sub-agent etiquette — Use run_sub_session for self-contained subtasks

Key anti-pattern rules:

### Anti-pattern: refusing without searching (CRITICAL)

**Never** emit any variant of these without a preceding `find_block` call:
- "We don't have a native X integration yet."
- "X isn't supported on the platform."
- "There's no block for X."

Correct flow:
1. find_block(query=" ")
2. If match → use it
3. If no match → THEN state the gap and offer fallbacks

Classic — One-Shot Strategy

The classic agent uses a template-based prompt with sections:

1. Constraints — Operating boundaries
2. Resources — Available capabilities
3. Commands — Available tools (auto-generated from components)
4. Best Practices — Behavioral guidelines
5. Efficiency Guidelines — Step budget awareness

The response format uses structured JSON via Pydantic schemas:

class AssistantThoughts:
    observations: str   # What happened
    reasoning: str      # Why this action
    self_criticism: str # What could be better
    plan: list[str]     # Next steps

Strengths & Weaknesses

Verdict

Key Files Quick Reference

Generated 2026-05-17 · Source: AutoGPT v0.6.22 · Analysis based on actual Python source code