Agent 工作原理概览

使用者可能会直接对 Agent 说：

请帮我取消订单。

模型快速返回结构化的 Tool Call：

{
说到"name"，"cancel_order"。"arguments": {
"orderId":
}
}

日志里出现了 cancel_order看起来 Agent 已经做出了正确决定。但查询订单程序时订单仍然是 “待发货”。这不是模型调用失败，而是提出动作和执行动作不是同一件事。

使用者痛点：模型告诉我们要取消订单。却没有把请求真正落到业务程序，导致使用者感受到“程序没有响应”，产生不信任感。

接下来还有一串没有发生的事情：

• 谁确认订单属于当前使用者？
• 谁校验订单是否仍可取消？
• 谁判断这项操作是否需要人工审批？
• 谁真正调用订单服务？
• 如果订单已经发货或服务超时谁处理失败？老实说，
• 工具返回结果后谁决定回复使用者还是继续调用其他工具？

Tool Calling 只建立了模型与应用之间的协议接口。要把这个调用请求变成真实的业务动作，应用必须接住模型输出、执行工具、再把真实结果送回模型。若模型继续产生新的 Tool Call，这个过程还要重复。

一、Tool Calling 只完成了“提出动作”

. 模型返回的是结构化决策

向模型声明工具时应用通常会提供工具名称、用途说明和参数结构。模型，而不是直接进入数据库执行 SQL。

使用者痛点：开发者误以为只要有 Tool Call 就代表着业务已完成。从而忽略了后端实际执行环节，导致业务层面的错误难还有时发现。

以取消订单为例，模型看到的工具定义可能是：

const cancelOrder = {
从name来看，"cancel_order"。description: "取消尚未发货且属于当前使用者的订单",parameters: {
type这方面，"object",properties: {
orderId: { type: "number" }
},required:
}
};

动作可以选择”，参数 Schema 限定它“应该用什么格式提出动作”。模型返回的 Name 与 Arguments 仅是一份结构化请求；真正的函数调用必须由应用侧接管并执行。OpenAI 与 Anthropic 的文档都明确：模型产生调用 → 应用执行代码 → 将 Tool Result 返回模型。

. 应用把请求变成真实动作

A Tool Call 从模型出来后需要：

参与者	输入	负责事项	输出	不负责事项
Model Runtime Policy Tool Executor	Model 当前 Context、工具定义 Runtime State / Policy Decision Tool 参数 & 权限校验 外部 API / DB 调用	生成最终回答或接下来结构化调用 解析、校验、选择分支、维护循环状态 依据风险/额度判断是否放行或暂停审批 已通过校验的参数调用业务程序	Final Output / Tool Call State 更新 / Run Result 批准/拒绝/暂停决定 Tool Result	直接完成业务动作 策略制定 业务实现

User Pain Point: 若缺少明确的 Policy 步骤。程序可能在未经授权的情况下直接调用关键业务接口，引发安全与合规风险。

. 一次完整往返包含两次模型交互

A 完整的 Client Tool 流程大致如下：

sequenceDiagram
participant U as 使用者
participant A as 应用 / Runtime
participant M as Model
participant T as cancel_order
U->A的观点是。请取消订单
从A->M来看，输入 + cancel_order 定义
M-->A这方面，Tool Call
A->A的观点是，校验参数、权限与审批策略
再看A->T，执行取消订单
再看T-->A，Tool Result
A->M这方面，原输入 + Tool Call + Tool Result
再看M-->A，订单 已取消
说到A-->U，最终答复

•  产生动作请求。
•  读取 Tool Result 并生成对使用者可见的最终答复。不过，

User Pain Point: 很多实现只保留第一轮交互。以为已经得到答案，从而遗漏第二轮的关键反馈环节，使得最终回复可能与真实业务状态不一致。

二、从一次往返到 Agent Run，中间多了一个循环

. 一次 Model Call 不等于一次 Agent Run

A Model Call 的边界很清晰：组装 Context → 调用模型 → 获得一次输出。Agent Run 的边界更长：从收到任务开始。经历若干次模型调用、工具执行与状态更新，直至运行完成、暂停、失败或被取消。

The OpenAI Agents SDK 把一个 Run 描述为持续到“真实停止点”的循环： 调用模型；检查输出，若有 Tool Call 则执行后继续；若有 Handoff 则切换处理者；没有后续工具且得到最终回答时才返回结果。

A typical Run might look like：

Model Call # → 查询订单Tool Result → 订单存在尚未发货
Model Call # → 取消订单Tool Result → 需要人工审批Pause → 等待负责人批准
Resume → 执行取消Model Call # → 生成最终答复Complete

User Pain Point: 如果仅记录最终文本而忽略中间的决策链。就无法追溯为何某个关键操作被拒绝或失败，也难以进行审计和调试。

. 最小循环是“决策—执行—反馈—更新”

The minimal Agent loop contains two repeating core steps:

1.  模型根据当前 Context 返回 Final Output 或 Tool Call。话说回来，
2.  应用执行工具。把 Tool Result 带入下一轮。

The Runtime bridges m,handling branching。state persistence and error handling.

flowchart LR
%% 样式定义
classDef runtime fill:#e8f4ff,stroke:#2478e5;话说回来，classDef model fill:#f0f9eb。stroke:#67c23a;classDef tool fill:#fdf6ec,stroke:#e6a23c;classDef endnode fill:#fef0f0,stroke:#f56c6c;A:::runtime
B::的观点是，model
C{模型输出}
说到D::，endnode
说到E::，tool
F{是否需要审批}
从G::来看，runtime
H::的观点是，tool
至于I::，runtime
J::的观点是，endnode
K::这方面，endnode
A --> B --> C
C -- Final Output --> D
C -- Tool Call --> E --> F
F -- 是 --> G
F -- 否 --> H --> I -.循环回流.-> A
%% 异常分支统一右下排布。不横穿主线
E -- 校验失败 --> J
H -- 执行异常 --> J
A -- Cancel or timeout --> K
%% 主线正向链路结束
Completed -->
Failed -->
Cancelled -->

. 环境反馈让接下来建立在

The model can only infer that a cancellation might be appropriate based on existing Context. The real environment may return completely different results:

• Cancellation succeeded.
• The order has already shipped – cannot cancel.
• The order does not belong to current user.
• The order service is temporarily unavailable.
• The action exceeds automatic‑processing limits and needs manual approval.

User Pain Point: 如果程序不把这些真实结果回馈给模型，就会出现“模型一直坚持已经取消”而并未完成的矛盾情形。

. Planning 可以存在但不是固定方框

If a task is complex,a Planner may emit an explicit checklist first. For simple tasks like order cancellation。model can decide step‑by‑step without an explicit plan.

三、循环为什么离不开 State？

. Context 是本轮模型真正看见的信息

The Context is what model receives for a single Model Call – instructions,selected messages。tool definitions,relevant bits of State and any on‑demand retrieved data.

User Pain Point: 开发者倾向于把整个会话历史全部塞进 Context，导致上下文窗炸，同时泄露敏感信息；另一面又可能遗漏关键状态，使得每轮推理缺乏必要信号。

. State 保存任务事实与恢复位置

A typical AgentState for cancellation scenario looks like:

interface AgentState {
再看runId，string;status: "running" | "paused" | "completed" | "failed" | "cancelled";turnCount: number;events: Array;pendingApproval?: {
再看call，ToolCall;decision，其实，: "approved" | "rejected";}，lastError?: string，}

User Pain Point: 如果 State 未持久化或更新不及时在程序崩溃后无法恢复到正确的位置，会导致重复扣费或重复撤单等严重错误。

. Session / Thread 用于组织连续运行

Name	Description
State	A snapshot of current run at a specific step.
Session / Thread	Keeps history & checkpoints toger so that a Runtime can locate correct context for subsequent calls.
* 不同框架对 Session 与 Thread 的实现细节不同。但主要都是帮助定位同一次连续交互*

User Pain Point: 缺少统一 Session 标识会导致同一使用者多次请求被误认为是不同任务，从而丢失上下文关联性。

. Memory 用于跨任务长期存储

• User prefers SMS notifications – stored in long‑term Memory.
• User’s default shipping address – reusable across sessions after proper consent.
• An order awaiting approval – belongs to current Run State。**not** Memory.

User Pain Point: 开发者误将应属于当前 Run 的临时数据写入全局 Memory，会造成数据污染并影响后续独立任务。

四者关系图示的观点是，

flowchart LR
%% 样式分类
classDef memory fill:#e1f5fe,stroke:#0288d1
classDef session fill:#f3e5f5,stroke:#7b1fa2
classDef state fill:#fff8e1,stroke:#f57c00
classDef runtime fill:#f1f8e9,stroke:#388e3c
classDef model fill:#fef2f2,stroke:#dc2626 

%% 数据源 至于M::，memory 从H::来看，session 说到T::，state

%% 中间流程节点 从S::来看，runtime C::的观点是，runtime 说到L::，model 说到O::，model R::的观点是，state 至于U::。runtime

%% 数据流走向 M -- 按需检索筛选 --> S H -- 裁剪/摘要压缩 --> S T -- 提取本轮相关事实 --> S

S --> C --> L --> O --> U

R --> U

%% 状态回流 & 长期记忆落库分支 U -.更新当前任务进度.-> T U -- 识别长期有效数据，异步写入 --> M

概念	保存什么	典型生命周期	是否直接对模型可见	订单案例
Context	本轮推理所需选定信息	一次 Model Call 的临时组合	是	包含最近一次查询结果 “orderId=123”，还有是否已通过审批标记。
State	当前任务事实、进度和控制信息	Run 生命周期内持久化，可恢复。话说回来，	否。仅 Runtime 使用。	记录 “pendingApproval = {callId:'c1',name:'cancel_order'}”。
Session / Thread	连续交互的历史与定位标识	跨 Run 可复用，用于检索历史。	否，仅在需要时加入 Context。不过，	同一客服会话中的多次询问 “查询物流”“修改地址”。
Memory	跨任务长期保存的信息 < td colspan= ? ? ? ?

---