AI Legion

Agents independently retrieve their event history from persistent memory, invoke LLMs (GPT-3.5/GPT-4) to generate decisions based on context, and record decisions back to memory before execution. Each agent maintains its own memory store and operates asynchronously, enabling parallel decision-making across multiple agents without blocking. The decision workflow converts unstructured LLM output into validated, executable action schemas through structured parsing and error recovery.

A centralized MessageBus component enables agents to send and receive messages asynchronously without direct coupling. Agents publish messages to the bus (targeting specific agents or broadcasting to all), and the bus routes messages to subscribed agents based on recipient filters. The system decouples agent communication from agent logic, allowing new agents to be added without modifying existing agent code, and supports both point-to-point and broadcast messaging patterns.

AI Legion integrates with OpenAI's API to invoke language models (GPT-3.5-turbo, GPT-4) for agent decision-making. The system handles API authentication through environment variables, supports model selection at startup, and manages API request/response formatting. The integration includes error handling for API failures, rate limiting, and token counting. Agents can be configured to use different models, enabling heterogeneous agent teams with varying capabilities and costs.

Developers can create custom modules by extending a base Module class and implementing action methods with typed parameters. Custom modules are registered with the ModuleManager and become available to all agents immediately. The module system provides a standardized interface for defining actions, validating parameters, and returning results. Modules can depend on external libraries or services, enabling integration with any capability (APIs, databases, ML models, etc.).

AI Legion supports configuration through command-line parameters (agent count, model selection) and environment variables (.env file). Startup configuration controls the number of agents created, the LLM model used, API credentials, and storage backend. The system reads configuration at startup and initializes agents with the specified parameters. Configuration is centralized in .env.template, enabling easy setup and deployment across environments.

A ModuleManager registry enables agents to execute actions through specialized modules (Core, Goals, Notes, Web, System, Messaging). Each module defines a set of callable actions with typed parameters and return values. When an agent decides on an action, the ActionHandler looks up the corresponding module, validates parameters against the module's schema, and executes the action. New modules can be created by extending a base Module class and registering with ModuleManager, allowing extensibility without modifying core agent logic.

Each agent maintains a Store (file-based, database, or custom implementation) that records all events (messages received, decisions made, actions executed) in chronological order. Agents retrieve their full event history on each decision cycle, enabling them to understand context and learn from past actions. The event-sourcing pattern ensures complete auditability and allows agents to reconstruct their state at any point in time by replaying events. Memory is agent-specific; each agent has isolated storage preventing cross-agent memory leaks.

Agents can be created at runtime through a factory pattern that initializes each agent with unique ID, isolated memory store, module manager, and message bus subscriptions. The system supports creating multiple agents with different configurations (model, modules, goals) without restarting the platform. Each agent operates independently in its own execution context, and the lifecycle is managed by the core system which handles agent startup, decision cycles, and graceful shutdown.

The Web module provides agents with capabilities to search the internet and extract content from web pages. Agents can invoke web search actions to find information, then fetch and parse page content to extract relevant data. The module integrates with external web APIs (search provider, page fetcher) and handles response parsing, error handling, and content extraction. Results are returned as structured data that agents can reason about in subsequent decision cycles.

The System module provides agents with file system capabilities (read, write, list, delete files) through a sandboxed interface that restricts access to a designated directory. Agents can create and manage files, read configuration or data files, and organize information on disk. The module handles file I/O errors, path validation, and prevents directory traversal attacks by restricting operations to the sandbox directory.

The Goals module enables agents to set, track, and complete goals as part of their autonomous operation. Agents can create goals (e.g., 'research topic X', 'complete task Y'), mark goals as in-progress or completed, and review their goal history. Goals are stored in the agent's memory, enabling agents to maintain focus on long-term objectives across multiple decision cycles. The system supports goal hierarchies (parent/child goals) and tracks goal completion status.

The Notes module enables agents to create, update, and retrieve notes as a form of persistent knowledge capture. Agents can write notes about findings, decisions, or important information, then retrieve and reference notes in subsequent decision cycles. Notes are stored in the agent's memory alongside other events, enabling agents to build up a knowledge base of insights over time. Notes can be tagged or categorized for easier retrieval.

AI Legion provides dual interfaces for user interaction: a console interface for local command-line interaction and a WebSocket server (port 8080) for remote clients. Users can send messages through either interface, which are broadcast to all agents via the MessageBus. Agents process messages as events and respond through the same interface. The WebSocket server enables real-time bidirectional communication with agents from web clients or external systems.