持久化 Agent 如何工作

查看 Markdown

Agent 仍然由你的框架运行：它的 prompt、tool 和模型选择都不变。Dex 把每段对话作为一个 Session Flow 运行，把其中每次模型调用和 tool call 作为一个 Step 运行。Dex 记录每个 Step 的结果，所以崩溃、部署或长时间等待都不会让已完成的工作重复。

你的应用

Client运行 Agentsend_user_message

消息

Thread → Session Flow

Agent Loop → Step

LLM 调用RunModelTool CallCallTool人工介入AwaitToolApprovalTool 结果ResumeTurn

聊天记录Attributes流式输出AgentEvents Stream

标签：你的框架。下方：Dex。

调用

模型

Tool

你的框架术语在 Dex 中的对应

在你的框架中	在 Dex 中	对你的影响
Agent	你的 Agent，由 Dex 适配器包装成一个 Session Flow	Prompt、tool 和模型选择保持不变。
Thread、对话、session	一个 Session：一次 Flow run。Flow ID 就是 Session ID。	Session 能经受崩溃和部署。停止后，在保留期内仍可读取。
运行 Agent	从 Client 调用 `send_user_message` RPC（TypeScript 中是 `sendUserMessage`）	Dex 在 turn 开始前记录这条消息。turn 进行中发送的消息会排队。
Turn	一个 turn：从一条用户消息到回复的那些 Step	Steer（`steer_user_message`）在下一个安全的 Step 边界结束 turn。`cancel_turn` 还会停止正在运行的模型调用，丢弃它的回答。两者都不会停止已经开始的 tool call。
LLM 调用	一个 `RunModel` Step	Dex 记录响应。重试会再次调用模型。
Tool call、function call	读取或幂等写入用 `CallTool` Step，其他写入用 `CallSingleAttemptTool` Step	在自己 Step 中运行的写入最多运行一次。崩溃导致结果未知时，模型看到 `outcome_unknown`。
并行 tool call	并行运行的 tool Step，然后是一个 `ResumeTurn` Step	`ResumeTurn` 等到所有结果，再交给模型。
人工介入、tool 确认	一个 `AwaitToolApproval` Step，通过 `resolve_interrupt` RPC（TypeScript 中是 `resolveInterrupt`）或在 Dex Web 中回答	等待可以持续数天，不占用 Worker。
Checkpointer、持久化执行插件	记录下来的 Step 结果。适配器在 Step 之间保存框架自己的状态。	崩溃只会重复正在运行的那个 Step。Agent 代码不需要遵守确定性规则。
聊天记录、短期记忆	Session 的 Attribute	跨 Session 的长期记忆放在你自己的存储里，通过 tool 访问。
流式回调	AgentEvents Stream	它是尽力而为的。`get_agent_snapshot`（TypeScript 中是 `getAgentSnapshot`）读取记录下来的对话。
MCP server、tool 集成	Tool source。官方 Connector 通过 `ConnectorToolSource` 接入。	每次 Connector 调用都带上它的凭据和一个幂等键。

有些 tool 在 RunModel 里或在模型提供方运行，那个 Step 重试时它们可能再运行一次。例如 Claude Agent SDK 中的读取和 Bash 这类 CLI tool、hosted tool，以及 Mastra 自己运行的 tool。LangGraph 图也可以在一个 RunModel 中调用多次模型。框架支持列出这些差别。

Session

一个 Session 保存一段对话：它的消息、tool call 和结果。它等待下一条消息时不占用 Worker。每个 Step 在 Session 继续之前保存，每个 Step 大约增加十分之一秒。新的 Session 从空白开始。

深入了解 Session介绍延迟、成本和记忆。

Tool call

每个 tool 都有一个 policy。它的 effect class 说明重复调用会产生什么：read 和 idempotent_write 可以再次运行，其他写入最多运行一次。同一次调用的每次尝试都使用同一个幂等键。把它传给 tool 写入的服务。

深入了解 Tool Call介绍每种结果，以及怎样核对未知结果。

审批

需要审批的 tool call 在 AwaitToolApproval 中等待，直到有人回答。默认情况下，非幂等写入会等待审批。审批人从你的应用或在 Dex Web 中批准或拒绝调用，模型会看到拒绝。

深入了解审批介绍 RPC、Dex Web 和审批期限。

Connector 作为 tool

Agent 可以把官方 Connector 的操作当作 tool 调用。Connector 的 manifest 决定每个操作的 effect class，应用选择提供哪些操作。每次调用都在自己的 tool Step 中运行，并使用 Connector 的凭据。

深入了解 Connector 作为 tool介绍每个框架的接入方式。

下一步

在生产环境运行 Agent：为真实用户运行 Session 之前的检查清单。
内置 Agent Loop：支持提问、计划和持久等待的 harness。