Update Mastra tutorial with working workflow and auth handling #696

nearestnabors · 2026-01-22T19:05:18Z

Preview: https://docs-git-mastra-tutorial-update-arcade-ai.vercel.app/en/get-started/agent-frameworks/vercelai

Summary

Updates Mastra tutorial workflow to use proper auth error handling with arcade.auth.start()
Changes workflow to send email digest as a DM instead of posting to #general channel
Uses Slack_WhoAmI to dynamically get user's Slack ID for DM
Passes authRequired/authUrl through workflow steps to handle OAuth flows
Uses ARCADE_USER_ID environment variable with sensible defaults
Updates documentation to explain workflow auth handling patterns
Adds key takeaway about workflows needing explicit auth handling

Test plan

Verify tutorial code samples compile without errors
Test workflow execution in Mastra Studio
Confirm email digest is sent as DM to user, not to #general

🤖 Generated with Claude Code

Note

Consolidates Mastra docs into a single, end‑to‑end tutorial that includes a working agent and workflow with explicit OAuth handling and Slack DM via Slack_WhoAmI, plus guidance like tool output truncation and Zod conversion.

Adds comprehensive mastra/page.mdx with agent, workflow, auth flow (arcade.auth.start()), and examples; removes old Mastra pages
Updates redirects in next.config.ts to point legacy Mastra paths to the new consolidated page
Tweaks CSS so only h3 headings are numbered in Steps; keeps nested list spacing fix
Updates agent-frameworks/_meta.tsx label to "Vercel AI SDK"
Regenerates public/llms.txt content and metadata

^{Written by Cursor Bugbot for commit 8ebed03. This will update automatically on new commits. Configure here.}

- Consolidate multi-page tutorial into single comprehensive page - Add tool configuration with MCP servers and individual tools - Include output truncation to prevent token overflow - Add email digest workflow example - Update Steps component CSS to not number nested h4-h6 headings - Add callout linking to multi-user auth guide - Update redirects to point old pages to new single page Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add auth error handling with arcade.auth.start() in workflow steps - Pass authRequired/authUrl through workflow steps - Use Slack_WhoAmI to get user's Slack ID - Send digest as DM instead of posting to #general channel - Use defaultUserId from ARCADE_USER_ID env var - Update documentation to explain workflow auth handling Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vercel · 2026-01-22T19:05:22Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
docs	Ready	Preview, Comment	Jan 22, 2026 7:48pm

github-actions

Style Review

Found 9 style suggestion(s).

Powered by Vale + Claude

app/en/get-started/agent-frameworks/mastra/page.mdx

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

- Changed workflow default userId from empty string to 'default-user' to match agent behavior - Fixed Gmail tool name from 'Gmail.ListEmails' (dot) to 'Gmail_ListEmails' (underscore) to match tool configuration

cursor · 2026-01-22T19:23:11Z

Bugbot Autofix resolved 2 of the 2 bugs found in the latest run.

✅ Fixed: Inconsistent default userId values between agent and workflow
- Changed workflow default userId from empty string to 'default-user' to match agent behavior in both tutorial and complete code sections.
✅ Fixed: Inconsistent tool name format uses dot vs underscore
- Changed tool name from 'Gmail.ListEmails' to 'Gmail_ListEmails' to match the tool configuration format in both tutorial and complete code sections.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is ON. A Cloud Agent has been kicked off to fix the reported issue.}

app/en/get-started/agent-frameworks/mastra/page.mdx

cursor · 2026-01-22T19:44:56Z

Bugbot Autofix resolved the bug found in the latest run.

✅ Fixed: Redundant key takeaways convey same information
- Removed the redundant bullet point at line 608 that duplicated the agent vs workflow information already provided in line 604.

torresmateo · 2026-01-22T20:02:11Z

nits:

if possible add bun to the list of runtimes/package managers?
have the selection of the runtime be sticky (so that I only need to pick it once)

nearestnabors and others added 3 commits January 22, 2026 18:06

Merge origin/main into mastra-tutorial-update

b058349

adding images to the Mastra example

e6368d9

nearestnabors requested review from sdserranog, teallarson and torresmateo January 22, 2026 19:06

vercel bot had a problem deploying to Preview January 22, 2026 19:08 Failure

fix image path

b2dfeb1

vercel bot deployed to Preview January 22, 2026 19:14 View deployment

Merge origin/main - keep Mastra redirects and fix image paths

10db0f3

nearestnabors enabled auto-merge (squash) January 22, 2026 19:14

🤖 Regenerate LLMs.txt

82a53a5

github-actions bot reviewed Jan 22, 2026

View reviewed changes

🤖 Regenerate LLMs.txt

f7de513

This comment was marked as resolved.

Sign in to view

Update app/en/get-started/agent-frameworks/mastra/page.mdx

347a54e

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

This comment was marked as resolved.

Sign in to view

This comment was marked as duplicate.

Sign in to view

vercel bot deployed to Preview January 22, 2026 19:20 View deployment

This comment was marked as outdated.

Sign in to view

Fix inconsistent userId defaults and tool name format in Mastra tutorial

20b1d81

- Changed workflow default userId from empty string to 'default-user' to match agent behavior - Fixed Gmail tool name from 'Gmail.ListEmails' (dot) to 'Gmail_ListEmails' (underscore) to match tool configuration

This comment was marked as duplicate.

Sign in to view

nearestnabors and others added 5 commits January 22, 2026 19:26

Update app/en/get-started/agent-frameworks/mastra/page.mdx

790dbeb

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update app/en/get-started/agent-frameworks/mastra/page.mdx

391629f

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update app/en/get-started/agent-frameworks/mastra/page.mdx

0c7f650

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update app/en/get-started/agent-frameworks/mastra/page.mdx

acd6362

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update app/en/get-started/agent-frameworks/mastra/page.mdx

d444a09

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

This comment was marked as duplicate.

Sign in to view

nearestnabors and others added 2 commits January 22, 2026 19:27

Update app/en/get-started/agent-frameworks/mastra/page.mdx

2475e57

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update app/en/get-started/agent-frameworks/mastra/page.mdx

3c3a580

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

This comment was marked as duplicate.

Sign in to view

Update app/en/get-started/agent-frameworks/mastra/page.mdx

b4b5a96

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

This comment was marked as duplicate.

Sign in to view

vercel bot deployed to Preview January 22, 2026 19:32 View deployment

Update app/en/get-started/agent-frameworks/mastra/page.mdx

923a28c

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

vercel bot deployed to Preview January 22, 2026 19:38 View deployment

cursor bot reviewed Jan 22, 2026

View reviewed changes

app/en/get-started/agent-frameworks/mastra/page.mdx Outdated Show resolved Hide resolved

Remove redundant key takeaway about agents vs workflows

8ebed03

vercel bot deployed to Preview January 22, 2026 19:48 View deployment

torresmateo approved these changes Jan 22, 2026

View reviewed changes

nearestnabors merged commit cad6d71 into main Jan 22, 2026
8 checks passed

github-actions bot mentioned this pull request Jan 22, 2026

Editorial improvements for #696 #697

Closed

Update Mastra tutorial with working workflow and auth handling #696

Update Mastra tutorial with working workflow and auth handling #696

Uh oh!

Conversation

nearestnabors commented Jan 22, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

vercel bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Style Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as outdated.

Uh oh!

cursor bot commented Jan 22, 2026

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as duplicate.

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot commented Jan 22, 2026

Uh oh!

Uh oh!

torresmateo commented Jan 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nearestnabors commented Jan 22, 2026 •

edited by cursor bot

Loading

vercel bot commented Jan 22, 2026 •

edited

Loading