Agent Substrate Documentation

Agent Substrate is an async-first Python runtime framework engineered for production AI agents that call tools, maintain durable memory across sessions, pause with zero server cost, and survive process crashes without losing state or duplicate tool charges.

Most agent frameworks focus on the initial prototype: wrapping an LLM in a simple prompt loop. Agent Substrate is built for day-2 production operations: deterministic replay, PostgreSQL WAL persistence, budget circuit breakers, and zero-cost hibernation.

---

Getting Started

---

Core Operational Capabilities

1. Durable Write-Ahead Logging (WAL)

Every message, tool invocation request, and state delta commits to an append-only PostgreSQL log before execution. If a worker pod crashes or restarts mid-session, it hot-replays from the last checkpoint in <10ms. Downstream tools use idempotency keys to guarantee that external actions (e.g. charging a card or sending an email) never trigger twice.

2. Zero-Cost Process Hibernation

When an agent waits for human sign-off, a customer reply, or a scheduled cron trigger, keeping the container resident wastes memory and compute. Agent Substrate serializes the execution pointer to PostgreSQL and frees the worker memory entirely (0 MB RAM / 0% CPU). When the resuming webhook arrives, the agent resumes execution instantly.

3. Loop Ceilings & Spend Governance

Production agents risk entering infinite reasoning loops or accumulating unexpected token bills. Agent Substrate enforces hard per-session ceilings on total dollar cost, token consumption, and execution step count. If an agent exceeds these bounds, the circuit breaker halts execution and notifies your alerting system.

4. Open FastMCP Tool Ecosystem

Integrate any external database, SaaS platform, or internal microservice via the Model Context Protocol (FastMCP). Substrate dynamically parses tool definitions from MCP servers and exposes them to reasoning loops with strict Pydantic parameter validation.

---

Platform Subsystem Matrix

The runtime is structured into decoupled layers, ensuring that changes to storage or telemetry do not impact agent logic:

Layer	Subsystem Components	Operational Responsibilities	Reference
L0 Kernel	Identity Schemas, Content Blocks	Immutable AgentId/ThreadId, typed content envelopes, zero third-party dependencies	Kernel API
L1 Reasoning	ReAct Loop, Supervisor Swarms	Deterministic step execution, agent-to-agent delegation, token sliding-window compaction	ReAct Agents
L1 Safety	Guardrail Tripwires, Circuit Breakers	Regex tripwires, LLM safety evaluators, spend limit bounds, step quotas	Guardrails
L2 Storage	PostgreSQL WAL, Redis PubSub	Append-only event store, session checkpointing, atomic optimistic locking	Persistence
L2 Capabilities	FastMCP Bridge, Python Sandbox	Model Context Protocol gateway, sandboxed code execution, Qdrant vector memory	Tool Chaining
L3 Serving	Human-in-the-Loop, SSE Streaming	Webhook pause/resume, token-by-token streaming, golden trajectory evals	Hibernation

---

Substrate Layer Stack

---

Ecosystem Compatibility

Agent Substrate is vendor-agnostic and connects seamlessly with your existing AI stack:

• Model Providers: OpenAI (GPT-4o, o3-mini), Anthropic (Claude 3.7 Sonnet), Google Gemini (2.0 Flash / Pro), DeepSeek (R1, V3), and local Ollama instances.
• Data & Cache: PostgreSQL 14+, Redis 7+, Qdrant Vector Search, SeaweedFS Object Storage.
• Protocols & Standards: Model Context Protocol (FastMCP), OpenTelemetry (OTel Traces & Spans).

---

Next Steps

Explore the detailed implementation guides:

• Building ReAct Agents — Implement a multi-step reasoning agent with typed tools.
• Multi-Agent Orchestration — Coordinate hierarchical teams with supervisor routing.
• Tool Chaining & Validation — Chain outputs between multiple heterogeneous tools safely.
• Spend Caps & Loop Limits — Prevent recursive loops and budget overruns.