---
title: "构建应用"
description: "使用兼容 AG-UI 的智能体与客户端，快速搭建面向用户的智能体应用。"
---

> 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 应用，也可以是任何能够接收、展示并响应 AG-UI 事件的系统。

## 适用场景

- 为现有产品接入智能体 Copilot / 助手能力
- 基于已支持 AG-UI 的框架或后端快速搭建交互界面
- 需要流式输出、工具可视化、状态同步与人机协同体验

## 快速创建

### 使用脚手架

```bash
npx create-ag-ui-app@latest
```

脚手架可以帮助你选择客户端与服务端组合，生成可运行的示例项目。完成后按项目提示安装依赖并启动：

```bash
npm run dev
# 或根据项目实际脚本使用 pnpm/yarn
```

> 提示：不同模板的端口与启动命令可能不同，请以生成项目的 README 为准。

## 应用端核心职责

一个典型的 AG-UI 应用需要完成以下工作：

1. **建立连接**：通过 HTTP(SSE) 或 WebSocket 等方式连接到智能体端点。
2. **发送输入**：向智能体提交 `RunAgentInput` 等兼容输入（包含消息、线程信息、工具、状态、上下文等，具体字段视实现与 SDK 而定）。
3. **订阅事件流**：按顺序接收并处理 AG-UI 事件。
4. **维护会话状态**：将事件归并为消息列表、工具调用状态、共享状态与 UI 状态。
5. **渲染交互界面**：实时展示流式文本、思考/步骤、工具进展、生成式 UI 与中断请求。
6. **回传用户交互**：将用户回复、前端工具结果、审批/编辑结果等作为后续输入或响应提交。

## 事件处理建议

- **生命周期**：在 `RUN_STARTED` 时初始化运行状态，在 `RUN_FINISHED` / `RUN_ERROR` 时收尾并处理错误或中断结果。
- **文本消息**：处理 `TEXT_MESSAGE_START/CONTENT/END`（或 Chunk 事件）实现流式渲染。
- **工具调用**：处理 `TOOL_CALL_START/ARGS/END/RESULT` 展示调用过程与结果；如支持前端工具，在收到调用后执行并回传结果。
- **状态同步**：用 `STATE_SNAPSHOT` 初始化，用 `STATE_DELTA`（JSON Patch）增量更新共享状态。
- **消息快照**：在需要全量同步时使用 `MESSAGES_SNAPSHOT` 重建会话视图。
- **自定义扩展**：通过 `CUSTOM` / `RAW` 事件承载协议外能力，同时保持对标准事件的兼容。

## 与现有客户端生态结合

- **CopilotKit**：提供成熟的 Web 端集成方案，可作为生产级应用的起点。
- **AG-UI Dojo**：用于对照不同框架与特性的交互行为与实现思路。
- **自研客户端**：当你需要完全自定义 UI 或运行在非 Web 环境时，可直接基于协议/SDK 实现。

## 下一步

- 了解[构建集成](https://ag-ui.ndjp.net/quickstart/integrations/)：当你需要让后端/框架输出 AG-UI 事件时
- 了解[构建客户端](https://ag-ui.ndjp.net/quickstart/clients/)：从零实现事件消费与交互界面
- 阅读[事件机制](https://ag-ui.ndjp.net/concepts/events/)与[事件参考](https://ag-ui.ndjp.net/reference/events/)获取完整协议细节

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