Skip to main content

​
System Architecture

Weaver is built for high-density, low-latency AI agent orchestration. It achieves sub-second boot times and minimal memory footprint (<10MB per agent) through a carefully designed Go-based architecture.
Weaver Architecture

​
Core Components

Weaver’s architecture consists of four primary components that work together to enable efficient agent orchestration:

Agent Loop

Core processing engine that handles LLM interactions and tool execution

Message Bus

Pub/sub system for routing messages between channels and agents

Gateway

Central dispatcher that manages channels and coordinates agent lifecycles

Workspace

Isolated directory structure for agent memory and file operations

​
Message Flow

The following diagram illustrates how messages flow through the Weaver system:

​
Key Design Principles

Each agent operates within a dedicated workspace directory, providing:
  • File system isolation with optional restriction to workspace boundaries
  • Session persistence for conversation history and memory
  • Tool execution context that prevents unauthorized file access
  • State management for atomic operations that survive crashes
type AgentLoop struct {
    workspace      string
    sessions       *session.SessionManager
    state          *state.Manager
    tools          *tools.ToolRegistry
    // ...
}
The message bus uses buffered channels for non-blocking communication:
type MessageBus struct {
    inbound  chan InboundMessage  // Buffered with 100 capacity
    outbound chan OutboundMessage // Buffered with 100 capacity
    handlers map[string]MessageHandler
}
This design enables:
  • Non-blocking message dispatch from channels
  • Concurrent agent processing without blocking channels
  • Backpressure handling through buffer saturation
Weaver implements a universal tool protocol that all agents understand:
type Tool interface {
    Name() string
    Description() string
    Parameters() map[string]interface{}
    Execute(args map[string]interface{}) *ToolResult
}
Tools can be:
  • Synchronous (file operations, shell commands)
  • Asynchronous (subagent spawning, long-running tasks)
  • Contextual (channel-aware for message sending)
Intelligent memory management prevents context overflow:
  • Token estimation using character-based heuristics (2.5 chars/token)
  • Automatic summarization when history exceeds 75% of context window
  • Emergency compression that drops oldest 50% of messages on overflow
  • Multi-part summarization for long conversations (split & merge strategy)
func (al *AgentLoop) maybeSummarize(sessionKey, channel, chatID string) {
    tokenEstimate := al.estimateTokens(newHistory)
    threshold := al.contextWindow * 75 / 100
    
    if len(newHistory) > 20 || tokenEstimate > threshold {
        go al.summarizeSession(sessionKey)
    }
}

​
Performance Characteristics

​
Boot Time
<1s
Agents start in under one second due to:
  • Compiled Go binary (no interpreter startup)
  • Lazy initialization of optional components
  • Pre-compiled tool registry
​
Memory Footprint
<10MB
Minimal memory usage achieved through:
  • No heavyweight frameworks or runtimes
  • Efficient Go garbage collection
  • Shared provider clients across tools
​
Request Latency
~100-300ms
Fast response times from:
  • Direct LLM API calls without middleware
  • Parallel tool execution where possible
  • Buffered message channels preventing blocking

​
Deployment Architecture

Weaver is designed for containerized deployment at scale:
1

Gateway Container

Single long-running gateway process that manages:
  • All channel connections (Telegram, Discord, Slack, etc.)
  • Message routing and dispatch
  • Health check endpoints (/health, /ready)
  • REST API for direct agent interaction
2

Agent Workspaces

Each agent gets an isolated workspace:
docker run --rm \
  -v $(pwd)/workspaces/task-1:/root/.weaver/workspace \
  -e GEMINI_API_KEY=$GEMINI_API_KEY \
  operatoronline/weaver agent -m "Task description"
3

Horizontal Scaling

Multiple gateway instances can run behind a load balancer:
  • Stateless gateway design (state in workspace volumes)
  • Shared workspace volumes via NFS/EBS/etc.
  • Independent LLM provider connections

​
Next Steps

Agent Loop

Deep dive into the agent processing lifecycle

Channels

Learn how channels connect users to agents

Build docs developers (and LLMs) love

Get started for freeTalk to us