Dapr Agents: Durable LLM Workflows on the Dapr Runtime

What Dapr Agents Actually Solves

An LLM agent that calls tools is a long-running process with side effects. It reads a database, calls an API, writes a record, then asks the model what to do next. If the machine dies halfway through, the work is gone and the side effects may already have happened. Dapr Agents targets that gap. The README describes it as a developer framework for "production-grade resilient AI agent systems that operate at scale", built on top of Dapr and using a durable-execution workflow engine that "guarantees each agent task executes to completion in the face of network interruptions, node crashes and other types of disruptive failures".

The audience is narrower than the pitch suggests. This is for Python developers who are past the notebook stage and need agents to run as services, with retries, state and telemetry handled by infrastructure rather than by code they wrote. The pyproject.toml requires Python >=3.11,<3.14, so a team on 3.10 or on a 3.14 preview is out before anything else is considered. The examples directory shows the intended shape of the work: 01-llm-call-open-ai, 02-durable-agent-tool-call, 03-agent-based-workflows, 04-multi-agent-workflows, and so on. A durable tool call is a first-class example, not an afterthought.

Actors, Workflows and the Dapr Sidecar

The mechanism is not a scheduler written inside the library. Dapr Agents builds on Dapr's Workflow API, which the README states uses actors "under the hood", described as "a single unit of compute and state that is thread-safe and natively distributed". Each agent is a virtual actor with state. The runtime decides which machine hosts it, and the workflow engine records progress so a failed step can resume from where it stopped rather than from the beginning.

That design is what makes scale-to-zero plausible. The README claims the virtual actor model allows "thousands of agents to run on demand on a single core machine with double-digit millisecond latency when scaling from zero", and that idle agents are reclaimed while keeping their state until needed again. Treat those numbers as the project's own claims, not as measured results. The architectural consequence is more interesting than the figure: because agents are addressed as actors, the application code does not contain placement logic, and the sidecar handles service discovery, mTLS and tracing.

Multi-agent coordination rides on the same runtime. The README lists service-to-service invocation for synchronous messaging and publish/subscribe over a message bus for event-driven task distribution, alongside the durable workflow building block. In practice that means the transport between agents is a Dapr component you configure, not an import you add.

Installing dapr-agents and Running a First Durable Agent

The package is published on PyPI as dapr-agents. The repository uses uv for its own development, and the Makefile installs test dependencies with pip install -e .[test]. For a first run, create an environment on a supported Python and install the package.

python -m venv .venv
source .venv/bin/activate
pip install dapr-agents

After installation, the importable package is dapr_agents, which is also the coverage target named in the Makefile. The next step is a running Dapr sidecar, because the workflow and state building blocks come from it. The repository ships a .devcontainer directory and a quickstarts directory, which is where you should look for the supported local setup rather than inventing one.

The examples are the real documentation. Start with the durable tool call example, since it exercises the retry path that distinguishes this framework from a plain agent loop.

cd examples/02-durable-agent-tool-call
ls

Each example directory is self-contained. The README does not spell out a single universal run command for them, so read the files in the directory you pick. If you want the smallest possible check that the runtime is wired correctly, examples/10-agent-executor-echo is the one to open first. When you run an example, the thing to watch for is the sidecar log: workflow scheduling, actor placement and state writes appear there, not in your agent's stdout.

MCP Auto-Discovery and Data Sources

Tool integration is the part of Dapr Agents that differs most from a typical Python agent framework. The README advertises "Zero-config MCP integration" where agents "auto-discover MCPServer tools from the Dapr sidecar". The repository backs this up with examples for each MCP transport: 06-agent-mcp-client-sse, 06-agent-mcp-client-stdio, 06-agent-mcp-client-streamablehttp, 06-agent-mcp-dapr-workflow, and an MCPServer example at 10-mcpserver.

The trade-off is visible in that list. Auto-discovery is convenient because tool registration moves out of the agent and into infrastructure, which means one deployment can expose tools to several agents without each one importing a client. It also means the sidecar is now part of your tool-calling path. If the sidecar is unhealthy, the agent does not fall back to a direct connection; the tools are simply not there. For a local prototype, that is friction with no payoff.

Data access follows the same pattern. The README states the framework has "built-in connectivity to over 50 enterprise data sources" through Dapr bindings and state stores, and points to PDF extraction as an example. The count comes from Dapr's component catalog, not from code in this repository. What this repository contributes is the agent-facing layer on top of those components.

Where Dapr Agents Is the Wrong Choice

The dependency list is the clearest signal of the cost. Installing dapr-agents pulls in dapr, dapr-ext-fastapi and dapr-ext-workflow, all pinned to the 1.18.0rc0 to 1.19.0 range, plus fastapi, uvicorn, aiohttp, cloudevents, protobuf, opentelemetry-api and more. That is a service runtime, not a library. For a script that summarizes a document once, you are paying for durability and messaging you will never use.

The second limitation is operational. Durable workflows need somewhere to keep their state, and the workflow engine needs a Dapr control plane. The README does not document rollback, and it does not describe what happens to in-flight agent workflows when the Dapr version changes. Note the version pins: the three Dapr packages are constrained to a release-candidate line, which means upgrading Dapr Agents may require upgrading your Dapr installation in step. Teams that cannot move their cluster on that cadence should treat this as a blocker.

Third, the abstraction hides the failure mode. The README says developers "do not need to know about the underlying concepts of the workflow engine", and that is true until something stalls. When a workflow does not complete, the diagnosis lives in Dapr's workflow and actor subsystems, and the skills you need are Dapr skills, not agent skills. If nobody on the team has run Dapr in production, the first incident will be expensive.

How It Compares to LangGraph

LangGraph is the comparison people search for, and the difference is architectural rather than feature-level. LangGraph expresses an agent as a graph of nodes and edges inside your Python process, with checkpointers that persist state to a store you configure. Dapr Agents expresses an agent as an actor managed by an external runtime, with the workflow engine, placement and transport living in the sidecar.

The practical difference shows up in two places. First, deployment: a LangGraph application is a Python process you can run anywhere Python runs, while Dapr Agents expects a Dapr sidecar and, for the Kubernetes examples, a cluster. Second, failure handling: LangGraph resumes from a checkpoint your code decides to write, while Dapr Agents delegates retry and recovery to the workflow engine. Neither is strictly better. The LangGraph model is easier to debug locally and easier to embed in an existing service. The Dapr model is easier to operate at fleet scale and gives you mTLS, scoped component access and resiliency policies without writing them.

If you are already running Dapr for other services, the second model costs you almost nothing extra. If you are not, you are adopting two systems, and the agent framework is the smaller of them.

Licence, Maintenance and Upgrade Cost

Dapr Agents is licensed under Apache-2.0, with the licence file at the repository root and the standard Apache header reproduced at the top of source files including pyproject.toml and the Makefile. Apache-2.0 includes an explicit patent grant and permits commercial use and modification. It also requires that you preserve the licence and attribution notices in redistributed code. Whether that interacts with your own licensing is a question for your legal team, not something to settle from a README.

The repository is not archived, and the last push was on 2026-09-10, ten days before this writing. Releases are frequent and small: v1.0.3 on 2026-05-19, v1.0.4 on 2026-06-11, v1.0.5 on 2026-06-15. The gap between the last release and the last push suggests the main branch is ahead of the published artifacts, so pinning to a release tag and pinning to main are different decisions here.

Upgrade cost is dominated by the Dapr version constraints, not by the agent code. Because dapr, dapr-ext-fastapi and dapr-ext-workflow are all bounded to the same minor range, a Dapr Agents upgrade is usually a Dapr upgrade. The repository has a pre-commit configuration and a Makefile target, hooks-run-all, that runs formatting, linting, type checking and unit tests before integration tests, which is the workflow a contributor would follow. For a consumer, the equivalent check is running your own agent workflows against the new Dapr version in a staging cluster before touching production.

Editorial conclusion

Adopt Dapr Agents if you already run Dapr or Kubernetes and need agent tasks that survive node crashes, retries and restarts, and if your team accepts a sidecar in the loop. Do not adopt it for a single-process prototype or a script that calls one model once; a plain agent library will get you there with less moving parts. Before committing, verify that your Python version is inside the requires-python range, that a Dapr control plane is available in your target environment, and that the workflow and actor building blocks are enabled there.

Frequently asked questions

Official sources

1. dapr/dapr-agents on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases