---
title: "持久化 Agent 如何工作"
description: "你在 Agent 框架里熟悉的术语，例如 thread、LLM 调用、tool call 和人工介入，对应到 Dex 的 Session Flow 和它的 Step。"
canonical_url: "https://docs.superdurable.io/zh-Hans/agent-frameworks/how-it-works/"
source: "docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/agent-frameworks/how-it-works.mdx"
locale: "zh-Hans"
---

> 供 AI Agent 使用的全部页面索引：https://docs.superdurable.io/zh-Hans/llms.txt

# 持久化 Agent 如何工作

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

> **图示**：你的应用的 Client 把消息（send_user_message）发进 Session Flow，也就是对话的 thread。在 Session Flow 里，Agent Loop 作为 Dex 记录的 Step 运行：LLM 调用是 RunModel，tool call 在读取或幂等写入时是 CallTool，其他写入时是 CallSingleAttemptTool，人工介入是 AwaitToolApproval，ResumeTurn 把 tool 结果交还给模型。聊天记录保存在 Session 的 Attribute 中，实时输出写到 AgentEvents Stream。这些 Step 调用你的模型和 tool。

<a id="term-map"></a>

## 你的框架术语在 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` 中调用多次模型。[框架支持](https://docs.superdurable.io/zh-Hans/agent-frameworks/framework-support.md)列出这些差别。

<a id="sessions"></a>

## Session

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

[深入了解 Session](https://docs.superdurable.io/zh-Hans/agent-frameworks/sessions.md)介绍延迟、成本和记忆。

<a id="tool-calls"></a>

## Tool call

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

[深入了解 Tool Call](https://docs.superdurable.io/zh-Hans/agent-frameworks/tool-calls.md)介绍每种结果，以及怎样核对未知结果。

<a id="approvals"></a>

## 审批

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

[深入了解审批](https://docs.superdurable.io/zh-Hans/agent-frameworks/approvals.md)介绍 RPC、Dex Web 和审批期限。

<a id="connectors"></a>

## Connector 作为 tool

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

[深入了解 Connector 作为 tool](https://docs.superdurable.io/zh-Hans/agent-frameworks/connectors-as-tools.md)介绍每个框架的接入方式。

<a id="next"></a>

## 下一步

- [在生产环境运行 Agent](https://docs.superdurable.io/zh-Hans/agent-frameworks/production.md)：为真实用户运行 Session 之前的检查清单。
- [内置 Agent Loop](https://docs.superdurable.io/zh-Hans/agent-frameworks/built-in-agent-loop.md)：支持提问、计划和持久等待的 harness。