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()不是可选的样式代码，而是让步骤流"生效注册"的必要动作——这也是课程示例中链尾必须调用它的原因。
注册工作流与 Agent：Mastra 实例配置
在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，摘要步产出summary，AI 分析步产出aiAnalysis.score与aiAnalysis.feedback。
Playground 的价值在于把执行图的每一步展开为可检查的中间态——你可以直接看到aiAnalysisStep收到的inputData正是上一步的完整输出，从而直观验证"输出即输入"的链式契约。
小结：AI 增强流水线的完整形态
至此，aiContentWorkflow构成了一条完整的 AI 驱动内容处理系统：
| 步骤 | 步骤 ID | 职责 | 新增输出字段 |
|---|---|---|---|
| 1 | validateContentStep | 验证内容、统计字数 | wordCount |
| 2 | enhanceContentStep | 生成阅读时长与难度元数据 | metadata |
| 3 | generateSummaryStep | 生成内容摘要 | summary |
| 4 | aiAnalysisStep | 调用 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），仅供参考
