---

name: mastra-best-practices

prettier-ignore

description: Mastra architectural patterns. Covers agent vs workflow choice, project structure, TypeScript ES2022 requirements, API keys setup, and accessing via mastra.getAgent/getWorkflow. license: Apache-2.0 metadata: author: Mastra version: "1.0.0" repository: https://github.com/mastra-ai/skills

Mastra Best Practices

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

---

Agent vs Workflow

---

TypeScript Config (Required)

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

Critical: CommonJS causes errors. Must use ES2022.

---

Project Structure

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

---

Environment Variables

CopyOPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
GOOGLE_GENERATIVE_AI_API_KEY=...

---

Quick Reference

Basic Agent

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

Basic Workflow

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

Structured Output

Copyconst 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

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

---

Key Conventions

1. Use mastra.getAgent('name') / mastra.getWorkflow('name') not direct imports
2. Always use env vars for API keys
3. ES2022 modules required (not CommonJS)
4. Test with Studio: npm run dev → http://localhost:4111

---

Resources

• Docs
• Agents
• Workflows