
一个支持智能体收到一张工单:订单 A-1001 到货时已损坏。它询问模型该怎么做,查询该订单,再次询问模型,然后发起退款。接着,运行它的 worker 被一次部署、一次缩容事件或一次内存不足错误杀死,进程把它所知道的关于这次运行的一切都带走了。
从头重新启动这次运行,你要为模型请求付两次费,调用订单 API 两次,还可能给客户退款两次。不重新启动,工单就会处于半处理状态,直到有人注意到。
Durable Task 是微软对该问题的解决方案,它也是 Azure Durable Functions 背后的引擎。你以普通 Python 代码编写编排器。它委托的工作作为活动运行,而 Azure Durable Task Scheduler 会记录每个已完成活动的结果。当某个 worker 死亡时,另一个 worker 会接手该编排,重放已记录的结果,并从当时正在执行的那一步继续。
Pydantic AI Harness 现已提供 AzureDurableTaskDurability,这项能力将智能体循环引入该模型。默认情况下,模型请求、函数工具调用、MCP 调用和持久化能力操作都作为 Durable Task 活动运行。在编排之外,智能体的运行方式与之前完全相同。Azure 团队也在他们那边发布了公告,见 隆重推出适用于 Pydantic AI 智能体的 Azure Durable Task.
快速上手
uv add logfire "pydantic-ai-harness[azure-durable-task]" "pydantic-ai-slim[anthropic]"
这个 azure-durable-task 额外的安装会安装 Durable Task Python SDK、Azure 托管的 worker 和 client,以及 azure-identity。示例使用 Anthropic,但 Pydantic AI 支持的任何提供商都可以使用。 Pydantic Logfire 会对智能体进行插桩,因此每次运行都会显示为一条 trace,其中包含每个模型请求、工具调用和活动。
在运行示例之前,请设置你的模型提供商密钥和一个 Logfire 写入令牌 :
export ANTHROPIC_API_KEY='your-anthropic-api-key'
export LOGFIRE_TOKEN='your-logfire-write-token'
对于本地开发,请启动 Durable Task Scheduler 模拟器 在 Docker 中:
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,其仪表板位于 http://localhost:8082。目前还不需要 Azure 订阅。
持久化支持智能体
将这项能力附加到智能体,为智能体指定一个 name,并编写编排器。该名称会作为前缀添加到智能体注册的每个活动上,因此它会被记录在编排历史中。将其保存为 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 是一个桩,它把退款记录到 Logfire ,而不是实际转移资金,因此该示例无需支付账户即可运行。除了幂等键之外,这两个工具本身都不需要做任何改动就能实现持久化,幂等键的作用将在重放一节中说明。
run_durable 是 Durable Task 生成器风格与异步智能体运行之间的桥梁,你可以在工作流中智能体所属的任何位置调用它。编排器返回与 JSON 兼容的输出。如果智能体以 Pydantic 模型作为 output_type, 返回 result.output.model_dump(mode='json').
最后,启动一个 worker 并从 main.py:
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 绑定每个能力各自的副本,因此 from_agent 会获取绑定的那个。输入 register(worker) 在 worker 启动之前,并在 worker 停止之后保留它。它注册智能体的活动并运行它们。编排器和客户端都是普通的 Durable Task SDK 代码,客户端可以位于另一个进程中,该进程从不导入智能体。 logfire.span 会包装客户端代码,而客户端代码从不重放,因此在 Logfire 中每张工单只出现一次。
当 worker 死亡时会发生什么
我在模拟器上运行了上面的智能体,并用 os._exit(1) 杀死了 worker,此时退款已经执行,但其结果尚未到达调度器。随后我启动了第二个 worker。在测试中,每个工具每次执行其主体时还会向文件追加一行:第一个 worker 发起了两次模型请求,运行了 ,并在 内部死亡。第二个 worker 没有重复前三个活动中的任何一个。它从历史记录中重放了它们,再次运行了 ,因为其结果从未被记录,发起了最后一次模型请求,并在一秒左右后完成了编排:退款工具运行了 issue_refund两次。这就是持久化执行的真实形态,也引出了我们的规则。重放与副作用每当一个活动完成时,SDK 都会从 t 开始重新运行你的编排器
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 没有重复前三个活动中的任何一个。它从历史记录中重放了它们,运行了 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.
退款工具运行了两次。这就是持久化执行的真实形态,也引出了我们的规则。
重放与副作用
每当一个活动完成时,SDK 都会从头重新运行你的编排器,并从历史记录中提供每一个已完成的结果。替换 worker 正是以这种方式恢复编排,这也意味着在编写智能体时需要注意几点:
- 活动至少执行一次。 如果某个工具的副作用已经发生,而其结果尚未被记录,worker 就可能死亡,正如上文所示。请让工具具备幂等性。
ctx.run_id,ctx.tool_call_id在重启后保持不变,这使它们成为良好的幂等键:这两issue_refund行也承载同样的内容。 - 编排器侧代码在每次重放时都会运行。 钩子、指令函数、输出校验器和内联工具必须是确定性的,且不得进行网络、文件或线程 I/O。请将 I/O 放在工具或能力的
@durable_operation方法中。 - 名称会被持久化。 活动名称来自智能体的
name、工具集 ID 和工具名称。在使用它们的编排仍在运行时,不要重命名其中任何一个。 - 重放成本随运行长度增长。 每次重放都会让智能体重新运行到其最新步骤,因此编排器的 CPU 开销会随步骤数量的平方增长。请将超长对话放在单独的编排中。
- 跨度会重复出现。 在编排器代码中创建的 Pydantic AI span 在每次重放时都会再次发出,因此一次运行会在 Logfire 中多次显示其 agent run 和 model request span。
- 错误会改变类型。 在模型请求或工具中抛出的异常会以
durabletask.task.TaskFailedError.UserError会保持其类型。
依赖项遵循同样的逻辑。它们作为数据进入活动,因此必须可 JSON 序列化(dataclasses、Pydantic 模型和 JSON 值),活动会从智能体的 deps_type在用到数据库客户端和 HTTP 会话的工具内部创建它们,而不是在 deps.
等待期间不占用活动的审批
超过阈值的退款、生产环境部署、付款:有些工具调用需要有人点头同意。在 Durable Task 中,审批属于编排器,编排会等待一个外部事件。等待期间不会运行任何活动,因此一次审核可以花五分钟,也可以花三天。
用以下方式标记该工具: 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
编排器会在其自定义状态中发布待处理的工具调用和一个新的事件名称。你的审核 UI 通过读取该状态来 client.get_orchestration_state(instance_id),向某人展示这些请求,并把其决定连同 client.raise_orchestration_event(instance_id, event_name, data={tool_call_id: True})智能体会带着完整的消息历史和已累积的用量恢复运行。
有两个细节很容易弄错。每次暂停都使用新的事件名称,意味着较晚做出的决定无法回应更晚的审核。而 Durable Task 在匹配事件名称时不区分大小写,因此工具调用 ID 应放在负载中,绝不能放在事件名称里。 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 而延迟调用属于智能体控制流,并非活动失败,因此它们永远不会消耗重试次数。 UserError ,而序列化失败则完全不会重试。如需更精细的控制, resolve_tool_options 会为每个工具返回一个策略,或者 False 在编排器中以内联方式运行纯函数工具,而不是作为活动运行。内联工具会在每一步重放,因此它们必须是确定性的且不涉及 I/O。MCP 和动态工具始终作为活动运行。
部署到 Azure
从模拟器迁移到真实调度器会改变 worker 和客户端。编排器和 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 = '<scheduler>.<region>.durabletask.io'
worker = DurableTaskSchedulerWorker(host_address=endpoint, taskhub='<hub>', token_credential=credential)
client = DurableTaskSchedulerClient(host_address=endpoint, taskhub='<hub>', token_credential=credential)
为 worker 的身份授予 Durable Task Data Contributor 在调度器或任务中心上的角色。在 worker 和客户端上使用同一个任务中心,并为每个环境使用单独的中心,这样预发布编排就永远不会对生产 worker 重放。
worker 是一个长期运行的 Python 进程。它运行在你已经运行这类进程的任何地方,例如 Azure Container Apps、AKS 或 VM。此能力使用独立的 Durable Task SDK,不会向 Azure Functions 注册任何内容。
该选用哪种持久执行方案
Pydantic AI 在这些引擎上持久运行。 持久执行概览 中列出的引擎都有一个完整示例,而 Azure Durable Task 文档 介绍这一集成:
Temporal 和 Restate 则在你的智能体前面放置一个服务器,正如 重述与 Pydantic AI 演练 展示。DBOS 在进程内运行,并将检查点写入你已有的数据库,而该 DBOS 和 Pydantic AI 文章 涵盖。 AWS Lambda 持久性 当智能体已经作为 Lambda 函数运行时,这是首选方案。
当你的基础设施位于 Azure 上时,Azure Durable Task 就是首选。Durable Task Scheduler 是一项托管服务,因此你无需运行、修补或扩展任何编排服务器。标识是 DefaultAzureCredential 你其他 Azure 服务已经在使用的身份。一旦你的身份在调度器上被授予 仪表板角色 ,其仪表板会显示每个编排和活动,无需单独部署工具。
常见问题
这需要 Azure Functions 吗?
不需要。该能力使用独立的 Durable Task Python SDK 和你自己的 worker 进程。Azure Durable Functions 构建在同一个引擎之上,但此集成不会向其注册编排器或活动。
我可以在编排内部向用户流式传输 token 吗?
不能向客户端流式传输。流式模型响应会在模型请求活动内部被缓冲,因为一个活动只返回一个已记录的结果。如果你需要实时事件,请向该能力传入一个 event_stream_handler 它作为活动运行,因此要像任何工具一样使其具备幂等性。
工具能否在活动内部读取 ctx.messages 活动内部?
不能。在活动内部,实时运行字段(如 ctx.messages 以及 ctx.prompt ,并且工具无法发出运行事件。活动只能接收序列化到其中的内容:工具参数、deps 以及运行标识符。如果在编排正在运行时重新部署会怎样?重放会按历史记录中的名称匹配活动,因此重命名智能体、工具集或工具会破坏记录了旧名称的编排。当某项变更涉及重命名时,请先让进行中的编排在旧 worker 上完成,或者让新版本针对全新的任务中心运行。试用星标 UserError,并且工具无法发出运行事件。活动只能接收序列化到其中的内容:工具参数、deps 以及运行标识符。
如果在编排正在运行时重新部署会怎样?
重放会按历史记录中的名称匹配活动,因此重命名智能体、工具集或工具会破坏记录了旧名称的编排。当某项变更涉及重命名时,请先让进行中的编排在旧 worker 上完成,或者让新版本针对全新的任务中心运行。
试用一下
启动模拟器,向 AzureDurableTaskDurability() 到你已有的智能体,并把这次运行包装在编排器中。然后在中途杀掉 worker,重新启动它,并观察仪表板, localhost:8082 ,因为运行会从中断的步骤继续。
当你想要的不止是第一次运行时:
- Azure Durable Task 文档涵盖了依赖项、延迟调用以及该能力支持的所有选项。 Azure Durable Task 文档 涵盖依赖项、延迟调用以及该能力支持的所有选项。
- 微软的 公告文章 会带你浏览调度器仪表板及其按活动划分的时间线。
- 在 Logfire,搜索
refund日志,搜索issue_refund查看工具主体是否运行了不止一次,并统计重复的编排器 span 以了解一次运行重放的频率。重试和 token 计数位于同一条 trace 上。 - 这个 Pydantic AI 能力 文档说明了能力如何将工具、钩子和设置打包在一起,以及 Pydantic AI Harness 概览 列出了货架的其余部分。
Harness 目前处于 0.x 版本,因此 API 可能会在小版本之间发生变化。变更会附带弃用警告,并在发布说明中提供迁移指南。如果出现问题或有功能缺失,可以在 GitHub 已开放,你可以在 Pydantic Slack.
在 Google 搜索中查看更多来自 Pydantic 的内容
将 Pydantic 添加为首选来源,以便更容易找到我们的最新文章。
将 Pydantic 选为 Google 上的首选来源(在新标签页中打开)准备好看看你的智能体实际在做什么了吗?
免费开始 免费开始 联系我们 联系我们探索我们的开源软件包