Dapr Agents：用于智能体 AI 系统的框架

Dapr Agents 是一个开发者框架，旨在构建可大规模运行且具备生产级弹性的 AI 智能体系统。它基于久经考验的 Dapr 项目构建，使软件开发者能够利用大型语言模型 (LLM) 创建具有推理、行动和协作能力的 AI 智能体，同时借助内置的可观测性和有状态工作流执行机制，确保无论工作流多么复杂，都能成功完成。

核心特性

• 规模化与高效性：在单个核心上高效运行数千个智能体。Dapr 可透明地将单智能体和多智能体应用分布到多台机器组成的集群中，并管理其生命周期。
• 工作流弹性：自动重试智能体工作流，确保任务顺利完成。
• Kubernetes 原生：轻松在 Kubernetes 环境中部署和管理智能体。
• 数据驱动型智能体：通过连接数十种不同的数据源，直接集成数据库、文档和非结构化数据。
• 多智能体系统：默认安全且可观测，支持智能体之间的协作。
• 厂商中立与开源：避免厂商锁定，在云端和本地部署中实现灵活性。
• 平台就绪：通过访问作用域和声明式资源，平台团队可以将 Dapr Agents 集成到其系统中。

为什么选择 Dapr Agents？

将可扩展的工作流作为一等公民

Dapr Agents 使用 持久化执行工作流引擎，可在网络中断、节点崩溃及其他类型的破坏性故障发生时，确保每个智能体任务都能执行到完成。开发者无需了解工作流引擎的底层概念——只需编写一个执行任意数量任务的智能体，这些任务就会自动分布到整个集群中。如果任何任务失败，它会自动重试，并从上次中断的地方恢复状态。

成本效益高的 AI 采用

Dapr Agents 构建于 Dapr 的 Workflow API 之上，该 API 在底层使用了 actor 模型——这是一种线程安全且原生分布式、兼具计算和状态功能的单一单元，非常适合构建智能体规模为零的架构。这最大限度地降低了基础设施成本，使每个人都能轻松采用 AI 技术。基于虚拟 actor 的底层模型允许数千个智能体按需在单核机器上运行，从零扩展时延迟仅为两位数毫秒级。当智能体未被使用时，系统会回收它们，但会保留其状态，直到下次需要时再重新激活。这种设计使得性能与资源效率之间无需权衡。

数据为中心的 AI 智能体

凭借与超过 50 种企业级数据源的内置连接，Dapr Agents 能够高效处理结构化和非结构化数据。从简单的 PDF 提取 到大规模的数据库交互，它只需极少的代码更改即可实现无缝的数据驱动型 AI 工作流。Dapr 的 绑定组件 和 状态存储组件 提供了对大量数据源的访问，可用于将数据摄入到智能体中。

加速开发

Dapr Agents 提供了一组 AI 功能，为开发者提供了完整的 API 表面来解决常见问题。其中包括：

• 多智能体通信
• 结构化输出
• 多个 LLM 提供商
• 上下文记忆
• 灵活的提示工程
• 智能工具选择
• MCP 集成。

集成的安全性与可靠性

通过构建在 Dapr 之上，平台和基础设施团队可以将 Dapr 的 弹性策略 应用到 Dapr Agents 所使用的他们所选的数据库和/或消息代理上。这些策略包括超时、重试/退避以及断路器机制。在安全性方面，Dapr 提供了将对特定数据库或消息代理的访问范围限定于一个或多个智能体应用部署的选项。此外，Dapr Agents 使用 mTLS 对其底层组件的通信层进行加密。

内置消息传递与状态基础设施

• 🎯 服务间调用：通过内置的服务发现、错误处理和分布式追踪功能，促进代理之间的直接通信。代理可以利用这一功能在多代理工作流中实现同步消息传递。
• ⚡️ 发布与订阅：通过共享的消息总线支持代理之间的松耦合协作。这实现了实时的事件驱动型交互，对于任务分配和协调至关重要。
• 🔄 持久化工作流：定义长期运行、持久化的工作流，将确定性流程与基于大语言模型的决策相结合。Dapr Agents 利用这一点无缝编排复杂的多步骤代理工作流。
• 🧠 状态管理：为代理提供灵活的键值存储，以便在多次交互中保留上下文信息，确保工作流中的连续性和适应性。
• 🤖 Actor 模式：实现虚拟 Actor 模式，使代理能够作为自包含的状态单元按顺序处理消息。这消除了并发问题，并提升了代理系统的可扩展性。

供应商中立与开源

作为 CNCF 的一部分，Dapr Agents 具备供应商中立性，从而避免了供应商锁定、知识产权风险或专有技术限制等问题。组织可以使用开源软件来构建自己的 AI 应用程序，既享有完全的灵活性和控制权，又能够进行审计和贡献。

路线图

请查看 项目视图，了解我们正在开发的一些主要功能：

如需完整的议题列表（包括 bug 修复），请访问我们的 GitHub 问题页面。

语言支持

语言	当前状态	开发状态	稳定状态
Python	开发中	预计 2025 年第二季度	预计 2025 年第四季度
其他语言	待定	待定	待定

文档

• 文档

社区

参与 Dapr Agents 的贡献

请参阅我们的 Dapr 社区行为准则。

有关开发环境搭建和指导原则，请参阅我们的 开发指南。

贡献者快速入门：

1. 安装依赖：uv sync --group dev --group test
2. 安装 pre-push 钩子：pre-commit install --hook-type pre-push
3. 进行更改并运行测试：uv run pytest tests -m "not integration"
4. 推送您的更改——钩子会自动运行。

开始使用

先决条件：

• Dapr CLI
• Python >=3.11
• uv

安装 Dapr Agents

dapr init
uv init
uv add dapr-agents

运行快速入门示例

如需对 Dapr Agents 的基础知识进行高层次介绍，请参阅我们的 快速入门。

运行示例

在快速入门中熟悉了项目的基础知识后，您可以进一步深入学习 示例。

加入我们

Dapr Agents 是 CNCF 下属的一个开源项目，我们欢迎全球开发者和组织的参与！

• GitHub 仓库：https://github.com/dapr/dapr-agents
• 文档：https://docs.dapr.io/developing-applications/dapr-agents/
• 社区 Discord：加入讨论。
• 贡献：打开一个议题或提交一个拉取请求，帮助改进 Dapr Agents！

Dapr Agents 快速上手指南

Dapr Agents 是一个用于构建生产级、高弹性 AI 智能体系统的开发框架。它基于成熟的 Dapr 项目，帮助开发者利用大语言模型（LLM）创建能够推理、行动和协作的 AI 智能体，同时提供内置的可观测性和有状态的工作流执行能力。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：支持 Linux, macOS 或 Windows (WSL2 推荐)
• Python 版本：>= 3.11
• 前置依赖工具：
  • Dapr CLI：用于管理 Dapr 运行时。
  • uv：高性能的 Python 包管理器。

提示：国内开发者若遇到下载缓慢问题，可配置 uv 使用国内镜像源（如清华源或阿里源）：

export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

按照以下命令快速初始化项目并安装 Dapr Agents：

1. 初始化 Dapr 运行时（如果尚未安装）：

   dapr init
   

2. 创建新的 Python 项目：

   uv init my-dapr-agent
   cd my-dapr-agent
   

3. 安装 Dapr Agents 库：

   uv add dapr-agents
   

基本使用

Dapr Agents 的核心优势在于其“耐用执行”（Durable Execution）工作流引擎，它能自动处理网络中断、节点故障等异常情况，确保智能体任务完成。

以下是一个最简单的概念性示例，展示如何定义一个基本的智能体工作流。更多详细案例请参考项目中的 quickstarts 和 examples 目录。

示例：创建一个简单的智能体任务

创建一个名为 agent_app.py 的文件：

from dapr.agents import Agent, WorkflowContext
import asyncio

# 定义智能体类
class MySimpleAgent(Agent):
    async def run(self, ctx: WorkflowContext, input_data: str) -> str:
        # 步骤 1: 记录开始状态 (状态会自动持久化)
        ctx.log(f"收到任务：{input_data}")
        
        # 步骤 2: 模拟调用 LLM 或外部工具进行推理
        # 在实际场景中，这里会集成具体的 LLM Provider
        reasoning_result = f"已处理数据：{input_data} - 分析完成"
        
        # 步骤 3: 返回结果
        return reasoning_result

# 入口点
if __name__ == "__main__":
    # 注意：实际运行通常需要通过 dapr run 命令启动以获得完整的工作流和演员模型支持
    # 例如：dapr run --app-id my-agent -- python agent_app.py
    print("Dapr Agent 定义完成。请使用 'dapr run' 命令启动应用以体验完整功能。")

运行智能体

使用 dapr run 命令启动应用，这将激活 Dapr 的侧车（Sidecar），提供状态管理、消息传递和工作流编排能力：

dapr run --app-id my-simple-agent -- python agent_app.py

下一步

• 快速入门教程：查看 ./quickstarts/README.md 了解核心概念。
• 完整示例：查看 ./examples/README.md 学习多智能体协作、数据库集成及复杂工作流编排。
• 官方文档：访问 Dapr Agents 文档 获取 API 参考和深度指南。