CopilotKit 用户界面（用于 ADK）

Supported in ADKPython

CopilotKit 是一组开源的前端库和运行时，可通过 AG-UI 将应用程序连接到智能体。与 ADK 配合使用时，ag-ui-adk 包将你的智能体暴露为 AG-UI 端点，而 CopilotKit 为该端点提供聊天界面、前端工具、生成式 UI 以及在 React、Angular、Vue、React Native 或 Slack 中的人工介入控制。

AG-UI 集成页面介绍了协议以及一个可搭建全栈示例的 create 命令。本页展示如何将 CopilotKit 添加到现有的 ADK 项目中。

使用场景

• 聊天界面：将 ADK 智能体的消息、工具调用和推理过程流式传输到面向 Web 或移动应用的打包聊天组件中。
• 前端工具：让智能体调用在浏览器中运行的函数，例如导航、打开记录或读取应用状态。
• 生成式 UI：使用应用组件而非纯文本来渲染工具调用和结果。
• 人工介入：在用户批准、编辑或拒绝建议的操作之前暂停智能体运行，然后根据回答恢复运行。
• 消息渠道：使用开源的 Channels SDK 在 Slack 中运行相同的智能体。

前提条件

• Python 3.10 至 3.14 和 Node.js 18 或更高版本
• 从 Google AI Studio 获取的 Gemini API 密钥，导出为 GOOGLE_API_KEY
• 一个 React 应用（如 Next.js），用于以下前端步骤

安装

安装后端包：

pip install google-adk ag-ui-adk fastapi "uvicorn[standard]"

在你的 Web 应用中安装前端包：

npm install @copilotkit/react-core @copilotkit/runtime @ag-ui/client hono zod

在智能体中使用

1. 通过 AG-UI 暴露智能体

agent.py

from fastapi import FastAPI
from google.adk.agents import Agent
from google.adk.apps import App, ResumabilityConfig

from ag_ui_adk import ADKAgent, AGUIToolset, add_adk_fastapi_endpoint

root_agent = Agent(
    model="gemini-flash-latest",
    name="copilotkit_agent",
    instruction=(
        "You are a helpful assistant. Use the frontend tools when they fit "
        "the request."
    ),
    tools=[AGUIToolset()],
)

adk_app = App(
    name="copilotkit_app",
    root_agent=root_agent,
    resumability_config=ResumabilityConfig(is_resumable=True),
)

ag_ui_agent = ADKAgent.from_app(
    adk_app,
    user_id="local_user",
    use_in_memory_services=True,
)

app = FastAPI()
add_adk_fastapi_endpoint(app, ag_ui_agent, path="/ag-ui")

AGUIToolset() 工具集使前端注册的工具可被智能体调用。使用 ADKAgent.from_app() 和 ResumabilityConfig 创建中间件，可在前端工具调用时暂停运行，并在结果返回时恢复运行。

启动后端：

uvicorn agent:app --reload --port 8000

2. 将端点注册到 CopilotKit Runtime

CopilotKit Runtime 运行在你的 Web 应用中，并将 AG-UI 运行转发到 ADK 端点。在 Next.js 应用中添加一个路由：

app/api/copilotkit/[[...slug]]/route.ts

import { HttpAgent } from "@ag-ui/client";
import {
  CopilotRuntime,
  InMemoryAgentRunner,
  createCopilotEndpoint,
} from "@copilotkit/runtime/v2";
import { handle } from "hono/vercel";

const runtime = new CopilotRuntime({
  agents: {
    default: new HttpAgent({
      url: process.env.ADK_AG_UI_URL ?? "http://localhost:8000/ag-ui",
    }),
  },
  runner: new InMemoryAgentRunner(),
});

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

export const GET = handle(app);
export const POST = handle(app);
export const PATCH = handle(app);
export const DELETE = handle(app);

3. 渲染聊天界面

在 React 树的根部附近挂载一次 Provider，然后在其下方的任意位置放置聊天组件：

app/providers.tsx

"use client";

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

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit" useSingleEndpoint={false}>
      {children}
    </CopilotKit>
  );
}

app/page.tsx

"use client";

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

export default function Page() {
  return (
    <main style={{ height: "100vh" }}>
      <CopilotChat agentId="default" />
    </main>
  );
}

CopilotChat 组件处理消息状态、流式传输、工具调用显示、附件和建议。

4. 添加前端工具

在浏览器中注册一个工具。ADK 端的 AGUIToolset() 会在每次运行时将其暴露给智能体：

app/SearchTool.tsx

"use client";

import { useFrontendTool } from "@copilotkit/react-core/v2";
import { z } from "zod";

export function SearchTool() {
  useFrontendTool({
    name: "searchDocs",
    description: "Search the current application documentation.",
    parameters: z.object({
      query: z.string(),
    }),
    handler: async ({ query }) => {
      const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`);
      return response.text();
    },
  });

  return null;
}

将 <SearchTool /> 渲染在 Provider 下方，<CopilotChat /> 旁边。

可用 Hooks

Hook	描述
useFrontendTool	注册一个在浏览器中执行的工具，并将结果返回给智能体
useRenderTool	按名称渲染后端工具的进度和结果
useComponent	注册一个纯渲染组件，智能体可以将其放置在聊天中
useHumanInTheLoop	注册一个工具，其 UI 必须调用 respond() 后运行才能继续
useAgentContext	在每次运行时将应用状态作为上下文共享给智能体
useAgent	在构建自定义聊天界面时读取消息、状态和运行状态

所有 hooks 均从 @copilotkit/react-core/v2 导出。参阅 CopilotKit hook 参考文档了解参数和返回值。

其他客户端

相同的 CopilotKit Runtime 路由和 ADK 端点可服务于每个 CopilotKit 客户端：

• Angular：使用 provideCopilotKit() 和 <copilot-chat> 组件的 @copilotkit/angular 包。参阅 Angular 指南。
• Vue：使用 CopilotKitProvider 和 CopilotChat 的 @copilotkit/vue 包。参阅 Vue 指南。
• React Native：使用无头 hooks 和可选的打包聊天组件（@copilotkit/react-native/components）的 @copilotkit/react-native 包。参阅 React Native 指南。

消息渠道

开源的 Channels SDK 可将 Slack 工作区直接连接到 ag-ui-adk 端点。它不需要 CopilotKit Runtime 路由：

npm install @copilotkit/bot @copilotkit/bot-slack @copilotkit/bot-ui

slack-bot.ts

import { createBot } from "@copilotkit/bot";
import {
  defaultSlackContext,
  defaultSlackTools,
  SanitizingHttpAgent,
  slack,
} from "@copilotkit/bot-slack";

const bot = createBot({
  adapters: [
    slack({
      botToken: process.env.SLACK_BOT_TOKEN!,
      appToken: process.env.SLACK_APP_TOKEN!,
    }),
  ],
  agent: (threadId) => {
    const agent = new SanitizingHttpAgent({
      url: process.env.ADK_AG_UI_URL ?? "http://localhost:8000/ag-ui",
    });
    agent.threadId = threadId;
    return agent;
  },
  tools: [...defaultSlackTools],
  context: [...defaultSlackContext],
});

bot.onMention(({ thread }) => thread.runAgent());

await bot.start();

适配器默认在 Socket 模式下运行，因此本地开发需要应用级令牌但不需要公共 URL。每个 Slack 线程映射到一个 AG-UI 线程，Block Kit 渲染、交互和审批由适配器处理。参阅 Channels 文档了解 Slack 应用设置和自托管部署。

更多资源

• CopilotKit ADK 文档
• CopilotKit（GitHub）
• AG-UI 的 ADK 中间件（ag-ui-adk）（PyPI）
• ADK 中间件源码
• AG-UI Dojo（含 ADK 在线示例）