|
History
|
||
|---|---|---|
| .. | ||
| patches | ||
| scripts | ||
| src | ||
| .env.example | ||
| .gitignore | ||
| CHANGELOG.md | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| README.md | ||
| request-context-presets.json | ||
| seed-traces.mjs | ||
| tsconfig.json | ||
| tsconfig.node.json | ||
| vitest.config.ts | ||
Mastra Agent Examples
This directory contains example agents demonstrating various Mastra features.
Getting Started
-
From the
mastrarepository root, change into this example directory and install dependencies:cd examples/agent pnpm install --ignore-workspace -
Set up environment variables:
cp .env.example .env # Edit .env with your API keys -
Run the example:
pnpm start
Available Scripts
pnpm start- Run the agent examplespnpm mastra:dev- Start Mastra development serverpnpm mastra:studio- Open Mastra Studio UIpnpm mastra:build- Build for productionpnpm mastra:start- Start production server
Computer-use agent
The computer-use-agent controls a remote Linux desktop through workspace screenshot, mouse, keyboard, and shell tools. It uses Daytona by default:
DAYTONA_API_KEY=your-daytona-api-key
To use E2B Desktop instead, set:
COMPUTER_USE_PROVIDER=e2b-desktop
E2B_API_KEY=your-e2b-api-key
Then start the linked workspace version of Mastra:
pnpm mastra dev
Open Computer Use Agent in Studio and try:
Take a screenshot and report the screen dimensions. Open a terminal through the desktop UI, create
/tmp/computer-use-demo.txtcontaining a unique marker, then use the shell tool to read the file and verify that the GUI and shell are operating on the same machine.
Only COMPUTER_USE_PROVIDER=e2b-desktop selects E2B Desktop; any other value uses Daytona. The selected provider's API key is required when the agent first uses a computer or shell tool.
Computer actions can create billable cloud sandboxes. Stop or destroy test sandboxes when you're finished, and don't share authenticated desktop stream URLs.
Request Context Presets
This example includes a demonstration of Mastra's Request Context Presets feature, which allows you to define named configurations that can be easily switched between in the Studio UI.
What are Request Context Presets?
Request context presets are predefined JSON configurations that can be selected from a dropdown in the Mastra Studio Playground. This feature enables you to quickly switch between different environments, user roles, or scenarios without manually editing JSON each time.
Using Request Context Presets
1. Running with Presets in Dev Mode
mastra dev --request-context-presets ./request-context-presets.json
2. Running with Presets in Studio Mode
mastra studio --request-context-presets ./request-context-presets.json
3. Using the Presets Dropdown
Once you start Mastra with the --request-context-presets flag:
- Open the Mastra Studio in your browser
- Navigate to an agent's page
- Look for the Request Context section
- You'll see a dropdown with available presets
- Select a preset to automatically populate the JSON editor with that configuration
- Click "Save" to apply the context to your agent interactions
The dropdown includes a "Custom" option that is automatically selected when you manually edit the JSON.
Available Presets in This Example
This example includes the following presets in request-context-presets.json:
Environment Presets
-
development: Development environment with debug logging
- API endpoint:
https://dev-api.example.com - Debug mode: enabled
- Log level: debug
- API endpoint:
-
production: Production environment with minimal logging
- API endpoint:
https://api.example.com - Debug mode: disabled
- Log level: error
- API endpoint:
-
staging: Staging environment for testing
- API endpoint:
https://staging-api.example.com - Debug mode: enabled
- Log level: info
- API endpoint:
Role-Based Presets
-
admin-user: Full administrative access
- Permissions: read, write, delete, manage
- Advanced tools: enabled
- Analytics: enabled
-
guest-user: Limited read-only access
- Permissions: read only
- Advanced tools: disabled
- Analytics: disabled
Request Context Demo Agent
The requestContextDemoAgent demonstrates how agents can dynamically adapt their behavior based on the request context:
Dynamic Agent Behavior
-
Instructions: Vary by environment and role
- Development mode includes verbose debugging instructions
- Production mode provides optimized, concise guidance
- Log level affects response detail
-
Model Selection: Automatically chooses appropriate model
- Production:
gpt-5(higher quality) - Development/Staging:
gpt-5-mini(faster iteration)
- Production:
-
Tool Availability: Conditionally provides tools based on permissions
apiRequestTool: Available to all users, uses environment-specific endpointsadminActionTool: Only available with "manage" permissionanalyticsTool: Only available whenfeatures.analyticsis enabled
Testing Different Presets
Try switching between presets to see how the agent behaves differently:
-
Select the development preset and ask: "Make an API request to fetch user data"
- Agent will use the dev API endpoint with debug logging
-
Select the admin-user preset and ask: "Show me analytics for the platform"
- Agent will have access to analytics tools
-
Select the guest-user preset and ask the same question
- Agent will explain it doesn't have permission for analytics
Creating Your Own Presets File
You can create custom presets for your own use cases:
{
"preset-name": {
"customField": "value",
"nested": {
"data": "example"
}
},
"another-preset": {
"userId": "user-123",
"tenant": "acme-corp"
}
}
Requirements:
- The file must contain a valid JSON object
- Each preset must be an object (not a string, number, or array)
- Preset values can contain any valid JSON structure
Benefits
- Faster Testing: Switch between configurations instantly
- Consistency: Ensure the same configuration is used across team members
- Documentation: Preset names serve as documentation of supported scenarios
- No Manual Editing: Reduce errors from typing JSON manually
- Environment Parity: Test production configurations in development
Dynamic Workflow Demo — daily-standup-digest
This example seeds a workflow at boot from a JSON DynamicWorkflowGraph, without ever calling createWorkflow(...). The workflow shows up in Studio like any other workflow because mastra.addDynamicWorkflow(...) persists it to WorkflowDefinitionsStorage and live-registers it in one shot.
What it demonstrates
- Declarative
tool/agent/mapping/foreach/conditional/workflowentry types round-tripping from JSON. - The three-scope template model:
${initData.teamName}and${stepResults.normalize-each-note}in amappingstep, with the array of per-note outputs JSON-encoded automatically. foreach(agent)withconcurrency, rehydrated from JSON.- A
conditionalstep with declarative predicates that picks between two nested dynamic sub-workflows (daily-standup-plainwhen there are no blockers,daily-standup-with-escalationwhen there are). Theconditional's output is{ markdown: string }regardless of branch, which becomes the parent workflow's terminal output. - Nested dynamic workflows as a first-class step type — the parent JSON references sub-workflows by id, they live in their own JSON files, and each can be inspected, run, or edited independently in Studio.
- Restart survival: kill
pnpm mastra dev, restart, and all three workflows are still there becauseLibSQLStore'sworkflowDefinitionsdomain persists them.
Files
src/mastra/dynamic-workflows/daily-standup-digest.json— the top-levelDynamicWorkflowGraph(normalize → detect blockers → conditional → nested sub-workflow).src/mastra/dynamic-workflows/daily-standup-plain.json— sub-workflow used when there are no blockers.src/mastra/dynamic-workflows/daily-standup-with-escalation.json— sub-workflow used when there are blockers; also drafts a tech-lead escalation message.src/mastra/dynamic-workflows/daily-standup-agents.ts— the three agents referenced byagentId.src/mastra/dynamic-workflows/daily-standup-tools.ts— the four tools referenced bytoolId.src/mastra/index.ts— imports the JSON files and seeds all three viamastra.addDynamicWorkflow(...)after theMastrainstance is constructed. The two sub-workflows are seeded before the parent socollectRefscan resolve their ids.
Try it
pnpm mastra dev
Then in Studio:
- Open Workflows →
daily-standup-digest. - Run with an input that has at least one real blocker to hit the escalation branch:
{ "teamName": "Platform", "notes": [ { "author": "Alex", "text": "yesterday shipped the auth fix. today wiring up the retry queue. blocked on staging creds." }, { "author": "Sam", "text": "finished the migration script. moving on to the dashboard rewrite. no blockers." } ] } - Or run with all-clear notes to hit the plain-digest branch:
{ "teamName": "Platform", "notes": [ { "author": "Alex", "text": "shipped auth fix. today: retry queue. no blockers." }, { "author": "Sam", "text": "migration done. today: dashboard rewrite. no blockers." } ] } - Confirm the run produces a
markdownoutput with a dated# Platform — Daily Standup (...)header. The blocker input additionally includes a## Escalationsection drafted by thestandup-escalationagent.
Proof of restart survival
- Run
pnpm mastra devonce so the workflow is upserted intomastra.db. - Stop the process.
- Delete
src/mastra/dynamic-workflows/daily-standup-digest.json(temporarily). - Restart
pnpm mastra dev— the workflow still appears in Studio because it was loaded from storage on boot, not from the JSON file. - Restore the JSON file when done.