Developing AI with Dapr

• 1: Agent Integrations
• 1.1: CrewAI
• 1.1.1: CrewAI Workflows
• 1.2: LangGraph
• 1.2.1: Agent Sessions
• 1.3: OpenAI
• 1.3.1: Agent Sessions
• 1.4: Tuning Engines
• 2: Dapr Agents
• 2.1: Introduction
• 2.2: Getting Started
• 2.3: Why Dapr Agents
• 2.4: Core Concepts
• 2.5: Agentic Patterns
• 2.6: Extensions and Activation Hooks
• 2.7: Hooks and Human-in-the-Loop
• 2.8: Integrations
• 2.9: Quickstarts
• 3: MCP
• 3.1: MCP through Dapr service invocation
• 3.2: Authenticating an MCP server
• 3.3: MCP access control
• 3.4: MCP security and trust posture
• 3.5: MCPServer resource
• 3.6: How-To: Use MCPServer resources

1 - Agent Integrations

What are agent integrations in Dapr?

Dapr augments and enhances other agentic frameworks by providing them with key critical features for running in production:

• Durable execution using Dapr Workflows for resilient and long-running AI tasks
• Portable agent context & memory using Dapr’s State Management API
• Reliable and secure agent-to-agent communication using Dapr Pub/Sub and Service Invocation
• Secure agent identity

With Dapr, developers writing AI systems using the framework of their choice enjoy accelerated development via the Dapr APIs and gain confidence taking agentic systems into production.

1.1 - CrewAI

What is the Dapr CrewAI integration?

Dapr provides CrewAI agents first class integrations that range from agent session management to connecting agents via pub/sub and orchestrating agentic workflows.

1.1.1 - CrewAI Workflows

Overview

Dapr Workflows make it possible to run CrewAI agents reliably, durably, and with built-in resiliency.
By orchestrating CrewAI tasks with the Dapr Workflow engine, developers can:

• Ensure long-running CrewAI work survives crashes and restarts.
• Get automatic checkpoints, retries, and state recovery.
• Run each CrewAI task as a durable activity.
• Observe execution through tracing, metrics, and structured logs.

This guide walks through orchestrating multiple CrewAI tasks using Dapr Workflows, ensuring each step is run exactly once even if the process restarts.

Getting Started

Initialize Dapr locally to set up a self-hosted environment for development. This process installs the Dapr sidecar binaries, provisions the workflow engine, and prepares a default components directory. For full details, see guide on initializing Dapr locally.

Initialize Dapr:

dapr init

Verify that daprio/dapr, openzipkin/zipkin, and redis are running:

docker ps

Install Python

Create a Python Virtual Environment (recommended)

python -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate

Install Dependencies

pip install dapr dapr-ext-workflow crewai

Create a Workflow to Run CrewAI Tasks

Create a file named crewai_workflow.py and paste the following:

from dapr.ext.workflow import (
    WorkflowRuntime,
    DaprWorkflowContext,
    WorkflowActivityContext,
    DaprWorkflowClient,
)
from crewai import Agent, Task, Crew
import time

wfr = WorkflowRuntime()

# ------------------------------------------------------------
# 1. Define Agent, Tasks, and Task Dictionary
# ------------------------------------------------------------
agent = Agent(
    role="Research Analyst",
    goal="Research and summarize impactful technology updates.",
    backstory="A skilled analyst who specializes in researching and summarizing technology topics.",
)

tasks = {
    "latest_ai_news": Task(
        description="Find the latest news about artificial intelligence.",
        expected_output="A 3-paragraph summary of the top 3 stories.",
        agent=agent,
    ),
    "ai_startup_launches": Task(
        description="Summarize the most impactful AI startup launches in the last 6 months.",
        expected_output="A list summarizing 2 AI startups with links.",
        agent=agent,
    ),
    "ai_policy_updates": Task(
        description="Summarize the newest AI government policy and regulation updates.",
        expected_output="A bullet-point list summarizing the latest policy changes.",
        agent=agent,
    ),
}

# ------------------------------------------------------------
# 2. Activity — runs ONE task by name
# ------------------------------------------------------------
@wfr.activity(name="run_task")
def run_task_activity(ctx: WorkflowActivityContext, task_name: str):
    print(f"Running CrewAI task: {task_name}", flush=True)

    task = tasks[task_name]

    # Create a Crew for just this one task
    temp_crew = Crew(agents=[agent], tasks=[task])

    # kickoff() works across CrewAI versions
    result = temp_crew.kickoff()

    return str(result)

# ------------------------------------------------------------
# 3. Workflow — orchestrates tasks durably
# ------------------------------------------------------------
@wfr.workflow(name="crewai_multi_task_workflow")
def crewai_workflow(ctx: DaprWorkflowContext):
    print("Starting multi-task CrewAI workflow", flush=True)

    latest_news = yield ctx.call_activity(run_task_activity, input="latest_ai_news")
    startup_summary = yield ctx.call_activity(run_task_activity, input="ai_startup_launches")
    policy_updates = yield ctx.call_activity(run_task_activity, input="ai_policy_updates")

    return {
        "latest_news": latest_news,
        "startup_summary": startup_summary,
        "policy_updates": policy_updates,
    }

# ------------------------------------------------------------
# 4. Runtime + Client (entry point)
# ------------------------------------------------------------
if __name__ == "__main__":
    wfr.start()

    client = DaprWorkflowClient()
    instance_id = "crewai-multi-01"

    client.schedule_new_workflow(
        workflow=crewai_workflow,
        input=None,
        instance_id=instance_id
    )

    state = client.wait_for_workflow_completion(instance_id, timeout_in_seconds=60)
    print(state.serialized_output)

This CrewAI agent starts a workflow that does news gathering and summary for the subjects of AI and startups.

Create the Workflow Database Component

Dapr Workflows persist durable state using any Dapr state store that supports workflows. Create a directory named components, then create the file workflowstore.yaml:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: workflowstore
spec:
  type: state.redis
  version: v1
  metadata:
  - name: redisHost
    value: localhost:6379
  - name: redisPassword
    value: ""
  - name: actorStateStore
    value: "true"

This component stores:

• Code execution checkpoints
• Execution history
• Deterministic resumption state
• Final output data

Set a CrewAI LLM Provider

CrewAI needs an LLM configuration or token to run. See instructions here.

For example, to set up OpenAI:

export OPENAI_API_KEY=sk-...

Run the Workflow

Launch the CrewAI workflow using the Dapr CLI:

dapr run \
  --app-id crewaiwf \
  --dapr-grpc-port 50001 \
  --resources-path ./components \
  -- python3 ./crewai_workflow.py

As the workflow runs, each CrewAI task is executed as a durable activity. If the process crashes, the workflow resumes exactly where it left off. You can try this by killing the process after the first activity and then rerunning that command line above with the same app ID.

Open Zipkin to view workflow traces:

http://localhost:9411

1.2 - LangGraph

What is the Dapr LangGraph integration?

Dapr provides LangGraph agents a first class integration to agent session management (checkpointers).

1.2.1 - Agent Sessions

Overview

The Dapr Python SDK provides integration with LangGraph Checkpointer using the dapr-ext-langgraph extension.

Getting Started

Initialize Dapr locally to set up a self-hosted environment for development. This process fetches and installs the Dapr sidecar binaries, runs essential services as Docker containers, and prepares a default components folder for your application. For detailed steps, see the official guide on initializing Dapr locally.

To initialize the Dapr control plane containers and create a default configuration file, run:

dapr init

Verify you have container instances with daprio/dapr, openzipkin/zipkin, and redis images running:

docker ps

Install Python

Download Dependencies

Download and install the Dapr LangGraph extension with:

• Stable
• Development

pip install dapr-ext-langgraph langchain_openai langchain_core langgraph langgraph-prebuilt

The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK extension before installing the <code>dapr-dev</code> package.

pip install dapr-ext-langgraph-dev langchain_openai langchain_core langgraph langgraph-prebuilt

Create a LangGraph Agent

To let Dapr handle the agent memory, utilize the DaprCheckpointer as the checkpointer object when compiling the graph. Pass the checkpointer just like any other checkpointer provider:

from dapr.ext.langgraph import DaprCheckpointer
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage
from langgraph.graph import START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode, tools_condition


def add(a: int, b: int) -> int:
    """Adds a and b.

    Args:
        a: first int
        b: second int
    """
    return a + b

tools = [add]
llm = ChatOpenAI(model="gpt-4o")
llm_with_tools = llm.bind_tools(tools)

sys_msg = SystemMessage(
    content='You are a helpful assistant tasked with performing arithmetic on a set of inputs.'
)

def assistant(state: MessagesState):
    return {'messages': [llm_with_tools.invoke([sys_msg] + state['messages'])]}

builder = StateGraph(MessagesState)
builder.add_node('assistant', assistant)
builder.add_node('tools', ToolNode(tools))
builder.add_edge(START, 'assistant')
builder.add_conditional_edges(
    'assistant',
    tools_condition,
)
builder.add_edge('tools', 'assistant')

memory = DaprCheckpointer(store_name='statestore', key_prefix='dapr')
react_graph_memory = builder.compile(checkpointer=memory)

config = {'configurable': {'thread_id': '1'}}

messages = [HumanMessage(content='Add 3 and 4.')]
messages = react_graph_memory.invoke({'messages': messages}, config)
for m in messages['messages']:
    m.pretty_print()

Set an OpenAI API key

export OPENAI_API_KEY=sk-...

Create a Python venv

python -m venv .venv                                                                                                                                                                      
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Create the database component

The component file is how Dapr connects to your databae. The full list of supported databases can be found here. Create a components directory and this file in it:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: statestore
spec:
  type: state.redis
  version: v1
  metadata:
  - name: redisHost
    value: localhost:6379
  - name: redisPassword
    value: ""

Next Steps

Now that you have a LangGraph agent using Dapr to manage the agent sessions, explore more you can do with the State API and how to enable resiliency policies for enhanced reliability.

1.3 - OpenAI

What is the Dapr OpenAI Agents integration?

Dapr provides OpenAI agents first class integrations that range from agent session management to connecting agents via pub/sub and orchestrating agentic workflows. The Dapr OpenAI integration is an extension in the OpenAI Python SDK that developers can use to augment OpenAI agents with the various Dapr APIs.

1.3.1 - Agent Sessions

Overview

By using Dapr to manage the state and session data for OpenAI agents, users can store agent state in all databases supported by Dapr, including key/value stores, caches and SQL databases. Developers also get built-in tracing, metrics and resiliency policies that make agent session data operate reliably in production.

Getting Started

Initialize Dapr locally to set up a self-hosted environment for development. This process fetches and installs the Dapr sidecar binaries, runs essential services as Docker containers, and prepares a default components folder for your application. For detailed steps, see the official guide on initializing Dapr locally.

To initialize the Dapr control plane containers and create a default configuration file, run:

dapr init

Verify you have container instances with daprio/dapr, openzipkin/zipkin, and redis images running:

docker ps

Install Python

Install Dependencies

pip install openai-agents dapr

Create an OpenAI Agent

Let’s create a simple OpenAI agent. Put the following in a file named openai_agent.py:

import asyncio
from agents import Agent, Runner
from agents.extensions.memory.dapr_session import DaprSession

async def main():
    agent = Agent(
        name="Assistant",
        instructions="Reply very concisely.",
    )

    session = DaprSession.from_address(
        session_id="123",
        state_store_name="statestore"
    )

    result = await Runner.run(agent, "What city is the Golden Gate Bridge in?", session=session)
    print(result.final_output)

    result = await Runner.run(agent, "What state is it in?", session=session)
    print(result.final_output)

    result = await Runner.run(agent, "What's the population?", session=session)
    print(result.final_output)

asyncio.run(main())

Set an OpenAI API key

export OPENAI_API_KEY=sk-...

Create a Python venv

python -m venv .venv                                                                                                                                                                      
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Create the database component

The component file is how Dapr connects to your databae. The full list of supported databases can be found here. Create a components directory and this file in it:

statestore.yaml:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: statestore
spec:
  type: state.redis
  version: v1
  metadata:
  - name: redisHost
    value: localhost:6379
  - name: redisPassword
    value: ""

Run The Agent

Now run the local Dapr process and your Python script using the Dapr CLI.

dapr run --app-id openaisessions --dapr-grpc-port 50001 --resources-path ./components -- python3 ./openai_agent.py

Open http://localhost:9411 to view your the traces and dependency graph.

You can see the session data stored in Redis with the following command

hgetall "123:messages" 

Next Steps

Now that you have an OpenAI agent using Dapr to manage the agent sessions, explore more you can do with the State API and how to enable resiliency policies for enhanced reliability.

Read more about OpenAI agent sessions and Dapr here.

1.4 - Tuning Engines

What is the Dapr Tuning Engines integration pattern?

Dapr Workflow owns durable execution, retries, service invocation, pub/sub, and sidecar-based application integration. Tuning Engines can sit behind workflow activities as an OpenAI-compatible AI endpoint that provides model routing, policy checks, approvals, usage attribution, and runtime traces.

Use this pattern when a Dapr application needs governed model calls without embedding provider-specific credentials or policy logic in every workflow.

Configuration

Set a Tuning Engines inference key and choose the model or routing alias your tenant has enabled:

export TE_INFERENCE_KEY=sk-te-your-inference-key
export TE_MODEL=auto

Activity example

import { WorkflowRuntime } from "@dapr/dapr";

type Input = {
  prompt: string;
  run_id: string;
};

function newId(prefix: string): string {
  return `${prefix}_${crypto.randomUUID().replaceAll("-", "")}`;
}

async function governedModelActivity(_ctx: unknown, input: Input) {
  const request_id = newId("req");
  const response = await fetch("https://api.tuningengines.com/v1/chat/completions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TE_INFERENCE_KEY}`,
      "Content-Type": "application/json",
      "X-TE-Run-ID": input.run_id,
      "X-TE-Request-ID": request_id,
    },
    body: JSON.stringify({
      model: process.env.TE_MODEL || "auto",
      messages: [{ role: "user", content: input.prompt }],
      metadata: {
        run_id: input.run_id,
        request_id,
        runtime: "dapr",
        event_type: "model.call",
      },
    }),
  });

  if (!response.ok) {
    throw new Error(`Tuning Engines request failed: ${response.status} ${await response.text()}`);
  }

  return response.json();
}

const runtime = new WorkflowRuntime();
runtime.registerActivityWithName("governedModelActivity", governedModelActivity);

The run_id and request_id metadata let Tuning Engines correlate the model call with policy decisions, approval requests, usage/cost logs, and trace events. Dapr continues to own the workflow state and the activity lifecycle.

2 - Dapr Agents

What is Dapr Agents?

Dapr Agents is a Python framework for building LLM-powered autonomous agentic applications using Dapr’s distributed systems capabilities. It provides tools for creating AI agents that can execute durable tasks, make decisions, and collaborate through workflows, while leveraging Dapr’s state management, messaging, and observability features for reliable execution at scale.

2.1 - Introduction

Dapr Agents is a developer framework for building durable and resilient AI agent systems powered by Large Language Models (LLMs). Built on the battle-tested Dapr project, it enables developers to create autonomous systems that have identity, reason through problems, make dynamic decisions, and collaborate seamlessly. It includes built-in observability and stateful workflow execution to ensure agentic workflows complete successfully, regardless of complexity. Whether you’re developing single-agent applications or complex multi-agent workflows, Dapr Agents provides the infrastructure for intelligent, adaptive systems that scale across environments.

Core Capabilities

• Agent Identity: With Dapr Agents, each agent is assigned a unique cryptographic identity that is used to authenticate agent interactions and enforce authorization across services and infrastructure.
• Durable Execution: Agents created with Dapr Agents are backed by Dapr’s workflow engine, which persists every agent interaction with LLMs and tools into a durable state store that can recover and continue execution even after the agent restarts.
• Resilience: Dapr Agents can recover from transient failures with automatic retry policies, timeouts, and circuit breakers, and can also apply durable retries backed by workflow state to recover from longer-lasting failures.
• Scale and Efficiency: Run thousands of agents efficiently on a single core. Dapr distributes single and multi-agent apps transparently across fleets of machines and handles their lifecycle.
• Data-Driven Agents: Directly integrate with databases, documents, and unstructured data by connecting to dozens of different data sources.
• Multi-Agent Systems: Secure and observable by default, enabling collaboration between agents.
• Kubernetes-Native: Easily deploy and manage agents in Kubernetes environments.
• Platform-Ready: Access scopes and declarative resources enable platform teams to integrate Dapr Agents into their systems.
• Vendor-Neutral & Open Source: Avoid vendor lock-in and gain flexibility across cloud and on-premises deployments.

Key Features

Dapr Agents provides specialized modules designed for creating intelligent, autonomous systems. Each module is designed to work independently, allowing you to use any combination that fits your application needs.

Agentic Patterns

Dapr Agents enables a comprehensive set of patterns that represent different approaches to building intelligent systems.

These patterns range from deterministic, workflow-driven designs to fully autonomous agents capable of dynamic planning and execution; each addresses different use cases and balances predictability against autonomy.

Developer Experience

Dapr Agents is a Python framework built on top of the Python Dapr SDK, providing a comprehensive development experience for building agentic systems.

Getting Started

Get started with Dapr Agents by following the instructions on the Getting Started page.

Framework integrations

Dapr Agents integrates with popular Python frameworks and tools. For detailed integration guides and examples, see the integrations page.

Operational support

Dapr Agents inherits Dapr’s enterprise-grade operational capabilities, providing comprehensive support for durable and reliable deployments of agentic systems.

Built-in Operational Features

• Observability - Distributed tracing, metrics collection, and logging for agent interactions and workflow execution
• Security - mTLS encryption, access control, and secrets management for secure agent communication
• Resiliency - Automatic retries, circuit breakers, and timeout policies for fault-tolerant agent operations
• Infrastructure Abstraction - Dapr components abstract LLM providers, memory stores, storage and messaging backends, enabling seamless transitions between different environments

These capabilities enable teams to monitor agent performance, secure multi-agent communications, and ensure reliable execution of complex agentic workflows.

Contributing

Whether you’re interested in enhancing the framework, adding new integrations, or improving documentation, we welcome contributions from the community.

For development setup and guidelines, see our Contributor Guide.

2.2 - Getting Started

Install Dapr CLI

While simple examples in Dapr Agents can be used without the sidecar, the recommended mode is with the Dapr sidecar. To benefit from the full power of Dapr Agents, install the Dapr CLI for running Dapr locally or on Kubernetes for development purposes. For a complete step-by-step guide, follow the Dapr CLI installation page.

Verify the CLI is installed by restarting your terminal/command prompt and running the following:

dapr -h

Initialize Dapr in Local Mode

Initialize Dapr locally to set up a self-hosted environment for development. This process fetches and installs the Dapr sidecar binaries, runs essential services as Docker containers, and prepares a default components folder for your application. For detailed steps, see the official guide on initializing Dapr locally.

To initialize the Dapr control plane containers and create a default configuration file, run:

dapr init

Verify you have container instances with daprio/dapr, openzipkin/zipkin, and redis images running:

docker ps

Install Python

Install uv

The Dapr Agents quickstarts use uv as the Python package manager. Install it by following the uv installation guide.

Configure an LLM

The quickstarts use Ollama by default so you can run everything locally without an API key.

Default: Ollama (Local)

1. Install and start Ollama:

• Linux
• macOS
• Windows

curl -fsSL https://ollama.com/install.sh | sh

brew install ollama

2. Pull a model with tool-calling support:

ollama serve    # Start the server (skip if already running)
ollama pull qwen3:0.6b

3. Export the required environment variables before running any quickstart:

• Linux/macOS
• Windows (PowerShell)

export OLLAMA_ENDPOINT=http://localhost:11434/v1
export OLLAMA_MODEL=qwen3:0.6b

$env:OLLAMA_ENDPOINT = "http://localhost:11434/v1"
$env:OLLAMA_MODEL = "qwen3:0.6b"

The resources/llm-provider.yaml component resolves {{OLLAMA_ENDPOINT}} and {{OLLAMA_MODEL}} from your environment automatically.

Alternative: OpenAI

To use OpenAI instead, replace resources/llm-provider.yaml with:

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-4o-mini"

Dapr also supports Anthropic, Mistral, and other providers through the Conversation API. Replace the component type and metadata while keeping name: llm-provider.

Prepare your environment

In this getting started guide, you’ll work directly from the Dapr Agents quickstarts. You’ll focus on 03_durable_agent_http.py—a reliable durable agent backed by Dapr’s workflow engine and exposed over HTTP.

1. Clone the repository

git clone https://github.com/dapr/dapr-agents.git
cd dapr-agents/quickstarts

2. Create a virtual environment and install dependencies

From the quickstarts folder:

uv venv

# Activate the virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
uv sync --active

This installs dapr-agents and any additional libraries needed by the examples.

Understand the application

This example creates an agent that assists with weather information and uses Dapr to handle LLM interactions, persist conversation history, and provide reliable, durable execution of the agent’s steps.

For this quickstart you’ll primarily work with:

• 03_durable_agent_http.py – the main durable weather agent application exposed over HTTP
• function_tools.py – contains slow_weather_func, the tool used by the agent
• resources/llm-provider.yaml – Conversation API and LLM configuration
• resources/agent-memory.yaml – conversation memory state store
• resources/agent-workflow.yaml – workflow and durable execution state store

Open 03_durable_agent_http.py:

from dapr_agents.llm import DaprChatClient

from dapr_agents import DurableAgent
from dapr_agents.agents.configs import AgentMemoryConfig, AgentStateConfig
from dapr_agents.memory import ConversationDaprStateMemory
from dapr_agents.storage.daprstores.stateservice import StateStoreService
from dapr_agents.workflow.runners import AgentRunner
from function_tools import slow_weather_func


def main() -> None:
    weather_agent = DurableAgent(
        name="WeatherAgent",
        role="Weather Assistant",
        instructions=["Help users with weather information"],
        tools=[slow_weather_func],
        # Configure this agent to use Dapr Conversation API.
        llm=DaprChatClient(component_name="llm-provider"),
        # Configure the agent to use Dapr State Store for conversation history.
        memory=AgentMemoryConfig(
            store=ConversationDaprStateMemory(
                store_name="agent-memory",
            )
        ),
        # This is where the execution state is stored
        state=AgentStateConfig(
            store=StateStoreService(store_name="agent-workflow"),
        ),
    )

    runner = AgentRunner()
    try:
        runner.serve(weather_agent, port=8001)
    finally:
        runner.shutdown()


if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\nInterrupted by user. Exiting gracefully...")

This single file is the full application and shows how to create a production-style durable agent with Dapr:

• DurableAgent wraps the LLM and tools in a workflow-backed execution model. Each step of reasoning and tool calls is persisted.
• slow_weather_func (from function_tools.py) represents a slow external call, allowing you to observe how durable workflows resume after interruptions.
• AgentRunner exposes the agent over HTTP on port 8001, so other services (or curl) can start and query durable tasks.

The sections below break down the key configuration areas and show how each Python configuration maps to a Dapr component.

LLM calls via Dapr Conversation API

In the agent definition:

llm=DaprChatClient(component_name="llm-provider"),

This uses Dapr Conversation API via the llm-provider component. The corresponding Dapr component is defined in resources/llm-provider.yaml:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: llm-provider
spec:
  type: conversation.openai
  version: v1
  metadata:
  - name: key
    value: "ollama"
  - name: model
    value: "{{OLLAMA_MODEL}}"
  - name: endpoint
    value: "{{OLLAMA_ENDPOINT}}"

• The conversation.openai component type is used for the Ollama-compatible OpenAI API.
• key is set to "ollama" for local Ollama inference; replace with a real API key when using a cloud provider.
• model and endpoint are resolved from environment variables at runtime.

With this setup, you can swap models or providers by editing the component YAML without changing the agent code.

Conversation memory with a Dapr state store

In the agent definition, conversation memory is configured as:

memory=AgentMemoryConfig(
  store=ConversationDaprStateMemory(
      store_name="agent-memory",
  )
),

This tells the agent to store conversation history in the agent-memory Dapr state store. The matching Dapr component is resources/agent-memory.yaml:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: agent-memory
spec:
  type: state.redis
  version: v1
  metadata:
    - name: redisHost
      value: localhost:6379
    - name: redisPassword
      value: ""

• The state store uses Redis to persist conversation turns.
• The agent reads and writes messages here so the LLM can maintain context across multiple HTTP calls.

You can browse this state later (for example, with Redis Insight) to see how conversation history is stored.

Durable execution state with a workflow state store

The agent’s durable execution state is configured as:

state=AgentStateConfig(
  store=StateStoreService(store_name="agent-workflow"),
),

This uses the agent-workflow Dapr state store. The corresponding component is resources/agent-workflow.yaml:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: agent-workflow
spec:
  type: state.redis
  version: v1
  metadata:
  - name: redisHost
    value: localhost:6379
  - name: redisPassword
    value: ""
  - name: actorStateStore
    value: "true"

• actorStateStore: "true" is a required setting that enables storage suitable for Dapr Workflows.
• If the process stops mid-execution, the workflow engine uses this state to resume from the last persisted step instead of starting over. This prevents complex agent workflows from re-executing LLM and tool calls that already completed.

Together, these features make the agent durable, reliable, and provider-agnostic, while keeping the agent code itself focused on behavior and tools.

Run the durable agent with Dapr

From the quickstarts folder, with your virtual environment activated:

uv run dapr run --app-id durable-agent --resources-path resources -- python 03_durable_agent_http.py

This:

• Starts a Dapr sidecar using the components in resources/.
• Runs 03_durable_agent_http.py with the durable WeatherAgent.
• Exposes the agent’s HTTP API on port 8001.

Trigger the agent with a prompt

In a separate terminal, ask the agent about the weather.

curl -i -X POST http://localhost:8001/agent/run \
  -H "Content-Type: application/json" \
  -d '{"task": "What is the weather in London?"}'

The response includes a WORKFLOW_ID that represents the workflow execution.

Query the workflow status or result

Use the WORKFLOW_ID from the POST response to query progress or final result:

curl -i -X GET http://localhost:8001/agent/instances/WORKFLOW_ID

Replace WORKFLOW_ID with the value you received from the POST request.

Expected behavior

• The agent exposes a REST endpoint at /agent/run.

• A POST to /agent/run accepts a prompt, schedules a workflow execution, and returns a workflow ID.

• You can GET /agent/instances/{WORKFLOW_ID} at any time (even after stopping and restarting the agent) to check status or retrieve the final answer.

• The workflow orchestrates:

  • An LLM call to interpret the task and decide if a tool is needed.
  • A tool call (using slow_weather_func) to fetch the weather data.
  • A final LLM step that incorporates the tool result into the response.

• Every step is durably persisted, so no LLM or tool call is repeated unless it fails.

Test durability by interrupting the agent

To see durable execution in action:

1. Start a run Send the POST request to /agent/run as shown above and note the WORKFLOW_ID.

2. Kill the agent process While the request is being processed (during slow_weather_func, which is intentionally delayed 5 seconds), stop the agent process:

   • Go to the terminal running uv run dapr run ....
   • Press Ctrl+C to stop the app and sidecar.

3. Restart the agent Start it again with the same command:

   uv run dapr run --app-id durable-agent --resources-path resources -- python 03_durable_agent_http.py

4. Query the same workflow In the other terminal, query the same workflow ID:

   curl -i -X GET http://localhost:8001/agent/instances/WORKFLOW_ID
   

You’ll see that the workflow continues from its last persisted step instead of starting over. The tool call or LLM calls are not re-executed unless required, and you do not need to send a new prompt. Once the workflow completes, the GET request returns the final result.

In summary, the Dapr Workflow engine preserves the execution state of the agent across restarts, enabling reliable long-running interactions that combine LLM calls, tools, and stateful reasoning.

Inspect workflow executions with Diagrid Dashboard

After starting the durable agent with Dapr, you can use the local Diagrid Dashboard to visualize and inspect your workflow state, including detailed execution history for each run. The dashboard runs as a container and connects to the same state store used by Dapr workflows (by default, the local Redis instance).

Start the Diagrid Dashboard container using Docker:

docker run -p 8080:8080 ghcr.io/diagridio/diagrid-dashboard:latest

Open the dashboard in a browser at http://localhost:8080 to explore your local workflow executions.

Inspect Conversation History with Redis Insight

Dapr uses Redis by default for state management and pub/sub messaging, which are fundamental to Dapr Agents’ agentic workflows. To inspect the Redis instance and see both conversation state for this durable agent, you can use Redis Insight.

Run Redis Insight:

docker run --rm -d --name redisinsight -p 5540:5540 redis/redisinsight:latest

Once running, access the Redis Insight interface at http://localhost:5540/.

Inside Redis Insight, you can connect to the Redis instance used by Dapr:

• Port: 6379
• Host (Linux): 172.17.0.1
• Host (Windows/Mac): host.docker.internal (for example, host.docker.internal:6379)

Redis Insight makes it easy to inspect keys and values stored in the state stores (such as agent-memory and agent-workflow), which is useful for debugging and understanding how your durable agents behave.

Here you can browse the state stores used by the agent (agent-memory) and explore their data.

Next Steps

Now that you have Dapr Agents installed via the quickstart, and a durable HTTP agent running end-to-end, explore more examples and patterns in the quickstarts section to learn about multi-agent workflows, pub/sub-driven agents, tracing, and deeper integration with Dapr’s building blocks.

2.3 - Why Dapr Agents

Dapr Agents is a production-ready, open-source framework (v1.0) for building and orchestrating LLM-based autonomous agents that leverages Dapr’s proven distributed systems foundation. Unlike other agentic frameworks that require developers to build infrastructure from scratch, Dapr Agents enables teams to focus on agent intelligence by providing enterprise-grade scalability, state management, and messaging capabilities out of the box. This approach eliminates the complexity of recreating distributed system fundamentals while delivering agentic workflows powered by Dapr.

Challenges with Existing Frameworks

Many agentic frameworks today attempt to redefine how microservices are built and orchestrated by developing their own platforms for core distributed system capabilities. While these efforts showcase innovation, they often lead to steep learning curves, fragmented systems, and unnecessary complexity when scaling or adapting to new environments.

These frameworks require developers to adopt entirely new paradigms or recreate foundational infrastructure, rather than building on existing solutions that are proven to handle these challenges at scale. This added complexity diverts focus from the primary goal: designing and implementing intelligent, effective agents.

How Dapr Agents Solves It

Dapr Agents takes a different approach by building on Dapr, leveraging its proven APIs and patterns including workflows, pub/sub messaging, state management, and service communication. This integration eliminates the need to recreate foundational components from scratch.

By integrating with Dapr’s runtime and modular components, Dapr Agents empowers developers to build and deploy agents that work as collaborative services within larger systems. Whether experimenting with a single agent or orchestrating workflows involving multiple agents, Dapr Agents allows teams to concentrate on the intelligence and behavior of LLM-powered agents while leveraging a proven framework for scalability and reliability.

Principles

Agent-Centric Design

Dapr Agents is designed to place agents, powered by LLMs, at the core of task execution and workflow orchestration. This principle emphasizes:

• LLM-Powered Agents: Dapr Agents enables the creation of agents that leverage LLMs for reasoning, dynamic decision-making, and natural language interactions.
• Adaptive Task Handling: Agents in Dapr Agents are equipped with flexible patterns like tool calling and reasoning loops (e.g., ReAct), allowing them to autonomously tackle complex and evolving tasks.
• Multi-agent Systems: Dapr Agents’ framework allows agents to act as modular, reusable building blocks that integrate seamlessly into workflows, whether they operate independently or collaboratively.

While Dapr Agents centers around agents, it also recognizes the versatility of using LLMs directly in deterministic workflows or simpler task sequences. In scenarios where the agent’s built-in task-handling patterns, like tool calling or ReAct loops, are unnecessary, LLMs can act as core components for reasoning and decision-making. This flexibility ensures users can adapt Dapr Agents to suit diverse needs without being confined to a single approach.

Backed by Durable Workflows

Dapr Agents places durability at the core of its architecture, leveraging Dapr Workflows as the foundation for durable agent execution and deterministic multi-agent orchestration.

• Durable Agent Execution: DurableAgents are fundamentally workflow-backed, ensuring all LLM calls and tool executions remain durable, auditable, and resumable. Workflow checkpointing guarantees agents can recover from any point of failure while maintaining state consistency.
• Deterministic Multi-Agent Orchestration: Workflows provide centralized control over task dependencies and coordination between multiple agents. Dapr’s code-first workflow engine enables reliable orchestration of complex business processes while preserving agent autonomy where appropriate.

By integrating workflows as the foundational layer, Dapr Agents enables systems that combine the reliability of deterministic execution with the intelligence of LLM-powered agents, ensuring reliability and scalability.

Modular Component Model

Dapr Agents utilizes Dapr’s pluggable component framework and building blocks to simplify development and enhance flexibility:

• Building Blocks for Core Functionality: Dapr provides API building blocks, such as Pub/Sub messaging, state management, service invocation, and more, to address common microservice challenges and promote best practices.
• Interchangeable Components: Each building block operates on swappable components (e.g., Redis, Kafka, Azure CosmosDB), allowing you to replace implementations without changing application code.
• Seamless Transitions: Develop locally with default configurations and deploy effortlessly to cloud environments by simply updating component definitions.

Message-Driven Communication

Dapr Agents emphasizes the use of Pub/Sub messaging for event-driven communication between agents. This principle ensures:

• Decoupled Architecture: Asynchronous communication for scalability and modularity.
• Real-Time Adaptability: Agents react dynamically to events for faster, more flexible task execution.
• Event-Driven Workflows: : By combining Pub/Sub messaging with workflow capabilities, agents can collaborate through event streams while participating in larger orchestrated workflows, enabling both autonomous coordination and structured task execution.

Decoupled Infrastructure Design

Dapr Agents ensures a clean separation between agents and the underlying infrastructure, emphasizing simplicity, scalability, and adaptability:

• Agent Simplicity: Agents focus purely on reasoning and task execution, while Pub/Sub messaging, routing, and validation are managed externally by modular infrastructure components.
• Scalable and Adaptable Systems: By offloading non-agent-specific responsibilities, Dapr Agents allows agents to scale independently and adapt seamlessly to new use cases or integrations.

Dapr Agents Benefits

Scalable Workflows as First-Class Citizens

Dapr Agents uses a durable-execution workflow engine that guarantees each agent task executes to completion despite network interruptions, node crashes, and other disruptive failures. Developers do not need to understand the underlying workflow engine concepts—simply write an agent that performs any number of tasks and these will be automatically distributed across the cluster. If any task fails, it will be retried and recover its state from where it left off.

Cost-Effective AI Adoption

Dapr Agents builds on Dapr’s Workflow API, which represents each agent as an actor, a single unit of compute and state that is thread-safe and natively distributed. This design enables a scale-to-zero architecture that minimizes infrastructure costs, making AI adoption accessible to organizations of all sizes. The underlying virtual actor model allows thousands of agents to run on demand on a single machine with low latency when scaling from zero. When unused, agents are reclaimed by the system but retain their state until needed again. This design eliminates the trade-off between performance and resource efficiency.

Data-centric AI agents

With built-in connectivity to over 50 enterprise data sources, Dapr Agents efficiently handles structured and unstructured data. From basic PDF extraction to large-scale database interactions, it enables data-driven AI workflows with minimal code changes. Dapr’s bindings and state stores, along with MCP support, provide access to numerous data sources for agent data ingestion.

Accelerated development

Dapr Agents provides AI features that give developers a complete API surface to tackle common problems, including:

• Flexible prompting
• Structured outputs
• Multiple LLM providers
• Contextual memory
• Intelligent tool selection
• MCP integration
• Multi-agent communications

Integrated Security and Reliability

By building on Dapr, platform and infrastructure teams can apply Dapr’s resiliency policies to the database and message broker components used by Dapr Agents. These policies include timeouts, retry/backoff strategies, and circuit breakers. For security, Dapr provides options to scope access to specific databases or message brokers to one or more agentic app deployments. Additionally, Dapr Agents uses mTLS to encrypt communication between its underlying components.

Built-in Messaging and State Infrastructure

• Service-to-Service Invocation: Enables direct communication between agents with built-in service discovery, error handling, and distributed tracing. Agents can use this for synchronous messaging in multi-agent workflows.
• Publish and Subscribe: Supports loosely coupled collaboration between agents through a shared message bus. This enables real-time, event-driven interactions for task distribution and coordination.
• Durable Workflow: Defines long-running, persistent workflows that combine deterministic processes with LLM-based decision-making. Dapr Agents uses this to orchestrate complex multi-step agentic workflows.
• State Management: Provides a flexible key-value store for agents to retain context across interactions, ensuring continuity and adaptability during workflows.
• LLM Integration: Uses Dapr Conversation API to abstract LLM inference APIs for chat completion, and provides native clients for other LLM integrations such as embeddings and audio processing.

Vendor-Neutral and Open Source

As part of the CNCF, Dapr Agents is vendor-neutral, eliminating concerns about lock-in, intellectual property risks, or proprietary restrictions. Organizations gain full flexibility and control over their AI applications using open-source software they can audit and contribute to.

2.4 - Core Concepts

Dapr Agents provides a structured way to build and orchestrate applications that use LLMs without getting bogged down in infrastructure details and with durability guarantees. The primary goal is to enable AI development by abstracting away the complexities of working with LLMs, tools, memory management, and distributed systems, allowing developers to focus on the business logic of their AI applications. Agents in this framework are the fundamental building blocks.

Agents

Agents are autonomous units powered by Large Language Models (LLMs), designed to execute tasks, reason through problems, and collaborate within workflows. Acting as intelligent building blocks, agents combine reasoning with tool integration, memory, and collaboration features to get to the desired outcome.

Dapr Agents provides two agent types, each designed for different use cases:

Agent

The Agent class is a conversational agent that manages tool calls and conversations using a language model. It provides synchronous execution with built-in conversation memory.

@tool
def my_weather_func() -> str:
    """Get current weather."""
    return "It's 72°F and sunny"

async def main():
    weather_agent = Agent(
        name="WeatherAgent",
        role="Weather Assistant",
        goal="Provide timely weather updates across cities",
        instructions=["Help users with weather information"],
        tools=[my_weather_func],
        memory = AgentMemoryConfig(
            store=ConversationDaprStateMemory(
                store_name="historystore",
                session_id="some-id",
            )
        ),
    )

    response1 = await weather_agent.run("What's the weather?")
    response2 = await weather_agent.run("How about now?")

This example shows how to create a simple agent with tool integration. The agent processes queries synchronously and maintains conversation context across multiple interactions using Dapr State Store API.

Durable Agent

The DurableAgent class is a workflow-based agent that extends the standard Agent with Dapr Workflows for long-running, fault-tolerant, and durable execution. It provides persistent state management, automatic retry mechanisms, and deterministic execution across failures.

from dapr_agents.workflow.runners import AgentRunner

async def main():
    travel_planner = DurableAgent(
        name="TravelBuddy",
        role="Travel Planner",
        goal="Help users find flights and remember preferences",
        instructions=["Help users find flights and remember preferences"],
        tools=[search_flights],
        memory = AgentMemoryConfig(
            store=ConversationDaprStateMemory(
                store_name="conversationstore",
                session_id="travel-session",
            )
        )
    )

    runner = AgentRunner()

    try:
        itinerary = await runner.run(
            travel_planner,
            payload={"task": "Plan a 3-day trip to Paris"},
        )
        print(itinerary)
    finally:
        runner.shutdown(travel_planner)

This example demonstrates creating a workflow-backed agent that runs autonomously in the background. The AgentRunner schedules the workflow for you, waits for completion, and ensures the agent can be triggered once yet continue execution across restarts.

Key Characteristics:

• Workflow-based execution using Dapr Workflows
• Persistent workflow state management across sessions and failures
• Automatic retry and recovery mechanisms
• Deterministic execution with checkpointing
• Built-in message routing and agent communication
• AgentRunner modes for DurableAgents: ad-hoc runs (runner.run(...)), pub/sub subscriptions (runner.subscribe(...)), and FastAPI services (runner.serve(...))
• Supports complex orchestration patterns and multi-agent collaboration

When to use:

• Multi-step workflows that span time or systems
• Tasks requiring guaranteed progress tracking and state persistence
• Scenarios where operations may pause, fail, or need recovery without data loss
• Complex agent orchestration and multi-agent collaboration
• Production systems requiring fault tolerance and scalability

In Summary:

• Regular Agent: Interaction is synchronous—you send conversational prompts and receive responses immediately. The conversation can be stored in memory or persisted, but the execution is ephemeral and does not survive restarts.

• DurableAgent (Workflow-backed): Interaction is asynchronous—you trigger the agent once, and it runs autonomously in the background until completion. The conversation state and the execution are persisted and can resume across failures or restarts.

Replay-Aware Logging

Because DurableAgent relies on Dapr Workflows, the underlying execution model uses event sourcing. This means the workflow code is re-executed (replayed) from the beginning to rebuild local state after awaiting external activities or tool calls.

To prevent duplicate logs from polluting your output during these rehydration cycles, Dapr Agents provides a ContextAwareLogger. This logger automatically hooks into the DaprWorkflowContext and silently suppresses log records when the workflow is actively replaying.

from dapr_agents.utils import get_context_aware_logger
from dapr_agents.workflow.decorators import workflow_entry

# Initialize the logger at the module level
logger = get_context_aware_logger(__name__)

@workflow_entry
def my_workflow(self, ctx: DaprWorkflowContext, wf_input: dict) -> str:
    # This will only print once, even if the workflow suspends and replays 5 times
    logger.info("Starting workflow execution...")
    # ...

Core Agent Features

An agentic system is a distributed system that requires a variety of behaviors and supporting infrastructure.

LLM Integration

Dapr Agents provides a unified interface to connect with LLM inference APIs. This abstraction allows developers to seamlessly integrate their agents with cutting-edge language models for reasoning and decision-making. The framework includes multiple LLM clients for different providers and modalities:

• DaprChatClient: Unified API for LLM interactions via Dapr’s Conversation API with built-in security (scopes, secrets, PII obfuscation), resiliency (timeouts, retries, circuit breakers), and observability via OpenTelemetry & Prometheus
• OpenAIChatClient: Full spectrum support for OpenAI models including chat, embeddings, and audio
• HFHubChatClient: For Hugging Face models supporting both chat and embeddings
• MistralChatClient: Native support for Mistral models via the official SDK, enabling custom endpoints and advanced multimodal features. Falls back to the MISTRAL_MODEL environment variable or mistral-large-latest if a model is not explicitly provided.
• NVIDIAChatClient: For NVIDIA AI Foundation models supporting local inference and chat
• ElevenLabs: Support for speech and voice capabilities

Prompt Flexibility

Dapr Agents supports flexible prompt templates to shape agent behavior and reasoning. Users can define placeholders within prompts, enabling dynamic input of context for inference calls. By leveraging prompt formatting with Jinja templates and Python f-string formatting, users can include loops, conditions, and variables, providing precise control over the structure and content of prompts. This flexibility ensures that LLM responses are tailored to the task at hand, offering modularity and adaptability for diverse use cases.

Using Prompty Templates

You can easily configure a Dapr Agent’s prompt, model parameters, and LLM provider all in one place using a .prompty file. For example, to configure an agent using Mistral:

---
name: Mistral Agent
model:
  api: chat
  configuration:
    type: mistral
    name: mistral-large-latest
  parameters:
    temperature: 0.7
    max_tokens: 500
---
system:
You are a helpful assistant.

Note: mistral-large-latest is used as an example. Please check the Mistral documentation for the most current model names.

Structured Outputs

Agents in Dapr Agents leverage structured output capabilities, such as OpenAI’s Function Calling, to generate predictable and reliable results. These outputs follow JSON Schema Draft 2020-12 and OpenAPI Specification v3.1.0 standards, enabling easy interoperability and tool integration.

# Define our data model
class Dog(BaseModel):
    name: str
    breed: str
    reason: str

# Initialize the chat client
llm = OpenAIChatClient()

# Get structured response
response = llm.generate(
    messages=[UserMessage("One famous dog in history.")], response_format=Dog
)

print(json.dumps(response.model_dump(), indent=2))

This demonstrates how LLMs generate structured data according to a schema. The Pydantic model (Dog) specifies the exact structure and data types expected, while the response_format parameter instructs the LLM to return data matching the model, ensuring consistent and predictable outputs for downstream processing.

Tool Calling

Tool Calling is an essential pattern in autonomous agent design, allowing AI agents to interact dynamically with external tools based on user input. Agents dynamically select the appropriate tool for a given task, using LLMs to analyze requirements and choose the best action.

@tool(args_model=GetWeatherSchema)
def get_weather(location: str) -> str:
    """Get weather information based on location."""
    import random
    temperature = random.randint(60, 80)
    return f"{location}: {temperature}F."

Each tool has a descriptive docstring that helps the LLM understand when to use it. The @tool decorator marks a function as a tool, while the Pydantic model (GetWeatherSchema) defines input parameters for structured validation.

1. The user submits a query specifying a task and the available tools.
2. The LLM analyzes the query and selects the right tool for the task.
3. The LLM provides a structured JSON output containing the tool’s unique ID, name, and arguments.
4. The AI agent parses the JSON, executes the tool with the provided arguments, and sends the results back as a tool message.
5. The LLM then summarizes the tool’s execution results within the user’s context to deliver a comprehensive final response.

This is supported directly through LLM parametric knowledge and enhanced by Function Calling, ensuring tools are invoked efficiently and accurately.

Tool Execution Modes

When an LLM returns multiple tool calls in a single turn, DurableAgent can execute them in two modes, configured via AgentExecutionConfig.tool_execution_mode:

from dapr_agents.agents.configs import AgentExecutionConfig, ToolExecutionMode

travel_planner = DurableAgent(
    name="TravelBuddy",
    ...
    execution=AgentExecutionConfig(
        max_iterations=10,
        tool_execution_mode=ToolExecutionMode.SEQUENTIAL,
    ),
)

MCP Support

Dapr Agents includes built-in support for the Model Context Protocol (MCP), enabling agents to dynamically discover and invoke external tools through a standardized interface. Using the provided MCPClient, agents can connect to MCP servers via three transport options: stdio for local development, sse for remote or distributed environments, and via streamable HTTP transport.

client = MCPClient()
await client.connect_sse("local", url="http://localhost:8000/sse")

# Convert MCP tools to AgentTool list
tools = client.get_all_tools()

Once connected, the MCP client fetches all available tools from the server and prepares them for immediate use within the agent’s toolset. This allows agents to incorporate capabilities exposed by external processes—such as local Python scripts or remote services without hardcoding or preloading them. Agents can invoke these tools at runtime, expanding their behavior based on what’s offered by the active MCP server.

Memory

Agents retain context across interactions, enhancing their ability to provide coherent and adaptive responses. Memory options range from simple in-memory lists for managing chat history to vector databases for semantic search, and also integrates with Dapr state stores, for scalable and persistent memory for advanced use cases from 28 different state store providers.

from dapr_agents import Agent, DurableAgent
from dapr_agents.agents.configs import AgentMemoryConfig
from dapr_agents.memory import (
    ConversationDaprStateMemory,
    ConversationListMemory,
    ConversationVectorMemory,
)

# 1. ConversationListMemory (Simple In-Memory) - Default
memory_list = ConversationListMemory()

# 2. ConversationVectorMemory (Vector Store)
memory_vector = ConversationVectorMemory(
    vector_store=your_vector_store_instance,
    distance_metric="cosine",
)

# 3. ConversationDaprStateMemory (Dapr State Store) via AgentMemoryConfig
durable_memory = AgentMemoryConfig(
    store=ConversationDaprStateMemory(
        store_name="historystore",  # Dapr component name
        session_id="my-session",
    )
)

# Using with a regular Agent (pass the memory instance directly)
agent = Agent(
    name="MyAgent",
    role="Assistant",
    memory=memory_list,
)

# Using with a DurableAgent (pass the AgentMemoryConfig)
travel_planner = DurableAgent(
    name="TravelBuddy",
    memory=durable_memory,
    # ... other configs ...
)

ConversationListMemory is the default memory implementation when none is specified. It provides fast, temporary storage in Python lists for development and testing. The Dapr’s memory implementations (all found in dapr_agents.memory) are interchangeable, allowing you to switch between them without modifying your agent logic or deployment model.

ConversationVectorMemory can be backed by any of the supported vector store implementations:

from dapr_agents.storage.vectorstores import RedisVectorStore
from dapr_agents.document.embedder.openai import OpenAIEmbedder
from dapr_agents.memory import ConversationVectorMemory

vector_store = RedisVectorStore(
    url="redis://localhost:6379",
    index_name="my_agent",
    embedding_function=OpenAIEmbedder(),
    embedding_dimensions=1536,
)

memory = ConversationVectorMemory(
    vector_store=vector_store,
    distance_metric="cosine",
)

Agents as Tools

Dapr Agents supports invoking other agents - whether Dapr Agents or 3rd party agent frameworks - as tools within a DurableAgent reasoning loop. This lets a parent agent delegate sub-tasks to specialized child agents and compose multi-agent systems without using a pub/sub message broker.

Agents registered in the same registry are available to use as tools automatically. This includes invoking 3rd party framework agents. Alternatively, use agent_to_tool from dapr_agents.tool.workflow for explicit wiring, cross-app routing, or invoking agents from other frameworks:

from dapr_agents.tool.workflow import agent_to_tool

# Invoke a separate agent as a tool call
aragorn_tool = agent_to_tool(
    "aragorn",
    description="Military Strategy. Goal: Lead the forces of Gondor.",
    target_app_id="aragorn-app",
)
# Use an agent as a tool within a DurableAgent
frodo = DurableAgent(
    name="frodo",
    role="Ring Bearer",
    goal="Carry the One Ring to Mordor",
    tools=[aragorn_tool],
    ...
)

When the LLM calls one of these tools, Dapr Agents schedules the target agent’s workflow as a DurableAgent (child workflow) and returns the result—handling cross-app routing and result marshalling transparently.

See the Agents as Tools example for a complete working implementation.

Agent Runner

AgentRunner wires DurableAgents into three complementary hosting modes:

1. run – trigger a durable workflow directly from Python (CLIs, tests, notebooks) and optionally wait for completion.
2. subscribe – automatically register every @message_router decorated handler on the agent (including DurableAgent.agent_workflow) so CloudEvents on the configured topics are validated against their message_model and scheduled as workflow runs.
3. serve – host the agent as a web service by combining subscribe with FastAPI route registration and an auto-started Uvicorn server. By default it exposes POST /agent/run (schedules the @workflow_entry) and GET /agent/instances/{instance_id} (fetches workflow status), but you can supply your own FastAPI app or customize host/port/paths.

travel_planner = DurableAgent(
    name="TravelBuddy",
    role="Travel Planner",
    goal="Help humans find flights and remember preferences",
    instructions=[
        "Find flights to destinations",
        "Remember user preferences",
        "Provide clear flight info.",
    ],
    tools=[search_flights],
)
runner = AgentRunner()

The snippets below reuse this travel_planner instance to illustrate each mode.

1. Ad-hoc execution with runner.run(...)

Use run when you want to trigger a durable workflow directly from Python code (tests, CLIs, notebooks, etc.). The runner locates the agent’s @workflow_entry, and schedules it. The .run() command is a blocking call that triggers the agent and and waits for its completion.

result = await runner.run(
    travel_planner,
    payload={"task": "Plan a 3-day trip to Paris"},
)
print(result)

This mode is ideal for synchronous automation or when you need to capture the final response programmatically. Pass wait=False for fire-and-forget instances.

2. Pub/Sub subscriptions with runner.subscribe(...)

subscribe scans the agent for every method tagged with @message_router—including the built-in agent_workflow—and automatically registers the necessary Dapr subscriptions using the topics and schemas defined in AgentPubSubConfig. Each incoming CloudEvent is validated against the declared message_model (for example, TriggerAction) before the runner schedules the workflow entry.

runner.subscribe(travel_planner)
await wait_for_shutdown()

Add your own @message_router methods to support extra topics or broadcast channels—the runner will discover them automatically and route messages to the appropriate handler. Use helpers such as wait_for_shutdown() (from dapr_agents.workflow.utils.core) to keep the process alive until you stop it.

3. FastAPI services with runner.serve(...)

serve is the one-line way to run a DurableAgent as a web service. It first calls subscribe(...), then spins up a FastAPI app (unless you pass your own) with two default endpoints:

• POST /agent/run: Validates the JSON body against the agent’s @workflow_entry signature and schedules a new workflow instance.
• GET /agent/instances/{instance_id}: Proxies workflow status queries (including payloads, if requested).

runner.serve(
    travel_planner,
    port=8001,
)

Because workflows are durable, the /run endpoint responds immediately with an instance ID even though the agent keeps working in the background. You can mount the generated FastAPI routes into a larger application or let serve run its own Uvicorn loop for standalone deployments.

Multi-agent Systems (MAS)

While it’s tempting to build a fully autonomous agent capable of handling many tasks, in practice, it’s more effective to break this down into specialized agents equipped with appropriate tools and instructions, then coordinate interactions between multiple agents.

Multi-agent systems (MAS) distribute workflow execution across multiple coordinated agents to efficiently achieve shared objectives. This approach, called agent orchestration, enables better specialization, scalability, and maintainability compared to monolithic agent designs.

Dapr Agents supports two primary orchestration approaches via Dapr Workflows and Dapr PubSub:

• Deterministic Workflow-based Orchestration - Provides clear, repeatable processes with predefined sequences and decision points
• Event-driven Orchestration - Enables dynamic, adaptive collaboration through message-based coordination among agents

Both approaches utilize a central orchestrator that coordinates multiple specialized agents, each handling specific tasks or domains, ensuring efficient task distribution and seamless collaboration across the system.

Deterministic Workflows

Workflows are structured processes where LLM agents and tools collaborate in predefined sequences to accomplish complex tasks. Unlike fully autonomous agents that make all decisions independently, workflows provide a balance of structure and predictability from the workflow definition, intelligence and flexibility from LLM agents, and reliability and durability from Dapr’s workflow engine.

This approach is particularly suitable for business-critical applications where you need both the intelligence of LLMs and the reliability of traditional software systems.

import time

import dapr.ext.workflow as wf

wfr = wf.WorkflowRuntime()

@wfr.workflow(name="support_workflow")
def support_workflow(ctx: wf.DaprWorkflowContext, request: dict) -> str:
    triage_result = yield ctx.call_child_workflow(
        workflow="agent_workflow",
        input={"task": f"Assist with the following support request:\n\n{request}"},
        app_id="triage-agent",
    )
    if triage_result:
        print("Triage result:", triage_result.get("content", ""), flush=True)

    recommendation = yield ctx.call_child_workflow(
        workflow="agent_workflow",
        input={"task": triage_result.get("content", "")},
        app_id="expert-agent",
    )
    if recommendation:
        print("Recommendation:", recommendation.get("content", ""), flush=True)

    return recommendation.get("content", "") if recommendation else ""

wfr.start()
time.sleep(5)

client = wf.DaprWorkflowClient()
request = {
    "customer": "alice",
    "issue": "Unable to access dashboard after recent update",
}
instance_id = client.schedule_new_workflow(
    workflow=support_workflow,
    input=request,
)
client.wait_for_workflow_completion(instance_id, timeout_in_seconds=60)
wfr.shutdown()

Here the call_child_workflow is used to invoke the workflow of two Dapr Agents and pass output from one as input to the other. This requires the DurableAgent to run as:

from dapr_agents import DurableAgent
from dapr_agents.agents.configs import AgentMemoryConfig
from dapr_agents.llm.dapr import DaprChatClient
from dapr_agents.memory import ConversationDaprStateMemory
from dapr_agents.workflow.runners.agent import AgentRunner

expert_agent = DurableAgent(
    name="expert_agent",
    role="Technical Support Specialist",
    goal="Provide recommendations based on customer context and issue.",
    instructions=[
        "Provide a clear, actionable recommendation to resolve the issue.",
    ],
    llm=DaprChatClient(component_name="llm-provider"),
    memory=AgentMemoryConfig(
        store=ConversationDaprStateMemory(
            store_name="agent-memory",
            session_id=f"expert-agent-session",
        )
    ),
)
runner = AgentRunner()
try:
    runner.serve(expert_agent, port=8001)
finally:
    runner.shutdown(expert_agent)

Workflow Patterns

Workflows enable the implementation of various agentic patterns through structured orchestration, including Prompt Chaining, Routing, Parallelization, Orchestrator-Workers, Evaluator-Optimizer, Human-in-the-loop, and others. For detailed implementations and examples of these patterns, see the Patterns documentation.

Message Router Workflows

The @message_router decorator binds a workflow directly to a Dapr Pub/Sub topic so every validated message automatically schedules a workflow instance. This pattern—used in the message-router quickstart—lets you push CloudEvent payloads onto a topic and have LLM-backed activities take over immediately.

from pydantic import BaseModel
from dapr_agents.workflow.decorators.routers import message_router

class StartBlogMessage(BaseModel):
    topic: str

@message_router(
    pubsub="messagepubsub",
    topic="blog.requests",
    message_model=StartBlogMessage,
)
def blog_workflow(ctx: DaprWorkflowContext, wf_input: dict) -> str:
    outline = yield ctx.call_activity(
        create_outline, input={"topic": wf_input["topic"]}
    )
    post = yield ctx.call_activity(write_post, input={"outline": outline})
    return post

During startup, call register_message_routes(targets=[blog_workflow], dapr_client=client) to automatically configure subscriptions, schema validation, and workflow scheduling. This keeps the workflow definition as the single source of truth for both orchestration and event ingress.

Workflows vs. Durable Agents

Both DurableAgent and workflow-based agent orchestration use Dapr workflows behind the scenes for durability and reliability, but they differ in how control flow is determined.

The key difference lies in control flow determination: with DurableAgent, the underlying workflow is created dynamically by the LLM’s planning decisions, executing entirely within a single agent context. In contrast, with deterministic workflows, the developer explicitly defines the coordination between one or more LLM interactions, providing structured orchestration across multiple tasks or agents.

Event-Driven Orchestration

Event-driven agent orchestration enables multiple specialized agents to collaborate through asynchronous Pub/Sub messaging. This approach provides powerful collaborative problem-solving, parallel processing, and division of responsibilities among specialized agents through independent scaling, resilience via service isolation, and clear separation of responsibilities.

Core Participants

The core participants in this multi-agent coordination systems are the following.

Durable Agents

Each agent runs as an independent service with its own lifecycle, configured as a standard DurableAgent with pub/sub enabled:

import asyncio

from dapr_agents.agents.configs import (
    AgentMemoryConfig,
    AgentProfileConfig,
    AgentPubSubConfig,
    AgentRegistryConfig,
    AgentStateConfig,
)
from dapr_agents.memory import ConversationDaprStateMemory
from dapr_agents.storage.daprstores.stateservice import StateStoreService
from dapr_agents.workflow.runners import AgentRunner
from dapr_agents.workflow.utils.core import wait_for_shutdown

registry = AgentRegistryConfig(
    store=StateStoreService(store_name="agentregistrystore"),
    team_name="fellowship",
)

frodo = DurableAgent(
    profile=AgentProfileConfig(
        name="Frodo",
        role="Ring Bearer",
        instructions=["Speak like Frodo, with humility and determination."],
    ),
    pubsub=AgentPubSubConfig(
        pubsub_name="messagepubsub",
        agent_topic="fellowship.frodo.requests",
        broadcast_topic="fellowship.broadcast",
    ),
    state=AgentStateConfig(
        store=StateStoreService(store_name="workflowstatestore", key_prefix="frodo:")
    ),
    registry=registry,
    memory=AgentMemoryConfig(
        store=ConversationDaprStateMemory(
            store_name="memorystore",
            session_id="frodo-session",
        )
    ),
)

async def main():
    runner = AgentRunner()
    try:
        runner.subscribe(frodo)
        await wait_for_shutdown()
    finally:
        runner.shutdown(frodo)

asyncio.run(main())

Orchestrator

The orchestrator coordinates interactions between agents and manages conversation flow by selecting appropriate agents, managing interaction sequences, and tracking progress. Dapr Agents offers three orchestration strategies: Random, RoundRobin, and LLM-based orchestration.

from dapr_agents.agents.configs import (
    AgentExecutionConfig,
    AgentPubSubConfig,
    AgentRegistryConfig,
    AgentStateConfig,
)
from dapr_agents.llm.openai import OpenAIChatClient
from dapr_agents.storage.daprstores.stateservice import StateStoreService
from dapr_agents.workflow.runners import AgentRunner
import dapr.ext.workflow as wf

llm_orchestrator = LLMOrchestrator(
    name="LLMOrchestrator",
    llm=OpenAIChatClient(),
    pubsub=AgentPubSubConfig(
        pubsub_name="messagepubsub",
        agent_topic="llm.orchestrator.requests",
        broadcast_topic="fellowship.broadcast",
    ),
    state=AgentStateConfig(
        store=StateStoreService(
            store_name="workflowstatestore", key_prefix="llm.orchestrator:"
        )
    ),
    registry=AgentRegistryConfig(
        store=StateStoreService(store_name="agentregistrystore"),
        team_name="fellowship",
    ),
    execution=AgentExecutionConfig(max_iterations=3),
    runtime=wf.WorkflowRuntime(),
)

runner = AgentRunner()
runner.serve(llm_orchestrator, port=8004)

The LLM-based orchestrator uses intelligent agent selection for context-aware decision making, while Random and RoundRobin provide alternative coordination strategies for simpler use cases. The runner keeps the orchestrator online as a Dapr app or HTTP service so clients can publish tasks over topics or REST calls.

Because both DurableAgent.agent_workflow and the orchestrators above are decorated with @message_router(message_model=TriggerAction), runner.subscribe(...) automatically wires the topics declared in AgentPubSubConfig and validates every incoming CloudEvent against the expected schema before scheduling the @workflow_entry. You can add additional message routers (each with its own message_model) to the same agent; the runner will discover them the next time it starts and extend the subscription list automatically.

Communication Flow

Agents communicate through an event-driven pub/sub system that enables asynchronous communication, decoupled architecture, scalable interactions, and reliable message delivery. The typical collaboration flow involves client query submission, orchestrator-driven agent selection, agent response processing, and iterative coordination until task completion.

This approach is particularly effective for complex problem solving requiring multiple expertise areas, creative collaboration from diverse perspectives, role-playing scenarios, and distributed processing of large tasks.

How Messaging Works

Messaging connects agents in workflows, enabling real-time communication and coordination. It acts as the backbone of event-driven interactions, ensuring that agents work together effectively without requiring direct connections.

Through messaging, agents can:

• Collaborate Across Tasks: Agents exchange messages to share updates, broadcast events, or deliver task results.
• Orchestrate Workflows: Tasks are triggered and coordinated through published messages, enabling workflows to adjust dynamically.
• Respond to Events: Agents adapt to real-time changes by subscribing to relevant topics and processing events as they occur.

By using messaging, workflows remain modular and scalable, with agents focusing on their specific roles while seamlessly participating in the broader system.

Message Bus and Topics

The message bus serves as the central system that manages topics and message delivery. Agents interact with the message bus to send and receive messages:

• Publishing Messages: Agents publish messages to a specific topic, making the information available to all subscribed agents.
• Subscribing to Topics: Agents subscribe to topics relevant to their roles, ensuring they only receive the messages they need.
• Broadcasting Updates: Multiple agents can subscribe to the same topic, allowing them to act on shared events or updates.

Why Pub/Sub Messaging for Agentic Workflows?

Pub/Sub messaging is essential for event-driven agentic workflows because it:

• Decouples Components: Agents publish messages without needing to know which agents will receive them, promoting modular and scalable designs.
• Enables Real-Time Communication: Messages are delivered as events occur, allowing agents to react instantly.
• Fosters Collaboration: Multiple agents can subscribe to the same topic, making it easy to share updates or divide responsibilities.
• Enables Scalability:The message bus ensures that communication scales effortlessly, whether you are adding new agents, expanding workflows, or adapting to changing requirements. Agents remain loosely coupled, allowing workflows to evolve without disruptions.

This messaging framework ensures that agents operate efficiently, workflows remain flexible, and systems can scale dynamically.

2.5 - Agentic Patterns

Dapr Agents simplify the implementation of agentic systems, from simple augmented LLMs to fully autonomous agents in enterprise environments. The following sections describe several application patterns that can benefit from Dapr Agents.

Overview

Agentic systems use design patterns such as reflection, tool use, planning, and multi-agent collaboration to achieve better results than simple single-prompt interactions. Rather than thinking of “agent” as a binary classification, it’s more useful to think of systems as being agentic to different degrees.

This ranges from simple workflows that prompt a model once, to sophisticated systems that can carry out multiple iterative steps with greater autonomy. There are two fundamental architectural approaches:

• Workflows: Systems where LLMs and tools are orchestrated through predefined code paths (more prescriptive)
• Agents: Systems where LLMs dynamically direct their own processes and tool usage (more autonomous)

On one end, we have predictable workflows with well-defined decision paths and deterministic outcomes. On the other end, we have AI agents that can dynamically direct their own strategies. While fully autonomous agents might seem appealing, workflows often provide better predictability and consistency for well-defined tasks. This aligns with enterprise requirements where reliability and maintainability are crucial.

The patterns in this documentation start with the Augmented LLM, then progress through workflow-based approaches that offer predictability and control, before moving toward more autonomous patterns. Each addresses specific use cases and offers different trade-offs between deterministic outcomes and autonomy.

Most of the patterns below can be combined with the hook system — a small set of callbacks on DurableAgent that let you log, rewrite, cache, or block individual tool calls and LLM calls without changing the agent body. Hooks are how Human-in-the-Loop is implemented (see the HITL section below) and they apply equally well to any of the other patterns.

Augmented LLM

The Augmented LLM pattern is the foundational building block for any kind of agentic system. It enhances a language model with external capabilities like memory and tools, providing a basic but powerful foundation for AI-driven applications.

This pattern is ideal for scenarios where you need an LLM with enhanced capabilities but don’t require complex orchestration or autonomous decision-making. The augmented LLM can access external tools, maintain conversation history, and provide consistent responses across interactions.

Use Cases:

• Personal assistants that remember user preferences
• Customer support agents that access product information
• Research tools that retrieve and analyze information

Implementation with Dapr Agents:

from dapr_agents import DurableAgent, tool

@tool
def search_flights(destination: str) -> List[FlightOption]:
    """Search for flights to the specified destination."""
    # Mock flight data (would be an external API call in a real app)
    return [
        FlightOption(airline="SkyHighAir", price=450.00),
        FlightOption(airline="GlobalWings", price=375.50)
    ]

# Create agent with memory and tools
travel_planner = DurableAgent(
    name="TravelBuddy",
    role="Travel Planner Assistant",
    instructions=["Remember destinations and help find flights"],
    tools=[search_flights],
)

Dapr Agents automatically handles:

• Agent configuration - Simple configuration with role and instructions guides the LLM behavior
• Memory persistence - The agent manages conversation memory
• Tool integration - The @tool decorator handles input validation, type conversion, and output formatting

The foundational building block of any agentic system is the Augmented LLM - a language model enhanced with external capabilities like memory, tools, and retrieval. In Dapr Agents, this is represented by the DurableAgent class. While a simple Agent class also exists, it is deprecated as of v1.0.0-rc.1; DurableAgent is the recommended choice for all new development. Augmented LLM capabilities alone are often not sufficient for complex enterprise scenarios, so they are typically combined with workflow orchestration that provides structure, reliability, and coordination for multi-step processes.

Prompt Chaining

The Prompt Chaining pattern addresses complex requirements by decomposing tasks into a sequence of steps, where each LLM call processes the output of the previous one. This pattern allows for better control of the overall process, validation between steps, and specialization of each step.

Use Cases:

• Content generation (creating outlines first, then expanding, then reviewing)
• Multi-stage analysis (performing complex analysis into sequential steps)
• Quality assurance workflows (adding validation between processing steps)

Implementation with Dapr Agents:

from dapr_agents import DaprWorkflowContext, workflow

@workflow(name='travel_planning_workflow')
def travel_planning_workflow(ctx: DaprWorkflowContext, user_input: str):
    # Step 1: Extract destination using a simple prompt (no agent)
    destination_text = yield ctx.call_activity(extract_destination, input=user_input)
    
    # Gate: Check if destination is valid
    if "paris" not in destination_text.lower():
        return "Unable to create itinerary: Destination not recognized or supported."
    
    # Step 2: Generate outline with planning agent (has tools)
    travel_outline = yield ctx.call_activity(create_travel_outline, input=destination_text)
    
    # Step 3: Expand into detailed plan with itinerary agent (no tools)
    detailed_itinerary = yield ctx.call_activity(expand_itinerary, input=travel_outline)
    
    return detailed_itinerary

The implementation showcases three different approaches:

• Basic prompt-based task (no agent)
• Agent-based task without tools
• Agent-based task with tools

Dapr Agents’ workflow orchestration provides:

• Workflow as Code - Tasks are defined in developer-friendly ways
• Workflow Persistence - Long-running chained tasks survive process restarts
• Hybrid Execution - Easily mix prompts, agent calls, and tool-equipped agents

Routing

The Routing pattern addresses diverse request types by classifying inputs and directing them to specialized follow-up tasks. This allows for separation of concerns and creates specialized experts for different types of queries.

Use Cases:

• Resource optimization (sending simple queries to smaller models)
• Multi-lingual support (routing queries to language-specific handlers)
• Customer support (directing different query types to specialized handlers)
• Content creation (routing writing tasks to topic specialists)
• Hybrid LLM systems (using different models for different tasks)

Implementation with Dapr Agents:

@workflow(name="travel_assistant_workflow")
def travel_assistant_workflow(ctx: DaprWorkflowContext, input_params: dict):
    user_query = input_params.get("query")
    
    # Classify the query type using an LLM
    query_type = yield ctx.call_activity(classify_query, input={"query": user_query})

    # Route to the appropriate specialized handler
    if query_type == QueryType.ATTRACTIONS:
        response = yield ctx.call_activity(
            handle_attractions_query,
            input={"query": user_query}
        )
    elif query_type == QueryType.ACCOMMODATIONS:
        response = yield ctx.call_activity(
            handle_accommodations_query,
            input={"query": user_query}
        )
    elif query_type == QueryType.TRANSPORTATION:
        response = yield ctx.call_activity(
            handle_transportation_query,
            input={"query": user_query}
        )
    else:
        response = "I'm not sure how to help with that specific travel question."
        
    return response

The advantages of Dapr’s approach include:

• Familiar Control Flow - Uses standard programming if-else constructs for routing
• Extensibility - The control flow can be extended for future requirements easily
• LLM-Powered Classification - Uses an LLM to categorize queries dynamically

Parallelization

The Parallelization pattern enables processing multiple dimensions of a problem simultaneously, with outputs aggregated programmatically. This pattern improves efficiency for complex tasks with independent subtasks that can be processed concurrently.

Use Cases:

• Complex research (processing different aspects of a topic in parallel)
• Multi-faceted planning (creating various elements of a plan concurrently)
• Product analysis (analyzing different aspects of a product in parallel)
• Content creation (generating multiple sections of a document simultaneously)

Implementation with Dapr Agents:

@workflow(name="travel_planning_workflow")
def travel_planning_workflow(ctx: DaprWorkflowContext, input_params: dict):
    destination = input_params.get("destination")
    preferences = input_params.get("preferences")
    days = input_params.get("days")

    # Process three aspects of the travel plan in parallel
    parallel_tasks = [
        ctx.call_activity(research_attractions, input={
            "destination": destination, 
            "preferences": preferences, 
            "days": days
        }),
        ctx.call_activity(recommend_accommodations, input={
            "destination": destination, 
            "preferences": preferences, 
            "days": days
        }),
        ctx.call_activity(suggest_transportation, input={
            "destination": destination, 
            "preferences": preferences, 
            "days": days
        })
    ]

    # Wait for all parallel tasks to complete
    results = yield wfapp.when_all(parallel_tasks)
    
    # Aggregate results into final plan
    final_plan = yield ctx.call_activity(create_final_plan, input={"results": results})
    
    return final_plan

The benefits of using Dapr for parallelization include:

• Simplified Concurrency - Handles the complex orchestration of parallel tasks
• Automatic Synchronization - Waits for all parallel tasks to complete
• Workflow Durability - The entire parallel process is durable and recoverable

Orchestrator-Workers

For highly complex tasks where the number and nature of subtasks can’t be known in advance, the Orchestrator-Workers pattern offers a powerful solution. This pattern features a central orchestrator LLM that dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes their results.

Unlike previous patterns where workflows are predefined, the orchestrator determines the workflow dynamically based on the specific input.

Use Cases:

• Software development tasks spanning multiple files
• Research gathering information from multiple sources
• Business analysis evaluating different facets of a complex problem
• Content creation combining specialized content from various domains

Implementation with Dapr Agents:

@workflow(name="orchestrator_travel_planner")
def orchestrator_travel_planner(ctx: DaprWorkflowContext, input_params: dict):
    travel_request = input_params.get("request")

    # Step 1: Orchestrator analyzes request and determines required tasks
    plan_result = yield ctx.call_activity(
        create_travel_plan,
        input={"request": travel_request}
    )

    tasks = plan_result.get("tasks", [])

    # Step 2: Execute each task with a worker LLM
    worker_results = []
    for task in tasks:
        task_result = yield ctx.call_activity(
            execute_travel_task,
            input={"task": task}
        )
        worker_results.append({
            "task_id": task["task_id"],
            "result": task_result
        })

    # Step 3: Synthesize the results into a cohesive travel plan
    final_plan = yield ctx.call_activity(
        synthesize_travel_plan,
        input={
            "request": travel_request,
            "results": worker_results
        }
    )

    return final_plan

The advantages of Dapr for the Orchestrator-Workers pattern include:

• Dynamic Planning - The orchestrator can dynamically create subtasks based on input
• Worker Isolation - Each worker focuses on solving one specific aspect of the problem
• Simplified Synthesis - The final synthesis step combines results into a coherent output

Evaluator-Optimizer

Quality is often achieved through iteration and refinement. The Evaluator-Optimizer pattern implements a dual-LLM process where one model generates responses while another provides evaluation and feedback in an iterative loop.

Use Cases:

• Content creation requiring adherence to specific style guidelines
• Translation needing nuanced understanding and expression
• Code generation meeting specific requirements and handling edge cases
• Complex search requiring multiple rounds of information gathering and refinement

Implementation with Dapr Agents:

@workflow(name="evaluator_optimizer_travel_planner")
def evaluator_optimizer_travel_planner(ctx: DaprWorkflowContext, input_params: dict):
    travel_request = input_params.get("request")
    max_iterations = input_params.get("max_iterations", 3)
    
    # Generate initial travel plan
    current_plan = yield ctx.call_activity(
        generate_travel_plan,
        input={"request": travel_request, "feedback": None}
    )

    # Evaluation loop
    iteration = 1
    meets_criteria = False

    while iteration <= max_iterations and not meets_criteria:
        # Evaluate the current plan
        evaluation = yield ctx.call_activity(
            evaluate_travel_plan,
            input={"request": travel_request, "plan": current_plan}
        )

        score = evaluation.get("score", 0)
        feedback = evaluation.get("feedback", [])
        meets_criteria = evaluation.get("meets_criteria", False)
        
        # Stop if we meet criteria or reached max iterations
        if meets_criteria or iteration >= max_iterations:
            break

        # Optimize the plan based on feedback
        current_plan = yield ctx.call_activity(
            generate_travel_plan,
            input={"request": travel_request, "feedback": feedback}
        )

        iteration += 1

    return {
        "final_plan": current_plan,
        "iterations": iteration,
        "final_score": score
    }

The benefits of using Dapr for this pattern include:

• Iterative Improvement Loop - Manages the feedback cycle between generation and evaluation
• Quality Criteria - Enables clear definition of what constitutes acceptable output
• Maximum Iteration Control - Prevents infinite loops by enforcing iteration limits

Human-in-the-Loop

Some agent actions are too consequential to leave entirely to the model. The Human-in-the-Loop (HITL) pattern pauses the agent on specific tool calls (or other high-risk steps) and waits for a human to approve or deny before continuing. Because the wait happens inside a Dapr workflow, the pause can last seconds, hours, or days — the workflow rehydrates wherever it left off when the human responds.

In Dapr Agents this pattern is implemented through the hook system: register a before_tool_call hook on a DurableAgent and return RequireApproval(...) for the steps that need human sign-off. The framework publishes an approval-request event to whichever delivery channel you’ve configured (HTTP, Dapr pub/sub, or a workflow event), suspends the workflow on wait_for_external_event, and resumes when an approve / deny response arrives — or auto-denies on timeout.

Use Cases:

• Approving destructive operations (deleting data, dropping tables, refunds above a threshold)
• Compliance gates on policy-sensitive tool calls (PII access, schema changes)
• Reviewing agent plans before execution in regulated environments
• Long-running, multi-step processes where one step must be confirmed by a domain expert

Implementation with Dapr Agents:

from dapr_agents import DurableAgent, Hooks
from dapr_agents.hooks import ToolHookContext, HookDecision, Proceed, RequireApproval
from dapr_agents.agents.configs import AgentApprovalConfig, AgentExecutionConfig


def gate_deletions(ctx: ToolHookContext) -> HookDecision:
    if ctx.step_name.startswith("delete_"):
        return RequireApproval(
            timeout_seconds=3600,
            instructions=f"Confirm deletion: {ctx.payload}",
        )
    return Proceed()


approval = AgentApprovalConfig(
    pubsub_name="messagepubsub",
    topic="agent-approval-requests",
    default_timeout_seconds=300,
)

agent = DurableAgent(
    name="OpsAgent",
    role="Operations Assistant",
    llm=...,
    tools=[delete_old_data, ...],
    hooks=Hooks(before_tool_call=[gate_deletions]),
    execution=AgentExecutionConfig(approval=approval),
)

The benefits of using Dapr for this pattern include:

• Durable pause - The workflow survives crashes and restarts while waiting; approvals are persisted in the state store
• Choice of delivery channel - Approve over HTTP (GET /hitl/approvals, POST /hitl/approvals/{id}/respond), Dapr pub/sub, or direct workflow events
• Timeout safety - Pending requests auto-deny if no human responds, so workflows never hang forever
• Composable with other patterns - HITL is a hook decision, so it layers cleanly on top of any of the patterns above

For the full hook API surface, including the other decisions (Skip, Mutate, Deny) and LLM-level hooks, see Hooks and Human-in-the-Loop.

Durable Agent

Moving to the far end of the agentic spectrum, the Durable Agent pattern represents a shift from workflow-based approaches. Instead of predefined steps, we have an autonomous agent that can plan its own steps and execute them based on its understanding of the goal.

Enterprise applications often need durable execution and reliability that go beyond in-memory capabilities. Dapr’s DurableAgent class helps you implement autonomous agents with the reliability of workflows, as these agents are backed by Dapr workflows behind the scenes. The DurableAgent extends the basic Agent class by adding durability to agent execution.

This pattern doesn’t just persist message history – it dynamically creates workflows with durable activities for each interaction, where LLM calls and tool executions are stored reliably in Dapr’s state stores. This makes it ideal for environments where reliability and durability is critical.

The Durable Agent also enables the “headless agents” approach where autonomous systems that operate without direct user interaction. Dapr’s Durable Agent exposes REST and Pub/Sub APIs, making it ideal for long-running operations that are triggered by other applications or external events.

Use Cases:

• Long-running tasks that may take minutes or days to complete
• Distributed systems running across multiple services
• Customer support handling complex multi-session tickets
• Business processes with LLM intelligence at each step
• Personal assistants handling scheduling and information lookup
• Autonomous background processes triggered by external systems

Implementation with Dapr Agents:

import asyncio

from dapr_agents import DurableAgent
from dapr_agents.agents.configs import (
    AgentExecutionConfig,
    AgentMemoryConfig,
    AgentPubSubConfig,
    AgentRegistryConfig,
    AgentStateConfig,
)
from dapr_agents.memory import ConversationDaprStateMemory
from dapr_agents.storage.daprstores.stateservice import StateStoreService
from dapr_agents.workflow.runners import AgentRunner

travel_planner = DurableAgent(
    name="TravelBuddy",
    role="Travel Planner",
    goal="Help users find flights and remember preferences",
    instructions=[
        "Find flights to destinations",
        "Remember user preferences",
        "Provide clear flight info",
    ],
    tools=[search_flights],
    pubsub=AgentPubSubConfig(
        pubsub_name="messagepubsub",
        agent_topic="travel.requests",
        broadcast_topic="travel.broadcast",
    ),
    state=AgentStateConfig(
        store=StateStoreService(store_name="workflowstatestore"),
    ),
    registry=AgentRegistryConfig(
        store=StateStoreService(store_name="registrystatestore"),
        team_name="travel-team",
    ),
    execution=AgentExecutionConfig(max_iterations=3),
    memory=AgentMemoryConfig(
        store=ConversationDaprStateMemory(
            store_name="conversationstore",
            session_id="travel-session",
        )
    ),
)

async def main():
    runner = AgentRunner()
    try:
        result = await runner.run(
            travel_planner,
            payload={"task": "Find weekend flights to Paris"},
        )
        print(result)
    finally:
        runner.shutdown(travel_planner)

asyncio.run(main())

The implementation follows Dapr’s sidecar architecture model, where all infrastructure concerns are handled by the Dapr runtime:

• Persistent Memory - Agent state is stored in Dapr’s state store, surviving process crashes
• Workflow Orchestration - All agent interactions managed through Dapr’s workflow system
• Service Exposure - AgentRunner.serve() exposes REST endpoints (e.g., POST /agent/run) that schedule the agent’s @workflow_entry
• Pub/Sub Input/Output - AgentRunner.subscribe() scans the agent for @message_router methods and wires the configured topics with schema validation

The Durable Agent enables the concept of “headless agents” - autonomous systems that operate without direct user interaction. Depending on the scenario you can:

1. Run durable workflows programmatically (runner.run as shown above)
2. Subscribe the agent to topics so other services can trigger it via pub/sub (runner.subscribe)
3. Serve the agent behind a FastAPI app with built-in /run and status endpoints (runner.serve)

These options make it easy to process requests asynchronously and integrate seamlessly into larger distributed systems.

Retry Policy

The Durable Agent supports Dapr Workflow’s RetryPolicy with the its WorkflowRetryPolicy:

• max_attempts: max_attempts: Maximum number of retry attempts for workflow operations. Default is 1 (no retries). Set DAPR_API_MAX_RETRIES environment variable to override default.
• initial_backoff_seconds: Initial backoff duration in seconds. Default is 5 seconds.
• max_backoff_seconds: Maximum backoff duration in seconds. Default is 30 seconds.
• backoff_multiplier: Backoff multiplier for exponential backoff. Default is 1.5.
• retry_timeout: Total timeout for all retries in seconds.

All of the fields are optional. It can be passed to the Durable Agent during instantiation:

from dapr_agents.agents.configs import WorkflowRetryPolicy
travel_planner = DurableAgent(
    name="TravelBuddy",
    ...
    retry_policy=WorkflowRetryPolicy(
        max_attempts=5,
        initial_backoff_seconds=10,
        max_backoff_seconds=60,
        backoff_multiplier=2.0,
        retry_timeout=300,
    )
    ...
)

Choosing the Right Pattern

The journey from simple agentic workflows to fully autonomous agents represents a spectrum of approaches for integrating LLMs into your applications. Different use cases call for different levels of agency and control:

• Start with simpler patterns like Augmented LLM and Prompt Chaining for well-defined tasks where predictability is crucial
• Progress to more dynamic patterns like Parallelization and Orchestrator-Workers as your needs grow more complex
• Consider fully autonomous agents only for open-ended tasks where the benefits of flexibility outweigh the need for strict control

2.6 - Extensions and Activation Hooks

The Dapr Agents activation hook is the supported seam for extending a DurableAgent with your own trigger source — a change-data-capture feed, a message queue, a cron timer, a webhook — without modifying the agent or its workflow. You register one callback with agent.add_activation(...); the runner invokes it exactly once when the agent is hosted and tears it down on shutdown.

Out of the box, a DurableAgent is triggered by a TriggerAction message on its pub/sub topic. An activation hook lets an extension stand up any event source and translate its events into agent runs — entirely from a separate package, with no changes to agent code.

How it works

1. An extension registers a callback: agent.add_activation(cb).
2. When the agent is hosted via any AgentRunner entry point — serve(), subscribe(), register_routes(), workflow(), or run() — the runner fires each registered callback exactly once, passing an ActivationContext.
3. The callback opens its event source (a subscription, a route, a poller) and returns an optional closer — a zero-arg callable the runner invokes on shutdown().
4. For each external event, the extension schedules an agent run with ctx.runner.run(ctx.agent, payload={"task": ...}, wait=False).

The callback fires once per (runner, agent) pair. Hosting the same agent through several entry points (for example serve(), which calls subscribe() internally) still fires it only once.

The ActivationContext

Each callback receives an immutable ActivationContext. Treat every field as read-only.

Because app may be None, a robust extension branches on the transport: mount an HTTP route when ctx.app is available, otherwise open a streaming subscription through ctx.dapr_client.

Writing an extension

The canonical shape is a factory that builds an _activate(ctx) closure, registers it, and returns it (so it can also be used as a decorator over a mapper):

from dapr_agents import ActivationContext

def queue_trigger(agent, *, source, mapper=None):
    """Attach an external-queue trigger to an agent."""
    mapper = mapper or (lambda event: {"task": str(event)})

    def _activate(ctx: ActivationContext):
        # Branch on transport: no FastAPI app under subscribe()/workflow()/run().
        if ctx.app is not None:
            handle = _mount_route(ctx.app, ctx, mapper)      # HTTP-style source
        else:
            handle = _open_stream(ctx.dapr_client, source, ctx, mapper)  # streaming source

        closed = {"done": False}
        def _close():                       # closers MUST be idempotent
            if closed["done"]:
                return
            closed["done"] = True
            handle.cancel()
        return _close

    agent.add_activation(_activate)
    return _activate

def _open_stream(dapr_client, source, ctx, mapper):
    def on_event(event):
        task = mapper(event)               # translate to a TriggerAction payload
        if task:                            # return None from mapper to skip an event
            ctx.runner.run(ctx.agent, payload=task, wait=False)
    return dapr_client.subscribe_with_handler(...)   # returns a cancel handle