Quickstart: run a durable agent with the Diagrid CLI

Agent frameworks like CrewAI, LangGraph, and others give you tools, LLM orchestration, and prompt management — but none of them handle what happens when things go wrong in production. Some offer basic checkpointing, but you still need to detect failures at scale, build your own recovery mechanisms, and coordinate resumption across instances to avoid duplicate runs.

Diagrid adds the missing infrastructure: automatic failure detection, automatic recovery at scale, and multi-instance agent coordination. Your agent code stays the same — Diagrid handles the rest.

Diagrid works with the following agent frameworks, select one and continue following the quickstart.

tip

Using Claude Code, Codex or the Copilot CLI? Try the AI coding agent version of this quickstart.

note

Diagrid Cloud is free and the fastest way to get started — no infrastructure to set up. For production or on-premises requirements, Diagrid also offers other hosting options, including BYOC and Enterprise Server.

Prerequisites

1. Log in to Diagrid

Authenticate to Diagrid using the following command:

diagrid login

This command opens a new browser window where you'll be shown a confirmation code that should match the code in your terminal. Confirm the code, and if you're not logged into Diagrid, you'll be redirected to login.

Confirm your user details are correct using the following command:

diagrid whoami

The expected output contains the name of the organization, your user name, and the Diagrid API endpoint.

2. Clone and Navigate

git clone https://github.com/diagridio/catalyst-quickstarts.git

Navigate to the quickstart directory for your framework:

cd catalyst-quickstarts/agents/dapr-agents/durable-agent

cd catalyst-quickstarts/agents/crewai

cd catalyst-quickstarts/agents/langgraph

cd catalyst-quickstarts/agents/strands

cd catalyst-quickstarts/agents/openai-agents

cd catalyst-quickstarts/agents/adk

cd catalyst-quickstarts/agents/pydantic-ai

cd catalyst-quickstarts/agents/microsoft-dotnet

cd catalyst-quickstarts/agents/spring-ai/event-planner

cd catalyst-quickstarts/agents/deepagents

cd catalyst-quickstarts/agents/deepagents

cd catalyst-quickstarts/agents/claude-agents

HolmesGPT has no directory in catalyst-quickstarts yet. Use the runnable examples in the python-ai repository instead:

git clone https://github.com/diagridio/python-ai.git
cd python-ai/examples/holmesgpt

cd catalyst-quickstarts/agents/mastra

3. Explore the Code

Invitations Manager — a durable agent that sends event invitations to guests via email and physical mail. Dapr Agents is the native AI agent framework built on Dapr — durability, state, and pub/sub are built into the agent itself.

Open main.py. The agent uses Pydantic models for structured tool input and output:

from typing import List
from pydantic import BaseModel, Field
from dapr_agents import tool, DurableAgent
from dapr_agents.llm import DaprChatClient

class InvitationResult(BaseModel):
    sent: int = Field(description="Number of invitations sent")
    method: str = Field(description="Delivery method")

class InvitationSchema(BaseModel):
    guest_count: int = Field(description="Number of guests to invite")
    event_type: str = Field(description="Type of event")

@tool(args_model=InvitationSchema)
def send_invitations(guest_count: int, event_type: str) -> List[InvitationResult]:
    """Send event invitations to guests."""
    return [
        InvitationResult(sent=int(guest_count * 0.7), method="email"),
        InvitationResult(sent=int(guest_count * 0.3), method="physical mail"),
    ]

The DurableAgent class brings everything together — memory, state, registry, and pub/sub are all configured at the agent level:

agent = DurableAgent(
    name="invitations-manager",
    role="Invitations Manager",
    goal="Send event invitations to guests using the send_invitations tool. Report how many were sent by email and physical mail.",
    instructions=[
        "When asked to send invitations, use the send_invitations tool with the guest count and event type.",
        "Always report back the exact number of invitations sent and via which delivery method.",
    ],
    tools=[send_invitations],
    llm=DaprChatClient(component_name="llm-provider"),
    memory=AgentMemoryConfig(
        store=ConversationDaprStateMemory(store_name="kvstore")
    ),
    state=AgentStateConfig(
        store=StateStoreService(store_name="kvstore", key_prefix="invitations-manager:"),
    ),
    registry=AgentRegistryConfig(
        store=StateStoreService(store_name="agent-registry"),
    ),
    pubsub=AgentPubSubConfig(
        pubsub_name="pubsub",
        agent_topic="events.invitations.requests",
        broadcast_topic="agents.broadcast",
    ),
)

runner = AgentRunner()
runner.serve(agent, port=int(os.environ.get("APP_PORT", "8006")))

tip

Unlike other frameworks, Dapr Agents has durability, state, pub/sub, and failure recovery built in natively. Automatic failure detection, crash recovery, and multi-instance coordination are all handled out of the box — no wrapper needed.

Crash Recovery Demo — a 3-step pipeline that demonstrates how Diagrid recovers from a mid-execution crash.

Open crash_test.py. It defines three tools that the agent calls in sequence. Step 2 deliberately takes about 10 seconds. That delay is the window the crash lands in: the app kills itself partway through it, so there is no source edit and nothing to time by hand:

from crewai import Agent, Task
from crewai.tools import tool
from diagrid.agent.crewai import DaprWorkflowAgentRunner

@tool("Step 1 - Search venues")
def step_one_search(city: str) -> str:
    """Search for event venues in a city. This is the first step."""
    return f"Found 3 venues in {city}. Now call step_two___compare_venues."

@tool("Step 2 - Compare venues")
def step_two_compare(data: str) -> str:
    """Compare the venue options. This is the second step."""
    time.sleep(int(os.environ.get("CRASH_DELAY_SECONDS", "10")))  # the window the crash lands in
    return "Grand Ballroom is the best option. Now call step_three___confirm_booking."

@tool("Step 3 - Confirm booking")
def step_three_confirm(selection: str) -> str:
    """Confirm the venue booking. This is the third and final step."""
    return "Booking confirmed for Grand Ballroom. All steps complete!"

The DaprWorkflowAgentRunner wraps the standard CrewAI agent — each tool call becomes a durable Dapr workflow activity:

runner = DaprWorkflowAgentRunner(
    name="venue-scout",
    agent=agent,
    max_iterations=10,
)

The tool order is the design. step_one_search completes and Diagrid records its result before step_two_compare starts, so the crash lands between two known points and the restart can show that only the interrupted tool ran again. The app also exposes POST /crash/run, which takes the workflow instance ID you want the run to use and an optional kill_after_seconds telling the application when to kill itself.

tip

CrewAI gives you multi-agent crews and tool orchestration but has no built-in durability. The DaprWorkflowAgentRunner wraps your existing agent — no code changes needed — and Diagrid adds automatic failure detection, crash recovery, and multi-instance coordination.

Crash Recovery Demo — a 3-node graph that demonstrates how Diagrid recovers from a mid-execution crash.

Open crash_test.py. It defines a 3-node StateGraph whose middle node deliberately takes about 10 seconds. That delay is the window the crash lands in: the app kills itself partway through it, so there is no source edit and nothing to time by hand:

from langgraph.graph import StateGraph, START, END
from diagrid.agent.langgraph import DaprWorkflowGraphRunner

def check_venues(state: PlannerState) -> dict:
    result = "Grand Ballroom available on March 15 (2PM-6PM, 6PM-11PM)"
    return {"results": state["results"] + [result]}

def compare_options(state: PlannerState) -> dict:
    time.sleep(int(os.environ.get("CRASH_DELAY_SECONDS", "10")))  # the window the crash lands in
    result = "Grand Ballroom (6PM-11PM) is the best option for 200 guests"
    return {"results": state["results"] + [result]}

def confirm_booking(state: PlannerState) -> dict:
    result = "Booking confirmed: Grand Ballroom, March 15, 6PM-11PM"
    return {"results": state["results"] + [result]}

graph = StateGraph(PlannerState)
graph.add_node("check_venues", check_venues)
graph.add_node("compare_options", compare_options)
graph.add_node("confirm_booking", confirm_booking)
graph.add_edge(START, "check_venues")
graph.add_edge("check_venues", "compare_options")
graph.add_edge("compare_options", "confirm_booking")
graph.add_edge("confirm_booking", END)

The DaprWorkflowGraphRunner wraps the compiled graph — each node becomes a durable Dapr workflow activity:

runner = DaprWorkflowGraphRunner(
    graph=graph.compile(),
    name="schedule-planner",
)

The node order is the design. check_venues completes and Diagrid records its result before compare_options starts, so the crash lands between two known points and the restart can show that only the interrupted node ran again. The app also exposes POST /crash/run, which takes the workflow instance ID you want the run to use and an optional kill_after_seconds telling the application when to kill itself.

tip

LangGraph gives you graph-based orchestration with conditional routing but has no built-in durability. The DaprWorkflowGraphRunner wraps your compiled graph — no code changes needed — and Diagrid adds automatic failure detection, crash recovery, and multi-instance coordination.

Crash Recovery Demo — a 3-step pipeline that demonstrates how Diagrid recovers from a mid-execution crash.

from strands import Agent, tool
from strands.models.openai import OpenAIModel
from diagrid.agent.strands import DaprWorkflowAgentRunner

@tool
def step_one_calculate(items: str) -> str:
    """Calculate initial budget from cost items. This is the first step."""
    return "Estimated budget: $8,550. Now call step_two_analyze."

@tool
def step_two_analyze(data: str) -> str:
    """Analyze the budget for cost savings. This is the second step."""
    time.sleep(int(os.environ.get("CRASH_DELAY_SECONDS", "10")))  # the window the crash lands in
    return "Found $1,200 in potential savings. Now call step_three_finalize."

@tool
def step_three_finalize(analysis: str) -> str:
    """Finalize the budget report. This is the third and final step."""
    return "Final budget: $7,350 (saved $1,200). All steps complete!"

The DaprWorkflowAgentRunner wraps the standard Strands agent — each tool call becomes a durable Dapr workflow activity:

runner = DaprWorkflowAgentRunner(
    name="budget-planner",
    agent=agent,
    max_iterations=10,
)

The tool order is the design. step_one_calculate completes and Diagrid records its result before step_two_analyze starts, so the crash lands between two known points and the restart can show that only the interrupted tool ran again. The app also exposes POST /crash/run, which takes the workflow instance ID you want the run to use and an optional kill_after_seconds telling the application when to kill itself.

tip

Strands gives you a model-driven agent framework with tool use but has no built-in durability. The DaprWorkflowAgentRunner wraps your existing agent — no code changes needed — and Diagrid adds automatic failure detection, crash recovery, and multi-instance coordination.

Crash Recovery Demo — a 3-step pipeline that demonstrates how Diagrid recovers from a mid-execution crash.

from agents import Agent, function_tool
from diagrid.agent.openai_agents import DaprWorkflowAgentRunner

@function_tool
def step_one_search(cuisine: str) -> str:
    """Search for catering options. This is the first step."""
    return f"Found 3 {cuisine} catering options. Now call step_two_compare."

@function_tool
def step_two_compare(data: str) -> str:
    """Compare catering options. This is the second step."""
    time.sleep(int(os.environ.get("CRASH_DELAY_SECONDS", "10")))  # the window the crash lands in
    return "Farm Fresh Events is the best value. Now call step_three_confirm."

@function_tool
def step_three_confirm(selection: str) -> str:
    """Confirm the catering selection. This is the third and final step."""
    return "Catering confirmed with Farm Fresh Events. All steps complete!"

The DaprWorkflowAgentRunner wraps the standard OpenAI Agents agent — each tool call becomes a durable Dapr workflow activity:

runner = DaprWorkflowAgentRunner(
    name="catering-coordinator",
    agent=agent,
    max_iterations=10,
)

tip

The OpenAI Agents SDK gives you function tools and agent handoffs but has no built-in durability. The DaprWorkflowAgentRunner wraps your existing agent — no code changes needed — and Diagrid adds automatic failure detection, crash recovery, and multi-instance coordination.

Crash Recovery Demo — a 3-step pipeline that demonstrates how Diagrid recovers from a mid-execution crash.

from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
from google.adk.tools import FunctionTool
from diagrid.agent.adk import DaprWorkflowAgentRunner

def step_one_find(event_type: str) -> str:
    """Find entertainment options. This is the first step."""
    return f"Found 3 entertainment options for {event_type}. Now call step_two_compare."

def step_two_compare(data: str) -> str:
    """Compare entertainment options. This is the second step."""
    time.sleep(int(os.environ.get("CRASH_DELAY_SECONDS", "10")))  # the window the crash lands in
    return "Live Jazz Band is the best option. Now call step_three_confirm."

def step_three_confirm(selection: str) -> str:
    """Confirm the entertainment booking. This is the third and final step."""
    return "Entertainment confirmed with Live Jazz Band. All steps complete!"

The agent itself is a standard ADK LlmAgent. It reaches OpenAI through ADK's LiteLLM wrapper, which is why the whole tab runs on the OPENAI_API_KEY you set in step 4 and needs no Google credentials:

agent = LlmAgent(
    name="entertainment_planner",
    model=LiteLlm(model="openai/gpt-4o-mini"),
    tools=[
        FunctionTool(step_one_find),
        FunctionTool(step_two_compare),
        FunctionTool(step_three_confirm),
    ],
)

The DaprWorkflowAgentRunner wraps that agent — each tool call becomes a durable Dapr workflow activity:

runner = DaprWorkflowAgentRunner(
    name="entertainment-planner",
    agent=agent,
    max_iterations=10,
)

The tool order is the design. step_one_find completes and Diagrid records its result before step_two_compare starts, so the crash lands between two known points and the restart can show that only the interrupted tool ran again. The app also exposes POST /crash/run, which takes the workflow instance ID you want the run to use and an optional kill_after_seconds telling the application when to kill itself.

tip

Google ADK gives you a comprehensive agent development kit but has no built-in durability. The DaprWorkflowAgentRunner wraps your existing agent — no code changes needed — and Diagrid adds automatic failure detection, crash recovery, and multi-instance coordination.

Crash Recovery Demo — a 3-step pipeline that demonstrates how Diagrid recovers from a mid-execution crash.

from pydantic_ai import Agent
from diagrid.agent.pydantic_ai import DaprWorkflowAgentRunner

def step_one_search(theme: str) -> str:
    """Search for decoration packages. This is the first step."""
    return f"Found 3 decoration packages for {theme}. Now call step_two_compare."

def step_two_compare(data: str) -> str:
    """Compare decoration packages. This is the second step."""
    time.sleep(int(os.environ.get("CRASH_DELAY_SECONDS", "10")))  # the window the crash lands in
    return "Elegant Events Decor is the best value. Now call step_three_confirm."

def step_three_confirm(selection: str) -> str:
    """Confirm the decoration selection. This is the third and final step."""
    return "Decorations confirmed with Elegant Events Decor. All steps complete!"

The DaprWorkflowAgentRunner wraps the standard Pydantic AI agent — each tool call becomes a durable Dapr workflow activity:

runner = DaprWorkflowAgentRunner(
    name="decoration-planner",
    agent=agent,
    max_iterations=10,
)

tip

Pydantic AI gives you a type-safe agent framework with structured outputs but has no built-in durability. The DaprWorkflowAgentRunner wraps your existing agent — no code changes needed — and Diagrid adds automatic failure detection, crash recovery, and multi-instance coordination.

Crash Recovery Demo — a 3-tool agent pipeline that demonstrates how Diagrid recovers from a mid-execution crash.

Open Program.cs. It defines three tools that the agent calls in sequence. Tool 2 takes about 10 seconds, and that delay is the window the crash lands in: when a request sends kill_after_seconds, tool 2 arms a timer as it starts and the app kills itself at a known point inside its own delay.

using Dapr.Workflow;
using Diagrid.AI.Microsoft.AgentFramework.Abstractions;
using Diagrid.AI.Microsoft.AgentFramework.Catalyst;
using Diagrid.AI.Microsoft.AgentFramework.Hosting;
using Microsoft.Extensions.AI;
using OpenAI;

// How long step_two_compare takes. This is the window the crash lands in: three
// instantaneous tools would give you nothing to interrupt.
var delaySeconds = int.TryParse(Environment.GetEnvironmentVariable("CRASH_DELAY_SECONDS"), out var seconds)
    ? seconds
    : 10;

var tools = new List<AITool>
{
    AIFunctionFactory.Create((string city) =>
    {
        Console.WriteLine($">>> TOOL 1: Searching venues in '{city}'...");
        Console.WriteLine(">>> TOOL 1 COMPLETE: Found 3 venues");
        return $"Found 3 venues in {city}. Now call step_two_compare.";
    }, "step_one_search", "Search for event venues in a city. This is the first step."),

    AIFunctionFactory.Create(async (string data) =>
    {
        // Read AND clear in one step, so one recorded request arms exactly one execution.
        var armed = SelfKill.Consume();
        Console.WriteLine(armed > 0
            ? $">>> TOOL 2: Comparing venues over ~{delaySeconds}s, but this process kills itself"
                + $" {armed}s into the run, as asked by kill_after_seconds. It resumes on restart."
            : $">>> TOOL 2: Comparing venues over ~{delaySeconds}s. KILL THE APP NOW to"
                + " test crash recovery (POST /crash/kill, or kill -9). It resumes on restart.");
        if (armed > 0)
        {
            // Armed here, where tool 2 actually starts, and not at the request: this tool is a
            // durable activity, so it runs on a genuine first execution and not on an attach.
            SelfKill.Arm(armed);
        }
        await Task.Delay(TimeSpan.FromSeconds(delaySeconds));
        Console.WriteLine(">>> TOOL 2 COMPLETE: Grand Ballroom is the best option");
        return "Grand Ballroom is the best option. Now call step_three_confirm.";
    }, "step_two_compare", "Compare the venue options. This is the second step."),

    AIFunctionFactory.Create((string selection) =>
    {
        Console.WriteLine(">>> TOOL 3: Confirming booking...");
        Console.WriteLine(">>> TOOL 3 COMPLETE: Booking confirmed for Grand Ballroom");
        return "Booking confirmed for Grand Ballroom. All steps complete!";
    }, "step_three_confirm", "Confirm the venue booking. This is the third and final step."),
};

IDaprAgentInvoker wraps each agent invocation in a durable Dapr workflow. This demo registers a workflow of its own anyway, for one reason: RunAgentAsync mints the instance ID itself, so nothing outside the process could be told which execution to watch. Registering CrashRecoveryWorkflow is what lets the caller supply the ID:

builder.Services.AddDaprAgents(registrations: options =>
    {
        // Registering our own workflow is what gives the caller the instance ID.
        options.RegisterWorkflow<CrashRecoveryWorkflow>();
    })
    .WithAgent(sp =>
    {
        // Canned by default: this quickstart is about durable execution, not model quality, so
        // it ships an offline model and needs no account. Set DIAGRID_QUICKSTART_MODEL=openai
        // (and export OPENAI_API_KEY) for a real provider.
        IChatClient chatClient;
        if (string.Equals(
            Environment.GetEnvironmentVariable("DIAGRID_QUICKSTART_MODEL"),
            "openai",
            StringComparison.OrdinalIgnoreCase))
        {
            var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY");
            chatClient = new OpenAIClient(apiKey)
                .GetChatClient("gpt-4.1-2025-04-14")
                .AsIChatClient();
        }
        else
        {
            chatClient = new CannedChatClient();
        }

        return chatClient.AsAIAgent(
            instructions: """
                You are an event planner. Call all three tools in sequence:
                1. First call step_one_search with the city name
                2. Then call step_two_compare with the result from step 1
                3. Finally call step_three_confirm with the result from step 2
                Do NOT skip any steps.
                """,
            name: "event-planner",
            tools: tools);
    })
    .WithCatalyst(new DiagridCatalystOptions
    {
        Registry = new RegistryMetadata { ResourceName = "agent-registry" },
    });

app.MapPost("/run", async (IDaprAgentInvoker invoker, RunRequest req, CancellationToken ct) =>
{
    var agent = invoker.GetAgent("event-planner");
    var result = await invoker.RunAgentAsync(agent, req.Prompt, cancellationToken: ct);
    return Results.Ok(new { response = result.Text });
});

CrashRecoveryWorkflow is the whole of the durability code the app writes by hand. WorkflowContext.RunAgentAsync keeps the agent run itself durable: every model call and every tool call is still a separate activity, so a completed activity is not replayed after a crash.

public sealed class CrashRecoveryWorkflow : Workflow<string, string>
{
    public override async Task<string> RunAsync(WorkflowContext context, string prompt)
    {
        var agent = context.GetAgent("event-planner");
        var response = await context.RunAgentAsync(agent, prompt);
        return response.Text;
    }
}

tip

The Microsoft Agent Framework provides a familiar .NET dependency injection experience. The Diagrid.AI.Microsoft.AgentFramework package bridges Microsoft's agent abstractions with Dapr Workflows — Diagrid adds automatic failure detection, crash recovery, and multi-instance coordination.

Crash Recovery Demo — a 3-tool agent pipeline that demonstrates how Diagrid recovers from a mid-execution crash.

The app is plain Spring AI — a ChatClient and three @Tool beans. Open EventPlannerTools.java; the agent calls the tools in sequence and tool 2 deliberately crashes the process:

@Component
public class EventPlannerTools {

  @Tool(name = "step_one_search", description = "Search for event venues in a city. This is the first step.")
  public String stepOneSearch(@ToolParam(description = "the city to search in") String city) {
    LOG.info(">>> TOOL 1: Searching venues in '{}'...", city);
    return "Found 3 venues in " + city + ". Now call step_two_compare.";
  }

  @Tool(name = "step_two_compare", description = "Compare the venue options. This is the second step.")
  public String stepTwoCompare(@ToolParam(description = "the venues found in step one") String data) {
    LOG.info(">>> TOOL 2: Comparing venues...");
    Runtime.getRuntime().halt(1); // 💥 Simulates a crash (halt skips shutdown hooks)
    return "Grand Ballroom is the best option. Now call step_three_confirm.";
  }

  @Tool(name = "step_three_confirm", description = "Confirm the venue booking. This is the third and final step.")
  public String stepThreeConfirm(@ToolParam(description = "the selected venue") String selection) {
    LOG.info(">>> TOOL 3: Confirming booking...");
    return "Booking confirmed for Grand Ballroom. All steps complete!";
  }
}

There is no durability code in the app. Adding the diagrid-spring-ai-starter to the classpath is what makes every ChatClient.call() run as a durable Dapr workflow — the model turns and each @Tool call become checkpointed activities:

<dependency>
  <groupId>io.diagrid</groupId>
  <artifactId>diagrid-spring-ai-starter</artifactId>
  <version>0.4.0</version>
</dependency>

0.4.0 is the version this quickstart pins. For newer releases see Maven Central.

The agent is a ChatClient bean, built from the injected ChatClient.Builder so the durability advisor attaches automatically. Being a bean is also what registers it: the registry records one agent per ChatClient bean, named after the bean, which is why the @Bean name matches the diagrid agent create name from step 6. Open EventPlannerAgentConfig.java:

@Configuration
public class EventPlannerAgentConfig {

  private static final String SYSTEM = """
      You are an event planner. Call all three tools in sequence:
      1. First call step_one_search with the city name
      2. Then call step_two_compare with the result from step 1
      3. Finally call step_three_confirm with the result from step 2
      Do NOT skip any steps.""";

  @Bean("spring-ai-event-planner")
  ChatClient eventPlanner(ChatClient.Builder builder) {
    return builder.defaultSystem(SYSTEM).build();
  }
}

The controller is ordinary Spring AI — it injects the bean and calls it:

@RestController
public class EventPlannerController {

  private final ChatClient chatClient;

  public EventPlannerController(ChatClient chatClient) {
    this.chatClient = chatClient;
  }

  @PostMapping("/run")
  public RunResponse run(@RequestBody RunRequest request) {
    String response = chatClient.prompt().user(request.prompt()).call().content();
    return new RunResponse(response);
  }

  public record RunRequest(String prompt) {}

  public record RunResponse(String response) {}
}

tip

Spring AI gives you ChatClient, tool calling, and model abstractions but has no built-in durability. The diagrid-spring-ai-starter adds it with no code changes — just one dependency — and Diagrid adds automatic failure detection, crash recovery, and multi-instance coordination.

Crash Recovery Demo — a 3-step pipeline that demonstrates how Diagrid recovers from a mid-execution crash.

from langchain_core.tools import tool
from deepagents import create_deep_agent
from diagrid.agent.deepagents import DaprWorkflowDeepAgentRunner

@tool
def step_one_search(event_type: str) -> str:
    """Search for transportation options. This is the first step."""
    return f"Found 3 transportation options for {event_type}. Now call step_two_compare."

@tool
def step_two_compare(data: str) -> str:
    """Compare transportation options. This is the second step."""
    time.sleep(int(os.environ.get("CRASH_DELAY_SECONDS", "10")))  # the window the crash lands in
    return "Premier Shuttle Co. is the best value. Now call step_three_confirm."

@tool
def step_three_confirm(selection: str) -> str:
    """Confirm the transportation selection. This is the third and final step."""
    return "Transportation confirmed with Premier Shuttle Co. All steps complete!"

The DaprWorkflowDeepAgentRunner wraps the Deep Agent — each tool call becomes a durable Dapr workflow activity:

agent = create_deep_agent(
    model="openai:gpt-4o-mini",
    tools=[step_one_search, step_two_compare, step_three_confirm],
    system_prompt="Execute exactly three tools in sequence...",
    name="transportation-planner",
)

runner = DaprWorkflowDeepAgentRunner(
    agent=agent,
    name="transportation-planner",
    max_steps=10,
)

tip

LangChain Deep Agents gives you a LangChain-compatible agent framework with tool use but has no built-in durability. The DaprWorkflowDeepAgentRunner wraps your existing agent — no code changes needed — and Diagrid adds automatic failure detection, crash recovery, and multi-instance coordination.

Sub-Agent Orchestration — a supervisor agent coordinates two specialist sub-agents (Researcher and Analyst), each running as an independent durable Dapr workflow.

Durable multi-agent orchestrationThe supervisor delegates to each sub-agent over the Agent Protocol. Every agent is its own Dapr workflow, so each LLM call and tool call is a durable activity.

Open subagent_workflows.py. Each sub-agent has its own tools and runs as a separate DaprWorkflowDeepAgentRunner:

from deepagents import AsyncSubAgent, create_deep_agent
from langchain.agents import create_agent
from langchain_core.tools import tool
from diagrid.agent.deepagents import DaprWorkflowDeepAgentRunner

@tool
def search_web(query: str) -> str:
    """Search the web for information on a given topic."""
    return f"Found 3 sources on '{query}': ..."

def make_researcher():
    return create_agent(
        model="openai:gpt-4o-mini",
        tools=[search_web],
        system_prompt="You are a research agent...",
        name="researcher",
    )

The supervisor uses AsyncSubAgent to delegate to sub-agents over HTTP via the Agent Protocol:

def make_supervisor():
    return create_deep_agent(
        model="openai:gpt-4o-mini",
        subagents=[
            AsyncSubAgent(
                name="researcher",
                description="Research agent that searches the web...",
                graph_id="researcher",
                url="http://localhost:8001",
            ),
            AsyncSubAgent(
                name="analyst",
                description="Analyst agent that produces analysis reports...",
                graph_id="analyst",
                url="http://localhost:8002",
            ),
        ],
        system_prompt="You are a supervisor that orchestrates research and analysis...",
        name="supervisor",
    )

Each sub-agent is wrapped in DaprWorkflowDeepAgentRunner and exposed via an AgentProtocolAdapter — a thin FastAPI server implementing the Agent Protocol (HTTP). The supervisor communicates with sub-agents over HTTP, and each agent's workflow is independently durable.

tip

Each sub-agent runs as its own independent Dapr workflow. If any agent crashes, only that agent's workflow is affected — the supervisor and other sub-agents continue running. On restart, each agent resumes from its last checkpointed state.

Crash Recovery Demo — a 3-step pipeline that demonstrates how Diagrid recovers from a mid-execution crash.

import os

from claude_agent_sdk import ClaudeAgentOptions, tool
from diagrid.agent.claude_agents import DaprWorkflowAgentRunner

@tool("step_one_search", "Search for photography options. This is the first step.", {"event_type": str})
async def step_one_search(args):
    text = f"Found 3 {args['event_type']} photography options. Now call step_two_compare."
    return {"content": [{"type": "text", "text": text}]}

@tool("step_two_compare", "Compare photography options. This is the second step.", {"data": str})
async def step_two_compare(args):
    time.sleep(int(os.environ.get("CRASH_DELAY_SECONDS", "10")))  # the window the crash lands in
    return {"content": [{"type": "text", "text": "Candid Frames is the best value. Now call step_three_confirm."}]}

@tool("step_three_confirm", "Confirm the photography selection. This is the third and final step.", {"selection": str})
async def step_three_confirm(args):
    return {"content": [{"type": "text", "text": "Photography confirmed with Candid Frames. All steps complete!"}]}

The DaprWorkflowAgentRunner wraps a standard Claude Agent SDK setup — each LLM turn and each tool call becomes a durable Dapr workflow activity:

options = ClaudeAgentOptions(
    system_prompt="Execute exactly three tools in sequence...",
    model=os.environ.get("CLAUDE_MODEL", "claude-sonnet-4-6"),
)

runner = DaprWorkflowAgentRunner(
    name="photography-planner",
    options=options,
    tools=[step_one_search, step_two_compare, step_three_confirm],
    max_iterations=10,
)

tip

The Claude Agent SDK gives you tool-calling with Anthropic models but has no built-in durability. The DaprWorkflowAgentRunner wraps your tools — no code changes needed — and Diagrid adds automatic failure detection, crash recovery, and multi-instance coordination.

Durable Investigation — an SRE agent that investigates a cluster problem, parks on a tool call that needs human approval, and resumes after a full process restart.

The examples directory contains basic.py (a single investigation run), server.py (an HTTP server with streaming and approval endpoints), and phase_a_schedule_and_park.py / phase_b_resume_after_crash.py (the crash-and-resume test).

Open server.py. DaprWorkflowHolmesRunner wraps a standard HolmesGPT setup — HolmesGPT renders its own prompt, toolsets, and runbooks locally, while every reasoning step and tool call becomes a durable Dapr workflow activity:

from diagrid.agent.holmesgpt import DaprWorkflowHolmesRunner


def main() -> None:
    runner = DaprWorkflowHolmesRunner(
        name="sre-agent",
        max_steps=10,
    )
    runner.serve(port=5001)

runner.serve() exposes the investigation over HTTP, including an approval endpoint for tool calls that fall outside the default allow list.

tip

HolmesGPT gives you a mature SRE toolset — Kubernetes, logs, and observability queries — but an investigation is a long, multi-step loop with no built-in durability. Wrapping it in DaprWorkflowHolmesRunner means a paused approval or a crashed process doesn't lose the investigation: Diagrid replays the completed steps and continues.

Crash Recovery Demo — an SRE agent that looks up an incident's status, demonstrating how Diagrid recovers from a mid-turn crash.

Open crash_test.ts. It serves the agent over HTTP. The tool the agent calls, checkIncidentStatus, deliberately takes about 10 seconds. That delay is the window the crash lands in: the app kills itself partway through it, so there is no source edit and nothing to time by hand:

import { Agent } from '@mastra/core/agent';
import { createTool } from '@mastra/core/tools';
import { DaprWorkflowAgentRunner } from '@diagrid/agent-mastra';
import { z } from 'zod';

const checkIncidentStatus = createTool({
  id: 'checkIncidentStatus',
  description: 'Check the status of an ongoing incident by its incident ID.',
  inputSchema: z.object({ incidentId: z.string().describe('e.g. INC-4471') }),
  execute: async ({ incidentId }) => {
    const delay = Number(process.env['CRASH_DELAY_SECONDS'] ?? '10');
    await sleep(delay * 1000); // the window the crash lands in
    return {
      incidentId,
      status: 'mitigated, monitoring for recurrence',
      assignee: 'on-call SRE',
    };
  },
});

const agent = new Agent({
  id: 'sre-agent',
  name: 'sre-agent',
  instructions:
    'You look up incident statuses. Always use the checkIncidentStatus ' +
    'tool to answer, then report the status in one short sentence.',
  model: resolveModel(),
  tools: { checkIncidentStatus },
});

The DaprWorkflowAgentRunner wraps the standard Mastra agent — each model call and each tool call becomes its own durable Dapr workflow activity:

const runner = new DaprWorkflowAgentRunner({
  agent,
  name: 'sre-agent',
  maxIterations: 10,
});

The tool order is the design. Model call 1 completes and Diagrid records its result before checkIncidentStatus starts, so the crash lands between two known points and the restart can show that only the interrupted step ran again. The app also exposes POST /crash/run, which takes the workflow instance ID you want the run to use and an optional kill_after_seconds telling the application when to kill itself. POST /crash/kill kills the process on demand, if you would rather aim the crash yourself.

tip

Mastra gives you agents, tool calling, and model routing but has no built-in durability. The DaprWorkflowAgentRunner wraps your existing agent — no code changes needed — and Diagrid adds automatic failure detection, crash recovery, and multi-instance coordination.

4. Configure API Key

This quickstart uses OpenAI as the LLM provider for every framework except the Claude Agents tab, which uses Anthropic. Diagrid is LLM-agnostic — you're free to use any provider supported by your chosen framework. The LangGraph, Microsoft Agent Framework and Spring AI tabs need no key at all: LangGraph's crash-test app makes no model call, and the other two ship a deterministic offline model you can swap for a real provider with DIAGRID_QUICKSTART_MODEL=openai.

The LLM is configured via DaprChatClient(component_name="llm-provider") — a Dapr component in resources/llm-provider.yaml that references your OpenAI API key:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: llm-provider
spec:
  type: conversation.openai
  version: v1
  metadata:
  - name: key
    value: "{{OPENAI_API_KEY}}"
  - name: model
    value: gpt-4.1-2025-04-14

Update the key value with your OpenAI API key.

macOS/Linux
Windows

export OPENAI_API_KEY="your-key-here"

$env:OPENAI_API_KEY = "your-key-here"

No API key needed. This tab runs crash_test.py, a 3-node graph with no model call in it at all, so there is nothing to configure here. Skip to the next step.

macOS/Linux
Windows

export OPENAI_API_KEY="your-key-here"

$env:OPENAI_API_KEY = "your-key-here"

macOS/Linux
Windows

export OPENAI_API_KEY="your-key-here"

$env:OPENAI_API_KEY = "your-key-here"

macOS/Linux
Windows

export OPENAI_API_KEY="your-key-here"

$env:OPENAI_API_KEY = "your-key-here"

macOS/Linux
Windows

export OPENAI_API_KEY="your-key-here"

$env:OPENAI_API_KEY = "your-key-here"

This tab needs no API key. The app ships an offline model (CannedChatClient) that calls the three tools in the order the demo needs, so the crash and the recovery are the only moving parts. The app logs which model it is using at startup: >>> Using the canned offline model for this one, >>> Using OpenAI for a real provider. To run against OpenAI instead, set both variables:

macOS/Linux
Windows

export DIAGRID_QUICKSTART_MODEL="openai"
export OPENAI_API_KEY="your-key-here"

$env:DIAGRID_QUICKSTART_MODEL = "openai"
$env:OPENAI_API_KEY = "your-key-here"

This tab needs no API key. The app ships an offline model (CannedChatModel) that calls the three tools in order, so the crash and the recovery are the only moving parts. It announces itself in the startup log, so no such line means the app is talking to a real provider. To run against OpenAI instead, set both variables:

macOS/Linux
Windows

export DIAGRID_QUICKSTART_MODEL="openai"
export OPENAI_API_KEY="your-key-here"

$env:DIAGRID_QUICKSTART_MODEL = "openai"
$env:OPENAI_API_KEY = "your-key-here"

On that path a missing or wrong key no longer stops the app from starting. The provider rejects the first request instead, and because the model call is a durable activity that failure is retried a few times before it surfaces.

macOS/Linux
Windows

export OPENAI_API_KEY="your-key-here"

$env:OPENAI_API_KEY = "your-key-here"

macOS/Linux
Windows

export OPENAI_API_KEY="your-key-here"

$env:OPENAI_API_KEY = "your-key-here"

macOS/Linux
Windows

export ANTHROPIC_API_KEY="your-key-here"

$env:ANTHROPIC_API_KEY = "your-key-here"

HolmesGPT resolves its LLM through LiteLLM. server.py needs only a provider key; the phase_a/phase_b scripts also read an explicit MODEL, so export both:

macOS/Linux
Windows

export OPENAI_API_KEY="your-key-here"
export MODEL="gpt-4.1-2025-04-14"

$env:OPENAI_API_KEY = "your-key-here"
$env:MODEL="gpt-4.1-2025-04-14"

macOS/Linux
Windows

export OPENAI_API_KEY="your-key-here"

$env:OPENAI_API_KEY = "your-key-here"

To run against a local Ollama model instead — no API key needed:

ollama serve &
ollama pull qwen3:0.6b
export OLLAMA_ENDPOINT="http://localhost:11434/v1"
export OLLAMA_MODEL="qwen3:0.6b"   # optional, this is the default

5. Install Dependencies

uv sync

uv sync

uv sync

uv sync

uv sync

uv sync

uv sync

dotnet build

mvn package -DskipTests

uv sync

uv sync

uv sync

python -m venv .venv
source .venv/bin/activate
pip install "diagrid[holmesgpt]"

caution

Install HolmesGPT in its own virtual environment. It ships strict dependency pins that conflict with the other agent extras, which is why it is not part of diagrid[all].

npm install