How to Build TypeScript Agents with Mastra Framework

What you need

Node.js 18+ and npm installed.

A Next.js or Node.js project (or start fresh).

An API key for your model provider.

Step 1: Install Mastra

Run `npm install mastra` in your project directory.

For a new project: `npx create-mastra` to scaffold a Mastra project with examples.

Set your API key as an environment variable: `OPENAI_API_KEY=sk-your-key`.

Step 2: Create your first agent

Define an agent with TypeScript types for structured outputs.

Example: `const researchAgent = new Agent({ name: 'researcher', model: openai('gpt-4'), instructions: 'You are a research specialist...' })`.

The typed output ensures your application gets predictable, validated results.

Step 3: Add MCP tools

Mastra has first-class MCP support. Import MCP tools and assign them to agents.

Tools can be web search, database queries, API calls, or any MCP-compatible service.

Each tool has typed input/output schemas for type safety.

Step 4: Add memory and context

Mastra supports persistent memory using the Mastra Memory API.

Configure memory storage: in-memory for development, Postgres or Redis for production.

Memory enables agents to maintain context across conversations and sessions.

Step 5: Deploy your agent

Mastra agents can be deployed as Next.js API routes, serverless functions, or standalone Node services.

Example Next.js route: `export async function POST(req) { const result = await agent.run(await req.json()); return Response.json(result); }`.

Monitor agent usage and performance with Mastra's built-in observability.

FAQ

Build Mastra Agents

1. Install Mastra: npm install mastra
2. Create a typed agent with instructions
3. Add MCP tools with typed schemas
4. Configure memory persistence
5. Deploy as API route or serverless function
6. Monitor with built-in observability