Mastra mastra/ai-sdk 实战把 Agent、Workflow 与 Agent 网络输出为 AI SDK 兼容的 UI 流【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/ai-sdk是 Mastra 官方推荐的与 Vercel AI SDK 集成的方式它通过注册自定义 API 路由把 Mastra 的 Agent、Workflow 和 Agent 网络执行结果以 AI SDK UI 兼容的 SSE 流格式返回给前端。读完本文你将掌握三条路由处理器chatRoute、workflowRoute、networkRoute的完整参数与默认值、脱离 Mastra 内置服务器使用框架无关处理器handleChatStream等的方法以及 SSE 心跳保活、流平滑、withMastra记忆中间件和./ui浏览器端消息转换等配套能力并能在源码层面理解这些功能背后的实现。包定位与环境要求Mastra 仓库中该包的 READMEclient-sdks/ai-sdk/README.md明确写道将 Mastra 与 AI SDK 一起使用的推荐方式就是安装mastra/ai-sdk包它提供自定义 API 路由与工具用于以 AI SDK 兼容格式流式传输 Mastra 的 Agent包括聊天、Workflow 与网络路由处理器以及面向 UI 集成的工具与导出类型。从 client-sdks/ai-sdk/package.json 可以确认运行环境约束安装npm install mastra/ai-sdk要求 Node.js 22.13.0peerDependencies为mastra/core 1.5.0-0 2.0.0-0与zod ^3.25.0 || ^4.0.0也就是说项目必须已安装 Mastra 核心且 zod 版本受兼容区间约束包导出两个入口主入口mastra/ai-sdk路由与流工具和子路径mastra/ai-sdk/ui浏览器安全的消息转换不含任何 Node 流工具见 src/ui.ts当前仓库中的包版本为1.10.3-alpha.1版本历史见 client-sdks/ai-sdk/CHANGELOG.md。路由注册总览三种 apiRoutesREADME 给出的最简用法是在Mastra实例的server.apiRoutes中注册chatRoute并通过:agentId路径参数实现动态 Agent 路由import { chatRoute } from mastra/ai-sdk; export const mastra new Mastra({ server: { apiRoutes: [ chatRoute({ path: /chat/:agentId, }), ], }, });除chatRoute外主入口 src/index.ts 还导出workflowRoute与networkRoute三者共同覆盖 Mastra 的三类可执行对象路由默认路径固定 ID 参数底层调用适用场景chatRoute/chat/:agentIdagentagent.stream()/agent.resumeStream()单 Agent 多轮对话workflowRoute/api/workflows/:workflowId/streamworkflowworkflow.createRun()run.stream()/run.resumeStream()流式执行并可视化 Workflow 步骤networkRoute/network/:agentIdagentagent.network()路由 Agent 将任务委派给其他 Agent 的多 Agent 网络三者共享同一套约定路径中必须包含:agentId/:workflowId参数或者显式传入固定的agent/workflowID若同时提供路径参数与固定 ID处理器会记录警告且固定 ID 优先见 src/chat-route.ts#L682-L688。路由通过mastra/core的registerApiRoute注册为 HTTP POST 端点并自带 OpenAPI 描述因此会出现在 Mastra 服务器的 API 文档中。chatRoute完整参数、请求体与版本选择chatRoute是最常用的路由。以下参数说明整理自 src/chat-route.ts 中chatRouteOptions类型定义与 JSDoc约 L456-L529参数默认值说明path/chat/:agentId路由路径包含:agentId时动态路由agent-不使用动态路由时固定的 Agent IDdefaultOptions-传给 Agent 执行的默认选项AgentExecutionOptions如maxSteps、requestContext、providerOptions、structuredOutputexperimentalTransform-转换为 AI SDK UI 块前应用到 Mastra 流上的实验性 transform见“流平滑”一节versionv5AI SDK UI 消息流版本v5|v6|v7agentVersion-Agent 版本选项类型直接派生自Mastra.getAgentById的第二参数保证与核心自动同步sendStarttrue是否发送start事件sendFinishtrue是否发送finish事件sendReasoningfalse是否包含推理步骤sendSourcesfalse是否包含引用来源heartbeatMs-SSE 心跳目标间隔 0关闭NaN、正无穷或超过 2,147,483,647 抛RangeErroronError默认序列化器自定义错误序列化函数缺省时默认序列化器会剥离敏感字段如APICallError.requestBodyValues其中包含系统提示词messageMetadata-附加到 AI SDK 流start/finish消息块的元数据映射函数一个结合固定 Agent 与默认选项的完整示例chatRoute({ path: /api/support-chat, agent: support-agent, defaultOptions: { maxSteps: 5, }, version: v7, sendReasoning: true, heartbeatMs: 15000, });请求体与查询参数根据源码中内嵌的 OpenAPI 定义请求体为 JSONmessages为必填{ messages: [ { role: user, content: 你好 } ], resumeData: { }, runId: xxx }messages数组中的消息遵循{ role: user | assistant | system, content: string }形态AI SDKUIMessage结构由前端useChat等钩子产生resumeData用于恢复挂起的 Agent 执行例如工具审批后的恢复提供resumeData时必须同时提供runId否则handleChatStream直接抛错src/chat-route.ts#L297-L299查询参数支持versionId指定 Agent 版本 ID与statusdraft或published二者互斥status取值非法或两者同传都会抛错src/chat-route.ts#L708-L724。内部执行链路从源码结构看chatRoute的 handler 依次做以下几件事src/chat-route.ts#L671-L768解析请求体确定 Agent ID固定agent优先于路径参数合并requestContext优先级为中间件上下文 路由defaultOptions 请求体多处同时提供时记录警告将c.req.raw.signal作为abortSignal注入参数使客户端断开能中止 Agent 执行调用handleChatStream生成 UI 消息流再用对应版本的createUIMessageStreamResponse包装为 HTTP 响应最后经withSseHeartbeat包装见“SSE 心跳保活”一节后返回。在handleChatStream内部还有两个值得了解的细节重新生成regenerate当trigger regenerate-message且最后一条消息是 assistant 消息时该消息会被剔除后再交给模型从而生成全新回复最后一条 assistant 消息的 ID 会被记录为lastMessageId随start块下发帮助前端识别响应归属src/chat-route.ts#L330-L345。v6/v7 原生工具审批恢复AI SDK v6/v7 会把用户对工具调用的审批回应重新提交在 assistant 消息的工具块上。extractV6NativeApprovals会扫描所有 assistant 消息中state approval-responded的工具块按runId:toolCallId复合键去重然后streamV6ApprovalResumes按请求顺序逐个调用agent.resumeStream恢复执行对AGENT_RESUME_TOOL_CALL_NOT_SUSPENDED、AGENT_RESUME_NO_SNAPSHOT_FOUND两类“目标已解析”错误容错跳过只有当所有目标都无法恢复时才抛出类型化错误src/chat-route.ts#L35-L179。该行为由端到端测试tool-call-approval.e2e.test.ts与录制文件验证。编辑器存储覆盖当 Mastra 配置了 editor 时Agent 的运行时配置指令、工具、模型等可能存放在存储配置而非代码定义中handleChatStream会调用editorAgent.applyStoredOverrides解析显式agentVersion优先否则默认取published版本与内置 Agent 处理器行为对齐src/chat-route.ts#L306-L324。workflowRoute步骤级流式可视化workflowRoute的选项类型见 src/workflow-route.ts#L171-L178path默认/api/workflows/:workflowId/stream、固定workflow、versionv5|v6|v7默认v5、includeTextStreamParts默认true是否包含文本流块、sendReasoning、sendSources后两者默认false。其请求体字段比聊天路由更丰富WorkflowStreamHandlerParamsrunId/resourceId运行标识resourceId优先取requestContext中的MASTRA_RESOURCE_ID_KEY其次取请求体inputData/initialStateWorkflow 输入与初始状态resumeData从挂起点恢复运行requestContext、tracingOptions、step。执行链路是mastra.getWorkflowById(workflowId)找到 Workflow 后createRun({ runId, resourceId })建立运行然后二选一——有resumeData时走run.resumeStream({ resumeData })否则run.stream({ inputData, initialState })src/workflow-route.ts#L114-L123。由于每一步的输入/输出/挂起状态都会实时下发前端可以做出步骤级的进度 UI。networkRoute多 Agent 网络的流式入口networkRoute的选项为path默认/network/:agentId、固定agent、defaultOptionsNetworkOptions、version、agentVersionsrc/network-route.ts#L173-L187。处理器调用agentObj.network(messages, { ...defaultOptions, ...rest })执行网络src/network-route.ts#L104-L124。其 OpenAPI 请求体在messages之外还接受requestContext、runId、maxSteps、threadId、resourceId、modelSettings、tools等字段即标准的 Agent 执行选项。框架无关处理器handleChatStream / handleWorkflowStream / handleNetworkStream三条路由之外包还导出对应的handleChatStream、handleWorkflowStream、handleNetworkStream。这三个函数不依赖 Hono 或 Mastra 的apiRoutes适合在非内置服务器例如 Next.js App Router 的 Route Handler中直接调用。JSDoc 中给出的 Next.js 示例// Next.js App Router import { handleChatStream } from mastra/ai-sdk; import { createUIMessageStreamResponse } from ai; import { mastra } from /src/mastra; export async function POST(req: Request) { const params await req.json(); const stream await handleChatStream({ mastra, agentId: weatherAgent, params, }); return createUIMessageStreamResponse({ stream }); }handleWorkflowStream与handleNetworkStream的用法同构只需替换workflowId或params。三者均提供按version重载的类型签名v5为可选、v6/v7必须显式传返回的流可以直接交给对应 AI SDK 版本的createUIMessageStreamResponse。流转换机制toAISdkStream 与 data part 类型mastra/ai-sdk的核心工作在“Mastra 流 → AI SDK UI 流”的转换上主入口导出toAISdkStream三版本统一入口与toAISdkV5Streamv5 专用别名实现在 src/convert-streams.ts。除 AI SDK 标准文本/工具/推理块外Mastra 还通过data part把执行结构下发给前端对应导出类型定义在 src/transformers.tsAgentAgentDataParttype: data-tool-agent携带整个运行的快照AgentRunSnapshot含steps、usage、finishReason并扩展了toolErrorsAgentStepDataPartdata-tool-agent-step携带单步详情。transformer 按runId缓冲增量text-delta、tool-call-delta、reasoning-delta、source、file等把流式增量累积为全量快照再下发因此前端任意时刻拿到的都是自洽的完整状态WorkflowWorkflowDataPartdata-workflow嵌套场景为data-tool-workflow包含运行状态与steps: Recordstring, StepResultWorkflowStepDataPartdata-workflow-step以${runId}:${stepId}为 ID 下发单步的完整StepResult含input、output、suspendPayload、resumePayloadNetworkNetworkDataPartdata-network/data-tool-network包含status: running | finished、各步骤数组、usage与output此外object-result块会转换为data-structured-output用于结构化输出场景。从源码结构看Agent transformer 还处理了两个易错点其一是 processors 可能在首个模型步骤之前轮换响应消息 IDtransformer 会“扣留”start块直到首个step-start确保广播的 ID 与实际持久化 ID 一致其二是 tripwire处理器主动中止若发生 tripwire 且未收到finish事件transformer 会在流结束时补发finishReason: other的finish块保证前端流状态机闭合src/transformers.ts#L496-L548。SSE 心跳保活heartbeatMs 与 withSseHeartbeat长时挂起或慢推理场景下中间代理常常关闭空闲连接。chatRoute的heartbeatMs参数配合 src/sse-heartbeat.ts 中的withSseHeartbeat解决这一问题它在源流空闲期间周期性插入: heartbeat\n\n这种 SSE 注释帧既不改变数据语义又能维持连接。实现上有几个关键约束值得在调参时了解心跳只插入在完整 SSE 帧边界LF-LF 换行对之间拆帧期间心跳暂停等待剩余字节src/sse-heartbeat.ts#L61-L69已缓冲的源数据、完成信号与错误永远优先于心跳数据不会因心跳被延迟heartbeatMs省略、 0或响应无 body 时原样返回NaN、正无穷或超过2_147_483_647时assertValidHeartbeatMs抛RangeErrorsrc/sse-heartbeat.ts#L9-L17。chat-route-heartbeat.test.ts对这套行为有专门测试。流平滑smoothStream 与 experimentalTransformsmoothStream是一个标记为实验性的 API它把 Mastra 的文本与推理块整理为“一致、有延迟”的输出块改善打字机式渲染的观感src/smooth-stream.ts。它实际上是mastra/core/stream中createSmoothStream的工厂封装import { smoothStream } from mastra/ai-sdk; chatRoute({ path: /chat/:agentId, experimentalTransform: smoothStream(), });从实现看MastraStreamTransformOptions可以是单个 transform 工厂或工厂数组applyMastraStreamTransforms用pipeThrough把每个工厂产生的TransformStream依次串联在原始流与 AI SDK 转换之间src/smooth-stream.ts#L27-L37。注释特别提示工厂可跨请求复用而TransformStream实例只能消费一次——所以导出的是工厂而非实例。该参数同时出现在chatRoute的defaultOptions与顶层选项中experimentalTransform名称本身也表明 API 可能变化生产使用前建议跟进 CHANGELOG。withMastra给任意 AI SDK 模型接入 Mastra 记忆与处理器除了路由主入口还导出withMastra与createProcessorMiddleware实现见 src/middleware.ts。它们把 Mastra 的处理器processors与记忆能力包装到任意 AI SDK 语言模型上使你在不经过 Mastra Agent 的情况下例如直接generateText也能拥有会话记忆import { openai } from ai-sdk/openai; import { withMastra } from mastra/ai-sdk; import { LibSQLStore } from mastra/libsql; const storage new LibSQLStore({ url: file:memory.db }); await storage.init(); const model withMastra(openai(gpt-4o), { memory: { storage, threadId: thread-123, resourceId: user-456, lastMessages: 10, semanticRecall: { vector: pinecone, embedder: openai.embedding(text-embedding-3-small), topK: 5, messageRange: 2, }, workingMemory: { enabled: true, template: # User Profile\n- **Name**:\n- **Preferences**:, }, }, inputProcessors: [myInputProcessor], outputProcessors: [myOutputProcessor], });WithMastraMemoryOptions的关键字段src/middleware.ts#L68-L83storageMemoryStorage适配器必填、threadId必填、resourceId、lastMessages取最近 N 条false禁用、semanticRecall需额外提供vector向量库与embedder索引名默认memory_messages、workingMemory启用后字符串template会被包装为 markdown 模板。从源码结构看withMastra按配置自动装配处理器workingMemory启用时创建WorkingMemory输入处理器lastMessages不为false时创建MessageHistory同时作为输入与输出处理器配置semanticRecall时创建SemanticRecallRAG 式召回。所有处理器最终经由createProcessorMiddleware注入 AI SDK 的wrapLanguageModel中间件函数同时支持 v2LanguageModelV2与 v3LanguageModelV3规格的模型。另一值得注意的机制是tripwire处理器在processInput/processOutputStream中调用abort(reason)会抛出内部TripWire中间件把该状态经providerOptions.mastraProcessors传递保证并发请求间状态隔离wrapGenerate/wrapStream检测到后返回一条包含阻断理由的“阻塞流”而非真正调用模型——这为内容过滤、策略拦截等场景提供了标准做法。createProcessorMiddleware则是面向需要精细控制的低层 APIJSDoc 明确建议一般场景直接使用withMastra。./ui 子路径浏览器端消息转换mastra/ai-sdk/ui子路径src/ui.ts只导出消息转换函数刻意保持浏览器安全不含 Node 流工具toAISdkMessages将 Mastra 存储的消息转换为当前 AI SDK 版本的UIMessagetoAISdkV5Messages/toAISdkV4Messages面向特定 AI SDK 大版本的显式转换。典型用途是前端加载历史会话从 Mastra 存储读出的数据库消息经toAISdkMessages转换后可以直接喂给 AI SDK 的useChat等组件与流式响应的消息结构保持一致。测试覆盖与相关路径这个包的测试目录能反映其能力边界均位于 client-sdks/ai-sdk/src/testschat-route-v7.test.tsv7 流行为、chat-route-heartbeat.test.ts心跳、resume-stream.test.ts挂起恢复、smooth-stream.test.ts、transformers.test.ts与transform-agent-cumulative-growth.test.ts累积快照、tool-call-approval.e2e.test.ts带录制的端到端审批恢复录制文件见recordings等。本地验证可运行pnpm --filter mastra/ai-sdk test包的scripts.test为vitest run。版本与使用边界结合当前仓库内容使用时需注意version参数支持v5/v6/v7三档 AI SDK UI 消息流默认v5v6/v7在运行时会共享 v6 的转换器并在边界处重新定型源码注释说明 v7 UI 块在运行时与 v6 结构一致主入口保留了弃用导出toAISdkFormatsrc/index.ts#L27-L28新代码应使用toAISdkStreamsmoothStream与experimentalTransform属实验性 API可能在未来版本变化路由的 OpenAPI 描述、错误约定400 校验失败 / 404 Agent 未找到均来自源码内嵌定义可直接用于对接前端错误处理所有行为以上述当前仓库源码为准包版本1.10.3-alpha.1peer 依赖锁定mastra/core 1.5.0-0 2.0.0-0Node 引擎要求22.13.0。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考