@ag-ui/马斯特拉
执行马斯特拉的AG-UI协议.
通过AG-UI协议连接 Mastra 代理(本地和远程)到前端应用. 支持流化响应,内存管理和工具执行.
安装
安装 @ag-ui/mastra 软件包 :
# npm
npm install @ag-ui/mastra
# pnpm
pnpm add @ag-ui/mastra
# yarn
yarn add @ag-ui/mastra
安装所需的对等依赖 :
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,因此进行整合测试,以便进行基线:
npm install @copilotkit/runtime@^1.76.0
使用量
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 打开每个工具 :
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。 。 。 .
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-UIprotocolVersion桥说话getCapabilities()返回适配器的 AG-UI 能力声明.
副代理人
马斯特拉监督员派代表到其下属机构(agents: { … })通过
agent-<name> 工具调用。 两个选项选择客户端所看到的
代表团:
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_ERRORA. 代表团的组成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,则adata:URI被读取为它所持有的字节. - 提供者文件控件是
file-id或者说image-file-id。 。 。 .
- 文本为 a
- 模型是否看到一个项目 由Mastra和提供者决定 而不是
桥。 马斯特拉的型号路由器(英语:
model: "openai/gpt-4.1-mini"诸如此类的) 滴数media工具结果中的项目,所以 base64 图像和文档不 到达这些模型, 在第一个回合, 也。 在经测试的供应商中,无 在工具结果中使一个提供者文件id,@ai-sdk/anthropic2(AI SDK) v5)没有用于工具输出的 URL 格式,并且@ai-sdk/openai3个file-url在这里. - 只重放内容表单:用于工具
toModelOutput返回时 文本或 json , 后一转则给模型原始结果. - 提供方文件控件
file(来源)在用户信件上用一个 警告: Mastra 没有提供者文件 ID 的输入通道.
在道场运行示例服务器
cd integrations/mastra/typescript/examples
pnpm install
pnpm run dev