企业官网建设流程全解析

如何在 Mastra Agent 中为 CopilotKit 配置后台任务

【免费下载链接】CopilotKitThe Frontend Stack for Agents & Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit

当 Mastra Agent 里有一个耗时的工具（深度调研、报告生成、批量任务）时，默认行为是工具在 agentic loop 内同步执行，整个对话被阻塞。Mastra 的后台任务机制可以把这类工具移出 agent loop：工具被标记background: { enabled: true }后，Mastra 会把它派发给BackgroundTaskManager，发出background-task-started生命周期事件，并立即返回一个占位结果，让对话继续。CopilotKit 这边的MastraAgent（AG-UI 适配器）会把这个生命周期映射为 AG-UI activity 事件（activity 类型mastra-background-task），同时抑制普通的 tool pill——于是这段工作只会以一张实时 "working" 活动卡片的形式出现在聊天记录里，注册了对应的 CopilotKit activity renderer 后卡片会内联渲染。

本文的目标就一件事：让一个 Mastra Agent 中的工具在后台运行，并在 CopilotKit 聊天界面中以活动卡片实时展示其状态。适用前提是你已经按 Mastra Quickstart 把 Mastra Agent 接入了 CopilotKit；如果还没有，先完成 Quickstart 中的"Run and connect"环节（从零开始可以用npx copilotkit@latest create并选择 Mastra 框架），本文从定义后台工具开始。

准备条件

Quickstart 列出的前置要求：

• Node.js 20+
• 一个 OpenAI API key（示例代码使用openai("gpt-4.1")，可换成 Mastra 支持的其他模型）
• 任意包管理器

如果你走的是 remote 路径（Mastra 以独立进程运行，通过npx mastra dev启动），先确认服务真的在提供你的 agent：

curl http://127.0.0.1:4111/api/agents

Quickstart 特别提醒：裸GET /不是存活检查——Mastra 在 agent 端口上提供 web console，无论有没有注册 agent 都会返回200。要检查/api/agents并在输出中按名字找到你的 agent（mastra dev默认占用 4111，被占时会向上试探到 4131，以实际打印的端口为准）。

第一步：定义一个可后台化的工具

用createTool定义工具时加上background: { enabled: true }，Mastra 就会把它派发给BackgroundTaskManager而不是内联执行：

import { createTool } from "@mastra/core/tools"; import { z } from "zod"; export const runDeepResearchTool = createTool({ id: "run_deep_research", description: "Kick off a long-running deep-research task on a topic. This runs in " + "the background while the conversation continues.", inputSchema: z.object({ topic: z.string().describe("The topic to research in depth."), }), background: { enabled: true }, // [!code highlight] execute: async ({ topic }) => { // Runs when the background worker executes the task. return JSON.stringify({ topic, summary: `Deep research on "${topic}" completed.`, }); }, });

execute只有在后台 worker 实际执行任务时才运行；派发那一轮它还没跑完。

第二步：在 Mastra 实例上启用 BackgroundTaskManager

后台工具只有在实例上启用了 manager 时才会被派发，并且必须配置了storage才能跟踪任务：

import { Mastra } from "@mastra/core/mastra"; import { LibSQLStore } from "@mastra/libsql"; import { backgroundAgentsAgent } from "./agents"; export const mastra = new Mastra({ agents: { backgroundAgentsAgent }, storage: new LibSQLStore({ id: "mastra-storage", url: ":memory:" }), backgroundTasks: { enabled: true }, // [!code highlight] });

文档示例使用LibSQLStore的:memory:配置；如果你的存储方案不同，保留storage这一项即可，因为它是任务跟踪的必要条件。

第三步：把工具加到 agent

import { Agent } from "@mastra/core/agent"; import { openai } from "@ai-sdk/openai"; import { runDeepResearchTool } from "@/mastra/tools/background-research"; // [!code highlight] export const backgroundAgentsAgent = new Agent({ id: "background-agents", name: "Background Agents Agent", tools: { runDeepResearchTool }, // [!code highlight] model: openai("gpt-4.1"), instructions: "You are a research assistant that dispatches long-running work to the " + "background. When the user asks you to research a topic, call the " + "run_deep_research tool ONCE, then send a short message saying the work " + "is running in the background.", });

instructions 里明确要求"只调用一次工具，然后回复说任务在后台运行"，是为了避免 agent 在同一轮反复派发任务。

第四步：在前端渲染活动卡片

写一个针对mastra-background-task这个 activity 类型的 renderer。标准聊天面会内联渲染已注册的 activity 消息，不需要自定义消息列表。

React 前端在<CopilotKit>上通过renderActivityMessages注册：

import { z } from "zod"; import type { ReactActivityMessageRenderer } from "@copilotkit/react-core/v2"; const contentSchema = z .object({ status: z.string().optional(), args: z.record(z.unknown()).optional() }) .passthrough(); export const backgroundTaskActivityRenderer: ReactActivityMessageRenderer< z.infer<typeof contentSchema> > = { activityType: "mastra-background-task", // [!code highlight] content: contentSchema, render: ({ content }) => { const working = content.status !== "completed" && content.status !== "failed"; const topic = (content.args?.topic as string | undefined) ?? "task"; return ( <div>import { CopilotKit, CopilotChat } from "@copilotkit/react-core/v2"; import { backgroundTaskActivityRenderer } from "./activity-card"; export default function Page() { return ( <CopilotKit runtimeUrl="/api/copilotkit" agent="background-agents" renderActivityMessages={[backgroundTaskActivityRenderer]} // [!code highlight] > <CopilotChat /> </CopilotKit> ); }

其中agent="background-agents"对应第三步里 agent 的id，runtimeUrl是 Copilot Runtime 在本应用内的路径。renderer 逻辑本身可以直接换成你自己的卡片：判断"工作中"的依据是status不是completed也不是failed。

可选分支：Angular 前端的做法是把卡片写成满足ActivityRenderer的组件，再把内容 schema 和组件配进RenderActivityMessageConfig，并在注入上下文中注册（注入器销毁时注册会自动移除）；Angular Showcase 导出了两个 Mastra activity 类型的现成配置，实现细节可参考仓库中showcase/angular/src/app/features/mastra/mastra-cards.ts与mastra-feature.component.ts对应的文档片段。

验证配置是否生效

在聊天里要求 agent 发起一个调研：

Kick off deep research on the current landscape of AI agent frameworks.

文档给出的预期结果：agent 调用run_deep_research，Mastra 在后台派发它，聊天中内联出现一张实时 "working" 活动卡片，没有出现阻塞性的 tool pill，同时对话保持可用。

关于任务完成的交付方式：out of band

这是配置后台任务时最重要的边界。派发那一轮的 stream 只携带started生命周期和占位结果——stream 关闭时工具的execute还没跑完。因此在这一轮内卡片会停留在 "working" 状态，最终结果通过带外方式送达。两条路径，取决于你的部署形态：

1. 有真正的后台 worker 的执行环境：通过getLocalAgents传入untilIdle: true，运行时可以把 manager 的 pubsub 事件（包括background-task-completed）接入同一条 stream，适配器对生命周期的映射（running→completed/failed/cancelled）会让卡片自动翻转状态。文档明确警告：单进程应用里没有后台 worker 时，任务根本不会在运行窗口内被执行，untilIdle只是白白把 stream 挂住，没有任何收益。
2. 没有后台 worker：通过 task manager 带外取结果，接口为backgroundTaskManager.stream()和getTask(taskId)。

untilIdle只存在于getLocalAgents（本地嵌入路径），remote 路径（getRemoteAgents）没有这个选项——如果你的 run 需要它，agent 就必须嵌入到 runtime 所在进程。

排查与限制

• 连不上 agent 服务时，把localhost换成0.0.0.0或127.0.0.1（有些机器上localhost先解析到 IPv6，会错过只绑定了 IPv4 的 agent 服务）。
• 确认 Mastra agent 实际端口与MASTRA_BASE_URL指向一致，curl http://127.0.0.1:4111/api/agents能按名字列出 agent。
• 确认 OpenAI API key 已正确配置在.env（starter 路径）或环境变量（已有 agent 路径）中。
• 后台工具只有在实例开启了backgroundTasks: { enabled: true }且配置了storage时才会被派发；只给工具加background标记而漏掉实例配置，工具不会进入后台队列。

完整的背景说明和可选的 Observational Memory 活动卡片（activity 类型mastra-observational-memory，默认关闭、需两个开关同时打开）见 Background Tasks 文档，runtime 挂载方式的 local/remote 选择依据见 Copilot Runtime 文档。

【免费下载链接】CopilotKitThe Frontend Stack for Agents & Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit