Mastra Best Practices

Quick reference for Mastra conventions. See mastra.ai/docs for details.

Agent vs Workflow

Use When

Agent Open-ended tasks (support, research) - reasons, decides tools, retains memory

Workflow Defined sequences (pipelines, approvals) - orchestrates specific steps in order

TypeScript Config (Required)

{ "compilerOptions": { "target": "ES2022", "module": "ES2022", "moduleResolution": "bundler" } }

Critical: CommonJS causes errors. Must use ES2022.

Project Structure

src/mastra/ ├── tools/ # Custom tools ├── agents/ # Agent configs ├── workflows/ # Workflows └── index.ts # Mastra instance

Environment Variables

OPENAI_API_KEY=... ANTHROPIC_API_KEY=... GOOGLE_GENERATIVE_AI_API_KEY=...

Quick Reference

Basic Agent

new Agent({ id: 'my-agent', name: 'My Agent', instructions: 'You are helpful', model: 'openai/gpt-4o', tools: { myTool } // optional })

Basic Workflow

createWorkflow({ id: 'my-workflow', inputSchema: z.object({ input: z.string() }), outputSchema: z.object({ output: z.string() }) }) .then(step1) .commit()

Structured Output

const response = await agent.generate('Extract: John, 30', { structuredOutput: { schema: z.object({ name: z.string(), age: z.number() }) } }) console.log(response.object) // Access via .object property

Streaming

const stream = await agent.stream('Tell a story') for await (const chunk of stream.fullStream) { console.log(chunk) }

Key Conventions

• Use mastra.getAgent('name') / mastra.getWorkflow('name') not direct imports

• Always use env vars for API keys

• ES2022 modules required (not CommonJS)

• Test with Studio: npm run dev → http://localhost:4111

Resources

• Docs

• Agents

• Workflows