---
title: "SDK 与客户端"
description: "AG-UI 多语言 SDK、客户端形态与接入实践指南。"
---

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

# SDK 与客户端

AG-UI 以标准化事件与交互模型为核心，配套多语言 SDK 与多种客户端形态，帮助团队在不同技术栈中快速接入。

## SDK 概览

### 语言支持（示例）

| 语言/生态 | 典型用途 | 说明 |
| --- | --- | --- |
| TypeScript / JavaScript | Web 客户端、Node.js 服务、框架集成 | 生态成熟，常与前端框架与 Mastra 等集成配合 |
| Python | 智能体后端、框架适配 | 多数智能体框架集成常用语言 |
| Kotlin / Java | JVM 服务端与 Android 生态 | 适合企业后端与移动端场景 |
| Go | 高性能服务与基础设施 | 适合网关、代理与后端服务 |
| .NET | 企业应用与微软生态 | 适合与 Microsoft Agent Framework 等协同 |
| Dart / Rust / Ruby / C++ 等 | 特定平台或性能需求 | 多为社区维护，请关注仓库状态 |

> SDK 的 API 设计、覆盖的事件类型与成熟度可能不同。接入前请查阅对应语言 SDK 的 README、版本说明与示例。

### SDK 通常提供的能力

- **事件模型与类型定义**：标准事件枚举、数据结构与序列化支持
- **客户端/连接工具**：建立运行、订阅事件流、发送输入
- **编码/解码与流处理**：处理 SSE/WebSocket 等传输与流式分片
- **状态与消息辅助**：帮助聚合快照/增量与消息流（视 SDK 而定）

## 客户端形态

### Web 应用

- 在浏览器中订阅 AG-UI 事件流，实时渲染聊天、工具状态、共享状态与生成式 UI。
- 可与 CopilotKit 等方案结合，加速构建生产级交互界面。
- 需关注流式渲染性能、长列表/长会话状态管理与错误恢复。

### 终端（CLI）

- 将事件流映射为终端输出（流式文本、进度、提示符交互）。
- 适合开发调试、运维工具与开发者工作流。
- 官方提供了从零构建 CLI 客户端的示例思路（参见 Quickstart：Build clients）。

### 聊天平台（Slack / Teams 等）

- 将 AG-UI 事件转换为平台消息、卡片与交互组件。
- 需处理平台特有的消息格式、权限与交互回调。
- 可参考 Channels SDK 等生态实现。

### 移动端与原生应用

- 通过对应语言 SDK 在 React Native 或原生技术栈中接入。
- 需考虑网络状态、后台行为与移动端 UI 交互模式。

## 接入实践

### 最小可用实现（MVP）

1. 建立与智能体端点的连接并发起运行。
2. 处理 `RUN_STARTED` / `RUN_FINISHED` / `RUN_ERROR`。
3. 实现 `TEXT_MESSAGE_*` 流式渲染。
4. 支持基本用户输入回传。

### 逐步增强

- **工具**：处理 `TOOL_CALL_*` 与 `TOOL_CALL_RESULT`，区分后端展示与前端执行。
- **状态**：支持 `STATE_SNAPSHOT` / `STATE_DELTA` / `MESSAGES_SNAPSHOT`。
- **人机协同**：处理中断结果与恢复输入。
- **高级事件**：按需支持推理、活动、子智能体与自定义事件。

### 工程建议

- **事件聚合层**：将协议事件转换为应用内部的统一状态模型，避免 UI 直接依赖原始事件细节。
- **可观测性**：记录事件序列与关键 ID，便于复现与排查协议对接问题。
- **兼容性**：对未知事件类型和可选字段做防御式处理。
- **安全性**：对工具执行、外部链接与生成内容进行必要的权限与校验控制。

## 参考资源

- [快速开始：构建客户端](https://ag-ui.ndjp.net/quickstart/clients/)
- [事件参考](https://ag-ui.ndjp.net/reference/events/)
- [AG-UI 官方文档](https://docs.ag-ui.com/)
- [AG-UI GitHub](https://github.com/ag-ui-protocol/ag-ui)
- [CopilotKit 文档](https://docs.copilotkit.ai/)（Web 集成参考）

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