近两年，AI Agent 正在从实验室走向生产环境。Agent 与用户界面之间的沟通桥梁——AG‑UI协议，正悄然成为业界共识。本文不走公式化路线，而是用轻松的笔触把它拆开来聊，让你在阅读时还Neng感受到一点小惊喜。

想象一个智Neng客服，它背后可Neng是 GPT‑4、Claude 或者自研的大模型。这些模型本身只会输出文本，Ru果没有统一的约定，前端只Neng靠硬编码的“请求‑响应”方式来显示结果。

传统 API：一次调用返回完整答案。

流式交互：需要边生成边展示，就像打字机一样。

AG‑UI 正是为了解决「实时流式」「工具调用」「状态同步」三大痛点而生，它把这些行为抽象成一套标准事件，让前后端像玩乐高一样拼接功Neng块。

组件层负责 UI 基础元素，常见库有 Ant Design X、Vercel AI SDK、CopilotKit 等。 智体层是业务逻辑所在负责调度模型、调用工具、维护状态；这里通常使用 AI SDK、LlamaIndex 等包装好的类库。 模型层提供具体的大语言模型服务，如 GPT‑4、Claude、Gemini 等。

这三层通过统一的协议进行对话，互不侵入，却又Neng共享信息。

// 只列出Zui常用的几种
export enum EventType {
  RUN_STARTED   = "RUN_STARTED",   // 整个任务启动
  TEXT_MESSAGE_START = "TEXT_MESSAGE_START", // 文本流开始
  TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT", // 内容片段
  TEXT_MESSAGE_END = "TEXT_MESSAGE_END",   // 文本流结束
  TOOL_CALL_START = "TOOL_CALL_START",     // 调用外部工具
  TOOL_CALL_RESULT = "TOOL_CALL_RESULT",    // 工具返回结果
  STATE_SNAPSHOT = "STATE_SNAPSHOT",       // 状态快照同步
  RUN_FINISHED   = "RUN_FINISHED"          // 完结标记
}

每一种事件dou有统一的 JSON 格式，前端只要订阅对应的流即可收到实时geng新。

AG‑UI 把「发布」与「订阅」职责交给了 RxJS。下面是一段极简版实现：

import { Observable, Subject } from 'rxjs';
import { EventEncoder } from '@ag-ui/encoder';
export function applyEvents(
  input: RunAgentInput,
  agent: AbstractAgent,
): Observable {
  const events$ = new Subject;
  // 向外部推送 RUN_STARTED
  events$.next({
    type: EventType.RUN_STARTED,
    threadId: input.threadId,
    runId: input.runId,
  });
  // 模拟模型产生文字流
  const stream = agent.generateStream;
  stream.subscribe(chunk => {
    events$.next({
      type: EventType.TEXT_MESSAGE_CONTENT,
      messageId: chunk.id,
      delta: chunk.text,
    });
  }, err => {
    events$.error;
  },  => {
    events$.next;
    events$.complete;
  });
  return events$.asObservable;
}

上面的代码里“Subject”充当了事件中心，所有订阅者dou会收到同样的信息。实际项目中会再加一层「持久化」或「安全校验」，但核心思路就是这么直接。

import express from 'express';
import { EventEncoder } from '@ag-ui/encoder';
import { OpenAI } from 'openai';
import { v4 as uuidv4 } from 'uuid';
const app = express;
app.use);
app.post => {
  const { threadId, runId, messages } = req.body;
  res.setHeader;
  const encoder = new EventEncoder;
  // SEND RUN_STARTED
  res.write(encoder.encode({
    type: 'RUN_STARTED',
    threadId,
    runId,
  }));
  const openai = new OpenAI;
  const stream = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages,
    stream: true,
});
let msgId = uuidv4;
res.write(encoder.encode({
   type: 'TEXT_MESSAGE_START',
   messageId: msgId,
   role: 'assistant',
}));
for await  {
   if  {
      res.write(encoder.encode({
        type: 'TEXT_MESSAGE_CONTENT',
        messageId: msgId,
        delta: chunk.choices.delta.content,
      }));
   }
}
res.write);
res.write);
res.end;
});
app.listen => console.log);

async function startChat {
   const response = await fetch('/agui', {
     method:'POST',
     headers:{'Content-Type':'application/json'},
     body:JSON.stringify({
        threadId:'t-'+Date.now,
        runId:'r-'+Date.now,
        messages:
     })
   });
   const reader = response.body.getReader;
   const decoder = new TextDecoder;
   let buffer='';
   while{
      const {done,value}=await reader.read;
      if break;
      buffer+=decoder.decode;
      const lines=buffer.split;
      buffer=lines.pop;               // 留下未完整的一行
      for{
         if){
            const json=line.slice.trim;
            if{
               const evt=JSON.parse;
               handleEvent;          // 自己实现 UI 渲染逻辑
            }
         }
      }
   }
}

配合一个简单的 #chatBox 区域，你就Nengkan到文字像打字机一样逐字出现——这正是 AG‑UI 想让你感受到的「实时交互」体验。

SSE 超时：hen多云平台默认对 HTTP 长连接有限制，需要在响应头里加 X-Accel-Buffering:false 或者开启心跳包。

事件顺序：A/B 测试发现，Ru果在发送 TEXT_MESSAGE_START 前先写入一次空白数据，Chrome 会geng快渲染首帧。

#CORS 与 token：SSE 同源策略严苛，建议把 token 放在查询字符串里或者使用 Cookie+SameSite=Strict 配合。

#日志调试：SSE 本身不支持直接查kan body，建议在后端把每条事件写入文件或 console，以免找不到根源。

#并发控制：Aggressive 并发调用同一个 Agent 时需要在前端为每个会话维护独立的 SSEChannel，防止消息错位。

顺便提一句，这些技巧大多来源于真实项目中的踩坑记录，用它们Ke以省去不少夜深人静时的“debug”苦恼。

*2025 年底* 的技术趋势预测显示，AI Agent 将从单点聊天向多模态协作进化。随着 Anthropic 开源 MCP以及 Google A2A 的出现，协议之间将形成「链路」而不是孤岛。AG‑UI 正在向以下两个方向演进：