Mastra 101

Welcome to Mastra 101! This guide will introduce you to Mastra, an opinionated TypeScript framework for building AI applications quickly. By the end of this guide, you'll understand the core concepts and be ready to build your first AI agent.

What is Mastra?

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack. Created by the team behind Gatsby, it provides everything you need to go from early prototypes to production-ready applications.

Key features:

• 🤖 Agents - Autonomous agents that use LLMs and tools to solve tasks
• 🔄 Workflows - Graph-based state machines for orchestrating complex processes
• 🧠 RAG - Retrieval Augmented Generation for equipping agents with knowledge
• 🔍 Observability - Built-in tracing, evals, and performance metrics
• 🚀 Deployment - Run locally or deploy to serverless cloud

Why Mastra?

Developer Experience

Mastra is purpose-built for TypeScript developers who want to build AI features without wrestling with complex infrastructure:

typescript

Production Ready

Unlike many AI frameworks, Mastra includes:

• Built-in tracing and observability
• Structured outputs and validation
• Memory management
• Human-in-the-loop capabilities
• Evaluation frameworks

Flexible Deployment

Run Mastra anywhere:

• Local development
• Next.js and React apps
• Standalone Node.js servers
• Serverless cloud deployments

Core Concepts

1. Agents

Agents are autonomous entities that use LLMs and tools to accomplish goals. They:

• Reason about user requests
• Decide which tools to use
• Maintain conversation memory
• Iterate until reaching a solution

Basic Agent Example:

typescript

2. Workflows

Workflows provide explicit control over execution flow. They're graph-based state machines perfect for:

• Multi-step processes
• Conditional logic
• Branching and merging
• Parallel execution

Workflow Example:

typescript

3. Tools

Tools extend agent capabilities beyond text generation. Agents decide when and how to use tools.

Tool Example:

typescript

4. Memory

Memory enables agents to maintain context across conversations:

typescript

5. RAG (Retrieval Augmented Generation)

RAG equips agents with knowledge from your data sources:

typescript

Installation

Quick Start

Create a new Mastra project:

bash

Or install manually:

bash

Set Your API Key

bash

Create Your First Agent

Create src/agent.ts:

typescript

Run It

Create src/test.ts:

typescript

Run with:

bash

Next Steps

Now that you understand the basics, here's what to explore next:

1. Advanced Agents

• Add tools to your agents
• Implement structured outputs
• Set up memory for persistence
• Use agent networks for multi-agent collaboration

2. Workflows

• Build complex multi-step processes
• Implement branching logic
• Add human-in-the-loop capabilities
• Use suspend/resume functionality

3. Production

• Set up observability and tracing
• Configure evaluations
• Deploy to Mastra Cloud
• Add authentication

4. RAG

• Index your documents
• Implement semantic search
• Add metadata filtering
• Build agentic RAG systems

Resources

• Documentation: mastra.ai/docs
• GitHub: github.com/mastra-ai/mastra
• Discord: Join the community
• YouTube: Watch tutorial videos
• Templates: Explore example projects

Common Patterns

Pattern 1: Agent with Tools

typescript

Pattern 2: Agent in Workflow

typescript

Pattern 3: Multi-Agent Network

typescript

Best Practices

1. Start Simple: Begin with basic agents, add complexity gradually
2. Use Descriptive Names: Clear names improve tool/agent selection
3. Implement Memory: Essential for conversational agents
4. Add Observability: Monitor your agents in production
5. Write Tests: Use evals to ensure quality
6. Version Control: Track prompt and agent changes

Conclusion

You now have a solid foundation in Mastra! The framework provides everything you need to build production-ready AI applications with TypeScript. Start with a simple agent, add tools and memory, then scale to workflows and multi-agent systems.

Happy building! 🚀