Dapr Agents on Dapr 文档库

简介

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents 是一个用于构建持久且弹性的 AI agent 系统的开发者框架，由大语言模型（LLMs）驱动。基于久经考验的 Dapr 项目构建，它使开发者能够创建具有身份、能够推理问题、做出动态决策并无缝协作的自主系统。它包含内置的可观测性和有状态工作流执行，确保 agent 工作流无论复杂度如何都能成功完成。无论您是开发单 agent 应用还是复杂的多 agent 工作流，Dapr Agents 都为智能、自适应系统提供可在跨环境中扩展的基础设施。

核心能力

Agent 身份：使用 Dapr Agents，每个 agent 都被分配一个唯一的加密身份，用于对 agent 交互进行身份认证并在服务和基础设施间强制执行授权。
持久执行：使用 Dapr Agents 创建的 agent 由 Dapr 的工作流引擎支持，该引擎将每个 agent 与 LLMs 和工具的交互持久化到持久状态存储中，即使在 agent 重启后也能恢复并继续执行。
弹性：Dapr Agents 可以通过自动重试策略、超时和熔断器从临时故障中恢复，还可以应用由工作流状态支持的持久重试以从持续时间更长的故障中恢复。
规模与效率：在单核上高效运行数千个 agent。Dapr 在机器集群间透明地分发单 agent 和多 agent 应用并处理它们的生命周期。
数据驱动 Agent：通过连接到数十种不同的数据源，直接与数据库、文档和非结构化数据集成。
多 Agent 系统：默认安全和可观测，支持 agent 之间的协作。
Kubernetes 原生：在 Kubernetes 环境中轻松部署和管理 agent。
平台就绪：访问范围和声明式资源使平台团队能够将 Dapr Agents 集成到其系统中。
供应商中立与开源：避免供应商锁定，并在云和本地部署间获得灵活性。

核心功能

Dapr Agents 提供专为创建智能、自主系统设计的专用模块。每个模块都设计为独立工作，允许您使用适合应用程序需求的任何组合。

入门指南

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents 概念

如果你想了解 Dapr Agents 的入门概述，并希望学习更多 Dapr Agents 基本术语，我们建议你先阅读介绍和核心概念部分。

安装 Dapr CLI

虽然 Dapr Agents 中的简单示例可以在不使用边车的情况下运行，但推荐模式是使用 Dapr 边车。要充分利用 Dapr Agents 的全部功能，请安装 Dapr CLI，用于在本地或 Kubernetes 上运行 Dapr 进行开发。完整的分步指南，请参阅 Dapr CLI 安装页面。

通过重启终端/命令提示符并运行以下命令来验证 CLI 是否已安装：

dapr -h

在本地模式下初始化 Dapr

注意

请确保已安装 Docker。

在本地初始化 Dapr 以设置用于开发的自托管环境。此过程会获取并安装 Dapr 边车二进制文件、将必要的服务作为 Docker 容器运行，并为你的应用程序准备一个默认组件文件夹。详细步骤，请参阅官方本地初始化 Dapr 指南。

要初始化 Dapr 控制平面容器并创建默认配置文件，请运行：

dapr init

验证你拥有运行中的容器实例，这些实例使用 daprio/dapr、openzipkin/zipkin 和 redis 镜像：

docker ps

安装 Python

注意

请确保已安装 Python。Python >=3.11。安装说明，请访问官方 Python 安装指南。

安装 uv

Dapr Agents 快速入门使用 uv 作为 Python 包管理器。按照 uv 安装指南进行安装。

为什么选择 Dapr Agents

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents 是一个用于构建和编排基于 LLM 的自主代理的开源框架，它利用 Dapr 经过验证的分布式系统基础。与要求开发者从零开始构建基础设施的其他代理框架不同，Dapr Agents 通过提供企业级的可扩展性、状态管理和消息传递能力，使团队能够专注于代理智能。这种方法消除了重新创建分布式系统基础组件的复杂性，同时提供了由 Dapr 支持的代理工作流。

现有框架的挑战

当今许多代理框架试图通过开发自己的平台来重新定义微服务的构建和编排方式，以处理核心的分布式系统能力。虽然这些努力展示了创新，但在扩展或适应新环境时，往往导致学习曲线陡峭、系统分散和不必要的复杂性。

这些框架要求开发者采用全新的范式或重新创建基础架构，而不是基于现有的、被证明能够在规模上处理这些挑战的解决方案。这种额外的复杂性分散了对主要目标的关注：设计和实现智能、有效的代理。

Dapr Agents 如何解决这些问题

Dapr Agents 采用了一种不同的方法，它基于 Dapr 构建，利用其经过验证的 API 和模式，包括工作流、发布订阅消息、状态管理和服务通信。这种集成消除了从零开始重新创建基础组件的需要。

通过与 Dapr 的运行时和模块化组件集成，Dapr Agents 赋予开发者构建和部署代理的能力，这些代理可以作为更大系统内的协作服务工作。无论是试验单个代理还是编排涉及多个代理的工作流，Dapr Agents 都允许团队专注于 LLM 驱动的代理的智能和行为，同时利用经过验证的框架来实现可扩展性和可靠性。

原则

代理中心设计

Dapr Agents 的设计理念是将由 LLM 驱动的代理置于任务执行和工作流编排的核心。这一原则强调：

LLM 驱动的代理：Dapr Agents 使创建能够利用 LLM 进行推理、动态决策和自然语言交互的代理成为可能。
自适应任务处理：Dapr Agents 中的代理配备了灵活的模式，如工具调用和推理循环（例如 ReAct），使它们能够自主处理复杂且不断变化的任务。
多代理系统：Dapr Agents 的框架允许代理作为模块化的、可复用的构建块，无缝集成到工作流中，无论是独立运行还是协作运行。

虽然 Dapr Agents 以代理为中心，但它也认识到在确定性工作流或更简单的任务序列中直接使用 LLM 的多功能性。在代理内置的任务处理模式（如 tool calling 或 ReAct 循环）不必要的场景中，LLM 可以作为推理和决策的核心组件。这种灵活性确保用户可以调整 Dapr Agents 以满足各种需求，而不局限于单一方法。

注意

代理可以独立使用并在后台创建工作流，或者作为确定性工作流中的自主步骤使用。

核心概念

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents 提供了一种结构化方式，用于构建和编排使用 LLM 的应用，让你无需陷入基础设施细节，同时具备持久性保证。它的核心目标，是通过抽象掉 LLM、工具、内存管理以及分布式系统的复杂性，使开发者能够把注意力集中在 AI 应用的业务逻辑上。在这一框架中，agent 是最基础的构建块。

Agents

Agent 是由大语言模型（LLM）驱动的自治单元，旨在执行任务、对问题进行推理，并在工作流中协作。作为智能构建块，agent 将推理能力与工具集成、内存和协作特性结合起来，以达成目标结果。

Dapr Agents 提供两类 agent，分别适用于不同场景：

Agent

已弃用

Agent 类自 v1.0.0-rc.1 起已弃用，未来版本将被移除。所有新开发都应使用 DurableAgent。

Agent 类是一种会话式 agent，使用语言模型管理工具调用与对话。它提供同步执行，并内置对话记忆。

@tool
def my_weather_func() -> str:
 """获取当前天气。"""
 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?")

这个示例展示了如何创建一个带工具集成的简单 agent。该 agent 会同步处理查询，并借助 Dapr State Store API 在多次交互之间保持对话上下文。

代理模式

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents 简化了代理系统的实现，从简单的增强型 LLM 到企业环境中的完全自主代理。以下各节描述了可以从 Dapr Agents 中受益的多种应用模式。

概述

代理系统使用设计模式（如反思、工具使用、规划和多代理协作）来实现比简单单次提示交互更好的结果。与其将"代理"视为二元分类，不如将系统视为具有不同程度代理性的系统更有用。

这一范围从简单的工作流（仅提示模型一次）到能够以更大自主性执行多个迭代步骤的复杂系统。有两种基本的架构方法：

工作流：通过预定义代码路径编排 LLM 和工具的系统（更具规范性）
代理：LLM 动态引导自身流程和工具使用的系统（更具自主性）

一端是可预测的工作流，具有明确定义的决策路径和确定性结果。另一端是能够动态引导自身策略的 AI 代理。虽然完全自主的代理看似吸引人，但工作流通常为明确定义的任务提供更好的可预测性和一致性。这与企业对可靠性和可维护性的要求一致。

本文档中的模式从增强型 LLM 开始，然后介绍基于工作流的方法（提供可预测性和控制），再转向更具自主性的模式。每个模式都针对特定的使用场景，并在确定性结果和自主性之间提供不同的权衡。

增强型 LLM

增强型 LLM 模式是任何代理系统的基础构建块。它通过外部能力（如记忆和工具）增强语言模型，为 AI 驱动应用提供基本但强大的基础。

此模式非常适合需要增强型 LLM 但不需要复杂编排或自主决策的场景。增强型 LLM 可以访问外部工具、维护对话历史，并在交互中提供一致的响应。

使用场景：

记住用户偏好的个人助手
访问产品信息的客户支持代理
检索和分析信息的研究工具

使用 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 自动处理：

集成

Mon, 01 Jan 0001 00:00:00 +0000

开箱即用工具

文本分割器

文本分割器模块是 Dapr Agents 中的一个基础集成，专为检索增强生成（RAG）工作流和其他 上下文学习 应用预处理文档而设计。其主要目的是将大型文档拆分为更小的、有意义的块，以便进行嵌入、索引和基于用户查询的高效检索。

通过关注可管理的块大小并通过重叠保留上下文完整性，文本分割器确保文档的处理方式能够支持问答、摘要和文档检索等下游任务。

为什么要使用文本分割器？

在构建 RAG 管道时，将文本拆分为更小的块有以下几个关键目的：

实现有效索引：块被嵌入并存储在向量数据库中，使其能够基于与用户查询的相似性进行检索。
保持语义连贯性：重叠的块有助于在分割之间保留上下文，确保系统能够连接相关信息。
处理模型限制：许多模型有输入大小限制。拆分确保文本在这些限制范围内同时保持有意义。

这一步对于将知识准备为可嵌入的搜索格式至关重要，是基于检索的工作流的基础。

文本拆分策略

文本分割器支持多种策略来有效处理不同类型的文档。这些策略在每个块的大小和保持上下文的需求之间取得平衡。

1. 基于字符的长度

工作原理：计算每个块中的字符数。
适用场景：简单有效，无需依赖外部分词工具即可进行文本拆分。

示例：

from dapr_agents.document.splitter.text import TextSplitter

# 基于字符的分割器（默认）
splitter = TextSplitter(chunk_size=1024, chunk_overlap=200)

2. 基于令牌的长度

工作原理：计算令牌数量，即语言模型使用的语义单元（例如单词或子词）。
适用场景：确保与 GPT 等模型的兼容性，令牌限制至关重要。

示例：

import tiktoken
from dapr_agents.document.splitter.text import TextSplitter

enc = tiktoken.get_encoding("cl100k_base")

def length_function(text: str) -> int:
 return len(enc.encode(text))

splitter = TextSplitter(
 chunk_size=1024,
 chunk_overlap=200,
 chunk_size_function=length_function
)

定义块大小函数的灵活性使文本分割器能够适应各种场景。

块重叠

为了保留上下文，文本分割器包含块重叠功能。这确保了一个块的部分内容延续到下一个块，有助于在顺序处理块时保持连续性。

示例：

当 chunk_size=1024 且 chunk_overlap=200 时，一个块的最后 200 个令牌或字符会出现在下一个块的开头。
这种设计有助于文本生成等任务，在这些任务中跨块保持上下文至关重要。

如何使用文本分割器

以下是使用文本分割器处理 PDF 文档的实用示例：

步骤 1：加载 PDF

import requests
from pathlib import Path

# Download PDF
pdf_url = "https://arxiv.org/pdf/2412.05265.pdf"
local_pdf_path = Path("arxiv_paper.pdf")

if not local_pdf_path.exists():
 response = requests.get(pdf_url)
 response.raise_for_status()
 with open(local_pdf_path, "wb") as pdf_file:
 pdf_file.write(response.content)

步骤 2：读取文档

在此示例中，我们使用 Dapr Agents 的 PyPDFReader。

快速入门

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents 快速入门展示了如何使用 Dapr Agents 构建具有 LLM 驱动的自主代理和事件驱动工作流的应用程序。快速入门是一个单一渐进式教程，从基本 LLM 调用逐步构建到持久代理、工作流、多代理编排和可观测性。

开始之前

设置本地 Dapr 环境。
安装 uv（快速入门使用的 Python 包管理器）。
安装 Ollama 进行本地 LLM 推理（默认），或获取 OpenAI API 密钥。

Dapr Agents 基础

Dapr Agents 基础快速入门在单个编号 Python 脚本目录中覆盖了完整的 Dapr Agents 编程模型。每一步都构建在前一步之上。

步骤	文件	你将学到
1	`01_llm_client.py`	使用 `DaprChatClient` 通过 Dapr Conversation API 调用 LLM
2	`02_durable_agent_http.py`	运行由 Dapr 工作流支持的持久代理，通过 HTTP 暴露
3	`03_durable_agent_pubsub.py`	通过发布订阅而非 HTTP 触发持久代理
4	`04_workflow_llm.py`	构建调用 LLM 作为活动的确定性 Dapr 工作流
5	`05_workflow_agents.py`	将多个专业代理编排为子工作流
6	`06_durable_agent_tracing.py`	使用 Zipkin 为代理和工作流启用分布式追踪
7	`07_durable_agent_hot_reload.py`	通过 Dapr Configuration Store 在运行时热重载代理配置

有关完整的设置说明，包括 LLM 配置和先决条件，请参阅快速入门 README。