智能体用户交互协议 (AG-UI)

将 Deep Agents 连接到符合 AG-UI 标准的前端交互组件与对话界面

智能体用户交互协议（Agent User Interaction Protocol, AG-UI）是一套标准化的事件传输规范，旨在解决 AI 智能体与丰富前端组件（富文本打字机、思考推理折叠块、工具调用执行卡片、人在回路表单）之间的解耦通信问题。

通过 AG-UI 适配器，Deep Agents 的内部执行事件可以直接转换为 AG-UI 标准流，供任何兼容 AG-UI 的前端组件库即插即用消费。

快速起步 (Quickstart)

1. 安装依赖包 (Install dependencies)

安装核心依赖：

npm install @ag-ui/langgraph deepagents @langchain/langgraph-cli

2. 创建 deep agent

使用标准方式配置你的智能体：

yarn add @ag-ui/langgraph deepagents @langchain/langgraph-cli

3. 启动智能体服务

将智能体通过 LangGraph API 暴露：

pnpm add @ag-ui/langgraph deepagents @langchain/langgraph-cli

4. 连接 AG-UI 适配器

使用适配器将 LangGraph 流转换为标准 AG-UI 协议事件：

import { createDeepAgent } from "deepagents";

export const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  systemPrompt: "You are an expert researcher.",
});

流式事件流规范 (Stream events)

AG-UI 定义了标准的事件生命周期：

• RUN_START：智能体任务启动。
• TEXT_MESSAGE_DELTA：文本 Token 增量打字机事件。
• TOOL_CALL_START / TOOL_CALL_DELTA / TOOL_CALL_END：工具调用的参数组装与执行结果。
• SUBAGENT_START / SUBAGENT_END：子智能体任务的派发与完成通知。
• RUN_END：整个会话轮次结束。

连接前端组件 (Connect a frontend)

在前端 UI 中，你可以使用任何支持 AG-UI 协议的标准组件库（如 CopilotKit、assistant-ui、AI Elements），直接挂载该端点：

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

编程式 API 参考 (Programmatic API)

AG-UI 适配器导出了灵活的工具函数，用于自定义事件映射、中间数据过滤和自定义鉴权校验。

另请参阅

• 前端集成总览 (Frontend overview)：探索更多前端交互模式。
• ACP 客户端协议 (ACP)：连接现代代码编辑器。

npx @langchain/langgraph-cli dev

Connect the AG-UI adapter

The TypeScript @ag-ui/langgraph adapter wraps the running graph as an AG-UI agent that any client can drive. Point it at the LangGraph server and name the graph to load. This works whether the graph was authored in Python or TypeScript.

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

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

AG-UI LangGraph adapter on npm

The @ag-ui/langgraph package implements the AG-UI protocol for LangGraph graphs, including deep agents.

Stream events

AG-UI is an event stream. As a deep agent runs, the adapter translates its LangGraph execution into typed AG-UI events. A client subscribes to those events and updates as they arrive, rather than waiting for the final answer.

A deep agent run maps onto many AG-UI event types. The main ones, among others:

Deep agent activity	AG-UI events
Run lifecycle	RUN_STARTED, RUN_FINISHED, RUN_ERROR
Graph node progress	STEP_STARTED, STEP_FINISHED
Assistant text	TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END
Tool calls	TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_RESULT
Reasoning	REASONING_START, REASONING_MESSAGE_CONTENT, REASONING_END
Shared state (todos, subagents, custom keys)	STATE_SNAPSHOT, STATE_DELTA
Conversation history	MESSAGES_SNAPSHOT

State updates use STATE_SNAPSHOT for a full baseline and STATE_DELTA (JSON Patch, RFC 6902) for incremental changes, so a client can keep todos, plans, and subagent status in sync without re-sending the whole state on every step.

To watch the stream directly, run the agent with a subscriber. Each event has a matching on…Event callback:

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]");
    },
  },
);

When a deep agent pauses for human input, the run finishes with an interrupt. By default, @ag-ui/langgraph emits a legacy on_interrupt custom event alongside RUN_FINISHED. To receive the structured AG-UI interrupt outcome on RUN_FINISHED (outcome.type === "interrupt"), set emitInterruptOutcome: true when you construct the agent:

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

Resume the run by sending the standard AG-UI resume field on the next input:

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

For the interrupt model itself, see Human-in-the-loop.

NOTE

For the complete event schema, see the AG-UI events reference.

Connect a frontend

Any AG-UI client can drive a deep agent exposed over the protocol, so you do not have to build message rendering, streaming, or state sync yourself. Point the client at the adapter (or a runtime that wraps it) and select the agent by its graphId.

CopilotKit

React chat runtime with AG-UI support for LangGraph and Deep Agents, including the Python FastAPI bridge.

AG-UI clients

The full list of AG-UI clients and SDKs, including terminal and mobile clients.

Build a custom client

Consume the event stream directly with the AG-UI SDK to build your own interface.

Programmatic API

LangGraphAgent connects to a deep agent on a LangGraph server and exposes it as an AG-UI agent. Construct it with the graph to load, then drive it with a few methods.

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?): Run the agent and stream AG-UI events to the subscriber's on…Event callbacks (see Stream events). Resolves when the run finishes.
• subscribe(subscriber): Attach a persistent subscriber that receives events across every run, rather than for a single call.
• abortRun(): Cancel the run in progress.

To seed input, pass initialMessages to the constructor, or call addMessage or setMessages before running.

See also

• CopilotKit: Python and TypeScript CopilotKit runtime patterns for Deep Agents over AG-UI
• Frontend overview: Build UIs that stream deep agent progress with the LangChain frontend SDKs
• Human-in-the-loop: Interrupt and resume model for deep agents
• Agent Client Protocol (ACP): Connect deep agents to code editors and IDEs
• AG-UI documentation: Protocol concepts, events, and client SDKs

---

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.