---
title: "构建客户端"
description: "从零实现 AG-UI 客户端，消费事件流并构建终端、Web 或其他形态的交互界面。"
---

> 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.

# 构建客户端

AG-UI 客户端负责连接智能体、发送输入并消费事件流。客户端不局限于 Web 页面：终端、移动应用、聊天平台等任何能处理事件并与用户交互的环境都可以成为客户端。

## 客户端的职责

1. **发起运行**：向智能体端点提交运行输入（消息、线程/运行 ID、工具、状态等）。
2. **接收事件流**：通过 SSE/WebSocket 等方式持续接收事件。
3. **解释协议事件**：按事件类型更新本地会话模型（消息、工具调用、状态、步骤、活动等）。
4. **渲染与交互**：将更新呈现给用户，并收集用户输入或前端工具执行结果。
5. **处理控制流**：支持取消、错误展示、中断处理与恢复。

## 示例：终端客户端思路

官方文档提供了基于 Mastra 与 OpenAI 的 CLI 客户端示例（展示如何连接智能体、实现工具并在终端交互）。典型步骤包括：

- 准备环境：Node.js（示例要求较新版本）、包管理器（如 pnpm）、API Key
- 安装依赖并配置智能体（如 `@ag-ui/mastra`、模型与工具）
- 建立事件订阅循环，将 `TEXT_MESSAGE_*` 渲染为流式输出
- 处理工具调用事件，在本地执行工具并将结果回传

> 具体代码与命令请以官方 Quickstart：Build clients 文档为准。

## 实现建议

### 1. 会话与状态模型

建议在客户端维护统一状态，例如：
- 消息列表（含角色、内容、进行中状态）
- 工具调用表（按 `toolCallId` 聚合参数流与结果）
- 共享应用状态（由 `STATE_SNAPSHOT/DELTA` 驱动）
- 当前运行状态（`runId`、步骤、错误、中断信息）

### 2. 事件分发与聚合

- 为每类事件实现处理器，避免在单一回调中堆叠复杂逻辑。
- 对流式事件（文本、工具参数、推理消息）按 ID 进行增量拼接。
- 收到 `*_END` 或运行结束事件时完成收尾与 UI 状态切换。

### 3. 健壮性

- 处理网络断开、超时与重连策略（按产品需求）。
- 对未知/自定义事件保留可观测记录，避免阻塞主流程。
- 在 `RUN_ERROR` 或中断结果时提供明确的用户反馈与恢复路径。

### 4. 渐进式接入

建议按能力逐步实现：
1. 文本流式聊天 + 运行生命周期
2. 工具调用展示与（可选）前端工具执行
3. 共享状态快照/增量同步
4. 人机协同中断、活动/推理/子智能体可视化
5. 自定义事件与业务扩展

## 生产环境提示

从零构建客户端有助于深入理解协议；生产环境可优先评估成熟客户端方案（如 CopilotKit 等）以获得更完整的功能与工程支持。

## 参考

- 官方文档：[Build clients](https://docs.ag-ui.com/quickstart/clients)
- [事件机制](https://ag-ui.ndjp.net/concepts/events/) 与 [事件参考](https://ag-ui.ndjp.net/reference/events/)
- [SDK 与客户端](https://ag-ui.ndjp.net/sdk/)

Source: https://ag-ui.ndjp.net/quickstart/clients/index.mdx
