Skip to main content

使用 CopilotKit

🌐 Using CopilotKit

CopilotKit 提供 React 组件，可快速将可自定义的 AI 助手集成到你的应用中。结合 Mastra，你可以构建具有双向状态同步和交互式用户界面的复杂 AI 应用。

访问 CopilotKit 文档 以了解有关 CopilotKit 的概念、组件和高级使用模式的更多信息。

🌐 Visit the CopilotKit documentation to learn more about CopilotKit concepts, components, and advanced usage patterns.

info

对于 Mastra 直接在你的 Next.js API 路由中运行的全栈集成方法，请参阅 CopilotKit 快速入门 指南。

🌐 For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the CopilotKit Quickstart guide.

tip

访问 Mastra 的 “UI Dojo” 查看 CopilotKit 与 Mastra 集成的真实示例。

🌐 Visit Mastra's "UI Dojo" to see real-world examples of CopilotKit integrated with Mastra.

集成指南
Direct link to 集成指南

🌐 Integration Guide

将 Mastra 作为独立服务器运行，并将你的 Next.js 前端（使用 CopilotKit）连接到其 API 端点。

🌐 Run Mastra as a standalone server and connect your Next.js frontend (with CopilotKit) to its API endpoints.

  1. 设置你的目录结构。可能的目录结构如下所示：

    🌐 Set up your directory structure. A possible directory structure could look like this:

    project-root
    ├── mastra-server
    │   ├── src
    │   │   └── mastra
    │   └── package.json
    └── my-copilot-app
        └── package.json

    启动你的 Mastra 服务器：

    🌐 Bootstrap your Mastra server:

    npx create-mastra@latest

    此命令将启动一个交互式向导，帮助你创建一个新的 Mastra 项目，包括提示你输入项目名称并设置基本配置。按照提示操作即可创建你的服务器项目。

    🌐 This command will launch an interactive wizard to help you scaffold a new Mastra project, including prompting you for a project name and setting up basic configurations. Follow the prompts to create your server project.

    导航到你新创建的 Mastra 服务器目录：

    🌐 Navigate to your newly created Mastra server directory:

    cd mastra-server # Replace with the actual directory name you provided

    你现在已经有一个基础的 Mastra 服务器项目准备好了。你应该有以下文件和文件夹：

    🌐 You now have a basic Mastra server project ready. You should have the following files and folders:

    src
    └── mastra
        ├── agents
        │   └── weather-agent.ts
        ├── scorers
        │   └── weather-scorer.ts
        ├── tools
        │   └── weather-tool.ts
        ├── workflows
        │   └── weather-workflow.ts
        └── index.ts
    note

    确保你已经在 .env 文件中为你的 LLM 提供商设置了适当的环境变量。

    🌐 Ensure that you have set the appropriate environment variables for your LLM provider in the .env file.

  2. 通过使用 @ag-ui/mastra 中的 registerCopilotKit() 帮手，为 CopilotKit 前端创建一个聊天路由。将其添加到你的 Mastra 项目（及其相关依赖）中：

    🌐 Create a chat route for the CopilotKit frontend by using the registerCopilotKit() helper from @ag-ui/mastra. Add it to your Mastra project (and its peer dependencies):

    npm install @ag-ui/mastra @copilotkit/runtime @ag-ui/core @ag-ui/client @ag-ui/encoder @ag-ui/langgraph @ag-ui/proto

    在你的 src/mastra/index.ts 文件中，注册聊天路由：

    🌐 In your src/mastra/index.ts file, register the chat route:

    src/mastra/index.ts
    import { Mastra } from '@mastra/core/mastra';
    import { registerCopilotKit } from '@ag-ui/mastra/copilotkit';
    // Rest of the imports...

    export const mastra = new Mastra({
      // Rest of the configuration...
      server: {
        cors: {
          origin: "*",
          allowMethods: ["*"],
          allowHeaders: ["*"],
        },
        apiRoutes: [
          registerCopilotKit({
            path: '/chat',
            resourceId: 'weatherAgent'
          })
        ]
      }
    });

    这将使 weatherAgent 以与 CopilotKit 兼容的格式在 /chat 上可用。你需要添加 CORS 配置，以允许 CopilotKit 前端访问 Mastra 服务器。在生产环境部署时，请确保将 CORS 来源限制为仅你的前端域名。

    🌐 This will make the weatherAgent available at /chat in a CopilotKit-compatible format. You have to add the CORS configuration to allow the CopilotKit frontend to access the Mastra server. For production deployments, make sure to restrict the CORS origins to only your frontend domain.

  3. 使用以下命令运行 Mastra 服务器：

    🌐 Run the Mastra server using the following command:

    npm run dev

    默认情况下，Mastra 服务器将运行在 http://localhost:4111 上。请保持该服务器运行，以便在接下来的步骤中我们设置 CopilotKit 前端连接到它。

    🌐 By default, the Mastra server will run on http://localhost:4111. Keep this server running for the next steps where we'll set up the CopilotKit frontend to connect to it.

  4. 返回上一级目录到你的项目根目录。

    🌐 Go up one directory to your project root.

    cd ..

    创建一个名为 my-copilot-app 的新的 Next.js 项目：

    🌐 Create a new Next.js project with the name my-copilot-app:

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

    导航到你新创建的 Next.js 项目目录：

    🌐 Navigate to your newly created Next.js project directory:

    cd my-copilot-app

  5. 安装 CopilotKit UI 包，你将用它来显示聊天界面：

    🌐 Install the CopilotKit UI packages which you'll use to display a chat interface:

    npm install @copilotkit/react-ui @copilotkit/react-core

    打开 Next.js 应用的首页路由（通常是 app/page.tsx 或 src/app/page.tsx），并将现有内容替换为以下代码，以设置一个基本的 CopilotKit 聊天界面：

    🌐 Open the home route of the Next.js app (usually app/page.tsx or src/app/page.tsx) and replace the existing contents with the following code to set up a basic CopilotKit chat interface:

    app/page.tsx
    import { CopilotChat } from "@copilotkit/react-ui";
    import { CopilotKit } from "@copilotkit/react-core";
    import "@copilotkit/react-ui/styles.css";

    export default function Home() {
      return (
        <CopilotKit
          runtimeUrl="http://localhost:4111/chat"
          agent="weatherAgent"
        >
          <CopilotChat
            labels={{
              title: "Weather Agent",
              initial: "Hi! 👋 Ask me about the weather, forecasts, and climate.",
            }}
          />
        </CopilotKit>
      );
    }

  6. 你已经准备好连接各个部分了！确保 Mastra 服务器和 CopilotKit 前端都在运行。启动 Next.js 开发服务器：

    🌐 You're ready to connect the pieces! Make sure both the Mastra server and the CopilotKit frontend are running. Start the Next.js development server:

    npm run dev

    你现在应该可以在浏览器中与你的代理聊天了。

    🌐 You should now be able to chat with your agent in the browser.

恭喜！你已成功通过单独服务器的方式将 Mastra 与 CopilotKit 集成。你的 CopilotKit 前端现在可以与独立的 Mastra 代理服务器通信。

🌐 Congratulations! You have successfully integrated Mastra with CopilotKit using a separate server approach. Your CopilotKit frontend now communicates with a standalone Mastra agent server.

部署
Direct link to 部署

🌐 Deployment

在使用 CopilotKit 部署 Mastra 服务器时，你必须将 @copilotkit/runtime 从打包包中排除。该软件包包含与打包不兼容的依赖，如果包含会导致 500 错误。

🌐 When deploying your Mastra server with CopilotKit, you must exclude @copilotkit/runtime from the bundle. This package contains dependencies that are not compatible with bundling and will cause 500 errors if included.

note

在使用 mastra dev 进行开发时不会出现此问题，因为它不需要打包。然而，任何使用 mastra build 进行部署的人都会遇到此问题。

🌐 This issue doesn't occur during development with mastra dev since it doesn't require bundling. However, anyone running mastra build for deployment will encounter this issue.

将 @copilotkit/runtime 包添加到你的打包工具外部配置中：

🌐 Add the @copilotkit/runtime package to your bundler externals configuration:

src/mastra/index.ts
export const mastra = new Mastra({
  bundler: {
    externals: ['@copilotkit/runtime'],
  },
 // Rest of the configuration...
});
目录