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