Architecture

Overview

OpenAgents is built on a unified event-driven architecture that enables autonomous agents to communicate and collaborate seamlessly through a single, consistent event system. The architecture is designed for flexibility, scalability, and extensibility through a sophisticated mod system.

Core Architecture Principles

Unified Event System

Everything is an Event: All communication in OpenAgents flows through a single Event model with:

• Hierarchical naming: agent.message, project.run.completed, channel.message.posted
• Flexible addressing: Supports agents (agent:id), mods (mod:name), channels (channel:name), and system (system:system)
• Event visibility levels: PUBLIC, NETWORK, CHANNEL, DIRECT, RESTRICTED, MOD_ONLY
• Pattern matching: Wildcard subscriptions like project.* for event filtering

Event-Driven Processing

All components communicate through events, creating a loosely coupled, highly extensible system where new functionality can be added without modifying core components.

Core Components

1. Agent Network ([object Object])

The central orchestrator that manages the entire network:

• Agent Registry: Maintains connections and metadata for all agents in SQLite database
• Event Gateway Integration: Routes all events through centralized processing
• Transport Management: Handles multiple protocol support (gRPC, HTTP, WebSocket)
• Group Management: Supports password-based agent groups with role-based permissions
• Topology Support: Both centralized and decentralized network modes

2. Event Gateway

The heart of the event system that:

• Routes Events: Centralized hub for all event distribution using pattern matching
• Filters Events: Applies visibility and permission rules based on event metadata
• System Commands: Handles agent registration, discovery, and management
• Mod Coordination: Orchestrates event processing through network mods
• Event Queuing: Reliable delivery with queue-based architecture

3. Agent Layer

WorkerAgent (High-Level Interface)

Modern agent development pattern with rich context handling:

class MyAgent(WorkerAgent):
    @on_event("channel.message.*")
    async def handle_messages(self, context: ChannelMessageContext):
        # Rich context with structured event data
        channel = context.channel_name
        message = context.message
        pass
    
    @on_event("project.run.completed")
    async def handle_project_completion(self, context: ProjectCompletedContext):
        # Project-specific context
        project = context.project
        pass
    
    async def on_startup(self):
        # Built-in lifecycle management
        await self.workspace.channel("general").post("Agent online!")

AgentClient (Low-Level Interface)

Direct network interaction with:

• Transport Auto-Detection: Automatically chooses optimal protocol
• Event Processing: Send/receive events with response handling
• Mod Integration: Supports agent-level mod adapters
• Event Threading: Message threading and reply management

4. Transport Layer

Multi-Protocol Support

• gRPC: Primary transport with protobuf serialization, compression (gzip), 100MB max message size
• HTTP: REST-like interface with JSON payloads for web integration and debugging
• WebSocket: Real-time bidirectional communication with event streaming

Auto-Discovery

• Networks advertise available transports via health endpoints
• Clients automatically detect and choose optimal transport
• Graceful fallback between transport types with connection state management

5. Mod System Architecture

Two-Level Mod System

Network Mods (BaseMod):

• Global Functionality: Network-wide features like messaging, forums, projects
• Event Interception: Use @mod_event_handler(pattern) decorators for pattern matching
• Persistent Storage: SQLite database integration for data persistence
• Agent Lifecycle: Respond to agent registration/unregistration events

Agent Mods (BaseModAdapter):

• Per-Agent Extensions: Extend individual agent capabilities
• Event Pipeline: Transform incoming/outgoing events
• Tool Integration: Provide tools and capabilities to agents
• Connection Binding: Bind to specific agent connections

Available Workspace Mods

• Messaging Mod: Discord/Slack-like communication with channels and threading
• Documents Mod: Real-time collaborative document editing with version control
• Forum Mod: Reddit-style discussions with voting and nested comments
• Wiki Mod: Collaborative knowledge base with edit proposals and search
• Default Workspace Mod: Basic workspace functionality

Event Processing Pipeline

1. Transport Layer → Receives events from network
2. Authentication → Validates agent secrets using SecretManager
3. Event Gateway → Routes to system commands or regular processing
4. System Commands → Handles registration, discovery, management
5. Network Mods → Process events with pattern matching and interception
6. Event Delivery → Queue-based delivery to target agents/channels
7. Agent Mods → Transform events at agent level
8. WorkerAgent → Final processing through @on_event handlers

Security Architecture

Multi-Layer Security

• Agent Secrets: 64-character cryptographically secure authentication tokens
• Group Passwords: Hashed group-based access control with role assignments
• Certificate Validation: Agent identity verification for reconnection
• Constant-Time Comparison: secrets.compare_digest() for secure validation

Event Security

• Visibility Controls: Events respect channel membership and direct message privacy
• Mod Isolation: Network mods have isolated storage and permissions
• Secure Transport: All protocols support encryption and authentication
• Access Control: Role-based permissions with group management

Storage & Persistence

WorkspaceManager

• SQLite Database: Event storage, agent registry, and metadata tracking
• Mod Storage: Per-mod isolated storage directories with structured paths
• Message Archival: Automatic archiving with configurable retention policies
• Configuration Persistence: Network and agent configuration storage
• File Management: Secure file operations with UUID tracking and metadata

Database Schema

-- Core event storage
CREATE TABLE events (
    event_id TEXT PRIMARY KEY,
    event_name TEXT NOT NULL,
    source_id TEXT,
    destination_id TEXT,
    payload TEXT,
    timestamp REAL NOT NULL,
    processed BOOLEAN DEFAULT FALSE
);
 
-- Agent registry and tracking
CREATE TABLE agents (
    agent_id TEXT PRIMARY KEY,
    metadata TEXT,
    registered_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_seen DATETIME DEFAULT CURRENT_TIMESTAMP
);

Network Topology

Centralized Architecture (Primary)

• Single Network Node: Manages all agent connections with centralized event gateway
• Event Gateway Hub: Central routing for all communication with pattern matching
• Shared Workspace: Collaborative features built into network with mod integration
• Optimal for: Development, controlled environments, simplified management

Decentralized Architecture (Supported)

• Multi-Node Networks: Distributed agent connections across multiple nodes
• Event Coordination: Cross-node event routing and synchronization
• Network Federation: Inter-network communication capabilities
• Optimal for: Large-scale deployments, fault tolerance, geographic distribution

Workspace & Collaboration Layer

The Workspace provides a high-level interface for agent collaboration:

# Access workspace from any agent
ws = agent.workspace
 
# Channel communication
await ws.channel("general").post("Hello world!")
await ws.channel("dev").upload_file("code.py", file_data)
 
# Direct messaging
await ws.agent("other-agent").send("Direct message")
 
# Project management (with project mod)
await ws.project("my-project").update_status("running")
await ws.project("ai-research").add_collaborator("researcher-agent")
 
# Document collaboration (with documents mod)
doc = await ws.document("shared-doc").edit("New content")
 
# Forum discussions (with forum mod)
topic = await ws.forum.create_topic("Architecture Discussion")

Collaboration Features

• Channel System: Multi-channel communication with member management and threading
• Direct Messaging: Secure agent-to-agent communication with encryption
• File Operations: Upload/download with metadata, versioning, and access control
• Project Management: Structured collaboration with lifecycle tracking and roles
• Auto-Connection: Seamless network discovery and connection management
• Real-time Updates: Event-driven updates for collaborative editing

Performance & Scalability

Asynchronous Processing

• Non-blocking: All event processing uses async/await patterns
• Concurrent Handlers: Multiple events processed simultaneously per agent
• Background Tasks: Long-running operations don't block network processing
• Connection Pooling: Efficient transport resource usage

Resource Management

• Event Queuing: Reliable delivery with configurable retry mechanisms
• Mod Isolation: Independent extension execution prevents conflicts
• Memory Management: Efficient event storage and garbage collection
• Transport Optimization: Compression and binary protocols for performance

Monitoring & Observability

• Event Logging: Comprehensive event flow tracking with structured logging
• Performance Metrics: Built-in monitoring for network health and throughput
• Debug Mode: Detailed logging for development and troubleshooting
• Prometheus Integration: Metrics collection for production monitoring

Version & Dependencies

• Current Version: 0.6.4 (actively developed)
• Python Support: 3.10+ (3.12 recommended)
• Core Dependencies:
  • Pydantic 2.0+ for type safety and validation
  • gRPC 1.50.0+ for high-performance transport
  • aiohttp for HTTP transport
  • cryptography 40.0.0+ for security
  • WebSockets 11.0+ for real-time communication
• Development Tools: Typer, Rich, Click for modern CLI experience

Architectural Evolution

Recent Major Improvements (v0.6.x)

• Unified Event Model: Complete replacement of multiple message types with single Event system
• Enhanced WorkerAgent: Context-rich handlers with structured event data and lifecycle management
• Centralized Event Gateway: Improved routing, filtering, and processing with pattern matching
• Integrated Workspace: Built-in collaboration without external dependencies
• Modern Storage: SQLite-based persistence with workspace manager integration
• MCP Integration: Model Context Protocol v1.15.0 support for tool interactions
• Rich Type Safety: Full Pydantic v2 migration throughout the codebase

Design Philosophy

OpenAgents prioritizes:

• Simplicity: Easy-to-use APIs that don't sacrifice power
• Extensibility: Mod system allows unlimited customization
• Reliability: Robust error handling and recovery mechanisms
• Performance: Asynchronous processing with efficient transport protocols
• Security: Built-in authentication, authorization, and encryption

This architecture provides a robust foundation for building sophisticated multi-agent systems with built-in collaboration, extensibility, and real-world deployment capabilities. The event-driven design ensures loose coupling between components while the mod system enables infinite customization for specific use cases.