进阶 pydantic.dev 2026-11-20 05:57:40 · 6 阅读

第28章 AWS Lambda 上的持久化 Pydantic AI Agent 构建指南

想象这样一个场景:一个 AI 客服 agent 处理工单花了十五分钟。它读取订单、调用 billing API、询问模型下一步该做什么、再调用另一个工具——结果在第 11 分钟左右 Lambda 调用超时了。Lambda 重试这次调用,handler 从第一行重新执行,于是同样的模型请求又发了一遍、同样的工具又跑了一遍、同样的 token 又计了一次费,而 billing API 对那张已经退过款的工单又退了一次款。结果就是:token 花了双倍,退款也重复了一次。

这听起来像 bug,其实不是。Lambda handler 是无状态的,重试没有任何可恢复的进度——因为之前的运行进度根本没有被记录下来。

AWS Lambda durable functions 让你能在 Lambda 上构建可靠的长时运行工作流。durable function 可以暂停、等待外部事件、重试失败的操作,并从上次中断的地方继续,即使 Lambda 回收了执行环境也没问题。其底层原理是:durable function 就是普通的 Lambda 函数,只是通过 checkpoint 和 replay 机制来追踪进度。一次执行最长可持续一年,且对于按需计费的函数,等待期间挂起不产生计算费用。

Pydantic AI Harness 现在支持 AWSLambdaDurability,这项能力让运行具备持久化:每次模型请求、function tool 调用、MCP 调用和动态工具集解析,都会作为 AWS Lambda durable functions 的一个 step 被 checkpoint。恢复执行时,会从 handler 顶部重放,已完成的步骤直接使用存储的结果。

Getting started uv add logfire "pydantic-ai-harness[aws-lambda]" "pydantic-ai-slim[bedrock]"

AWS Durable Execution SDK 需要 Python 3.11 或更高版本。本文所有 trace 背后的 instrumentation 都来自 logfire。

一个放在 handler 里的 agent

把 agent 放进 handler 并部署,这是最朴素的起点。对于一个四秒内就能完成的查询来说,这也已经是终点了:

from typing import Any

import logfire from pydantic_ai import Agent

logfire.configure() logfire.instrument_pydantic_ai()

agent = Agent('bedrock:us.amazon.nova-pro-v1:0')

@agent.tool_plain def get_weather(city: str) -> str: return f'It is sunny in {city}.'

def handler(event: dict[str, Any], context: Any) -> str: return agent.run_sync(str(event['prompt'])).output

上限问题出在重试上。当调用方重试一个失败的 handler——比如超时、限流或瞬时网络错误之后的异步调用或事件源调用——整个运行会从头再来,你不仅要为失败的步骤付费,还要为已经完成的工作再付一次。

构建 durable Lambda handler

构建 agent 时挂载这个 capability,然后用 durable_agent_handler 适配 handler 主体:

from typing import Any

import logfire from aws_durable_execution_sdk_python import DurableContext, durable_execution from pydantic_ai import Agent

from pydantic_ai_harness.aws_lambda import AWSLambdaDurability, durable_agent_handler

logfire.configure() logfire.instrument_pydantic_ai()

agent = Agent( 'bedrock:us.amazon.nova-pro-v1:0', name='support', capabilities=[AWSLambdaDurability()], )

@agent.tool_plain def get_weather(city: str) -> str: return f'It is sunny in {city}.'

@durable_execution @durable_agent_handler async def handler(event: dict[str, Any], context: DurableContext) -> str: result = await agent.run(str(event['prompt'])) return result.output

两个装饰器加一个 capability。注意 @durable_execution 必须放在最外层,因为 Lambda 调用的是它的包装函数;顺序颠倒会在定义 handler 时抛出 UserError。在底层,durable_agent_handler 把 async agent 托管在一个后台事件循环上,并在 Lambda handler 线程上处理它的 step,同步的 durable API 和异步的 agent 运行因此能汇入同一条连续的 step 序列。

用 durable 配置部署,并调用一个已发布的版本,因为进行中的执行会固定在启动它的那个版本上:

aws lambda create-function \ --function-name support-agent \ --runtime python3.13 \ --handler handler.handler \ --role \ --zip-file fileb://support-agent.zip \ --timeout 300 --memory-size 1024 \ --durable-config '{"ExecutionTimeout":3600,"RetentionPeriodInDays":7}'

aws lambda wait function-active-v2 --function-name support-agent aws lambda wait function-updated-v2 --function-name support-agent aws lambda publish-version --function-name support-agent

create-function 返回时,Lambda 可能仍在配置函数。两个 waiter 会确认 State=Active 和 LastUpdateStatus=Successful,避免 publish-version 与配置工作产生竞争并因 ResourceConflictException 失败。

--role 指定的角色需要 lambda:CheckpointDurableExecution 和 lambda:GetDurableExecutionState 权限,AWS 托管策略 AWSLambdaBasicDurableExecutionRolePolicy 已包含这些权限。控制台创建 durable function 时会自动附加,但 CLI 不会——所以如果像上面这样用一个普通 execution role 部署,函数会在第一次 checkpoint 时失败。

agent 保持原有的 API 不变。还是同一个 Agent、同样的工具、同样的 output_type(如果有),而运行现在可以在它所在的调用结束后继续存活。

仅仅挂载 capability 并不会让运行持久化。只有通过 durable_agent_handler 或 run_durable 进入的运行才会被 checkpoint,所以 handler 主体里的 await agent.run(...) 才是持久化路径。如果你在别处用自己的 asyncio.run(...) 驱动同一个 agent,会得到一个功能完全正常但不持久化的运行,且没有任何警告。而在 handler 主体里调用 agent.run_sync(...) 甚至走不到这一步:主体已经运行在事件循环上,run_sync 无法在事件循环内调用。

Step 名称由 agent 的名称(如果 agent 未命名,则使用 AWSLambdaDurability(name=...))加上各工具集的 id 组成。上面的天气工具会被 checkpoint 为 support__function_toolset__.call_tool:get_weather,模型请求则是 support__model.request。当恢复的执行出现意外行为时,你要读的就是这些名字。

跨调用观察一次运行

片段里的两行 Logfire 代码让 durable run 变得可读。logfire.instrument_pydantic_ai() 会把每次模型请求和工具调用都记入 trace,而这些正是 Lambda 以上述 step 名称 checkpoint 的操作,所以 durable 日志里的每个 step 都有一个对应的 span,可以打开查看参数。

不过,恢复后的运行并不是一条 trace。每次调用各自记录自己的 trace,而接手该运行的那次调用只记录真正执行的步骤——已完成的步骤直接返回存储的结果而不再执行,所以没有可记录的内容。读一次恢复的运行,就要按顺序读这些调用;第二条 trace 很短恰恰是好事,那是你没有重复付费的工作。

运行值得时再调优

Checkpoint 以 step 为粒度,配置也以工具为单位。工具在 aws_lambda 键下的元数据可以设置该工具的 retry_strategy、step_semantics 和 serdes:

from aws_durable_execution_sdk_python.config import StepSemantics from pydantic_ai.toolsets import FunctionToolset

toolset = FunctionToolset(id='billing')

@toolset.tool_plain(metadata={'aws_lambda': {'step_semantics': StepSemantics.AT_MOST_ONCE_PER_RETRY}}) def charge_card(amount: int) -> str: return f'charged {amount}'

AWSLambdaDurability(step_config=...) 为所有 step 设置基础配置,工具级元数据按键逐项覆盖——只设置 step_semantics 的工具会保留基础的重试策略。另一个极端是 metadata={'aws_lambda': False},让工具完全脱离 checkpoint,每次尝试都内联执行,这对廉价且无副作用的操作来说是正确选择。MCP 工具不能退出 checkpoint,因为它们执行的 I/O 不应重复运行。

两个约束:

Step 是至少一次语义,且默认会重试。step 在执行完之后才 checkpoint,所以如果中断恰好发生在工具产生副作用和写入 checkpoint 之间,恢复时工具会重新执行。SDK 的默认策略允许总共六次尝试(初始一次加五次重试),带指数退避。请保持副作用幂等。对于确实绝不能重复的工具,AT_MOST_ONCE_PER_RETRY 只是答案的一半:它能阻止同一次尝试内重复执行,但重试策略仍会发起新的尝试并执行函数体。两者都要设置,并搭配 RetryPresets.none()。顺手关掉两层重试中的一层,因为 Pydantic AI 和 provider 客户端各有自己的重试,叠加会让尝试次数成倍增加,还会错误处理 Retry-After。

改变运行的形状会破坏进行中的执行。Checkpoint 按操作到达的顺序匹配,所以新增工具、移除 MCP server、修改退出配置、添加 event_stream_handler 或更换模型,都会让旧代码上启动的执行的序列发生错位。发布新版本,让旧版本自然排空。这和 schema migration 要求的纪律是一回事,只不过应用在 agent 的形状上。

该选哪种 durable execution

Pydantic AI 官方支持五种 durable execution 方案。Temporal 和 Restate 在 agent 前面放一个服务器,提供持久化编排。DBOS 以库的形式在进程内运行,checkpoint 写入你已有的数据库,Prefect 则带来工作流框架的事务语义。Lambda durability 是唯一不增加任何组件的方案:如果 agent 本来就是一个函数,持久化只需一个 capability、两个装饰器和部署时的一个配置项。durable execution 文档涵盖了全部五种方案。

AWS Lambda durability 文档详细记录了所有 step 名称、每工具配置和配额,capability matrix 则追踪其余内容。

Frequently asked questions

这支持任意模型 provider 吗,还是只支持 Amazon Bedrock?

支持 Pydantic AI 的任何 provider。这个 capability checkpoint 的是模型请求本身,而不是特定客户端;未使用 agent 默认模型的模型操作会把其 model id 记录在 step 名称里,恢复的执行因此能把每个 checkpoint 映射回它对应的模型。示例中出现 Bedrock 只是因为它是多数 Lambda 部署最先想到的 provider。

Checkpoint 的开销是什么?

Step 会消耗 durable execution 的 operations 和 storage 配额。一轮对话消耗一个 model step,外加每次工具调用一个 step。大的工具结果会占用 storage 配额,所以应该存储引用而非负载,或者用 FileSystem serdes 把大值保存在 Amazon S3 Files 上、只 checkpoint 一个文件指针。收益在于:你不必为每次重试重复支付模型请求和工具调用的费用。详见 durable functions quotas。

工具还能并行运行吗?

不能,在 durable handler 内不行。step 的身份来自步骤到达的顺序,并发调度的工具调用可能在恢复时互相认领对方的 checkpoint。运行在 handler 内会切换为顺序执行工具,在其他地方则保留配置的并行度。

如果我在执行进行中重新部署会怎样?

执行会坏掉,除非你使用版本。恢复的执行按位置匹配 checkpoint,所以步骤数量或顺序的任何变更都会使旧代码下启动的执行失效,重命名 agent 或 toolset id 也会改变记录的名称。发布新版本部署,让进行中的执行在旧版本上跑完。

durable execution 能向外流式输出 token 吗?

不能流给调用方。durable execution 完成时只返回一个值,运行期间没有可供流式输出的通道。run_stream 和 iter 在 handler 内仍然可用,且正常 checkpoint;event_stream_handler 则能在 model step 内获得实时的模型事件,agent 级的每个事件会在各自的 step 中被 checkpoint。

评论 (0)