使用 CloudBase 和 AG-UI 协议构建 AI Agent

构建一个真正有用的 AI Agent，不仅仅是调用 LLM API 那么简单——它需要管理状态、处理实时事件，以及在不同设备间创造流畅的用户体验。在这篇文章中，我将分享如何用 CloudBase 云函数和 AG-UI 协议构建 shenmiren-agent。

为什么选择 AG-UI？

传统的 Agent 架构有一个根本性问题：前端和后端是松耦合的。你发送一条消息，等待回复，然后重复。没有共享状态的概念，更谈不上实时观察和操控。

AG-UI（Agent-Generated User Interface）通过将 Agent 的内部状态作为一等公民来解决这个问题。Agent 发出事件，前端据此渲染。这带来了无限可能：

无需轮询的实时进度更新
逐 token 出现的流式文本
Agent 可动态调用的客户端工具
通过向量搜索实现的跨会话持久记忆

架构概览

系统由三层构成：

CloudBase 云函数 — 托管 Agent 逻辑、LLM 调用和工具执行
AG-UI 协议 — 基于 SSE 的事件流，实现 Agent 与前端之间的实时通信
客户端 — React/Web 组件，订阅 Agent 发出的事件

用 LangGraph 管理状态

我选择 LangGraph 作为 Agent 框架，因为它将 Agent 行为建模为状态图而非线性链。图的每个节点代表一种特定能力——路由、工具调用、记忆检索、响应生成。

const workflow = new StateGraph(AgentState)
  .addNode("router", routerNode)
  .addNode("memory", memoryNode)
  .addNode("llm", llmNode)
  .addNode("tools", toolsNode)
  .addEdge("__start__", "router")
  .addConditionalEdges("router", decideNext)
  .compile();

客户端工具——秘密武器

让 Agent 真正具备交互能力的关键，是它能调用客户端工具——在用户浏览器或应用中执行、而非在服务端执行的函数。包括：

show_confirm_dialog — 询问用户确认操作
show_toast — 显示通知提示
navigate_to_page — 切换当前视图
play_voice — 文字转语音播放

Agent 可以在对话中途决定调用这些工具，创造出与原生应用交互几乎无异的体验。

记忆系统

短期记忆存储在 CloudBase KV 数据库中，保证快速访问。长期语义记忆使用向量嵌入存于数据库，支持 RAG 风格的检索，在 Agent 需要上下文时提供历史会话信息。

记忆系统将每条信息分类：conversation、insight、plan、milestone、preference。这个分类法帮助 Agent 在正确的时机获取正确的信息。

部署

全部运行在 CloudBase 的 serverless 基础设施上。Agent 函数部署为 HTTP 函数，通过自定义域名暴露，由 CloudBase 边缘网络加速，实现全球低延迟响应。

完整源码可在 GitHub orange-gi/zhiyuxing 查看。欢迎探索、fork 和基于此构建。如果你感兴趣参与贡献，欢迎提 issue——需要改进的地方还有很多。