0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/examples/agent
History 2026-11-12 07:20:12 -08:00
..
patches chore(security): Vanta 2026-10-23/26 - storybook 9.1.21, body-parser, fast-uri, multer, serialize-javascript, zod pins, esbuild/bundle-name overrides (#28325) 2026-10-26 16:39:13 -04:00
scripts chore(skills): add builder-smoke-test skill for Agent Builder (#16579) 2026-05-14 12:21:02 -05:00
src feat(mcp-apps-components): draw a whole observability dashboard (#29645) 2026-11-07 09:33:22 -08:00
.env.example docs: document computer-use sandboxes and add an agent example (#21712) 2026-08-25 22:35:52 -05:00
.gitignore feat: add submitted plan support to agent clients and Playground (#21658) 2026-08-17 20:42:44 +02:00
CHANGELOG.md chore: version - exit prerelease mode 2025-02-20 20:53:55 +01:00
package.json chore(deps): Vanta 2026-11-12 — raise undici to 8.12.4 / 7.30.2 (#30205) 2026-11-12 07:20:12 -08:00
pnpm-lock.yaml chore(deps): Vanta 2026-11-12 — raise undici to 8.12.4 / 7.30.2 (#30205) 2026-11-12 07:20:12 -08:00
pnpm-workspace.yaml chore(deps): Vanta 2026-11-12 — raise undici to 8.12.4 / 7.30.2 (#30205) 2026-11-12 07:20:12 -08:00
README.md feat(editor): make model fallback lists editable and persistent (#27287) 2026-11-02 18:53:39 +01:00
request-context-presets.json Wire request context through dataset experiments (#17597) 2026-06-05 08:40:20 -07:00
seed-traces.mjs feat(playground): redesign agent traces tab with EntityListPageLayout (#14644) 2026-03-26 13:23:42 -05:00
tsconfig.json fix(examples:agent): ts was not set up (#6780) 2025-08-15 14:12:25 -04:00
tsconfig.node.json fix(examples:agent): ts was not set up (#6780) 2025-08-15 14:12:25 -04:00
vitest.config.ts feat(evals): Vitest integration for runEvals (@mastra/evals/vitest) (#22665) 2026-09-01 11:31:30 +02:00

Mastra Agent Examples

This directory contains example agents demonstrating various Mastra features.

Getting Started

  1. From the mastra repository root, change into this example directory and install dependencies:

    cd examples/agent
    pnpm install --ignore-workspace
    
  2. Set up environment variables:

    cp .env.example .env
    # Edit .env with your API keys
    
  3. Run the example:

    pnpm start
    

Available Scripts

  • pnpm start - Run the agent examples
  • pnpm mastra:dev - Start Mastra development server
  • pnpm mastra:studio - Open Mastra Studio UI
  • pnpm mastra:build - Build for production
  • pnpm 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.txt containing 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:

  1. Open the Mastra Studio in your browser
  2. Navigate to an agent's page
  3. Look for the Request Context section
  4. You'll see a dropdown with available presets
  5. Select a preset to automatically populate the JSON editor with that configuration
  6. 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
  • production: Production environment with minimal logging

    • API endpoint: https://api.example.com
    • Debug mode: disabled
    • Log level: error
  • staging: Staging environment for testing

    • API endpoint: https://staging-api.example.com
    • Debug mode: enabled
    • Log level: info

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)
  • Tool Availability: Conditionally provides tools based on permissions

    • apiRequestTool: Available to all users, uses environment-specific endpoints
    • adminActionTool: Only available with "manage" permission
    • analyticsTool: Only available when features.analytics is enabled

Testing Different Presets

Try switching between presets to see how the agent behaves differently:

  1. Select the development preset and ask: "Make an API request to fetch user data"

    • Agent will use the dev API endpoint with debug logging
  2. Select the admin-user preset and ask: "Show me analytics for the platform"

    • Agent will have access to analytics tools
  3. 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 / workflow entry types round-tripping from JSON.
  • The three-scope template model: ${initData.teamName} and ${stepResults.normalize-each-note} in a mapping step, with the array of per-note outputs JSON-encoded automatically.
  • foreach(agent) with concurrency, rehydrated from JSON.
  • A conditional step with declarative predicates that picks between two nested dynamic sub-workflows (daily-standup-plain when there are no blockers, daily-standup-with-escalation when there are). The conditional'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 because LibSQLStore's workflowDefinitions domain persists them.

Files

  • src/mastra/dynamic-workflows/daily-standup-digest.json — the top-level DynamicWorkflowGraph (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 by agentId.
  • src/mastra/dynamic-workflows/daily-standup-tools.ts — the four tools referenced by toolId.
  • src/mastra/index.ts — imports the JSON files and seeds all three via mastra.addDynamicWorkflow(...) after the Mastra instance is constructed. The two sub-workflows are seeded before the parent so collectRefs can resolve their ids.

Try it

pnpm mastra dev

Then in Studio:

  1. Open Workflows → daily-standup-digest.
  2. 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." }
      ]
    }
    
  3. 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." }
      ]
    }
    
  4. Confirm the run produces a markdown output with a dated # Platform — Daily Standup (...) header. The blocker input additionally includes a ## Escalation section drafted by the standup-escalation agent.

Proof of restart survival

  1. Run pnpm mastra dev once so the workflow is upserted into mastra.db.
  2. Stop the process.
  3. Delete src/mastra/dynamic-workflows/daily-standup-digest.json (temporarily).
  4. Restart pnpm mastra dev — the workflow still appears in Studio because it was loaded from storage on boot, not from the JSON file.
  5. Restore the JSON file when done.

Learn More