# @ag-ui/mastra 中文文档

规范地址：https://npmcn.com/package/%40ag-ui/mastra/

版本：2\.0\.2
npm 元数据更新时间：2026-10-30T20:58:05.719Z
中文译文更新时间：2026-11-05T17:19:50.303Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ag-ui/mastra
原文对照：https://npmcn.com/package/%40ag-ui/mastra/?lang=original
项目主页：https://github.com/ag-ui-protocol/ag-ui#readme
源码仓库：https://github.com/ag-ui-protocol/ag-ui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1 MB，35 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：@ag-ui/core \>=1\.0\.0，@mastra/core \>=1\.29\.0 \<2\.0\.0-0，@ag-ui/client \>=1\.0\.0，@mastra/client-js \>=1\.0\.0-0 \<2\.0\.0-0，@copilotkit/runtime ^1\.76\.0
- 首次发布：2025-06-10T15:00:36.315Z
- 最新版本发布：2026-10-30T20:58:05.286Z
- 近 30 天下载量：658067（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 24 个）

## 中文简介

执行马斯特拉的AG-UI协议.

## 安装

```sh
npm install @ag-ui/mastra
```

也可以使用：`pnpm add @ag-ui/mastra`、`yarn add @ag-ui/mastra`、`bun add @ag-ui/mastra`

## README

# @ag-ui/马斯特拉

执行马斯特拉的AG-UI协议.

通过AG-UI协议连接 Mastra 代理(本地和远程)到前端应用. 支持流化响应,内存管理和工具执行.

## 安装

安装 `@ag-ui/mastra` 软件包 :

```bash
# npm
npm install @ag-ui/mastra
# pnpm
pnpm add @ag-ui/mastra
# yarn
yarn add @ag-ui/mastra
```

安装所需的对等依赖 :

```bash
npm install @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client
```

可选的 CopilotKit 集成从 `@ag-ui/mastra/copilotkit`。 。 。 . 仅在使用该切入点时安装对等依赖 。 这需要 `@copilotkit/runtime` `^1.76.0`,它使用AG-UI 1.0代理类型和协议. 这提高了可选运行时的对等点 `^1.60.1`; 使用此选项的应用程序 进入点必须升级 CopilotKit. 运行时间和共享发展 依赖性还使用1.76.0,因此进行整合测试,以便进行基线:

```bash
npm install @copilotkit/runtime@^1.76.0
```

## 使用量

```ts
import { MastraAgent } from "@ag-ui/mastra";
import { mastra } from "./mastra"; // Your Mastra instance

// Create an AG-UI compatible agent
const agent = new MastraAgent({
  agent: mastra.getAgent("weather-agent"),
  resourceId: "user-123",
});

// Run with streaming
const result = await agent.runAgent({
  messages: [{ role: "user", content: "What's the weather like?" }],
});
```

## 特征

-   **本地远程代理( R)** - 与流程和网络Mastra代理商合作
-   **内存整合** - 自动线程和工作内存管理
-   **工具流** - 实时工具调用执行和结果
-   **国家管理** - 双向状态同步
-   **人类的跳动** – Mastra 工具暂停/恢复连接到 AG-UI 中断

## 中断(工具暂停/恢复)

当一个 Mastra 工具暂停时, 桥将结束运行 `RunFinishedEvent.outcome = { type: "interrupt", interrupts }`。每个暂停地图 改为: `Interrupt` (单位:千美元)`reason`, (中文(简体) ), `toolCallId`, (中文(简体) ), `responseSchema` 解析自 `resumeSchema`,以及 `message` 当悬浮有效载荷有字符串时 `message`(三); 马斯特拉有效载荷`toolName`, (中文(简体) ), `suspendPayload`, (中文(简体) ), `args`, (中文(简体) ), `resumeSchema` 编辑 快捷键 `runId`) 生活在 `metadata.mastra`。 。 `id` 实值 `` `${runId}::${toolCallId}` ``: 客户端只进行往返 `interruptId` 打开 恢复,所以快照 `runId` 被编码为id并解码后退出.

运行报告最多中断一次, 因为恢复只能继续一次 暂停通话。 Mastra 一次运行一个可暂停和批准的工具, 因此,稍后的呼叫暂停 在恢复运行。 如果一条溪流仍然暂停 第二通电话,桥头记录一个警告 并把它留在结果.

继续一个 `RunAgentInput.resume` 输入该ID。 A 类 `resolved` 条目 通过它 `payload` 去马斯特拉 `resumeStream`页:1 `cancelled` 减少 呼叫并结束运行而不恢复。 这需要客户端读取 中断结果并发送 `RunAgentInput.resume`,例如副驾驶 Kit `>= 1.76.0`。 。 。 .

远程中断和批准支持需要一个具有可调用的代理手柄 `resumeStream`老年人 `@mastra/client-js` 版本仍为普通版本 流着,但是 `getCapabilities().humanInTheLoop` 报告 `supported`, (中文(简体) ), `interrupts`,以及 `approvals` 作为 `false` 当这种方法无法使用时. 试图通过这样的手柄恢复报告升级错误 .

## 工具核准

玛斯特拉的本土审批门被通向AG-UI中断. 标记工具为 `requireApproval: true`,或设置 `requireToolApproval: true` 在经纪人的 `defaultOptions` 打开每个工具 :

```ts
const recordExpense = createTool({
  id: "record-expense",
  inputSchema: z.object({ amount: z.number() }),
  requireApproval: true,
  execute: async ({ amount }) => ({ recorded: true, amount }),
});
```

Mastra 暂停通话 `execute` 运行和流 `tool-call-approval`。 。 。 . 桥挡住工具呼叫 以中断方式结束运行 `reason` 实值 `mastra:tool_approval`和电话的 `toolCallId`, (中文(简体) ), `responseSchema` (马斯特拉的) `{ approved: boolean }` 计划)和 `toolName`, (中文(简体) ), `args` 和快照 `runId` 下级 `metadata.mastra`。 。 `id` 实值 `` `mastra-approval::${runId}::${toolCallId}` ``,以及 `metadata.mastra.type` 实值 `mastra_tool_approval`。 。 。 .

**存储.** 暂停调用在 Mastra 的工作流程快照中直到用户 决定,然后恢复运行从存储中加载. 配置持久性存储 并给代理商 `Memory` 由持续存储支持 因此线程保持了固定的工具呼叫. 对于远程特工,这是 服务器的存储 。 不要使用内嵌 libsql URL(`:memory:`: 有集合 连接每个连接都获得自己的空数据库,所以快照是 在简历中丢失。 使用文件 URL 如 `file:./mastra.db` 换句话说.

**批准UI.** 和副驾驶 Kit v2 一起, 宣布批准和拒绝 `useInterrupt`,并有两个呼叫 `resolve`。 。 。 . `event.value` 这是 `Interrupt`。 。 。 .

```tsx
useInterrupt({
  agentId: "tool_approval",
  renderInChat: true,
  enabled: (event) =>
    (event.value as Interrupt)?.reason === "mastra:tool_approval",
  render: ({ resolve }) => (
    <ApprovalCard
      onApprove={() => resolve({ approved: true })}
      onReject={() => resolve({ approved: false })}
    />
  ),
});
```

拒绝方式 `resolve({ approved: false })` 或者说 `cancel()`。 。 。 .

**继续.** 发送一个条目进行中断 `id`数字 :

-   `{ status: "resolved", payload: { approved: true } }` 批准(同样批准) `payload: true`) (中文(简体) ).
-   `{ status: "resolved", payload: { approved: false } }` 减少.
-   `{ status: "cancelled" }` 下降,无论载荷.
-   任何其他已解决的有效载荷(无, `null`, (中文(简体) ), `{}`, (中文(简体) ), `{ approve: true }`, (中文(简体) ), `{ approved: "yes" }`, 字符串)失败 `RUN_ERROR` 编码 `MASTRA_INVALID_TOOL_APPROVAL`马斯特拉不叫,所以批准保留 尚未答复,仍可答复.

桥接通了最初的呼叫,按了快照键 `runId` 财务报告和审定财务报表 `toolCallId`: 当地代理人 打给马斯特拉 `approveToolCall` 或者说 `declineToolCall`,远程代理呼叫 `resumeStream({ approved })`,这就是这些电话在服务器上所做的。 这个 恢复运行原始调用及其结果: 工具的输出 或Mastra在拒绝时的拒绝信息,而不运行工具.

## 跑步如何结束

-   故意停止运行(`abortRun()`,远程手柄自己的 `ClientOptions.abortSignal`或马斯特拉自己的 `abort`关闭它打开的东西 结尾 `RUN_FINISHED` 携带 `outcome: { type: "cancelled" }`运行 未订阅的订阅者被丢弃,不再寄出更多信息 .
-   在前端工具上停止的运行, 将它称为“ 成功” 并把它们命名为 `outcome.pendingToolCallIds`。左侧的任何其他呼叫 没有结果( 服务器呼叫, 背景调用, A2UI 渲染) 子代理)获得占位符 `TOOL_CALL_RESULT` 首先,一个消费者 生成流中的待决呼叫只看到前端.
-   当马斯特拉报告运行结束的原因时(其结束原因: `stop`, (中文(简体) ), `length`, (中文(简体) ), `tool-calls`,(......), `RUN_FINISHED` 原样不变 `metadata.mastra.finishReason`,所以客户端可以告诉一个关闭 由 步骤限制或从完成的答案中得出的长度限制。 取消运行 携带无.
-   `RUN_STARTED` 声明 AG-UI `protocolVersion` 桥说话 `getCapabilities()` 返回适配器的 AG-UI 能力声明.

## 副代理人

马斯特拉监督员派代表到其下属机构(`agents: { … }`)通过 `agent-<name>` 工具调用。 两个选项选择客户端所看到的 代表团:

```ts
new MastraAgent({
  agent: supervisor,
  resourceId: "user-123",
  subagentVisibility: "attributed", // default "hidden"
  subagentToolResults: "omit", // default "full"
});
```

-   `subagentVisibility: "hidden"` 使桥梁保持原样: 客户端看到授权工具调用及其结果,没有看到 子代理的自流.
-   `subagentVisibility: "attributed"` 使每个代表团成为AG-UI子代理 援引: `SUBAGENT_STARTED`,然后是子代理文本、推理和工具 电话流 直播和标签 `subagentRunId`,则 `SUBAGENT_FINISHED` 或者说 `SUBAGENT_ERROR`A. 代表团的组成 `subagentRunId` 其父母随其本人的电话编号(`D1/d9`因此 运行中恢复中止的引用再次宣布相同的ID. 需要一个 AG-UI 1.0客户端.
-   `subagentToolResults: "omit"` 发送自定义子代理工具 结果为空( 一个失败的调用保留其错误), 以保留大结果 线. 监督员的模型认为,代表团本身的结果是: 从来没有省略.
-   失败的子代理以 `SUBAGENT_ERROR` 代码 `MASTRA_SUBAGENT_ERROR` (其模型或工具失败), `MASTRA_TRIPWIRE` 联合国 处理器被屏蔽)或 `CANCELLED` (运行先停止),带信息 从不堆叠。 只有援引结束:主管得到 代表团的结果和运行继续.
-   `getCapabilities()` 当地监督人员 `"attributed"` 模式声明 `multiAgent` 及其子代理及其描述.
-   `RUN_FINISHED` 使用中包括每个子代理的模型调用 可见度,每个提供者和模型一个条目。 本地主管的副代理 被贴上他们自己的模型的标签; 一个远程的保持没有贴上标签,作为自己的 使用过。 玛斯特拉在暂停时 没有任何子代理的用途, 所以,运行恢复 它算起子代理的电话 从暂停之前 也:在两次赛跑中,每个赛事被计算一次.

一个子代理 `data-*` 用作工具的工作流程 `agent.network()` 为: 未归属.

## 理由和工具结果

-   推理范围包括提供者的手工艺品(一种反人类思维签名或 编辑后块, 一个 OpenAI 推理项 ID 和加密内容) 发送为 `REASONING_ENCRYPTED_VALUE` 为推理信息。 当那个消息降临 在运行中输入, 直接在它的助手信息前, 桥 把推理交给马斯特拉 带着那些艺术品.
-   一个工具 `toModelOutput` 返回内容窗体(`{ type: "content" }`(中文(简体) ) aG-UI 中包含部分的结果 `TOOL_CALL_RESULT`; 任何其他 结果是JSON弦 它一直是.
-   作为内容部分( 前端工具的答案, 或服务器) 给出的工具信息 工具 客户端稍后发送的结果)保留其文本作为 原始结果并将其部分交给 Mastra 作为工具的模型输出:
    -   文本为 a `text` 项目,以及 `data` 字节为 `media` 和他们的迷你玩具。 A 类 `data` 没有字符串值或 mimeType 的源被丢入 警告 警告他们.
    -   uRL 从未作为 `media`: 图像 URL( an) `image/*` mIME TYPE,或一个 无图像部分)是 `image-url`,其他的则 `file-url`,则a `data:` URI被读取为它所持有的字节.
    -   提供者文件控件是 `file-id` 或者说 `image-file-id`。 。 。 .
-   模型是否看到一个项目 由Mastra和提供者决定 而不是 桥。 马斯特拉的型号路由器(英语:`model: "openai/gpt-4.1-mini"` 诸如此类的) 滴数 `media` 工具结果中的项目,所以 base64 图像和文档不 到达这些模型, 在第一个回合, 也。 在经测试的供应商中,无 在工具结果中使一个提供者文件id, `@ai-sdk/anthropic` 2(AI SDK) v5)没有用于工具输出的 URL 格式,并且 `@ai-sdk/openai` 3个 `file-url` 在这里.
-   只重放内容表单:用于工具 `toModelOutput` 返回时 文本或 json , 后一转则给模型原始结果.
-   提供方文件控件 `file` (来源)在用户信件上用一个 警告: Mastra 没有提供者文件 ID 的输入通道.

## 在道场运行示例服务器

```bash
cd integrations/mastra/typescript/examples
pnpm install
pnpm run dev
```

## 常见问题

### @ag-ui/mastra 是什么？

执行马斯特拉的AG-UI协议\.

### 如何安装 @ag-ui/mastra？

在项目目录运行 npm install @ag-ui/mastra，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@ag-ui/core（\>=1\.0\.0）、@mastra/core（\>=1\.29\.0 \<2\.0\.0-0）、@ag-ui/client（\>=1\.0\.0）、@mastra/client-js（\>=1\.0\.0-0 \<2\.0\.0-0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ag-ui/mastra 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ag-ui/mastra 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ag-ui/mastra 可以商用吗？

@ag-ui/mastra 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @ag-ui/mastra 的下载量有多少？

根据 npm 官方下载统计，@ag-ui/mastra 在 2026/10/05 – 2026/11/03 这 30 天内被下载 658,067 次，日均约 21,936 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ag-ui/mastra 还在维护吗？

最新版本 2\.0\.2 发布于 2026/10/31（7 天前）；至今共发布 43 个版本，其中过去 12 个月发布了 24 个；首次发布于 2025/06/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。