AI Swarm Network & Ralph Agent
Relevant source files
The following files were used as context for generating this wiki page:
The AI Swarm Network is a decentralized ecosystem designed to facilitate trustless, verifiable AI computations through a distributed network of specialized autonomous agents. Within this network, the Ralph Agent serves as a specialized autonomous coding agent capable of implementing software features, running quality checks, and maintaining codebase patterns through iterative cycles.
The system leverages a multi-layer architecture to handle strategic positioning, technical execution, media production, and network growth. By utilizing decentralized GPU compute and on-chain identity pallets, the network ensures that AI agents operate as first-class citizens with verifiable capabilities and reputation scores.
Sources: scripts_infrastructure/ralph/prd.json, apps/x3-desktop/src-tauri/src/crm/agents.rs:16-25, apps/atlas-sphere-clean/X3_END_TO_END_GAPS_MASTER_PLAN.md:144-149
Swarm Architecture & Layers
The AI Swarm is organized into a 15-agent "surgical swarm" divided into four distinct functional layers. This hierarchy ensures a separation of concerns between high-level strategy and low-level execution.
Swarm Hierarchy Diagram
The following diagram illustrates the relationship between the four layers of the agent swarm.
Layer Definitions
| Layer | Responsibility | Key Primary Agents |
|---|---|---|
| Strategic | Defines positioning, narrative, security posture, and market intelligence. | ArchNode, VaultGuard |
| Execution | Handles SEO, technical documentation, benchmarks, and validator operations. | WebWeaver, DocForge, ProofEngine |
| Media | Produces video scripts, storyboards, and UI visualizations. | FrameX, PixelForge |
| Growth | Manages funnels, CRM analytics, and community narratives. | ConvertX, InsightGrid |
Sources: apps/x3-desktop/src-tauri/src/crm/agents.rs:41-385
Ralph Agent: Autonomous Coding Lifecycle
The Ralph Agent is an autonomous entity specialized in codebase modification. It operates on a specific execution loop driven by the project's Product Requirements Document (prd.json) and a progress log.
Ralph Execution Flow
This diagram shows the iterative cycle the Ralph Agent follows to implement features.
Core Tasks and Quality Requirements
- Story Implementation: Ralph picks the highest priority user story where
passes: falseand implements it on the branch specified in the PRD. - Quality Checks: Ralph must execute mandatory checks including
cargo clippy,cargo test, and for frontend stories,dev-browserverification. - Pattern Consolidation: Discovered reusable patterns (e.g., "Use sql template for aggregations") are added to the
Codebase Patternssection ofprogress.txt. - AGENTS.md Maintenance: Ralph identifies directories with edited files and updates local
AGENTS.mdfiles with non-obvious requirements or dependencies.
Sources: scripts_infrastructure/ralph/prompt.md:18-65
AI Agent Identity & On-Chain Registry
Agents in the swarm are registered as first-class citizens using a Substrate pallet. This ensures that every agent has a cryptographic identity and a verifiable track record.
Identity Components
- Agent ID: SS58 address for EVM or Pubkey for SVM.
- Metadata: Includes name, capabilities, and model types supported.
- Reputation: A score (0-100) derived from completed jobs, earnings, and age.
- Staking: A minimum requirement of 100 X3 tokens is necessary for registration to prevent Sybil attacks.
Sources: scripts_infrastructure/ralph/prd.json: userStory AI-001, scripts_infrastructure/ralph/prd.json: userStory AI-010
Identity Management Schema
Technical Execution & Models
The swarm utilizes local LLM models (specifically qwen2.5-coder:14b) via Ollama to perform tasks without requiring external API keys.
Agent Definition Structure
The system defines agents using the AgentDef struct, which encapsulates the agent's identity and operational constraints.
pub struct AgentDef {
pub id: String,
pub name: String,
pub role: String,
pub layer: String,
pub avatar: String,
pub color: String,
pub model: String,
pub system_prompt: String,
pub capabilities: Vec<String>,
pub status: String,
}
Sources: apps/x3-desktop/src-tauri/src/crm/agents.rs:27-38
Key System Prompt Themes
- Survivability: Agents are instructed to emphasize X3 Chain as high-throughput infrastructure that institutions can depend on.
- Proof-Centric: Narratives must be backed by benchmarks; agents are forbidden from using "hype" words like "revolutionary" without proof.
- Layered Security: The InfoSec agent (VaultGuard) drafts audit reports and manages OPSEC guides for the validator network.
Sources: apps/x3-desktop/src-tauri/src/crm/agents.rs:41-85, apps/x3-desktop/src-tauri/src/crm/agents.rs:113-130
Swarm Operations & Task Management
The network manages tasks and memory through centralized API services and local storage.
Task Management APIs
The Swarm API (x3-swarm-api) tracks the status of various tasks assigned to agents. Each task includes permission tiers and path restrictions to ensure security.
| Field | Description | Example |
|---|---|---|
permission_tier | Defines what the agent can access. | constrained, read-only |
allowed_paths | Whitelisted directories for the task. | crates/x3-swarm-core/src |
forbidden_paths | Blacklisted directories (e.g., secrets). | ./.git, secrets/ |
approval_required | Whether a human must approve the task. | manual, auto |
Sources: reports/swarm_report.md:14-25
Swarm Interaction Sequence
The following diagram shows how a user interacts with an agent through the system.
Conclusion
The AI Swarm Network provides a robust, layered framework for autonomous agent coordination. By combining the iterative implementation capabilities of the Ralph Agent with the specialized roles of the 15-agent surgical swarm, the project achieves a high degree of automation in both technical development and ecosystem management. The system's reliance on on-chain identities and verifiable compute ensures that this autonomous behavior remains secure and aligned with the network's constitutional laws.
Sources: apps/x3-desktop/src-tauri/src/crm/agents.rs:857-876, scripts_infrastructure/ralph/prd.json: userStory AI-015