---
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 集成（Integration）。

## 何时需要构建集成

- 你使用的智能体框架/平台尚未提供 AG-UI 支持
- 你有自研的 Agent 编排、工具系统或运行时，希望暴露统一交互协议
- 你希望将已有协议/事件体系转换为 AG-UI 事件流

如果已有现成集成（如 LangGraph、CrewAI、Mastra 等），通常可直接使用对应集成并转向[构建应用](https://ag-ui.ndjp.net/quickstart/applications/)。

## 两种实现方式

### 1. 直接发射 AG-UI 事件

在智能体或服务端执行逻辑中，按协议要求直接产生并输出 AG-UI 事件。

**优点**：语义最贴近协议，行为可控，便于精细支持流式、状态与中断等能力。  
**适用**：新建服务、自研运行时、可深度改造执行流程的系统。

关键要求：
- 在一次运行中正确发出生命周期事件（如 `RUN_STARTED`，以及 `RUN_FINISHED` 或 `RUN_ERROR`）。
- 对流式内容使用 Start/Content/End 或 Chunk 模式。
- 为工具调用、状态同步等能力输出对应事件。
- 保证事件中的标识符（`threadId`、`runId`、`messageId`、`toolCallId` 等）一致且可关联。

### 2. 通过中间件/适配层转换

将现有框架或协议的事件/回调转换为 AG-UI 事件，并将 AG-UI 输入转换为后端可理解的请求。

**优点**：复用现有系统能力，改造成本较低。  
**适用**：已有成熟 Agent 框架、希望快速接入 AG-UI 客户端生态的场景。

关键要求：
- 建立清晰的事件映射（消息、工具、状态、生命周期、错误）。
- 处理流式分片与结束条件，避免消息或工具调用无法闭合。
- 在必要时使用 `RAW`/`CUSTOM` 事件承载无法直接映射的信息，同时尽量提供标准事件。

## 集成实现要点

### 输入处理

集成需要接收 AG-UI 兼容输入（具体结构以协议/SDK 为准），通常包括：
- 线程与运行标识（`threadId`、`runId` 等）
- 消息历史与当前用户输入
- 可用工具定义（含前端工具）
- 共享状态与上下文
- 中断恢复时的响应数据（如适用）

### 事件输出

- **传输层**：可选择 SSE、WebSocket 等；确保支持流式推送与连接管理。
- **顺序与一致性**：同一消息/工具调用的事件应可通过 ID 正确关联。
- **错误处理**：在失败时发出 `RUN_ERROR`（并按实现约定携带错误信息），避免客户端悬挂。
- **状态同步**：按需发出 `STATE_SNAPSHOT` / `STATE_DELTA` / `MESSAGES_SNAPSHOT`。

### 能力覆盖建议

可按优先级逐步实现：
1. 基础：运行生命周期 + 文本消息流式输出
2. 进阶：工具调用与结果、共享状态
3. 高级：前端工具、人机协同中断、推理/活动/子智能体事件、生成式 UI 相关能力

## 参考模板与资源

- 官方仓库中的集成模板与现有实现（如 middleware/server starter、各框架集成目录）
- [事件参考](https://ag-ui.ndjp.net/reference/events/)：标准事件类型与字段
- [核心架构](https://ag-ui.ndjp.net/concepts/architecture/)：端到端交互模型
- [AG-UI Dojo](https://dojo.ag-ui.com/)：对照目标行为

## 下一步

- 完成集成后，可按[构建应用](https://ag-ui.ndjp.net/quickstart/applications/)验证客户端体验
- 如需自定义消费端，参考[构建客户端](https://ag-ui.ndjp.net/quickstart/clients/)

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