docs: add Mastra integration cookbook page - #3150
Draft
pranaygp wants to merge 10 commits into
Draft
Conversation
Documents running Mastra workflows on Workflow SDK via the experimental @mastra/workflow package: how the generic runner walks the serialized step graph, the Mastra-to-Workflow-SDK primitive mapping, Next.js setup, why the consumer re-export file is required, human-in-the-loop with suspend/resume, and current limitations. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
|
Contributor
The page only exists in the v5 content tree, so an unprefixed /cookbook/... link resolves against v4 and fails the link lint. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
Verified against the @mastra/workflow implementation:
- Drop the claim that workflow and step IDs must be static string
literals. Mastra step ids are ordinary strings and can be anything;
the real requirement is the re-export file, already documented.
- Describe what run.start() actually resolves to — a full Mastra
WorkflowResult with status, input, steps, and the success, failure,
and suspended payloads — instead of implying a two-field object.
- Resume from a route with resumeHook() on the mastra:${runId}:${stepId}
token. run.resume() works, but awaiting its result only does so in the
process that started the run, which is rarely the resuming route.
- Document run watching, including the mastra:events run stream and the
Mastra event types it carries.
- Add the peer version ranges and the rest of what init() returns, and
correct the unsupported list.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
The re-export file does not pin step IDs to the consumer's source tree — export-reachable package files keep a name@version ID either way (#3152). State its real purpose (compiler discovery plus loading definitions into the flow handler) and note that upgrading the package changes its shipped step IDs, so in-flight runs must drain first. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
Runs are pinned to the deployment that recorded their step IDs, so a package version bump is intended invalidation rather than a hazard. Removes the incorrect drain-before-upgrade advice. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
The Mastra page said awaiting run.resume() only worked in the process that started the run. The package now mirrors the Workflow SDK run id onto the Mastra snapshot, so run.resume(), run.watch(), and run.cancel() work from any process when the Mastra instance has storage configured. Reframe the choice between resumeHook() and run.resume() around what each returns rather than around a process limitation, and note the item index appended to hook tokens inside .foreach(). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
The resume, watch, and cancel failures share one message template, so anchoring the quote on the invariant tail lets readers searching a cancel or watch failure find the page. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
docs/content/docs/v5/cookbook/integrations/mastra.mdx, a cookbook integration guide for running Mastra workflows on Workflow SDK via the new (experimental)@mastra/workflowpackage. Registered in the integrationsmeta.jsonand linked from the cookbook index.What the page covers
createWorkflow()/createStep()authoring API and run API stay the same; the execution engine underneath becomes Workflow SDK. No worker process to operate, zero-infra local dev, managed in production.@mastra/workflowships a generic"use workflow"runner that deterministically walks the serialized step graph in the workflow sandbox. Each stepexecute, branch condition, and loop predicate runs in a"use step"function. Includes a mapping table from Mastra concepts to Workflow SDK primitives (suspend()→ hooks,.sleep()→ durablesleep(), run watching → namespaced run streams, cancel →run.cancel()).withWorkflow, the consumer re-export file, authoring a workflow withinit({ runner: mastraRunner }), registering onnew Mastra(...), starting a run from a route handler, inspecting withnpx workflow web."use workflow"/"use step"files reachable from the consumer's source tree so the compiler transforms them, and its side-effect import loads the Mastra workflow definitions into the flow-handler process. Cross-linked to the Publishing Libraries cookbook page whose pattern this follows.@mastra/workflowrenames every step it ships. The page frames this as safe rather than hazardous, because runs are pinned to the deployment that recorded their IDs: resume re-enqueues againstworkflowRun.deploymentId(packages/core/src/runtime/resume-hook.ts:215-227,runs.ts:168) and only an explicitdeploymentId: 'latest'moves a run to newer code (start.ts:279-306). New runs get the new version; in-flight runs finish on the old one. No drain step. Pinning is per-world, so the callout says "on worlds with deployment pinning, such as Vercel" rather than stating it flatly:world-vercelpreservesdeploymentIdacross re-enqueue (packages/world-vercel/src/queue.ts:406,417-418,490),world-localpins only per SDK version, andworld-postgresreturns a constant (packages/world-postgres/src/queue.ts:133-135). Note the version-embedded ID holds re-export or not — an export-reachable package file keeps itsname@versionID either way (packages/builders/src/module-specifier.ts:370-402), which is publishing-libraries.mdx overstates the consumer re-export: package step IDs still embed name@version #3152. The page deliberately does not repeat the Publishing Libraries page's claim that re-exporting relocates the IDs.suspend({ reason }), resumed from a route withresumeHook()on themastra:${runId}:${stepId}token.run.resume()works from any process as well, including one that never saw the run start, provided theMastrainstance has storage configured — the package mirrors the Workflow SDK run id onto the Mastra snapshot, and storage is where the two ids are mapped.run.watch()andrun.cancel()work cross-process on the same condition. The page frames the choice around what each call returns (resumeHook()returns when the hook is released;run.resume()waits for the next stopping point and hands back theWorkflowResult) rather than around a process limitation. Two specifics verified against the package source by its author: the.foreach()token suffix is the item's index, zero-based and counted across the whole input array rather than restarting per concurrency batch (suspendTokeninsrc/workflows/walker.ts:106-110, offsets at450-455); and the store must be a hosted database, since afile:URL gives each serverless invocation its own empty copy and reproduces the veryCannot resume run ...error storage prevents.run.watch()/run.stream(), plus the underlyingmastra:eventsnamespaced run stream and the Mastra event types it carries.streamLegacy()/perStepstreaming unsupported and.map()untested.Related PRs
Part of a series adding Workflow SDK support to Mastra:
@mastra/workflowexamples/workflow-sdkThis PR should merge once the package is published — until then the install instructions point at something that isn't on npm yet, so it stays in draft.
Docs Preview
(Behind deployment protection — requires Vercel team access.)
Notes for reviewers
/v5/cookbook/integrations/mastra; the unprefixed/cookbook/...form used by its siblings resolves against v4 and fails the link lint. Happy to add a v4 copy instead if you'd rather it ship on the default docs version.@mastra/workflowbuild with passing end-to-end tests, and the Workflow SDK side (resumeHook,getRun().getReadable()) against this repo's own API reference pages. The package is not published yet, so the install instructions are the one thing that can't be exercised.docs/content/, matching the majority of prior docs-only PRs.🤖 Generated with Claude Code