---
title: "运行与步骤"
description: "1.0：运行何时开始与结束、期间可发生什么，以及步骤如何标记阶段。"
---

> Documentation Index
> Fetch the complete documentation index at: https://ag-ui.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 运行与步骤

消费者发送 [`RunAgentInput`](https://ag-ui.ndjp.net/spec/1-0/basic/run-input/)；生产者以携带一次或多次运行的事件流作答——被请求的运行，可能前面还有重放的历史。本页陈述运行何时开始与结束、这些边界意味着什么；运行**内部**的顺序规则属于[事件模式](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/)。

## 运行

流 MUST 以 `RUN_STARTED` 或 `RUN_ERROR` 开始。生产者 MUST NOT 先发射任何其他事件，消费者 MUST 把以其他事件开始的流视为协议违规。`RUN_ERROR` 可以先出现，因为运行可能在开始前就失败——无法到达智能体的传输有失败要报告，却没有运行可供挂载。

```text
[*] --RUN_STARTED--> Active
[*] --RUN_ERROR--> Failed
Active --RUN_FINISHED--> Closed
Active --RUN_ERROR--> Failed
Closed --RUN_STARTED--> Active   （新运行）
Closed --RUN_ERROR--> Failed     （迟到失败）
Failed --RUN_STARTED--> Active   （新运行）
```

### `RUN_STARTED`

开启运行。它携带运行的标识符、生产者自己的 `protocolVersion` 声明（按[版本规则](https://ag-ui.ndjp.net/spec/1-0/basic/versioning/#版本协商)），并 MAY 回显启动该运行的输入，使未发起请求的消费者也能看到智能体被问了什么。`parentRunId` 命名派生本次运行的那次运行——当智能体把另一个智能体作为独立运行而非同一运行内的[子智能体](https://ag-ui.ndjp.net/spec/1-0/events/subagents/)调用时。

### `RUN_FINISHED`

关闭未失败的运行，并报告它如何结束：

- 其 `outcome` 区分**完成**的运行、**等待外部输入而中断**的运行，以及**完成前被停止**的运行；缺省 outcome 表示成功。中断结果及其后续见[中断与恢复](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/interrupt-resume/)；取消结果见[下文](#已取消的运行)。outcome 报告生产者对运行结束原因所知的内容：因[前端工具调用](https://ag-ui.ndjp.net/spec/1-0/events/tool-calls/#前端工具)而停止的运行是**已完成的运行**，其成功结果 MAY 在 `pendingToolCallIds` 中命名未回答的调用，因为应用在这样一次调用之后是否继续线程是应用的决定，不是生产者的。
- 生产者 MUST NOT 发送 schema 未描述的 outcome 值。
- `result` 是 OPTIONAL，携带运行的返回值（若有）。
- `usage` 是 OPTIONAL，按提供商与模型各一条报告 token 用量，遵循[下文记账](#token-用量)。只想要总量的消费者对各条目求和。

消费者不认识的 outcome 与其他未识别内容一样，按同样条件被剥离。剥离可选字段使其缺省，而缺省 outcome 表示成功——因此消费者不必区分**完成的运行**与**因在该消费者发布之后命名的原因而结束的运行**。

> 这限制了 outcome 集合能有用增长的程度。后续版本新增的终止状态会以成功运行到达旧消费者，因此需要旧消费者**注意到**新结束方式的版本，不能仅通过 `outcome` 表达——它需要一个旧消费者已视为重要的载体。这也是取消结果在 1.0 就命名的原因：若之后添加，被取消的运行会以已完成运行到达每个 1.0 消费者。

### 已取消的运行

运行可以在完成前被有意停止——由它为之运行的人、由应用自己的代码、由生产者执行的限制。它没有失败，也没有在等待任何内容，但也没有完成；无法把它与已完成运行区分的消费者会把部分工作当作全部呈现。取消结果命名这种结束。

- 在完成前停止运行、且原因不是失败的生产者 MUST 以携带取消结果的 `RUN_FINISHED` 关闭它。MUST NOT 把被停止的运行报告为成功——既不以成功结果，也不通过省略 outcome。
- 已关闭运行的一切在此成立。生产者 MUST 在取消它的 `RUN_FINISHED` 之前关闭运行开启的内容——消息、工具调用、步骤、子智能体——与成功前完全一样。关闭工具调用确立的是其参数文本**完整**，不是**有效**，因此参数中途被截断的调用照常关闭，如何处理无法解析的参数是应用的决定，按[工具调用规则](https://ag-ui.ndjp.net/spec/1-0/events/tool-calls/#tool_call_end)。无法按序关闭的生产者——停止把流从它下面拆掉——改为报告 `RUN_ERROR`：该运行没有干净结束，而 `RUN_ERROR` 正是为没有干净结束的运行准备的。
- 被取消的运行没有返回值：`result` SHOULD 缺省。`usage` MAY 报告停止前累积的 token。
- 被取消的运行不等待任何东西。其 outcome 不携带中断，线程上的下一次运行是普通新运行，不是恢复。
- 消费者 MUST NOT 把被取消的运行呈现为成功，也 MUST NOT 呈现为失败——用户要求的停止不是要展示给他的错误。

停止前投递的一切仍然有效，与 `RUN_ERROR` 之后一样。除此之外如何呈现停止是消费者的事。

取消是生产者对其所运行运行**的**报告。放弃流的消费者——关闭连接、停止读取——拥有的是[截断运行](https://ag-ui.ndjp.net/spec/1-0/basic/transports/#截断)，不是被取消的运行：它 MUST NOT 为从未收到结束的运行合成 `RUN_FINISHED`，无论取消与否。

### `RUN_ERROR`

结束失败的运行。`message` 说明出了什么问题，供人阅读；`code` 是 OPTIONAL 且机器可读，是协议未定义词汇的开放字符串；`usage` MAY 按与 `RUN_FINISHED` 相同的[记账](#token-用量)报告失败前累积的 token。

`RUN_ERROR` 是格式良好的事件：生产者在报告**自己的**失败，而不是发送消费者应拒绝的内容。把运行视为失败意味着消费者 MUST 把失败暴露给应用代码，并 MUST NOT 报告运行成功。它不规定**如何**——启动运行的那个调用是抛错、以失败 resolve，还是通过回调报告，都是实现的事，两个一致消费者可以不同。

### token 用量

`RUN_FINISHED` 与 `RUN_ERROR` 上的 `usage` 报告运行中模型调用的成本，按提供商与模型各一条 [`TokenUsage`](https://docs.ag-ui.com/spec/1-0/schema#tokenusage)。各提供商计数方式不同——有的把缓存提示 token 折进输入计数，有的并列报告，有的把推理与其余输出分开——因此协议固定一种记账，生产者负责翻译进去。每个计数要么是总量，要么是总量的具名部分：

- `inputTokens` 是该调用被计费的每个提示 token：缓存与否、写入缓存与否、文本与否。`outputTokens` 是每个生成的 token，含推理。
- `cachedInputTokens`（缓存读）、`cacheWriteInputTokens`（缓存写）与 `reasoningTokens` 是这些总量的**部分**，绝不是附加量。两个缓存计数互斥。提供商在较小总量旁报告其中之一的，生产者 MUST 在发射条目前把它加进总量；提供商已包含它的，生产者 MUST NOT 重复添加。
- `totalTokens` 是 `inputTokens` 加 `outputTokens`。生产者 MAY 自行计算而非复制提供商总量，且 MUST NOT 复制计数方式不同的提供商总量。
- 缺失计数表示提供商未报告；零表示它报告了零。生产者 MUST NOT 为没有数据的计数发射零，消费者 MUST NOT 把缺失计数读作零。

**运行是记账边界：**

- 用量覆盖运行内发起的每一次模型调用，包括其[子智能体](https://ag-ui.ndjp.net/spec/1-0/events/subagents/)发起的调用：子智能体事件不携带自己的用量，子智能体的调用属于该运行。
- 作为独立运行被调用的智能体——由 `parentRunId` 命名——在自己的终止事件上报告自己的用量，派生它的运行 MUST NOT 把该用量计入自身。
- [恢复](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/interrupt-resume/)被中断运行的运行只报告它自己发起的调用。被中断运行已报告了自己的，想要线程总量的消费者跨线程各运行求和。

在此记账下，只想要总量的消费者对各条目与各运行的 `totalTokens` 求和；计算成本的消费者拥有按各自费率计价缓存读、缓存写与推理所需的每个部分，且不会重复计算。

### 运行关闭之后

运行以 `RUN_FINISHED` 或 `RUN_ERROR` 结束，之后即为已关闭。一旦运行关闭：

- 生产者 MUST NOT 为该运行发射任何进一步事件，除了下面两条。
- 生产者 MAY 发射 `RUN_STARTED` 以在同一流上开始新运行。
- 生产者 MAY 在 `RUN_FINISHED` 之后发射 `RUN_ERROR`，报告在已报告成功之后浮现的失败——例如刷新时的传输错误。此时消费者 MUST 把运行视为失败。
- 生产者 MUST NOT 在 `RUN_ERROR` 之后发射除 `RUN_STARTED` 外的任何内容。

消费者 MUST 拒绝运行关闭后到达的任何其他事件。

### 单流多运行

单条流 MAY 按序携带多次运行——重放线程是常见情形。生产者 MUST 在开启下一次运行前关闭当前运行：运行仍活跃时出现 `RUN_STARTED` 是违规。

流内跨运行，消息累积，[状态](https://ag-ui.ndjp.net/spec/1-0/events/state/)持续存在，除非某事件替换它。重述历史的生产者——重放消费者输入已携带内容的线程——MUST 以快照重述：`MESSAGES_SNAPSHOT` 按 id 协调，`STATE_SNAPSHOT` 替换，因此消费者已持有的重述是幂等的。重新流式传输消费者已持有的消息会追加而非重述，这就是流式三件套只用于新内容的原因。

运行作用域的跟踪——打开的消息、打开的工具调用、打开的步骤、活跃子智能体——不跨越边界：`RUN_FINISHED` 要求运行开启的一切已关闭，`RUN_ERROR` 随运行结束任何仍打开的内容。新运行以没有任何打开项开始。

## 步骤

步骤标记运行的阶段，供显示进度的 UI 使用。`STEP_STARTED` 开启步骤，`STEP_FINISHED` 关闭它，按 `stepName` 匹配。

- 生产者 MUST NOT 开启名称已打开的步骤，MUST NOT 关闭从未开启的步骤。
- 生产者开启的每个步骤 MUST 在运行结束前关闭。
- 步骤 MAY 彼此重叠，也可与运行中其他内容重叠；步骤是流上一段区间的标签，不是容器。

## 数据类型

事件形状由 [schema 参考](https://docs.ag-ui.com/spec/1-0/schema)定义：`RunStartedEvent`、`RunFinishedEvent`（含 `RunFinishedOutcome`）、`RunErrorEvent`、`StepStartedEvent`、`StepFinishedEvent` 与 `TokenUsage`。

## 错误处理

有两件不同的事会让运行糟糕地结束，消费者要把它们分开。

**消费者拒绝的流**是它检测到的协议违规：本页生产者 MUST NOT 做的每件事在被消费者看到时都是致命的——`RUN_STARTED` 之前的事件、关闭后除允许的两条之外的事件、嵌套 `RUN_STARTED`、不平衡的步骤，或 `RUN_FINISHED` 时仍打开的任何内容。生产者有过错，流不可信。

**用 `RUN_ERROR` 报告自身失败的运行**正相反：一致生产者在说它的工作没有成功。流格式良好，消费者按上述规则接受它。

消费者 MUST NOT 把两者互相呈现。任一种失败都保留失败前投递的一切——`RUN_ERROR` 说的是运行没有完成，不是它的事件没有发生。

Source: https://ag-ui.ndjp.net/spec/1-0/events/lifecycle/index.mdx
