Agent User Interaction Protocol (AG-UI)

通过 Agent User Interaction Protocol (AG-UI) 暴露深度智能体，以将事件流式传输到任何 AG-UI 客户端或前端。

Agent User Interaction Protocol (AG-UI) 是一种开放、轻量、基于事件的协议，它标准化了 AI 智能体连接到面向用户的应用程序的方式。 通过 AG-UI 暴露深度智能体，会将其运行转变为类型化的事件流（消息、工具调用、推理、状态和生命周期），任何 AG-UI 客户端都可消费该事件流，因此你可以驱动前端，而无需将其与 LangGraph 内部实现耦合。

NOTE

AG-UI 是为智能体与用户的交互而设计的：即智能体后端与面向用户的前端之间的连接。它不同于其他 Deep Agents 协议：

• AG-UI 将深度智能体连接到前端应用程序（本页）。
• Agent Client Protocol (ACP) 将深度智能体连接到代码编辑器和 IDE。
• Model Context Protocol (MCP) 让深度智能体能够调用由外部服务器托管的工具。
• Agent2Agent (A2A) 将深度智能体连接到其他智能体。

快速开始

将深度智能体作为 LangGraph 图提供服务，然后连接 TypeScript @ag-ui/langgraph 适配器，以便 AG-UI 客户端可以驱动它。

安装依赖

安装 Deep Agents 和 LangGraph CLI 以服务该图。后续步骤中使用的 AG-UI 适配器是 TypeScript（@ag-ui/langgraph）。如需 Python 的 CopilotKit 或 AG-UI FastAPI 桥接，请参阅 CopilotKit。

pip

pip install deepagents "langgraph-cli[inmem]"

uv

uv add deepagents "langgraph-cli[inmem]"

使用 createDeepAgent（Python 中为 create_deep_agent）创建的深度智能体就是一个 LangGraph 图。将其作为 LangGraph 服务器提供服务，即可向 AG-UI 客户端暴露它，然后将 AG-UI 适配器指向该服务器。

创建深度智能体

定义智能体并导出该图，以便 LangGraph 服务器可以加载它。

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    system_prompt="You are an expert researcher.",
)

服务该智能体

在项目根目录的 langgraph.json 文件中注册该图。

{
  "dependencies": ["."],
  "graphs": {
    "deep_agent": "./agent.py:agent"
  },
  "env": ".env"
}

启动 LangGraph 开发服务器。它通过 HTTP 在 http://localhost:2024 暴露该图。

langgraph dev

连接 AG-UI 适配器

TypeScript @ag-ui/langgraph 适配器会将正在运行的图包装为任何客户端都能驱动的 AG-UI 智能体。将它指向 LangGraph 服务器并指定要加载的图。无论该图是用 Python 还是 TypeScript 编写的，这都适用。

import { LangGraphAgent } from "@ag-ui/langgraph";

const agent = new LangGraphAgent({
  graphId: "deep_agent",
  deploymentUrl: "http://localhost:2024",
});

•AG-UI LangGraph adapter on npm

@ag-ui/langgraph 包为 LangGraph 图（包括深度智能体）实现 AG-UI 协议。

流式事件

AG-UI 是一个事件流。当深度智能体运行时，适配器会将其 LangGraph 执行转换为类型化的 AG-UI 事件。客户端订阅这些事件并在事件到达时进行更新，而不是等待最终答案。

一次深度智能体运行会映射到多种 AG-UI 事件类型。其中主要的有：

深度智能体活动	AG-UI 事件
运行生命周期	RUN_STARTED, RUN_FINISHED, RUN_ERROR
图节点进度	STEP_STARTED, STEP_FINISHED
Assistant 文本	TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END
工具调用	TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_RESULT
推理	REASONING_START, REASONING_MESSAGE_CONTENT, REASONING_END
共享状态（待办事项、子智能体、自定义键）	STATE_SNAPSHOT, STATE_DELTA
对话历史	MESSAGES_SNAPSHOT

状态更新使用 STATE_SNAPSHOT 表示完整基线，使用 STATE_DELTA（JSON Patch，RFC 6902）表示增量变更，因此客户端可以让待办事项、计划和子智能体状态保持同步，而无需在每一步都重新发送整个状态。

要直接观察该流，请使用订阅者运行智能体。每个事件都有一个匹配的 on…Event 回调：

import { LangGraphAgent } from "@ag-ui/langgraph";

const agent = new LangGraphAgent({
  graphId: "deep_agent",
  deploymentUrl: "http://localhost:2024",
  initialMessages: [
    { id: "1", role: "user", content: "Research the AG-UI protocol." },
  ],
});

await agent.runAgent(
  {},
  {
    onTextMessageContentEvent({ event }) {
      process.stdout.write(event.delta);
    },
    onToolCallStartEvent({ event }) {
      console.log(`\n[tool] ${event.toolCallName}`);
    },
    onStateSnapshotEvent({ event }) {
      console.log("\n[state]", event.snapshot);
    },
    onRunFinishedEvent() {
      console.log("\n[done]");
    },
  },
);

当深度智能体暂停以等待人类输入时，运行会以中断结束。默认情况下，@ag-ui/langgraph 会在发出 RUN_FINISHED 的同时发出一个遗留的 on_interrupt 自定义事件。要在 RUN_FINISHED 上接收结构化的 AG-UI 中断结果（outcome.type === "interrupt"），请在构造智能体时设置 emitInterruptOutcome: true：

const agent = new LangGraphAgent({
  graphId: "deep_agent",
  deploymentUrl: "http://localhost:2024",
  emitInterruptOutcome: true,
});

在下一次输入时发送标准的 AG-UI resume 字段，以恢复运行：

const input = {
  threadId: "t1",
  runId: "r2",
  messages: [],
  resume: [
    { interruptId: "int-abc", status: "resolved", payload: { approved: true } },
  ],
};

关于中断模型本身，请参阅人在回路。

INFO

完整的事件 schema，请参阅 AG-UI 事件参考。

连接前端

任何 AG-UI 客户端都可以驱动通过该协议暴露的深度智能体，因此你不必自己构建消息渲染、流式传输或状态同步。将客户端指向该适配器（或包装它的运行时），并通过其 graphId 选择智能体。

•CopilotKit

带有 AG-UI 支持的 React 聊天运行时，适用于 LangGraph 和 Deep Agents，包括 Python FastAPI 桥接。

•AG-UI clients

AG-UI 客户端和 SDK 的完整列表，包括终端和移动客户端。

{ }Build a custom client

使用 AG-UI SDK 直接消费事件流，以构建你自己的界面。

编程式 API

LangGraphAgent 连接到 LangGraph 服务器上的深度智能体，并将其作为 AG-UI 智能体暴露。用要加载的图构造它，然后通过几个方法驱动它。

import { LangGraphAgent } from "@ag-ui/langgraph";

const agent = new LangGraphAgent({
  graphId: "deep_agent",              // matches a key in langgraph.json
  deploymentUrl: "http://localhost:2024",
});

• runAgent(parameters?, subscriber?)：运行智能体，并将 AG-UI 事件流式传输到订阅者的 on…Event 回调（参见流式事件）。运行完成时 resolve。
• subscribe(subscriber)：附加一个持久订阅者，它会在每次运行时接收事件，而不是仅针对单次调用。
• abortRun()：取消正在进行的运行。

要预置输入，请将 initialMessages 传递给构造函数，或在运行前调用 addMessage 或 setMessages。

另请参阅

• CopilotKit：在 AG-UI 之上使用 Python 和 TypeScript 的 CopilotKit 运行时模式来构建 Deep Agents
• 前端概览：使用 LangChain 前端 SDK 构建可流式输出深度智能体进度的 UI
• 人在回路：深度智能体的中断与恢复模型
• Agent Client Protocol (ACP)：将深度智能体连接到代码编辑器和 IDE
• AG-UI 文档：协议概念、事件和客户端 SDK

---