Subsystem Architecture (L0 – L3)
Agent Substrate is designed around a fundamental invariant: Decoupled Compute and State.
Traditional agent frameworks bundle execution state, socket connections, and tool buffers directly into the worker memory space. When a worker dies, runs out of memory, or waits on a long webhook, the entire agent state is compromised. Agent Substrate solves this through a 4-tier layer hierarchy with zero circular dependencies.
The Four Layers
L0: Kernel Primitives (substrate.kernel)
The foundation of the entire ecosystem. Pure Python contracts, immutable identity types, and streaming message deltas.
- Zero External Dependencies: Does not import any networking, database, or LLM libraries.
- Core Types:
AgentId,SessionId,ThreadId,ChatMessage,TextBlock,ToolUseBlock. - Streaming Specifications: Standardized event schemas for chunked token emission.
L1: Agent Reasoning Core (substrate.agents)
The autonomous decision loop and multi-agent coordination brain.
- ReAct Loop: Multi-step reasoning with backtracking and structured error handling.
- Orchestrator Swarms: Supervisor agents that delegate tasks to specialized worker agents with strict sub-budget governance.
- Context Compaction: Sliding-window summary algorithms that compress turn history by up to 87% without losing factual context.
- Security Guardrails: Pre-turn and post-turn tripwires that block prompt injections and redact PII.
L2: Subsystems (Dual Layer)
Split cleanly into Infrastructure and Capabilities to isolate persistence from external execution:
L2 - S1: Infrastructure (substrate.infrastructure)
- PostgreSQL Append-Only Journal: Immutable write-ahead logging (WAL) of every state change.
- Redis Hot Cache: Millisecond state retrieval for active conversational turns.
- Distributed Observability: Native W3C OpenTelemetry trace contexts streaming to Datadog, Honeycomb, or Grafana.
L2 - S2: Capabilities (substrate.capabilities)
- Zero-Egress Python Sandbox: Firecracker / subprocess sandbox executing dynamic code safely when no tool matches.
- Tool Chaining Bridge: Script multiple tools in a single execution turn, piping data by reference without LLM round-trips.
- Vector & Episodic Memory: Semantic recall backed by pgvector or Qdrant.
- Artifact Versioning: Durable file outputs stored in SeaweedFS or S3.
L3: Fabric & Serving (substrate.fabric & substrate.serving)
The production edge boundary handling external traffic and long-running workflows.
- Durable Human Gates: Pause execution for hours, days, or weeks with zero server compute consumption.
- SSE Monolith: Real-time event streaming over Server-Sent Events.
- Continuous Evals: Benchmark agent trajectories against safety and correctness test suites.
Dependency Invariant Rules
To ensure long-term stability and eliminate architectural decay:
- L0 Imports Nothing External: The Kernel must never import L1, L2, L3, or heavy third-party packages.
- Strict Downward Dependencies: Higher layers may import lower layers, but lower layers never import higher layers.
- Zero Circular Imports: Enforced automatically by static analysis in CI pipelines.