第2章 基于 Azure Durable Task 构建持久化 Pydantic AI Agent
一名客服支持人员接到工单:订单 A-1001 到货时已损坏。它向模型询问处理方式,查询订单,再次询问模型,然后发起退款。此时运行它的 worker 可能因一次部署、缩容事件或内存溢出而被杀掉,进程随之带走它对这个运行过程的全部记忆。
从头重跑一遍,模型请求要付费两次,订单 API 要调用两次,甚至可能给客户退两次款。不重跑,工单就半途搁置,直到有人发现。
Durable Task 是微软针对这个问题的答案,也是 Azure Durable Functions 背后的引擎。你用普通 Python 代码编写 orchestrator,它委派出去的工作以 activity 形式运行,Azure Durable Task Scheduler 会记录每个已完成 activity 的结果。当某个 worker 挂掉时,另一个 worker 接管编排,回放已记录的结果,从中断的那一步继续执行。
Pydantic AI Harness 现已推出 AzureDurableTaskDurability,这个 capability 把 agent 循环纳入上述模型。默认情况下,模型请求、函数工具调用、MCP 调用和 durable capability 操作各自作为一个 Durable Task activity 运行。在编排之外,agent 的运行方式和以前完全一样。Azure 团队也在他们那边发布了公告,见 Introducing Azure Durable Task for Pydantic AI agents。
快速上手 uv add logfire "pydantic-ai-harness[azure-durable-task]" "pydantic-ai-slim[anthropic]"
azure-durable-task 这个 extra 会安装 Durable Task Python SDK、Azure 托管的 worker 和 client,以及 azure-identity。示例使用 Anthropic,但 Pydantic AI 支持的任何 provider 都可以。Pydantic Logfire 会自动埋点 agent,每次运行都会呈现为一条 trace,包含所有模型请求、工具调用和 activity。
运行示例前,先设置模型 provider 的 key 和 Logfire 写入 token: export ANTHROPIC_API_KEY='your-anthropic-api-key' export LOGFIRE_TOKEN='your-logfire-write-token'
本地开发时,用 Docker 启动 Durable Task Scheduler 模拟器: docker run --rm --name dts-emulator \ -p 127.0.0.1:8080:8080 -p 127.0.0.1:8082:8082 \ mcr.microsoft.com/dts/dts-emulator:v0.0.9
模拟器在 8080 端口为 SDK 提供一个名为 default 的 task hub,其仪表盘在 http://localhost:8082。暂时还不需要 Azure 订阅。 一个持久化的客服 agent 给 agent 挂上 capability,为其命名,然后编写 orchestrator。这个名字会作为 agent 注册的每个 activity 的前缀,因此会被记录进编排历史。把下面代码保存为 support_agent.py: from collections.abc import Generator
import logfire from durabletask import task from pydantic_ai import Agent, RunContext from pydantic_ai_harness.azure_durable_task import AzureDurableTaskDurability, run_durable
logfire.configure(service_name='support-agent') logfire.instrument_pydantic_ai()
agent = Agent( 'anthropic:claude-sonnet-5-5', name='support', instructions='Look up the order, then refund it if it arrived damaged.', capabilities=[AzureDurableTaskDurability()], )
@agent.tool_plain def lookup_order(order_id: str) -> dict[str, str]: return {'order_id': order_id, 'status': 'delivered', 'note': 'box arrived crushed', 'total': '42.00'}
@agent.tool def issue_refund(ctx: RunContext[None], order_id: str, amount: str) -> str: idempotency_key = f'{ctx.run_id}:{ctx.tool_call_id}' logfire.info('refund {order_id} {amount}', order_id=order_id, amount=amount, idempotency_key=idempotency_key) # Stub: call your payments API here with idempotency_key, so a repeated call is a no-op. return f'Refunded {amount} on {order_id}'
def support(ctx: task.OrchestrationContext, prompt: str) -> Generator[task.Task[object], object, str]: result = yield from run_durable(ctx, lambda: agent.run(prompt)) return result.output
这两个工具就是普通的 Pydantic AI 工具。issue_refund 只是个 stub,把退款记录到 Logfire 而不真的动钱,所以示例不需要支付账户就能跑起来。为了让它们持久化,工具本身无需任何改动,除了幂等 key——后面讲回放的章节会解释它。
run_durable 是 Durable Task 生成器风格与异步 agent 运行之间的桥梁,在工作流中 agent 该出现的位置调用它即可。Orchestrator 需返回 JSON 兼容的输出。如果 agent 的 output_type 是 Pydantic 模型,就返回 result.output.model_dump(mode='json')。
最后,在 main.py 中启动 worker 并调度一次编排: import logfire from durabletask.client import TaskHubGrpcClient from durabletask.worker import TaskHubGrpcWorker
from support_agent import AzureDurableTaskDurability, agent, support
emulator = dict(host_address='localhost:8080', metadata=[('taskhub', 'default')], secure_channel=False)
worker = TaskHubGrpcWorker(emulator) worker.add_orchestrator(support)
durability = AzureDurableTaskDurability.from_agent(agent) assert durability is not None
with durability.register(worker), worker, TaskHubGrpcClient(emulator) as client: worker.start() with logfire.span('support ticket A-1001'): instance_id = client.schedule_new_orchestration( support, input='Order A-1001 arrived damaged. Please sort it out.' ) state = client.wait_for_orchestration_completion(instance_id, timeout=60) assert state is not None state.raise_if_failed() print(state.get_output())
Agent 会为每个 capability 绑定自己的副本,所以要用 from_agent 取出已绑定的那个。register(worker) 要在 worker 启动前进入、在 worker 停止后退出,它负责注册 agent 的 activity 并运行它们。Orchestrator 和 client 就是普通的 Durable Task SDK 代码,client 甚至可以放在一个从不导入 agent 的独立进程里。logfire.span 包裹的是 client 代码,永远不会被回放,所以每张工单在 Logfire 里只出现一次。
worker 挂掉时会发生什么 我用上面的 agent 对着模拟器跑了一遍,并在 issue_refund 内部用 os._exit(1) 杀掉 worker——时机选在退款已执行、但其结果尚未送达 scheduler 之间。然后启动第二个 worker。为了验证,每个工具在函数体执行时都往文件追加一行: lookup_order A-1001 pid=10761 issue_refund A-1001 key=d3885ebc...:support:d6b9f9de...:toolu_01M455EcNkh3yCYePF2ieJAt pid=10761 issue_refund A-1001 key=d3885ebc...:support:d6b9f9de...:toolu_01M455EcNkh3yCYePF2ieJAt pid=10821
第一个 worker 发起了两次模型请求,执行了 lookup_order,然后在 issue_refund 内部挂掉。第二个 worker 没有重复前三个 activity,而是从历史中回放它们;issue_refund 因为结果从未被记录而重新执行了一次,接着发起最后一次模型请求,约一秒后完成编排: COMPLETED I've refunded order A-1001 in full, $42.00. The order was marked delivered, and its note said the box arrived crushed, which matches the damage you reported.
退款工具执行了两次。这就是持久化执行的真实面貌,由此引出下面几条规则。
回放与副作用 每当一个 activity 完成,SDK 都会从头重新运行你的 orchestrator,并从历史中提供所有已完成的结果。替补 worker 就是这样恢复编排的。这对 agent 的写法意味着几件事:
Activity 至少执行一次。worker 可能在工具的副作用发生后、结果被记录之前挂掉,就像上面的例子。务必让工具幂等。ctx.run_id 和 ctx.tool_call_id 在重启后保持不变,是理想的幂等 key:上面两条 issue_refund 记录携带的就是同一个 key。
Orchestrator 侧的代码在每次回放时都会执行。Hook、instruction 函数、输出校验器和内联工具必须是确定性的,不得做网络、文件或线程 I/O。把 I/O 放进工具,或放在 capability 的 @durable_operation 方法里。
名字会被持久化。Activity 名来自 agent 名、toolset ID 和工具名。只要还有使用它们的编排正在运行,就不要重命名其中任何一项。
回放成本随运行长度增长。每次回放都会把 agent 重跑到最新一步,因此 orchestrator 的 CPU 开销随步数呈平方增长。超长对话应拆分到独立编排中。
Span 会重复。在 orchestrator 代码中创建的 Pydantic AI span 每次回放都会再次发出,所以一次运行在 Logfire 里会多次出现 agent run 和模型请求的 span。
错误类型会变。模型请求或工具中抛出的异常到达 orchestrator 时会变成 durabletask.task.TaskFailedError。UserError 则保持原类型。
依赖的处理逻辑相同。它们以数据形式传入 activity,因此必须是 JSON 可序列化的(dataclass、Pydantic 模型和 JSON 值),activity 会根据 agent 的 deps_type 重建它们。数据库客户端和 HTTP session 应在用到它们的工具内部创建,而不是放在 deps 里。
等待期间不占用 activity 的审批 超过阈值的退款、生产环境部署、付款:某些工具调用需要人工点头。在 Durable Task 中,审批属于 orchestrator,编排会等待一个外部事件。等待期间没有任何 activity 在运行,所以审批花五分钟还是三天都无所谓。
给工具标记 requires_approval=True,并把 DeferredToolRequests 加入输出类型: from collections.abc import Generator
from durabletask.task import OrchestrationContext, Task from pydantic import TypeAdapter import logfire from pydantic_ai import Agent, DeferredToolRequests, DeferredToolResults, UserError from pydantic_ai_harness.azure_durable_task import AzureDurableTaskDurability, run_durable
logfire.configure(service_name='payment-review') logfire.instrument_pydantic_ai()
agent = Agent( 'anthropic:claude-sonnet-5-5', name='review', output_type=[str, DeferredToolRequests], capabilities=[AzureDurableTaskDurability()], )
@agent.tool_plain(requires_approval=True) def approve_payment(amount: int) -> str: return f'Paid {amount}'
def review(ctx: OrchestrationContext, prompt: str) -> Generator[Task[object], object, str]: result = yield from run_durable(ctx, lambda: agent.run(prompt)) while isinstance(result.output, DeferredToolRequests): requests = result.output event_name = f'review:{ctx.new_uuid()}' ctx.set_custom_status({ 'event': event_name, 'requests': TypeAdapter(DeferredToolRequests).dump_python(requests, mode='json'), }) payload = yield ctx.wait_for_external_event(event_name) approvals = TypeAdapter(dict[str, bool]).validate_python(payload, strict=True) if set(approvals) != {call.tool_call_id for call in requests.approvals}: raise UserError('Decisions must match the reviewed tool-call IDs exactly.') result = yield from run_durable( ctx, lambda: agent.run( message_history=result.all_messages(), deferred_tool_results=DeferredToolResults(approvals=dict(approvals)), usage=result.usage, conversation_id=result.conversation_id, ), ) ctx.set_custom_status(None) return result.output
Orchestrator 会把待审批的工具调用和一个新的事件名写入 custom status。你的审批 UI 通过 client.get_orchestration_state(instance_id) 读取该状态,把请求展示给人工,再用 client.raise_orchestration_event(instance_id, event_name, data={tool_call_id: True}) 把决定发回。agent 恢复时带着完整的消息历史和已累计的 usage。
有两个细节容易踩坑。每次暂停都用新的事件名,可以避免一个迟到的决定回应到后面某次审批上。另外 Durable Task 匹配事件名时不区分大小写,所以 tool-call ID 应放在 payload 里,绝不要放进事件名。Azure Durable Task 文档里有一个 submit_review 辅助函数,会在触发事件前检查审批是否仍处于待定状态。
按角色分别重试 通过传入原生的 RetryPolicy 值,可以分别为模型请求和工具调用设置重试策略: from datetime import timedelta
import logfire from durabletask.task import RetryPolicy from pydantic_ai_harness.azure_durable_task import AzureDurableTaskDurability
logfire.configure(service_name='support-agent') logfire.instrument_pydantic_ai()
durability = AzureDurableTaskDurability( model_options=RetryPolicy(first_retry_interval=timedelta(seconds=1), max_number_of_attempts=3), tool_options=RetryPolicy(first_retry_interval=timedelta(seconds=1), max_number_of_attempts=2), )
ModelRetry 和延迟调用属于 agent 控制流,不算 activity 失败,因此不会消耗重试次数。UserError 和序列化失败则完全不重试。需要更细粒度的控制时,resolve_tool_options 可以为每个工具返回一个策略,或返回 False,让纯函数工具直接在 orchestrator 中内联运行而非作为 activity。内联工具在每一步回放时都会执行,所以必须确定性且无 I/O。MCP 和动态工具始终以 activity 方式运行。
部署到 Azure 从模拟器切换到真实的 scheduler 时,需要改的是 worker 和 client。Orchestrator 和 register(worker) 保持不变: import logfire from azure.identity import DefaultAzureCredential from durabletask.azuremanaged.client import DurableTaskSchedulerClient from durabletask.azuremanaged.worker import DurableTaskSchedulerWorker
logfire.configure(service_name='support-worker', environment='production') logfire.instrument_pydantic_ai()
credential = DefaultAzureCredential()
endpoint = '
给 worker 的身份授予 scheduler 或 task hub 上的 Durable Task Data Contributor 角色。worker 和 client 要使用同一个 task hub,且每个环境单独一个 hub,避免 staging 的编排回放到生产 worker 上。
worker 是一个长驻的 Python 进程,部署在你现在跑这类进程的地方即可,比如 Azure Container Apps、AKS 或虚拟机。这个 capability 使用独立的 Durable Task SDK,不会向 Azure Functions 注册任何东西。
该选哪种持久化执行 Pydantic AI 可以在这些引擎上持久化运行。持久化执行概览为其中列出的引擎提供了完整示例,Azure Durable Task 文档则覆盖本篇介绍的集成:
Temporal DBOS Prefect Restate AWS Lambda Absurd pgtask Azure Durable Task Apache Airflow
Temporal 和 Restate 需要在 agent 前面部署一个服务器,详见 Restate 与 Pydantic AI 的实操指南。DBOS 在进程内运行,并把检查点写入你已有的数据库,详见 DBOS 与 Pydantic AI 的文章。当 agent 本来就以 Lambda 函数形式运行时,AWS Lambda 的持久化是自然之选。
如果你的基础设施在 Azure 上,Azure Durable Task 就是合适的选择。Durable Task Scheduler 是托管服务,你无需运行、打补丁或扩容任何编排服务器。身份验证用的是其他 Azure 服务已经在用的 DefaultAzureCredential。一旦你的身份在 scheduler 上拥有仪表盘角色,仪表盘就能展示每次编排和 activity,不需要额外部署什么工具。
常见问题 这需要 Azure Functions 吗? 不需要。这个 capability 使用独立的 Durable Task Python SDK 和你自己的 worker 进程。Azure Durable Functions 基于同一引擎构建,但本集成不会向它注册 orchestrator 或 activity。
能在编排中把 token 流式输出给用户吗? 不能直接给到客户端。流式模型响应会在模型请求 activity 内部缓冲,因为一个 activity 只返回一个被记录的结果。如果需要实时事件,可以给 capability 传入 event_stream_handler。它同样以 activity 方式运行,所以要像其他工具一样保证幂等。
工具能在 activity 里读取 ctx.messages 吗? 不能。在 activity 内部,ctx.messages 和 ctx.prompt 这类实时运行字段会抛出 UserError,工具也无法发出运行事件。activity 只能收到被序列化进去的内容:工具参数、deps 和运行标识符。
编排还在运行时重新部署会怎样? 回放按历史中记录的名字匹配 activity,所以重命名 agent、toolset 或工具会破坏已记录旧名字的编排。改动涉及重命名时,先让进行中的编排跑完旧 worker,或者让新版本使用全新的 task hub。
试一试 启动模拟器,给你现有的 agent 加上 AzureDurableTaskDurability(),把运行包进一个 orchestrator。然后在中途杀掉 worker,重新启动,在 localhost:8082 的仪表盘上看着运行从中断的那一步继续。
想深入了解更多时:
Azure Durable Task 文档覆盖了依赖、延迟调用以及该 capability 的所有选项。 微软的发布公告带你看遍 scheduler 仪表盘和逐 activity 的时间线。 在 Logfire 里搜索 issue_refund 的退款日志,看看某个工具函数体是否执行了不止一次;数一数重复的 orchestrator span,就能知道一次运行回放了多少回。重试和 token 统计也在同一条 trace 上。 Pydantic AI 的 capabilities 文档解释了 capability 如何打包工具、hook 和配置,Pydantic AI Harness 概览列出了货架上的其余产品。
Harness 目前处于 0.x 版本,API 在 minor 版本之间可能变动。变更会附带弃用警告,发布说明中提供迁移指引。如果遇到问题或缺少功能,GitHub 上的 issues 随时开放,你也可以在 Pydantic Slack 里找到我们。