跳到主要内容

SDK 与客户端

AG-UI 多语言 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,便于复现与排查协议对接问题。
  • 兼容性:对未知事件类型和可选字段做防御式处理。
  • 安全性:对工具执行、外部链接与生成内容进行必要的权限与校验控制。

参考资源

Type to search…

↑↓ navigate↵ selectEsc close