Mastra — TypeScript AI Agent Framework

What it is

Mastra is an open-source TypeScript framework for building AI agents. It provides a unified API for creating agents with tool use, retrieval-augmented generation (RAG), multi-step workflows, and integrations with third-party services. Unlike Python-centric agent frameworks, Mastra is designed from the ground up for the TypeScript/Node.js ecosystem.

The framework targets full-stack TypeScript developers who want to build AI-powered applications without switching to Python. It includes a CLI for project scaffolding (npx create-mastra@latest), a local development server, and built-in support for popular LLM providers (OpenAI, Anthropic, Google).

How it saves time or tokens

Mastra reduces the integration burden of building AI agents. Instead of wiring together separate libraries for LLM calls, vector search, tool execution, and workflow orchestration, Mastra provides all of these as first-class features in a single package. This eliminates dependency management overhead and ensures components work together without compatibility issues.

The built-in RAG support is particularly valuable. Mastra handles document chunking, embedding generation, vector storage, and retrieval within the same framework, so you do not need to set up a separate vector database pipeline. This saves both development time and the tokens that would be wasted on hallucinated answers without proper context retrieval.

How to use

1. Create a new Mastra project:

```bash

npx create-mastra@latest my-agent

cd my-agent

npm run dev

```

1. Or add to an existing project:

```bash

npm install mastra @mastra/core

```

1. Define an agent with tools and start using it.

Example

A Mastra agent with a custom tool:

import { Agent, createTool } from '@mastra/core';
import { z } from 'zod';

const weatherTool = createTool({
  id: 'get-weather',
  description: 'Get current weather for a city',
  inputSchema: z.object({
    city: z.string().describe('City name'),
  }),
  execute: async ({ context }) => {
    const resp = await fetch(
      `https://wttr.in/${context.city}?format=j1`
    );
    const data = await resp.json();
    return { temp: data.current_condition[0].temp_C };
  },
});

const agent = new Agent({
  name: 'WeatherBot',
  instructions: 'Help users check weather conditions.',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-20250514' },
  tools: { 'get-weather': weatherTool },
});

const response = await agent.generate(
  'What is the weather in Tokyo?'
);
console.log(response.text);

Mastra core features:

Related on TokRepo

• AI Tools for Agents — Compare Mastra with other agent development frameworks.
• AI Tools for Coding — Browse coding tools in the TypeScript ecosystem.

Common pitfalls

• Expecting full parity with Python agent frameworks. Mastra is TypeScript-native, which means some Python-only libraries (LangChain integrations, certain vector stores) are not directly available. Check Mastra's integration list before assuming a specific service is supported.
• Not using Zod schemas for tool inputs. Mastra uses Zod for type-safe tool parameter validation. Defining tools without proper schemas leads to runtime errors when the LLM passes unexpected parameter types.
• Running the dev server in production. The npm run dev command starts a local development server with hot reloading and debugging features. For production, build the project and run the compiled output, or deploy to a serverless platform.