Building an Agent with Mastra Framework: TypeScript-First Agent Development

What Is Mastra

Mastra is an open-source TypeScript framework designed specifically for building AI agents, workflows, and RAG pipelines. Unlike general-purpose libraries that bolt agent capabilities onto existing chat abstractions, Mastra treats agents as first-class primitives with built-in support for tools, memory, structured outputs, and multi-step workflows.

The framework follows a "TypeScript-first" philosophy — every component is fully typed, schemas are defined with Zod, and the developer experience prioritizes IDE autocompletion and compile-time safety.

Project Setup

Scaffold a new Mastra project using the CLI:

flowchart TD
    USER(["User message"])
    LLM["LLM call<br/>with tools schema"]
    DECIDE{"Model wants<br/>to call a tool?"}
    EXEC["Execute tool<br/>sandboxed runtime"]
    RESULT["Append tool_result<br/>to messages"]
    GUARD{"Output passes<br/>guardrails?"}
    DONE(["Final reply"])
    BLOCK(["Refuse and log"])
    USER --> LLM --> DECIDE
    DECIDE -->|Yes| EXEC --> RESULT --> LLM
    DECIDE -->|No| GUARD
    GUARD -->|Yes| DONE
    GUARD -->|No| BLOCK
    style LLM fill:#4f46e5,stroke:#4338ca,color:#fff
    style EXEC fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style GUARD fill:#f59e0b,stroke:#d97706,color:#1f2937
    style DONE fill:#059669,stroke:#047857,color:#fff
    style BLOCK fill:#dc2626,stroke:#b91c1c,color:#fff

npx create-mastra@latest my-agent-app
cd my-agent-app

The CLI prompts you for your preferred LLM provider and generates a project structure:

my-agent-app/
  src/
    mastra/
      agents/
        index.ts       # Agent definitions
      tools/
        index.ts       # Tool definitions
      index.ts         # Mastra instance
  .env
  package.json

Install dependencies and set your API key:

npm install
echo "OPENAI_API_KEY=sk-proj-your-key" > .env

Defining Tools

Tools give your agent capabilities beyond text generation. Each tool has a typed input schema, a description for the LLM, and an execute function:

// src/mastra/tools/index.ts
import { createTool } from "@mastra/core";
import { z } from "zod";

export const searchDocsTool = createTool({
  id: "search_docs",
  description: "Search the documentation for relevant articles",
  inputSchema: z.object({
    query: z.string().describe("The search query"),
    limit: z.number().default(5).describe("Max results to return"),
  }),
  outputSchema: z.object({
    results: z.array(
      z.object({
        title: z.string(),
        snippet: z.string(),
        url: z.string(),
      })
    ),
  }),
  execute: async ({ context }) => {
    const { query, limit } = context;
    const results = await searchKnowledgeBase(query, limit);
    return { results };
  },
});

export const createTicketTool = createTool({
  id: "create_support_ticket",
  description: "Create a support ticket for unresolved issues",
  inputSchema: z.object({
    title: z.string(),
    description: z.string(),
    priority: z.enum(["low", "medium", "high"]),
  }),
  execute: async ({ context }) => {
    const ticket = await ticketService.create(context);
    return { ticketId: ticket.id, status: "created" };
  },
});

The inputSchema serves dual purpose: it generates the JSON Schema sent to the LLM for function calling and it validates the arguments at runtime before execute runs.

Defining an Agent

Agents combine a model, system instructions, and tools into a coherent unit:

// src/mastra/agents/index.ts
import { Agent } from "@mastra/core";
import { searchDocsTool, createTicketTool } from "../tools";

export const supportAgent = new Agent({
  name: "Support Agent",
  instructions: `You are a customer support agent for a SaaS platform.
Your primary task is to answer user questions by searching documentation.
If you cannot resolve an issue after searching, create a support ticket.
Always be concise and reference specific documentation links.`,
  model: {
    provider: "OPEN_AI",
    name: "gpt-4o",
    toolChoice: "auto",
  },
  tools: {
    search_docs: searchDocsTool,
    create_support_ticket: createTicketTool,
  },
});

Registering with the Mastra Instance

The Mastra instance is the central registry for all agents, tools, and workflows:

// src/mastra/index.ts
import { Mastra } from "@mastra/core";
import { supportAgent } from "./agents";

export const mastra = new Mastra({
  agents: { supportAgent },
});

Running the Agent

Execute the agent programmatically or through the built-in dev server:

import { mastra } from "./mastra";

async function main() {
  const agent = mastra.getAgent("supportAgent");

  const response = await agent.generate(
    "How do I reset my password? I've tried the forgot password link but it's not sending emails."
  );

  console.log(response.text);
}

main();

For development, Mastra provides a playground:

npx mastra dev

This launches a local web interface where you can interact with your agents, inspect tool calls, and debug conversation flows.

Adding Memory

Mastra supports persistent memory so agents remember context across conversations:

import { Agent } from "@mastra/core";
import { PostgresMemory } from "@mastra/memory";

const memory = new PostgresMemory({
  connectionString: process.env.DATABASE_URL!,
});

export const supportAgent = new Agent({
  name: "Support Agent",
  instructions: "...",
  model: { provider: "OPEN_AI", name: "gpt-4o" },
  tools: { /* ... */ },
  memory,
});

With memory enabled, calling agent.generate() with a threadId parameter automatically loads and saves conversation history.

Workflows for Multi-Step Processes

For complex operations that go beyond a single agent loop, Mastra provides typed workflows:

import { Workflow, Step } from "@mastra/core";
import { z } from "zod";

const onboardingWorkflow = new Workflow({
  name: "user-onboarding",
  triggerSchema: z.object({
    userId: z.string(),
    plan: z.enum(["free", "pro", "enterprise"]),
  }),
});

onboardingWorkflow
  .step(new Step({
    id: "create-workspace",
    execute: async ({ context }) => {
      return { workspaceId: await createWorkspace(context.userId) };
    },
  }))
  .then(new Step({
    id: "send-welcome",
    execute: async ({ context }) => {
      await sendWelcomeEmail(context.userId, context.workspaceId);
      return { emailSent: true };
    },
  }));

FAQ

How does Mastra compare to LangChain.js?

Mastra is more opinionated and TypeScript-native. LangChain.js offers broader integrations and a larger community, but Mastra provides tighter type safety, a built-in dev playground, and a cleaner API surface. Mastra is a good choice if you want a batteries-included framework specifically for agent applications rather than a general-purpose LLM toolkit.

Can I use Mastra with providers other than OpenAI?

Yes. Mastra supports Anthropic, Google Gemini, and Groq out of the box. Specify the provider in the agent's model configuration. The tool calling interface remains identical regardless of the underlying model provider.

Is Mastra suitable for production deployments?

Mastra is designed for production use. It supports deployment to Vercel, Cloudflare Workers, and any Node.js server. The framework includes built-in observability hooks, error handling, and structured logging for production monitoring.

---

#Mastra #TypeScript #AIAgents #Framework #ToolCalling #AgentMemory #AgenticAI #LearnAI #AIEngineering