Mastra 工作流注册指南将 Workflow 挂载到 Mastra 实例并接入 Agents 与 Tools【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本指南讲解 Mastra 中工作流注册这一关键步骤如何把通过createWorkflow定义好的工作流Workflow注册进主Mastra实例使其与 Agent、Tool 等其他原语primitive一起被统一管理与调度。读完本文你将掌握src/mastra/index.ts的完整配置方式、注册背后的源码执行链路以及注册后如何通过getWorkflow/listWorkflows校验和访问工作流为后续在 Playground 中可视化运行或编程式调用打下基础。一、注册前准备工作流从定义到就绪在注册之前工作流本身需要先在独立的文件中完成定义并commit()。以 Mastra 官方课程docs/src/course/04-workflows中构建的内容处理工作流为例定义位于src/mastra/workflows/content-workflow.tsimport { createWorkflow } from mastra/core/workflows import { z } from zod export const contentWorkflow createWorkflow({ id: content-processing-workflow, description: Validates and enhances content, 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(), }), }), }) .then(validateContentStep) .then(enhanceContentStep) .commit()这一步完成后contentWorkflow是一个已提交committed的工作流实例它拥有类型安全的输入/输出 SchemaZod 定义步骤通过.then()按顺序串联.commit()则固化整个工作流定义。注意此时工作流只是存在于文件中还没有被任何Mastra实例认识——这正是本指南要解决的下一步。二、更新 Mastra 配置注册你的工作流打开 Mastra 应用的入口文件src/mastra/index.ts导入工作流并将其加入Mastra构造函数的workflows字段// Import your workflow import { contentWorkflow } from ./workflows/content-workflow export const mastra new Mastra({ // Register your workflow here workflows: { contentWorkflow, }, // ...Existing code // 例如已有的 agents、tools、storage 等配置 })这里有两个关键约定workflows是一个以注册键key为索引的对象而不是数组。键名contentWorkflow就是之后mastra.getWorkflow(contentWorkflow)所用的查询 key如果src/mastra/index.ts中已经注册过其他工作流只需把新工作流作为新条目追加进同一个workflows对象即可例如workflows: { existingWorkflow, contentWorkflow }不要新建第二个对象覆盖原有注册。Mastra类的构造配置类型定义packages/core/src/mastra/index.ts也印证了这一点Config接口中的workflows?: TWorkflows其中TWorkflows extends Recordstring, AnyWorkflow见index.ts#L255-L270与index.ts#L311-L313。也就是说workflows字段天然就是一个键 → 工作流实例的映射表注册工作流就是把工作流实例塞进这张表。三、注册背后发生了什么构造函数与 addWorkflow 源码链路仅仅两行配置Mastra构造函数内部却完成了一整套初始化流程。从源码看packages/core/src/mastra/index.ts#L1726-L1732构造函数在初始化阶段遍历config.workflows的每个条目并调用this.addWorkflow(workflow, key)if (config?.workflows) { Object.entries(config.workflows).forEach(([key, workflow]) { if (workflow ! null) { this.addWorkflow(workflow, key); } }); }而addWorkflowindex.ts#L4960-L5009的核心逻辑依次是去重保护若注册键已存在于#workflows注册表中直接返回避免重复注册workflow.__registerMastra(this)把工作流与当前Mastra实例绑定建立双向引用workflow.__registerPrimitives({ logger, storage })将实例的 logger 与 storage 注入工作流。这一点很重要——工作流运行时的日志记录、跨分支状态协调、运行状态持久化都依赖 storage而 logger 则负责观测与追踪自动commit()若工作流尚未.commit()注册时会被自动补上提交动作保证进入注册表的一定是已固化的定义写入注册表workflows[workflowKey] workflow附加能力注册调用registerStaticWorkflowScorers(workflow)注册工作流相关的评估器scorer声明式调度schedule检测如果工作流声明了schedule配置则置位#hasScheduledWorkflow标记并在调度 worker 已启动时同步注册声明式调度行。这也解释了为何带定时调度的工作流在注册后即可被调度器发现。另外值得注意的细节构造函数中有一条针对 config 被展开spread导致字段为 undefined 的防御逻辑index.ts#L119-L143若传入的 workflow 为null/undefined会抛出带明确错误码如MASTRA_ADD_WORKFLOW_UNDEFINED的MastraError。因此在组装配置对象时建议直接写字面量对象而不是用{ ...config }展开可能带 getter 或不可枚举属性的来源对象。仓库测试用例可以验证这一注册路径的真实性例如packages/core/src/workflows/__tests__/declarative-step-entries.test.ts#L256-L263中的bind辅助函数正是通过new Mastra({ workflows: { [workflow.id]: workflow }, ... })将工作流挂载到实例后再执行.map()、.tool()等步骤的packages/core/src/mastra/list-active-workflow-runs.test.ts#L56也展示了多工作流workflows: { firstWorkflow, secondWorkflow }的注册形态。四、注册后的访问与校验getWorkflow / getWorkflowById / listWorkflows注册完成后工作流就进入Mastra的中央注册表#workflows你可以通过三类 API 访问它1.mastra.getWorkflow(id)按注册键查询index.ts#L3549-L3575实现以注册时使用的 key 直接查表返回工作流实例若未找到抛出错误码为MASTRA_GET_WORKFLOW_BY_ID_NOT_FOUND、HTTP 状态为 404 的MastraError错误详情中还会带上当前已注册的所有工作流 keyworkflows: Object.keys(this.#workflows)便于排查拼写错误。传入{ serialized: true }时只返回{ name }形式的序列化摘要。const wf mastra.getWorkflow(contentWorkflow) const run await wf.createRun() const result await run.start({ inputData: { content: ..., type: article } })2.mastra.getWorkflowById(id)按工作流自身 id 查询与注册键不同工作流在createWorkflow({ id: content-processing-workflow })中声明了自己的id。getWorkflowByIdindex.ts#L3881会先按注册键直查找不到时再遍历注册表匹配workflow.id因此即使注册键与工作流内部 id 不同也能命中。3.mastra.listWorkflows()列出全部注册工作流index.ts#L4865-L4879返回按 key 索引的全部工作流记录。注意它会过滤掉内部隐藏工作流如通知调度 dispatch 工作流确保你看到的是业务侧可用的完整清单。这也是 Playground、服务端路由等能力发现工作流的底层依据。五、注册的边界与常见场景场景一一个实例注册多个工作流workflows是对象而非数组多个工作流并列即可export const mastra new Mastra({ workflows: { contentWorkflow, summarizeWorkflow, reportGenerator: createWorkflow({ ... }).commit(), }, })场景二工作流与 Agent、Tool 共存工作流注册与 Agent、Tool 注册互相独立、互不干扰。Mastra类本身就是agents、workflows、storage、logging、observability 等的中央编排器见index.ts#L677的类注释工作流既可以独立运行也可以在步骤中调用已注册的 Tool甚至通过 Agent 步骤与 Agent 协同对应课程后续章节12-using-agent-in-workflow.md与13-creating-ai-enhanced-workflow.md的主题。场景三注册时工作流未 commitaddWorkflow会在注册阶段自动对未提交的工作流执行commit()index.ts#L4981-L4983所以即使你在定义文件中遗漏了.commit()注册到 Mastra 后依然可用——但推荐在定义处显式 commit让定义完成这一状态更清晰。六、验证注册结果并进入下一步工作流注册成功后最快、最直观的验证方式是启动 Mastra 开发服务器在 Playground 中查看并运行它npm run dev启动后你会看到类似 Mastra Dev Server starting...与 Studio available at: http://localhost:4111的输出。打开浏览器访问http://localhost:4111在导航中点击 Workflows即可看到刚刚注册的contentWorkflow。点击进入后Playground 会根据工作流的inputSchema自动生成输入表单填入示例内容并点击 Run Workflow就能实时观察步骤执行进度、执行耗时与最终输出结果详见课程07-using-playground.md。此时你的工作流已经真正长在 Mastra 实例上它被统一注册、可被 Playground 发现、可通过getWorkflow编程式调用并与其他 Agent、Tool 一起构成了完整的 Mastra 应用。如果希望工作流定时自动触发还可以在定义中加入schedule配置——注册时源码会自动完成调度同步这同样是本节注册动作带来的能力延伸。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考