CopilotKit

CopilotKit 提供了一个完整的 React 聊天运行时，当您希望智能体返回结构化 UI 负载而非仅返回纯文本时，它与 LangGraph 的配合尤为出色。在此模式下，您的 LangGraph 部署同时服务图形 API 和一个自定义的 CopilotKit 端点，而前端则将助手消息解析为动态的 React 组件。在服务器端，copilotkit 包提供了 CopilotKitMiddleware，使得 LangGraph 图形、LangChain 智能体或 Deep Agent 能够遵循 Agent UI (AG-UI) 线路协议，将工具和消息事件流式传输到聊天 UI，并读写共享的 CopilotKit 状态切片，同时提供辅助函数以便在您的图形前端挂载一个与 CopilotKit 兼容的 HTTP 端点。当您需要以下功能时，这种方法非常有用：

一个现成的聊天运行时，而不是自己手动接线 stream.messages
一个自定义的服务器端点，可以在部署的图形旁边添加特定于提供商的行为
从受限组件注册表渲染的结构化生成式 UI

CopilotKit for LangGraph 文档还介绍了基于同一中间件和客户端的生成式 UI、人在回路中 (HITL) 和共享状态。

有关 CopilotKit 特定的 API、UI 模式和运行时配置，请参阅 CopilotKit 文档。有关 Deep Agent 的演练，请参阅 CopilotKit 文档中的 Deep Agents and CopilotKit。

工作原理

从高层次看，CopilotKit 位于您的 React 应用和 LangGraph 部署之间。前端将对话状态发送到挂载在图形 API 旁边的自定义 /api/copilotkit 路由，该路由将请求转发给 LangGraph，而响应则会返回助手消息以及您的组件注册表可以渲染的任何结构化 UI 负载。

照常部署图形：使用 LangSmith 或 LangGraph 开发服务器。
使用 HTTP 应用扩展部署：在图形 API 旁边挂载一个 CopilotKit 路由。
将前端包装在 CopilotKit 中：并将其指向该自定义运行时 URL。
注册动态 UI 组件：并在渲染时将助手响应解析为这些组件。

Python 服务器端您将获得什么

copilotkit 及相关包是 LangGraph 部署与 CopilotKit 客户端之间的桥梁。

组件	角色
`CopilotKitMiddleware`	将 CopilotKit 和 AG-UI 状态及请求合并到您的智能体中，包括前端的工具调用和上下文。将其添加到 create_agent 或 create_deep_agent 的 `middleware` 列表中。
`CopilotKitState`（子类）	自定义状态：扩展 `CopilotKitState`，使 CopilotKit 键成为图形状态的一部分。
`LangGraphAGUIAgent`	将编译好的图形与运行时所需的名称和描述打包在一起。
`add_langgraph_fastapi_endpoint`（来自 ag-ui-langgraph）	连接一个 FastAPI 应用，使 CopilotKit 能够在同一个 LangGraph 进程上运行您的图形。当您在 `langgraph.json` 中添加了自定义 `http` 应用而不是使用单独的 HTTP 服务器时，请使用此函数。

CopilotKitMiddleware 对于 create_deep_agent 和 create_agent 创建的图形（当您将其添加到 middleware 列表中时）是相同的中间件。对于带有 CopilotKitState 和 FastAPI 桥接的 create_agent 图形，请遵循下面的 Python main.py 示例。结构化生成式 UI（例如客户端的 useAgentContext 和 output_schema）需要额外的中间件，将 Copilot 状态映射到结构化输出策略，如本节中可展开的 src/middleware.py 示例所示。在 langgraph.json 的 http 键上挂载 app，遵循常规的 LangGraph 或 LangSmith 部署方式，因此一个进程同时为图形和同一个 FastAPI 应用服务 CopilotKit 客户端。

安装

后端端点：

uv add copilotkit ag-ui-langgraph fastapi uvicorn

中间件包与 Deep Agents 技术栈并存。将其与您的聊天模型包一起安装（此示例使用 OpenAI）：

pip install -U deepagents copilotkit langchain-openai

uv add deepagents copilotkit langchain-openai

前端应用：

bun add @copilotkit/react-core @copilotkit/react-ui @hashbrownai/core @hashbrownai/react

将 CopilotKit 与 Deep Agent 结合使用

将 CopilotKitMiddleware 添加到传递给 create_deep_agent 的 middleware 列表中。该中间件允许 CopilotKit 路由前端工具调用，并使聊天状态与您的图形保持一致。将您配置的任何其他中间件保留在同一列表中。编译好的图形随后即可插入到支持 CopilotKit 或 AG-UI 的进程中（例如，下面的 FastAPI 模式）或 CopilotKit 文档中的指南，如 Deep Agents and CopilotKit。

from deepagents import create_deep_agent
from copilotkit import CopilotKitMiddleware
from langgraph.checkpoint.memory import MemorySaver


def get_weather(location: str) -> str:
    """返回一个地点的简单天气字符串。"""
    return f"今天{location}的天气是晴天。"


agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[get_weather],
    middleware=[CopilotKitMiddleware()],  # AG-UI、前端工具和上下文
    system_prompt="您是一位乐于助人的研究助手。",
    checkpointer=MemorySaver(),
)

使用自定义端点扩展 LangGraph 部署

核心思想是 LangGraph 部署不仅仅服务图形。它还可以加载一个 HTTP 应用，这使您能够在部署本身旁边挂载额外的路由。在 langgraph.json 中，将 http.app 指向您的自定义应用入口点：

{
  "dependencies": ["."],
  "graphs": {
    "copilotkit_shadify": "./main.py:agent"
  },
  "http": {
    "app": "./main.py:app"
  }
}

在 Python 中，创建一个 FastAPI 应用，并通过 CopilotKit 的 AG-UI 桥接暴露 LangGraph 智能体：

main.py

from typing import Any, TypedDict

from ag_ui_langgraph import add_langgraph_fastapi_endpoint
from copilotkit import CopilotKitMiddleware, CopilotKitState, LangGraphAGUIAgent
from fastapi import FastAPI
from langchain.agents import create_agent

from src.middleware import apply_structured_output_schema, normalize_context


class AgentState(CopilotKitState):
    pass


class AgentContext(TypedDict, total=False):
    output_schema: dict[str, Any]


agent = create_agent(
    model="openai:gpt-5.5",
    middleware=[
        normalize_context,
        CopilotKitMiddleware(),
        apply_structured_output_schema,
    ],
    context_schema=AgentContext,
    state_schema=AgentState,
    system_prompt=(
        "您是一位乐于助人的 UI 助手。使用可用的组件构建可视化回复。"
    ),
)

app = FastAPI()

add_langgraph_fastapi_endpoint(
    app=app,
    agent=LangGraphAGUIAgent(
        name="copilotkit_shadify",
        description="一个返回结构化组件负载的 UI 助手。",
        graph=agent,
    ),
    path="/",
)

这个自定义应用是关键的扩展点：它在不替换底层 LangGraph 部署的情况下，挂载了一个支持 CopilotKit 的运行时。在 Python 中，等效的工作发生在中间件中：规范化 CopilotKit 上下文，并将来自 useAgentContext(...) 的 output_schema 转发到模型的结构化输出配置中。

src/middleware.py

import json
from collections.abc import Mapping

from langchain.agents.middleware import before_agent, wrap_model_call
from langchain.agents.structured_output import ProviderStrategy


@wrap_model_call
async def apply_structured_output_schema(request, handler):
    schema = None
    runtime = getattr(request, "runtime", None)
    runtime_context = getattr(runtime, "context", None)

    if isinstance(runtime_context, Mapping):
        schema = runtime_context.get("output_schema")

    if schema is None and isinstance(getattr(request, "state", None), dict):
        copilot_context = request.state.get("copilotkit", {}).get("context")
        if isinstance(copilot_context, list):
            for item in copilot_context:
                if isinstance(item, dict) and item.get("description") == "output_schema":
                    schema = item.get("value")
                    break

    if isinstance(schema, str):
        try:
            schema = json.loads(schema)
        except json.JSONDecodeError:
            schema = None

    if isinstance(schema, dict):
        request = request.override(
            response_format=ProviderStrategy(schema=schema, strict=True),
        )

    return await handler(request)


@before_agent
def normalize_context(state, runtime):
    copilotkit_state = state.get("copilotkit", {})
    context = copilotkit_state.get("context")

    if isinstance(context, list):
        normalized = [
            item.model_dump() if hasattr(item, "model_dump") else item
            for item in context
        ]
        return {"copilotkit": {**copilotkit_state, "context": normalized}}

    return None

结果是清晰的关注点分离：

LangGraph 仍然负责图形执行和持久化
CopilotKit 负责面向聊天的运行时契约
您的自定义端点将它们粘合在一次部署中

当您使用 CopilotKit 运行时适配器时，请将您的 CopilotKit runtimeUrl 指向 FastAPI（或其他）应用暴露的路由，而不仅仅是原始的图形 REST 接口。遵循 CopilotKit 文档中关于 Node CopilotRuntime 中的 LangGraphHttpAgent 或 LangGraphAgent 的说明；Python 端的图形和中间件仍然定义工具行为和智能体逻辑。 :::

构建前端应用

在前端，将您的应用包装在 CopilotKit 中，并将其指向自定义运行时 URL：

import { CopilotKit } from "@copilotkit/react-core";
import { CopilotChat, useAgentContext } from "@copilotkit/react-core/v2";
import { s } from "@hashbrownai/core";

import { useChatKit } from "@/components/chat/chat-kit";
import { chatTheme } from "@/lib/chat-theme";

export function App() {
  return (
    <CopilotKit runtimeUrl={import.meta.env.VITE_RUNTIME_URL ?? "/api/copilotkit"}>
      <Page />
    </CopilotKit>
  );
}

function Page() {
  const chatKit = useChatKit();

  useAgentContext({
    description: "output_schema",
    value: s.toJsonSchema(chatKit.schema),
  });

  return <CopilotChat {...chatTheme} />;
}

这里有两个重要部分：

runtimeUrl="/api/copilotkit" 将聊天发送到您的自定义后端路由，而不是直接发送到原始的 LangGraph API
useAgentContext(...) 将 UI 架构发送给智能体，以便模型知道应该产生什么结构化输出格式

注册动态组件

组件注册表位于 useChatKit() 中。在此您定义允许智能体发出的组件集合，例如卡片、行、列、图表、代码块和按钮。

import { s } from "@hashbrownai/core";
import { exposeComponent, exposeMarkdown, useUiKit } from "@hashbrownai/react";

import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";
import { CodeBlock } from "@/components/ui/code-block";
import { Row, Column } from "@/components/ui/layout";
import { SimpleChart } from "@/components/ui/simple-chart";

export function useChatKit() {
  return useUiKit({
    components: [
      exposeMarkdown(),
      exposeComponent(Card, {
        name: "card",
        description: "用于包装生成式 UI 内容的卡片。",
        children: "any",
      }),
      exposeComponent(Row, {
        name: "row",
        props: {
          gap: s.string("Tailwind 间距大小") as never,
        },
        children: "any",
      }),
      exposeComponent(Column, {
        name: "column",
        children: "any",
      }),
      exposeComponent(SimpleChart, {
        name: "chart",
        props: {
          labels: s.array("类别标签", s.string("一个标签")),
          values: s.array("数值", s.number("一个值")),
        },
        children: false,
      }),
      exposeComponent(CodeBlock, {
        name: "code_block",
        props: {
          code: s.streaming.string("要显示的代码"),
          language: s.string("编程语言") as never,
        },
        children: false,
      }),
      exposeComponent(Button, {
        name: "button",
        children: "text",
      }),
    ],
  });
}

这个注册表成为了智能体与 UI 之间的契约。模型不是在生成任意的 JSX，而是在生成必须根据您暴露的组件和属性进行验证的结构化数据。

将助手消息渲染为动态 UI

一旦助手响应到达，自定义消息渲染器将决定如何显示它。在此示例中：

助手消息根据 UI 套件架构被解析为结构化 JSON
有效的结构化输出被渲染为真实的 React 组件
用户消息被渲染为普通的聊天气泡

import type { AssistantMessage } from "@ag-ui/core";
import type { RenderMessageProps } from "@copilotkit/react-ui";
import { useJsonParser } from "@hashbrownai/react";
import { memo } from "react";

import { useChatKit } from "@/components/chat/chat-kit";
import { Squircle } from "@/components/squircle";

const AssistantMessageRenderer = memo(function AssistantMessageRenderer({
  message,
}: {
  message: AssistantMessage;
}) {
  const kit = useChatKit();
  const { value } = useJsonParser(message.content ?? "", kit.schema);

  if (!value) return null;

  return (
    <div className="group/msg mt-2 flex w-full justify-start">
      <div className="magic-text-output w-full px-1 py-1">{kit.render(value)}</div>
    </div>
  );
});

export function CustomMessageRenderer({ message }: RenderMessageProps) {
  if (message.role === "assistant") {
    return <AssistantMessageRenderer message={message} />;
  }

  return (
    <div className="flex w-full justify-end">
      <Squircle className="w-full max-w-[64ch] px-4 py-3">
        <pre>{typeof message.content === "string" ? message.content : JSON.stringify(message.content, null, 2)}</pre>
      </Squircle>
    </div>
  );
}

这种渲染器模式使得集成感觉很原生：

CopilotKit 处理聊天状态和传输
自定义渲染器决定助手负载如何成为 UI
Hashbrown 将经过验证的结构化数据转换为具体的 React 元素

资源

CopilotKit 文档中的 Deep Agents and CopilotKit — 端到端的 Next.js、开发服务器和 Deep Agent 路径
CopilotKit: LangGraph features — 生成式 UI、HITL、共享状态
LangGraph 部署 — 生产和开发服务器

最佳实践

保持自定义端点轻量： 用它来将 CopilotKit 适配到您的图形部署，而不是复制图形内部已有的业务逻辑
显式发送架构： useAgentContext 应在每次页面挂载时描述 UI 契约
注册受限的组件集： 只暴露您确实希望模型使用的组件和属性
将渲染视为解析步骤： 在渲染助手内容之前，根据您的架构对其进行解析
保持用户消息为纯文本： 只有助手消息需要结构化渲染器；用户消息可以保持为普通的聊天气泡

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

工作原理

Python 服务器端您将获得什么

安装

将 CopilotKit 与 Deep Agent 结合使用

使用自定义端点扩展 LangGraph 部署

构建前端应用

注册动态组件

将助手消息渲染为动态 UI

资源

最佳实践

​工作原理

​Python 服务器端您将获得什么

​安装

​将 CopilotKit 与 Deep Agent 结合使用

​使用自定义端点扩展 LangGraph 部署

​构建前端应用

​注册动态组件

​将助手消息渲染为动态 UI

​资源

​最佳实践

工作原理

Python 服务器端您将获得什么

安装

将 CopilotKit 与 Deep Agent 结合使用

使用自定义端点扩展 LangGraph 部署

构建前端应用

注册动态组件

将助手消息渲染为动态 UI

资源

最佳实践