前端概览

使用 CopilotKit 和 AG-UI 协议为你的 CrewAI 智能体构建交互式用户界面。

为你的智能体赋予用户界面

CrewAI 负责运行你的智能体。CopilotKit 为它们提供前端。两者结合，让你可以构建这样的应用：用户与 Crew 或 Flow 对话，实时观看其工作过程，批准其决策，并看到其输出以实时 UI 呈现，而不是大段文字。

两者通过 AG-UI 协议连接。ag-ui-crewai 包可将任何 Crew 或 Flow 暴露为 AG-UI 端点。CopilotKit 的 React hooks 和组件消费该端点。这解锁了远超聊天框的体验：

•Generative UI

将智能体的工具调用和状态渲染为你自己的 React 组件。

•Human-in-the-Loop

在运行中途暂停智能体以收集用户批准或输入。

•Shared State

让智能体状态与应用 UI 保持双向同步。

•Channels

将同一个智能体作为 Slack、Discord 或 Teams 机器人运行。

本指南端到端地把一个 Crew 或 Flow 与 Next.js 前端连接起来。本节其余内容都建立在你在此搭建的应用之上。

架构

共有三个部分：

1. CrewAI 智能体服务器 —— 一个通过 AG-UI 提供你的 Crew 或 Flow 的 Python 进程（FastAPI + ag-ui-crewai）。
2. CopilotKit 运行时 —— 一个 Next.js 路由，用于注册你的智能体并将请求代理给它。
3. React 前端 —— <CopilotKit> provider 以及聊天和生成式 UI 组件。

React app  ──►  CopilotKit runtime (/api/copilotkit)  ──►  CrewAI server (AG-UI)  ──►  Crew / Flow

NOTE

本指南介绍自托管路径：你使用 ag-ui-crewai 自行运行 CrewAI 智能体服务器，它可在本地运行，无需托管服务。CopilotKit 也提供托管路径（CopilotKit Cloud / Enterprise Intelligence），包含托管线程和检查器 —— 如果你想要那种方式，参见 CopilotKit CrewAI 快速入门。本节的前端代码在两种方式下完全相同；区别只在于智能体的托管和注册方式。

NOTE

CrewAI 以三种形态运行在 AG-UI 之后：常规 Flows（本系列指南中一直使用）、Conversational Flows（原生、会话感知、基于轮次，功能完全对等），以及 Crews（基础聊天）。本节的前端在它们之间完全一致 —— 只有后端的编写和注册方式不同。

集成指南

Serve your agent over AG-UI

将集成包安装到你的 CrewAI 项目中：

pip install ag-ui-crewai

从 FastAPI 应用中暴露你的智能体。Flow 使用 add_crewai_flow_fastapi_endpoint；Crew 使用 add_crewai_crew_fastapi_endpoint。你可以注册任意多个，每个都用自己的路径。

Flow

# server.py
from fastapi import FastAPI
from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint
from my_agents.recipe_flow import RecipeFlow

app = FastAPI(title="CrewAI Agent Server")

add_crewai_flow_fastapi_endpoint(
    app=app,
    flow=RecipeFlow(),
    path="/recipe",
)

Crew

# server.py
from fastapi import FastAPI
from ag_ui_crewai.endpoint import add_crewai_crew_fastapi_endpoint
from my_agents.research_crew import ResearchCrew

app = FastAPI(title="CrewAI Agent Server")

add_crewai_crew_fastapi_endpoint(
    app=app,
    crew=ResearchCrew().crew(),
    path="/research",
)

运行它：

uvicorn server:app --port 8000

NOTE

在启动服务器之前，设置你的 LLM 服务商所需的环境变量（例如 OPENAI_API_KEY）。

Create a Next.js app

如果你还没有前端，先生成一个脚手架：

npx create-next-app@latest my-app
cd my-app

安装 CopilotKit 和 CrewAI AG-UI 客户端：

npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/crewai

Add the CopilotKit runtime

创建一个路由，把你的 CrewAI 智能体注册到 CopilotKit 运行时。每个智能体通过 CrewAIAgent 指向你的 Python 服务器上的某个路径。

// app/api/copilotkit/route.ts
import {
  CopilotRuntime,
  InMemoryAgentRunner,
  createCopilotEndpoint,
} from "@copilotkit/runtime/v2";
import { CrewAIAgent } from "@ag-ui/crewai";
import { handle } from "hono/vercel";

const runtime = new CopilotRuntime({
  agents: {
    recipe: new CrewAIAgent({ url: "http://localhost:8000/recipe" }),
  },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

const handler = handle(app);
export const GET = handler;
export const POST = handler;

Wrap your app with the provider

将 <CopilotKit> 指向该运行时路由，并指定你注册的智能体名称。

// app/page.tsx
"use client";
import { CopilotKit } from "@copilotkit/react-core";
import { CopilotSidebar } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export default function Page() {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit" agent="recipe">
      <YourApp />
      <CopilotSidebar agentId="recipe" labels={{ modalHeaderTitle: "Assistant" }} />
    </CopilotKit>
  );
}

Run it

启动两个进程并打开应用。现在在侧边栏中聊天即可运行你的 Crew 或 Flow。

uvicorn server:app --port 8000   # terminal 1
npm run dev                       # terminal 2

聊天 UI 选项

CopilotKit 提供三种可互换的聊天界面。只需更换组件；接线方式完全相同。

Sidebar

import { CopilotSidebar } from "@copilotkit/react-core/v2";

<CopilotSidebar agentId="recipe" />

Popup

import { CopilotPopup } from "@copilotkit/react-core/v2";

<CopilotPopup agentId="recipe" />

Inline

import { CopilotChat } from "@copilotkit/react-core/v2";

<CopilotChat agentId="recipe" />

接下来去哪里

•Generative UI

将工具调用和智能体状态渲染为自定义组件。

⚡Frontend Actions

让智能体调用在浏览器中运行的函数。

•Human-in-the-Loop

将智能体的操作置于用户批准之后。

•Predictive State

在智能体工作过程中，将进行中的状态流式传输到 UI。