---
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 定义了智能体后端与用户应用之间的标准交互架构：通过**事件流**输出执行过程，通过**兼容输入**接收用户与应用侧信息。

## 架构概览

典型部署中，AG-UI 连接以下组件：

- **应用（Application）**：面向用户的界面，如 Web 聊天、Copilot 面板、终端或聊天平台机器人。
- **AG-UI 客户端（Client）**：负责协议通信的组件/SDK（如 HTTP Agent 客户端或特定集成客户端）。
- **智能体后端（Agent / Server）**：执行推理与工具调用的服务，可由框架实现或自研。
- **安全代理/网关（可选）**：用于鉴权、路由、多智能体接入或协议转换。

通信方向是双向的：客户端向智能体发送运行输入；智能体向客户端持续推送事件流。

## 设计原则

1. **事件驱动通信**：智能体在执行期间发出标准化事件，客户端按事件更新 UI 与状态。
2. **双向交互**：支持用户输入、前端工具结果、审批与中断响应等回传。
3. **轻量与低约束**：协议尽量减少对实现细节的强制要求，便于适配多种框架。
4. **传输灵活**：同一语义可承载于 SSE、WebSocket、Webhook 等不同传输方式。
5. **可兼容与可扩展**：支持宽松格式匹配、原生事件转换，以及 `RAW`/`CUSTOM` 扩展。

## 运行与事件模型

一次智能体运行通常由生命周期事件界定：

- `RUN_STARTED`：运行开始，建立 `runId` / `threadId` 等上下文
- 运行过程中：发出文本、工具、状态、步骤、活动、推理、子智能体等事件
- `RUN_FINISHED` 或 `RUN_ERROR`：运行结束（成功、失败或中断结果，视协议版本与实现而定）

客户端应将事件流归并为一致的会话状态模型，以支持实时渲染、回放与错误恢复。

## 核心事件类别（概览）

| 类别 | 典型事件 | 用途 |
| --- | --- | --- |
| 生命周期 | `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`, `STEP_*` | 标识运行与步骤边界 |
| 文本消息 | `TEXT_MESSAGE_START/CONTENT/END` 等 | 流式文本输出 |
| 工具调用 | `TOOL_CALL_START/ARGS/END/RESULT` 等 | 工具执行与结果传递 |
| 状态管理 | `STATE_SNAPSHOT`, `STATE_DELTA`, `MESSAGES_SNAPSHOT` | 共享状态与消息同步 |
| 活动 | `ACTIVITY_SNAPSHOT`, `ACTIVITY_DELTA` | 结构化进行中活动展示 |
| 推理 | `REASONING_*` | 可展示的推理/过程信息 |
| 子智能体 | `SUBAGENT_STARTED/FINISHED/ERROR` | 子智能体生命周期与归因 |
| 特殊/扩展 | `RAW`, `CUSTOM` | 外部事件透传与自定义扩展 |

详细字段与语义见[事件机制](https://ag-ui.ndjp.net/concepts/events/)与[事件参考](https://ag-ui.ndjp.net/reference/events/)。

## 输入与双向能力

客户端向智能体提交的输入通常包含（具体以 SDK/实现为准）：
- 会话标识与运行参数
- 用户消息与历史上下文
- 可用工具定义（包括前端可执行工具）
- 共享状态与应用上下文
- 中断恢复时的用户响应

这使得智能体不仅能“输出”，还能在执行中请求前端动作或人工介入。

## 与 MCP / A2A 的关系

- **MCP** 解决智能体如何访问工具与数据源。
- **A2A** 解决智能体之间如何通信与协作。
- **AG-UI** 解决智能体如何与最终用户及其界面交互。

三者可在同一系统中分层协作：智能体通过 MCP 使用工具、通过 A2A 协同其他智能体、通过 AG-UI 向用户呈现过程并接收反馈。

## 实现建议

- **后端/集成端**：优先保证生命周期与消息流正确闭合，再逐步扩展工具、状态与中断能力。
- **客户端**：以事件 ID 为键聚合流式增量，维护单一可信的会话状态源。
- **传输层**：根据实时性与部署环境选择 SSE 或 WebSocket，并处理断线与重试。
- **兼容性**：对未知事件类型保持前向兼容（记录/忽略但不中断主流程，视需求而定）。

Source: https://ag-ui.ndjp.net/concepts/architecture/index.mdx
