跳到主要内容

AG-UI: 文本消息、工具调用和推理过程

事件是 AG-UI 的核心。如果智能体支持 AG-UI 作为输出格式，在每次运行智能体时，所得到的输出是一个事件流。客户端需要做的就是根据事件流中的事件类型，进行相应的处理。

事件​

AG-UI 中的事件可以分成如下几类，见下表。

类别描述
生命周期事件（Lifecycle Events）监控 Agent 运行过程中的生命周期进展。
文本消息事件（Text Message Events）处理文本内容的流式传输。
工具调用事件（Tool Call Events）管理 Agent 执行工具调用的过程。
状态管理事件（State Management Events）在 Agent 与 UI 之间同步状态。
活动事件（Activity Events）表示正在进行中的活动及其执行进度。
特殊事件（Special Events）支持自定义功能和扩展能力。
草案事件（Draft Events）仍处于开发中的提议事件类型。

每个事件都有如下几个属性：

属性描述
type事件类型标识符，用于表示具体的事件类型。
timestamp可选时间戳，表示事件创建的时间。
rawEvent可选字段，如果事件经过转换，则包含原始事件数据。

生命周期事件​

生命周期事件与智能体运行的生命周期相关。每次智能体的运行都遵循一定的模式。

  1. 从一个 RunStarted 事件开始。
  2. 包含多个可选的 StepStarted 和 StepFinished 事件对。
  3. 以一个 RunFinished 或 RunError 事件作为结束，分别对应成功和失败两种情况。

下图展示了生命周期事件在智能体和客户端交互时的流程。

文本消息事件​

文本消息事件表示会话中的文本消息的生命周期。文本消息事件以流式的方式传输，内容是增量传递的。一条文本消息的传输过程，会包含如下事件。

  1. 从一个 TextMessageStart 事件开始。
  2. 一个或多个 TextMessageContent 事件，包含文本消息的片段。
  3. 以一个 TextMessageEnd 事件作为结束。

下图展示了文本消息事件在智能体和客户端交互时的流程。

TextMessageStart​

TextMessageStart 事件中会包含 messageId 和 role，分别表示消息的 ID 和角色。

TextMessageContent​

TextMessageContent 事件的 messageId 表示消息的 ID， 而 delta 则表示文本消息的片段。

TextMessageEnd​

TextMessageEnd 事件中只包含 messageId。

工具调用事件​

工具调用事件与工具调用的生命周期相关。工具调用也遵循同样的流式模式。

  1. 从一个 ToolCallStart 事件开始。
  2. 一个或多个 ToolCallArgs 事件表示工具调用的参数。
  3. 以一个 ToolCallEnd 事件作为结束。

下图展示了工具调用事件在智能体和客户端交互时的流程。

ToolCallStart​

ToolCallStart 事件包含 toolCallId，toolCallName 和 parentMessageId 属性，相关的说明见下表。

属性描述
toolCallId工具调用的唯一标识符。
toolCallName被调用工具的名称。
parentMessageId可选的父消息 ID。

ToolCallArgs​

ToolCallArgs 事件中包含 toolCallId 和 delta。delta 的作用与TextMessageContent 事件一样。

ToolCallEnd​

ToolCallEnd 事件中仅包含 toolCallId。

ToolCallResult​

ToolCallResult 事件表示工具调用的结果，相关的说明见下表。

属性描述
messageId此结果所属的会话消息 ID。
toolCallId与对应的 ToolCallStart 事件中的 ID 相匹配。
content工具执行产生的实际结果或输出内容。
role可选的角色标识符，通常对于工具执行结果使用 "tool"。

推理事件​

推理事件用来提供 LLM 内部的推理过程。

  1. 从一个 ReasoningStart 事件开始。
  2. ReasoningMessageStart 事件表示推理消息的开始。
  3. 一个或多个 ReasoningMessageContent 事件表示推理消息的文本片段。
  4. ReasoningMessageEnd 事件表示推理消息的结束。
  5. 以一个 ReasoningEnd 事件作为结束。

下图展示了推理事件在智能体和客户端交互时的流程。

ReasoningStart​

ReasoningStart 事件仅包含属性 messageId，表示消息 ID。

ReasoningMessageStart​

ReasoningMessageStart 事件中包含属性 messageId 和 role。role 的值通常是 "reasoning"。

ReasoningMessageContent​

ReasoningMessageContent 事件的结构与文本消息事件是一样的，同样使用 delta 来表示消息的文本片段。

ReasoningMessageEnd​

ReasoningMessageEnd 事件中仅包含属性 messageId。

ReasoningEnd​

ReasoningEnd 事件中仅包含属性 messageId。

CopilotKit 集成​

文本消息、推理过程和工具都是智能体中最基本的内容。如果使用 CopilotKit，已经内置提供了相关的支持。

  • 与智能体交互时，界面上所展示的流式响应输出，是对文本消息事件的处理。
  • 如果模型返回了推理消息，会在界面上以流式的方式显示。
  • 模型调用工具时，工具的名称，输入参数和返回结果，会在界面上显示。

对于智能体的前端应用来说，这些开箱即用的功能简化了与 AG-UI 集成的实现。

文本消息​

CopilotKit 的聊天界面默认使用流式方式来展示消息。

工具调用​

在 CopilotKit 中使用 useDefaultRenderTool 来启动默认的工具渲染界面。

启用默认的工具渲染
import { CopilotChat, useDefaultRenderTool } from "@copilotkit/react-core/v2";

function Chat() {
  useDefaultRenderTool();

  return <CopilotChat />;
}

下图展示了 CopilotKit 中对工具调用的渲染方式。

CopilotKit 中的工具调用

推理过程​

为了演示 AG-UI 的推理事件，需要一个支持推理的模型，并且把推理过程以明文发送回调用者。

OpenAI 和 Anthropic 的模型并不会以明文方式发送完整的推理过程。

这里用的模型是 DeepSeek V4 Flash，通过 OpenRouter 来调用。

下图展示了 CopilotKit 中对推理消息的渲染方式。

CopilotKit 中的推理消息

标签：
最后于 更新