AG-UI: 快速入门

在上一篇文章中对 AG-UI 进行了基本的介绍，着重说明了 AG-UI 在智能体开发中的重要性。这篇文章将介绍如何在实际的智能体开发中使用 AG-UI，通过具体的实例来说明如何使用 AG-UI 打通智能体的后端和前端。

智能体的开发框架众多，这里使用 LangGraph 作为智能体的后端实现。

在前端开发中，AG-UI 作为一个开放协议，提供了官方的 TypeScript SDK，作为 AG-UI 的客户端。不过该客户端只是提供了 AG-UI 协议层相关的内容，包括 AG-UI 客户端，事件的定义等。直接基于 AG-UI 客户端构建智能体前端界面会比较复杂，涉及到不同事件的界面展示。更好的做法是使用 CopilotKit 库。CopilotKit 也是 AG-UI 规范的提出者。CopilotKit 提供了与智能体界面开发相关的很多组件，可以快速构建应用。

智能体后端

先从智能体后端开始介绍。在 LangChain 和 LangGraph 的帮助下，创建智能体已经变得非常简单了。只需要使用 create_agent 方法就可以创建出智能体。创建时只需要系统提示就足够了。

创建 LangGraph 智能体
def build_graph() -> CompiledStateGraph:
    return create_agent(
        model="openai:gpt-4.1-mini",
        system_prompt="You are a cooking assistant that provides practical, safe, and concise cooking advice.",
        checkpointer=InMemorySaver(),
    )

有了智能体之后，下一步是接入 AG-UI。直接使用 AG-UI 提供的 LangGraph 集成库 ag-ui-langgraph 即可。代码如下所示，逻辑很简单。创建一个 FastAPI 的 app 提供 REST API。再创建一个 LangGraphAgent，使用之前创建的 graph。LangGraphAgent 的作用是封装 LangGraph 的 graph，以适配 AG-UI 协议。最后使用 add_langgraph_fastapi_endpoint 把 LangGraphAgent 添加到 FastAPI 的 app，这样就提供了支持 AG-UI 的 API endpoint。

创建支持 AG-UI 的 API endpoint
app = FastAPI(title="LangGraph AG-UI Agent")

agui_agent = LangGraphAgent(
    name="cooking-agent",
    description="A simple LangGraph agent exposed over the AG-UI protocol.",
    graph=build_graph(),
)

add_langgraph_fastapi_endpoint(app, agui_agent, "/agent")

只需要启动 FastAPI 服务，就得到了 AG-UI 的访问点。

智能体前端

在前端实现中，创建一个 NextJS 的应用，并添加 CopilotKit 相关的依赖。前端应用也分成服务器和客户端两个部分。服务器的部分使用 CopilotKit Runtime 来连接支持 AG-UI 的智能体后端。我们可以把 CopilotKit Runtime 理解为一个代理。CopilotKit Runtime 负责连接不同的智能体，并提供一些管理功能，比如访问智能体的认证信息。

下面的代码是 NextJS 上的一个 API 路由。首先创建 CopilotRuntime。在创建时，指定该 runtime 可以访问的智能体。LangGraphHttpAgent 表示以 HTTP 方式连接的 LangGraph 智能体。每个智能体都有一个 ID 作为标识。由于只有一个智能体，使用默认的 ID 值 default 即可。

接着使用 copilotRuntimeNextJSAppRouterEndpoint 方法创建 NextJS 的路由实现，指定了访问的路径 /api/copilotkit。

使用 CopilotKit Runtime 的 NextJS 路由
import {
  CopilotRuntime,
  EmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { LangGraphHttpAgent } from "@copilotkit/runtime/langgraph";

const agentUrl = process.env.AGENT_URL || "http://localhost:8000/agent";

const runtime = new CopilotRuntime({
  agents: {
    default: new LangGraphHttpAgent({
      url: agentUrl,
    }),
  },
});

const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
  endpoint: "/api/copilotkit",
  runtime,
  serviceAdapter: new EmptyAdapter(),
});

export const dynamic = "force-dynamic";
export const POST = handleRequest;
export const GET = handleRequest;

在前端代码中，CopilotKit 组件连接到 runtime 提供的 API endpoint，由 runtimeUrl 指定。下面代码中的 CopilotProvider 封装了 CopilotKit。

基于 CopilotKit 的前端实现
"use client";

import { CopilotKit } from "@copilotkit/react-core/v2";
import "@copilotkit/react-ui/styles.css";

type CopilotProviderProps = {
  children: React.ReactNode;
};

export function CopilotProvider({ children }: CopilotProviderProps) {
  const enableInspector = process.env.NODE_ENV === "development";

  return (
    <CopilotKit runtimeUrl="/api/copilotkit" enableInspector={enableInspector}>
      {children}
    </CopilotKit>
  );
}

CopilotChat 组件提供了最基本的聊天界面。

这样就完成了前端界面的开发。

智能体后端​

智能体前端​

智能体后端

智能体前端