IAF AI-Piloted Edition

Executive Summary

Intelligenism Agent Framework (IAF) AI-Piloted Edition is a multi-agent orchestration framework purpose-built for one radical capability: to be fully understood, modified, and managed by external AI systems. While other agent frameworks are designed for human developers to write code, IAF is designed so that AI agents can operate it through file system manipulation alone.

This edition builds on the original IAF architecture, adding a comprehensive self-description layer, validation toolchain, structured logging, and operational safety mechanisms. The result is a framework that any flagship LLM with file read/write and shell access can take over, configure, and run autonomously.

Core Positioning

Architecture Overview

IAF is organized into four independent layers. Each layer communicates through the file system and HTTP APIs, with no direct code coupling between layers.

Design Principles

• Possibility Management — Each agent owns a complete copy of its engine code. Changes to one agent never affect another. This eliminates cascading failures and enables per-agent experimentation.
• Additive Complexity — Adding a new agent is adding a directory. Adding a new tool is dropping a file. Adding a new automation pipeline is editing a JSON array. None of these operations require modifying existing code.
• File System as Control Plane — Every configuration, identity definition, tool registration, and automation pipeline is expressed as a file. An AI with Read/Write/Edit/Bash capabilities can manage the entire system without calling any internal API.
• Process Isolation — Each agent runs in its own subprocess context. Tube steps execute in isolated subprocesses. A crash in one agent or step cannot bring down the system.
• Convention Over Configuration — Tools are discovered by scanning *_tools.py files. Pages by scanning *.html files. Agents by scanning directories. No registration code needed.

AI Operability Layer

The AI Operability Layer is the defining addition of this edition. It is a set of self-description files, validation tools, and operational safety mechanisms that enable external LLMs to fully manage IAF. This layer adds no runtime overhead to the framework. It exists purely as an interface between the external AI operator and the IAF file system.

System Map (MANIFEST.json)

A machine-readable snapshot of the entire system state, auto-generated by generate_manifest.py and refreshed on server startup. An external LLM reads this single file to understand what agents, tubes, dispatches, and tools exist.

The manifest includes: all agent IDs with their config paths, model assignments, tool lists, and log file locations; all dispatch strategies with participating agents; all tubes with their trigger types and step chains; and framework conventions for file naming patterns.

Operation Playbook (PLAYBOOK.md)

A comprehensive text manual that maps every management intent to a concrete sequence of file operations. An external LLM reads this file to learn how to create agents, add tools, configure automation pipelines, modify behavior, and handle errors.

The playbook covers: agent lifecycle (create, configure, add tools, modify behavior), tube management (create, trigger, monitor), dispatch strategy creation, engine modification procedures with diff-based synchronization, and safety protocols.

Validation Script (validate.py)

Structured Logging (call_log.jsonl)

Each agent writes a structured JSONL log of every invocation. The external LLM reads these logs to understand what happened during agent execution, diagnose failures, and verify that automated pipelines are working correctly.

Tool Contract (TOOL_CONTRACT.md)

A specification document that defines the exact format for writing new tool files. When an external LLM needs to give an agent a new capability, it reads this contract to produce a correctly structured *_tools.py file that will be automatically discovered and loaded.

Safety Mechanisms

• Git Snapshot Script (auto_commit.sh) — Creates a Git commit before any batch modification. The external LLM runs bash auto_commit.sh before making changes, enabling instant rollback via git revert if anything goes wrong.
• Hot Reload — All configuration files are hot-reloaded. agent_config.json, SOUL.md, context files, tools, tubes.json, dispatch configs, and rules files are re-read on every invocation or polling cycle. Zero restart needed.
• Dangerous Operation List — The playbook explicitly marks high-risk operations (deleting agent directories, modifying engine code, changing provider keys) and mandates Git snapshots before any such operation.

Agent Layer

Each agent is an independent directory under agents/ containing its complete runtime: engine code, identity, tools, skills, context strategy, and logs. Creating a new agent is a directory copy operation: cp -r template/ agents/new_agent/.

Agent Directory Structure

Five-Layer Message Assembly

Tool Auto-Discovery and Hot Reload

The tool executor scans the agent's tools/ directory for files matching *_tools.py and imports their TOOLS dictionaries. On each agent invocation, the executor checks the directory modification time. If any file has been added, removed, or modified since the last scan, tools are re-discovered automatically. An external LLM can write a new tool file and it takes effect on the very next agent call, with zero restart required.

Three Capability Tiers

Dispatch Layer

The Dispatch layer orchestrates multi-agent collaboration. Each collaboration strategy is a self-contained directory that can be independently developed and deployed. The layer does not call the agent engine directly. Instead, it treats agent directories as data sources and calls the LLM API through its own context assembly pipeline.

Strategy Structure

Tube Layer (Signal Topology)

The Tube layer is the automation and scheduling dimension of IAF. It connects agents, dispatches, and other tubes through declarative signal pathways defined in a single file: tube/tubes.json. The tube runner polls this file every 15 seconds, checks trigger conditions, and executes step chains in isolated subprocesses.

Enhanced Execution (New in This Edition)

• Step-Level Retry — Each step can define a retry policy with maximum attempts and delay between retries. Failed steps are retried according to their configuration before being marked as failed. All retry attempts are logged.
• Failure Strategy — Each step can define an on_fail policy: stop (default, halt the tube) or continue (skip failed step, proceed to next). This enables resilient pipelines where non-critical steps can fail without blocking the entire workflow.
• Inter-Step Data Passing — Step outputs are captured in tube/staging/{tube_id}_{timestamp}/ as text files. Subsequent steps can reference the previous step's output via the $PREV_OUTPUT placeholder in their payload.

Trigger and Target Extensibility

External LLM Takeover Model

The defining feature of the AI-Piloted Edition is that the entire framework can be managed by an external LLM agent (Claude Code, GPT Agent, or any agent with file and shell access) without touching any internal API or using any IAF-internal tool.

The External Operator's Toolkit

Onboarding Sequence

An external LLM takes over an IAF instance in three reads:

Operation Loop

Why File System, Not API

Traditional frameworks expose control through Python APIs, requiring the controlling LLM to generate syntactically correct code, manage imports, handle type systems, and reason about runtime state. IAF eliminates all of these failure modes by expressing control as file operations.

Editing a JSON field has a near-zero chance of causing a syntax error compared to modifying a Python class definition. Dropping a file in a directory is an atomic operation that either succeeds completely or fails obviously. And every change is automatically versioned through Git, providing a complete audit trail and rollback capability.

Competitive Landscape

The fundamental architectural difference is that IAF treats the file system as its primary control interface, while all other frameworks treat Python code as their primary control interface. This is not a feature that can be added to existing frameworks through a plugin or wrapper. It is a foundational design decision that shapes the entire architecture.

Potential Applications

AI-Managed Website Operations

An external LLM creates specialized agents (content monitor, SEO analyzer, uptime checker, report generator), wires them into scheduled tubes, and uses dispatch for multi-agent analysis of complex issues. The entire setup is created and maintained through file operations.

Autonomous Research Pipelines

A tube-driven pipeline where Agent A collects data, Agent B analyzes it, and a roundtable dispatch synthesizes conclusions. The external LLM monitors logs, adjusts agent prompts based on output quality, and adds new pipeline stages as research evolves.

Self-Evolving Agent Teams

The external LLM reviews agent performance through call_log.jsonl, identifies underperforming agents, modifies their SOUL.md or tool configurations, validates changes, and monitors improvement. Over time, the agent team evolves its capabilities without human intervention in the optimization loop.

Multi-Model Orchestration

Different agents can use different LLM providers and models. The external LLM can assign cost-effective models to simple monitoring tasks and premium models to complex analysis, optimizing the cost-capability tradeoff across the entire system through agent_config.json edits.

Technical Specifications

File Inventory Summary

Links

• GitHub (AI Edition) — Intelligenism-Agent-Framework-AI-Operability-Edition
• GitHub (Standard Edition) — intelligenism-agent-framework
• IAF Architecture Docs — Standard Edition Architecture Overview
• Website — intelligenism.club
• Theory — intelligenism.org