Mastra 工作流实战：构建 AI 增强的内容处理流水线（aiContentWorkflow）

Mastra 工作流实战构建 AI 增强的内容处理流水线aiContentWorkflow【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文基于 Mastra 官方课程「Workflows」章节的实操文档 13-creating-ai-enhanced-workflow.md讲解如何在前序课程搭建的三步内容处理工作流基础上接入 AI Agent 分析步骤构建一条完整的 AI 增强型工作流aiContentWorkflow。读完本文你将掌握如何用createWorkflow声明带 Schema 的增强工作流、如何在 Mastra 实例中同时注册多个 Workflow 与 Agent、如何利用mastra.getAgent()在步骤内调用 Agent以及commit()与执行图构建的底层机制。从三步流程到四步 AI 流水线在课程的 第 12 课 中我们已经创建了aiAnalysisStep——一个通过 Agent 对内容进行质量评分和反馈的步骤在更早的 第 9 课 中创建了generateSummaryStep。本课的核心任务是把原有工作流的三个步骤验证 → 增强 → 摘要与 AI 分析步骤串成一条新流水线得到一条AI 增强的完整内容处理系统Validates——validateContentStep验证内容并统计字数Enhances——enhanceContentStep补充元数据阅读时长、难度等级Summarizes——generateSummaryStep基于首句与字数生成摘要Analyzes——aiAnalysisStep调用 AI Agent 输出 1–10 的质量评分与改进反馈。这条流水线的关键设计是数据只增不减每一步的outputSchema都包含上一步输出的全部字段再叠加本步新增的字段。到第四步结束输出对象同时持有content、metadata、summary和aiAnalysis四个维度的数据。创建增强工作流完整代码与 Schema 解析在src/mastra/workflows/content-workflow.ts课程示例项目结构中新增如下工作流定义export const aiContentWorkflow createWorkflow({ id: ai-content-workflow, description: AI-enhanced content processing with analysis, inputSchema: z.object({ content: z.string(), type: z.enum([article, blog, social]).default(article), }), outputSchema: z.object({ content: z.string(), type: z.string(), wordCount: z.number(), metadata: z.object({ readingTime: z.number(), difficulty: z.enum([easy, medium, hard]), processedAt: z.string(), }), summary: z.string(), aiAnalysis: z.object({ score: z.number(), feedback: z.string(), }), }), }) .then(validateContentStep) .then(enhanceContentStep) .then(generateSummaryStep) .then(aiAnalysisStep) .commit()输入 Schema 与输出 Schema 的对应关系输入 Schema只有两个字段content待处理内容和type内容类型取值为article/blog/social未提供时默认article。输出 Schema是整条流水线终态的契约wordCount由第一步产出metadata.readingTime/difficulty/processedAt由第二步产出summary由第三步产出aiAnalysis.score/aiAnalysis.feedback由第四步产出。这个写法体现了一个重要约定工作流的outputSchema描述的是最后一个步骤的输出而不是任意中间态。由于每一步都透传了上游字段末步输出天然满足整条工作流的输出 Schema。.then()链与.commit()的底层机制从源码结构看createWorkflow是 packages/core/src/workflows/create.ts 中定义的工厂函数普通场景下它构造Workflow类实例若声明了schedule参数则自动切换到 evented 引擎。Workflow类本身并不在构造时构建执行图而是在commit()时才固化// packages/core/src/workflows/workflow.ts commit() { this.executionGraph this.buildExecutionGraph(); this.committed true; return this as unknown as Workflow...; }见 workflow.ts#L2657-L2670。buildExecutionGraph()返回{ id: this.id, steps: this.stepFlow }即把.then()链式声明的步骤数组固化为执行图。如果跳过.commit()就直接创建运行实例createRun()会抛出明确错误Uncommitted step flow changes detected. Call .commit() to register the steps.见 workflow.ts#L2703-L2710。因此.commit()不是可选的样式代码而是让步骤流生效注册的必要动作——这也是课程示例中链尾必须调用它的原因。注册工作流与 AgentMastra 实例配置在src/mastra/index.ts中更新 Mastra 配置同时注册两个工作流原版contentWorkflow与 AI 增强版aiContentWorkflow和contentAgent第 11 课 中创建的 Agent// In src/mastra/index.ts import { contentWorkflow, aiContentWorkflow } from ./workflows/content-workflow import { contentAgent } from ./agents/content-agent export const mastra new Mastra({ workflows: { contentWorkflow, aiContentWorkflow, // Add the AI-enhanced version }, agents: { contentAgent }, // ... rest of configuration })这里有两个容易踩坑的点均可在核心源码中得到印证1. 注册键名必须与getAgent()的查询名一致。步骤内部通过mastra.getAgent(contentAgent)按注册键名取回 Agent 实例。getAgent的实现位于 packages/core/src/mastra/index.ts它在内部#agents映射中查找若找不到会抛出MASTRA_GET_AGENT_BY_NAME_NOT_FOUND类型的MastraError错误详情中还会附带当前所有可用 Agent 的键名列表便于排查拼写错误const agent this.#agents?.[name]; if (!agent) { const error new MastraError({ id: MASTRA_GET_AGENT_BY_NAME_NOT_FOUND, domain: ErrorDomain.MASTRA, category: ErrorCategory.USER, text: Agent with name ${String(name)} not found, details: { status: 404, agentName: String(name), agents: Object.keys(this.#agents ?? {}).join(, ) }, }); throw error; }其测试用例 config-spread.test.ts 验证了两类行为mastra.getAgent(testAgent)返回与注册对象同一引用toBe(agent)而查询未注册名会抛错。所以本例中agents: { contentAgent }的键名、以及步骤内getAgent(contentAgent)的字符串必须完全一致。2. 同一个工作流文件导出两个工作流是安全的。从源码结构看每个createWorkflow(...).commit()返回的是独立的Workflow实例持有各自的stepFlow与执行图aiContentWorkflow复用了contentWorkflow的前三个步骤对象但步骤流是各自独立声明的两者互不影响。Mastra 支持在workflows字段中并列注册多个工作流Playground 会按注册键名分别展示。回顾 AI 分析步骤步骤内如何调用 Agent为了理解第四条边aiAnalysisStep的工作方式回顾第 12 课中的步骤定义见 12-using-agent-in-workflow.md。其核心在于execute的上下文参数解构出的mastra实例execute: async ({ inputData, mastra }) { const { content, type, wordCount, metadata, summary } inputData // 组装提示词把类型、内容、字数、阅读时长、难度一并交给 Agent const prompt Analyze this ${type} content: ... // 通过 mastra 实例获取 Agent调用 generate() const contentAgent mastra.getAgent(contentAgent) const { text } await contentAgent.generate([{ role: user, content: prompt }]) // 解析 AI 响应带兜底 let aiAnalysis try { aiAnalysis JSON.parse(text) } catch { aiAnalysis { score: 7, feedback: AI analysis completed. text } } return { content, type, wordCount, metadata, summary, aiAnalysis } }这段实现有两点工程价值值得注意mastra实例是步骤访问全局资源的统一入口。在每步的execute函数中Mastra 会把宿主实例注入上下文使步骤能够访问 Agents、Tools甚至其他 Workflows。这避免了在步骤模块中硬编码导入 Agent 对象保持了步骤与配置解耦。对 LLM 输出的 JSON 解析做了兜底。aiAnalysisStep要求模型按{score: number, feedback: ...}格式返回try/catch保证即使模型返回非 JSON 文本步骤也不会失败而是回退为默认评分 7 并保留原始文本。这是把不可控的 LLM 输出接入强 Schema 流水线的稳健姿势——工作流的outputSchema承诺了aiAnalysis一定是{score: number, feedback: string}结构。在 Playground 中验证 AI 增强工作流注册完成后启动mastra dev进入 Mastra Playground打开Workflows标签页在下拉列表中选中ai-content-workflow即aiContentWorkflow的id按输入 Schema 填写测试数据例如{ content: Mastra lets you build AI agents and workflows in TypeScript., type: blog }运行测试逐步骤查看每步的输入/输出验证步产出wordCount增强步产出metadata摘要步产出summaryAI 分析步产出aiAnalysis.score与aiAnalysis.feedback。Playground 的价值在于把执行图的每一步展开为可检查的中间态——你可以直接看到aiAnalysisStep收到的inputData正是上一步的完整输出从而直观验证输出即输入的链式契约。小结AI 增强流水线的完整形态至此aiContentWorkflow构成了一条完整的 AI 驱动内容处理系统步骤步骤 ID职责新增输出字段1validateContentStep验证内容、统计字数wordCount2enhanceContentStep生成阅读时长与难度元数据metadata3generateSummaryStep生成内容摘要summary4aiAnalysisStep调用 Agent 做质量评分与反馈aiAnalysis本节的几个关键结论可归纳为createWorkflow({ id, inputSchema, outputSchema })声明工作流契约.then()串联步骤.commit()固化执行图见 create.ts 与 workflow.ts#L2657-L2670步骤内通过mastra.getAgent(name)访问全局 Agent注册键名与查询名必须一致否则会抛出MASTRA_GET_AGENT_BY_NAME_NOT_FOUND错误见 mastra/index.ts#L2269-L2300每一步透传上游全部字段并叠加新字段使末步输出满足整条工作流的outputSchema对 LLM 结构化输出必须做解析兜底才能安全接入强类型流水线。课程的后续章节14-understanding-parallel-execution.md 起将在这条串行流水线的基础上讲解如何用branch等机制实现步骤的并行执行进一步压缩多步骤工作流的总耗时。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考