---
title: "调试 AG-UI 集成"
description: "使用 AG-UI Dojo 与常见调试模式排查集成问题。"
---

> 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 集成

调试基于智能体的应用可能很有挑战，尤其是在处理 AG-UI 这样的实时、事件驱动协议时。本指南介绍 AG-UI Dojo——一个用于学习、测试与调试 AG-UI 实现的强大工具。

## AG-UI Dojo

AG-UI Dojo 是把 AG-UI 带到新平台的最佳方式，也是学习协议基础能力的绝佳资源。它提供一个结构化环境，用于测试与验证 AG-UI 协议的每个组件。

### 什么是 Dojo

Dojo 由一系列 “hello world” 规模的演示组成，覆盖 AG-UI 提供的不同构建块。每个演示：

1. 展示某个具体的 AG-UI 能力
2. 并排呈现用户可见交互与底层代码
3. 让你测试并验证自己的实现

### 把 Dojo 当作实现清单

在把 AG-UI 带到新平台或界面时，可以把 Dojo 当作完整的“待办清单”：

1. 逐个完成每个演示
2. 在你的环境中实现并测试每个 AG-UI 构建块
3. 当所有演示在你的实现中正常工作时，就可以确信能够在其上构建完整功能的 Copilot 与智能体原生应用

这种系统化方法确保你覆盖了完整 AG-UI 实现所需的全部功能。

### 把 Dojo 当作学习资源

对刚接触 AG-UI 的开发者，Dojo 是交互式学习资源：

- 每个条目演示一个具体的 AG-UI 能力
- 你能看到交互从用户视角是什么样
- 底层代码同时展示，帮助理解其工作原理
- 逐步增加的复杂度帮助从基础到高级建立理解

### 常见调试模式

使用 Dojo 调试 AG-UI 实现时，请留意这些模式：

1. **事件顺序问题**：确认事件按正确顺序发射并具有正确嵌套（例如 `TEXT_MESSAGE_START` 在 `TEXT_MESSAGE_CONTENT` 之前）
2. **数据格式问题**：确保事件载荷符合每种事件类型的预期结构
3. **传输层调试**：检查所选传输机制（SSE、WebSocket 等）是否正确投递事件
4. **状态同步**：确认状态更新通过快照与增量正确应用
5. **工具执行**：验证工具调用与响应被正确格式化与处理

## 开始使用 Dojo

1. 克隆仓库：[github.com/ag-ui-protocol/ag-ui](https://github.com/ag-ui-protocol/ag-ui)
2. 按 README 中的说明完成设置
3. 按顺序逐个完成演示
4. 使用提供的测试用例验证你的实现

Dojo 的结构化方法使其成为学习 AG-UI、确保实现满足全部要求的宝贵资源。

## 在线体验

你也可以直接访问 [dojo.ag-ui.com](https://dojo.ag-ui.com/)，按框架与特性浏览演示，并查看对应的代码与讲解。

## 相关页面

- [事件机制](https://ag-ui.ndjp.net/concepts/events/)
- [事件参考](https://ag-ui.ndjp.net/reference/events/)
- [构建客户端](https://ag-ui.ndjp.net/quickstart/clients/)

Source: https://ag-ui.ndjp.net/tutorials/debugging/index.mdx
