用途
当智能体运行必须经受重启、worker 迁移或长时间等待时，应使用持久化执行。AI SDK for Python 本身不提供持久化能力，需要自行构建可重放的工作流。
主要能力
- 自定义
Agent.loop，将副作用放入持久化步骤中。 - 需要放入持久化步骤的副作用包括：模型调用、工具 I/O、审批或恢复边界。
- 保持工作流可重放：持久化步骤应接收 JSON 输入并返回 JSON 输出。
消息序列化
data = message.model_dump(mode="json")
message = ai.messages.Message.model_validate(data)
模型步骤
持久化的模型步骤应在步骤内部消费 ai.stream(...)，并返回一条完整的 assistant Message。
@workflow.step
async def llm_step(
model_data: dict[str, object],
messages_data: list[dict[str, object]],
tools_data: list[dict[str, object]],
) -> dict[str, object]:
model = ai.Model.model_validate(model_data)
messages = [
ai.messages.Message.model_validate(message)
for message in messages_data
]
tools = [ai.Tool.model_validate(tool) for tool in tools_data]
async with ai.stream(model, messages, tools=tools) as stream:
async for _event in stream:
pass
if stream.message is None:
raise RuntimeError("LLM stream ended without a message")
return stream.message.model_dump(mode="json")
持久化工具
优先将工具体包裹在持久化步骤中：
@ai.tool
@workflow.step
async def ask_mothership(question: str) -> str:
response = await mothership_client.ask(question)
return response.summary
如果工作流系统需要独立的活动调度，则调度一个零参数可调用对象，返回 ai.tool_result(...)。不要直接调用 tool.fn。
Agent 循环
将模型步骤的结果作为一条完整消息使用。不要用 ai.Stream、ai.events.replay_message_events 或 ai.util.merge 包裹它——这些工具用于非持久化应用中的流式分发，而在工作流环境中不可行，因为流被视为副作用。
class DurableAgent(ai.Agent):
async def loop(self, context: ai.Context):
while context.keep_running():
result = await llm_step(
context.model.model_dump(mode="json"),
[m.model_dump(mode="json") for m in context.messages],
[t.model_dump(mode="json") for t in context.tools],
)
assistant_message = ai.messages.Message.model_validate(result)
context.add(assistant_message)
async with ai.ToolRunner() as runner:
for tool_call in assistant_message.tool_calls:
runner.schedule(context.resolve(tool_call))
async for event in runner.events():
yield event
context.add(runner.get_tool_message())
适用场景
- 智能体运行需要跨进程重启或 worker 迁移继续执行。
- 工作流中存在长时间等待、审批或恢复边界。
- 需要将模型调用与工具 I/O 作为可重放步骤管理。
限制
该模式不会向调用方流式输出模型 token。这通常是持久化工作流的合理取舍，因为许多持久化系统不支持异步生成器。可以构建基于队列的旁路通道来实现流式输出；但这类流不能用于调度工具或直接影响控制流。