Quickstart (5 Minutes)

Build and run your first durable AI agent with tool calling, memory, and failover protection in under five minutes.

1. Installation

Install the core package using pip or uv:

bash

# Using uv (recommended)
uv add agent-substrate

# Or using pip
pip install agent-substrate

Environment Configuration

Set your model provider key in your environment or .env file:

bash

export ANTHROPIC_API_KEY="sk-ant-..."
# Or OpenAI / Gemini / OpenRouter
export OPENAI_API_KEY="sk-proj-..."

2. Define a Tool

Tools in Agent Substrate use type annotations to automatically infer input schemas for the LLM:

python

from substrate.capabilities.tools import tool

@tool(name="query_customer_revenue", description="Look up Q3 revenue for an enterprise customer")
async def query_customer_revenue(customer_name: str) -> dict:
    # Simulated database query
    return {
        "customer": customer_name,
        "q3_revenue": "$142,500",
        "contract_status": "Active",
        "renewal_date": "2026-11-30"
    }

3. Create and Run Your Agent

Instantiate a ReActAgent with your chosen model, tools, and budget guardrails:

python

import asyncio
from substrate.agents import ReActAgent
from substrate.agents.middleware.guardrails import SafetyGuardrail

async def main():
    agent = ReActAgent(
        model="claude-3-7-sonnet",
        tools=[query_customer_revenue],
        middleware=[
            SafetyGuardrail(block_prompt_injection=True, redact_pii=True)
        ],
        max_steps=10,
        max_cost_usd=2.00  # Hard budget ceiling
    )

    # Run the agent turn with a dedicated session thread
    result = await agent.run(
        prompt="Check the revenue for Acme Corp and calculate their monthly burn.",
        thread_id="thr_quickstart_01"
    )

    print("Agent Final Response:\n", result.text)
    print(f"\nExecution Metrics: {result.total_tokens} tokens, ${result.total_cost:.4f} USD")

if __name__ == "__main__":
    asyncio.run(main())

4. What Just Happened?

When you executed agent.run(), Agent Substrate performed the following guarantees:

Durable Session Allocation: Assigned your thread (thr_quickstart_01) to an isolated workspace.
Pre-Turn WAL Commit: Saved the inbound user prompt to the append-only event log before making any model calls.
ReAct Reasoning Loop: The model decided to invoke query_customer_revenue(customer_name="Acme Corp").
Tool Execution & Memoization: Executed the tool safely, recorded its output, and synthesized the final response.
State Hibernation: De-allocated worker memory immediately after the turn finished (0% idle CPU).

Next Steps

Explore the Subsystem Architecture to understand the L0–L3 hierarchy.
Learn how PostgreSQL WAL & Replay guarantees zero data loss on server restarts.
Connect external databases and tools using the FastMCP Gateway.

Was this page helpful?

Suggest edits Raise issue