Mastra Agent Builder

Scaffold and ship production agents in TypeScript with Mastra, the open-source agent framework that runs on Node and edge runtimes. This skill knows Mastra's primitives end to end — Agent, typed tools, durable workflows, memory, and RAG — so you can go from an empty repo to a deployable agent without reverse-engineering the docs. It's aimed at developers who want a single typed codebase rather than a pile of orchestration glue.

When to use it

• Standing up a new agent project (npm create mastra@latest) and wiring models, tools, and memory.
• Converting a one-shot LLM call into a multi-step workflow with branching, retries, and human-in-the-loop pauses.
• Adding semantic recall or working memory so an agent remembers across threads.
• Building a RAG pipeline: chunk, embed, store in a vector DB, and query with relevance.
• Defining strongly-typed tools the model can call, validated with Zod.

How it works

Agents are created with new Agent({ name, instructions, model, tools, memory }). Models are routed through the Vercel AI SDK, so you pass providers like openai('gpt-4o') or anthropic('claude-3-5-sonnet') directly.

Tools use createTool({ id, description, inputSchema, outputSchema, execute }) where the schemas are Zod objects — the model only sees validated input/output.

Durable control flow uses createWorkflow(...) composed from createStep(...), chained with .then(), .branch(), .parallel(), .dountil() / .dowhile(), .foreach(), and .map(), finalized with .commit(). Steps can call suspend() and later resume() for approval gates or external events.

Memory (new Memory(...)) provides working memory, semantic recall over threads/resources, and pluggable storage. RAG combines chunkers, embeddings, and a vector store such as PgVector or PineconeStore, queried via a vector-query tool.

Example

curl -fsSL --create-dirs -o ~/.claude/skills/mastra-typescript-agents/SKILL.md https://claudeskil.com/skills/mastra-typescript-agents/SKILL.md
npm create mastra@latest

import { Agent } from '@mastra/core/agent';
import { createTool } from '@mastra/core/tools';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const weather = createTool({
  id: 'get-weather',
  description: 'Current weather for a city',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ tempC: z.number() }),
  execute: async ({ context }) => fetchWeather(context.city),
});

export const agent = new Agent({
  name: 'concierge',
  instructions: 'Help users plan trips.',
  model: openai('gpt-4o'),
  tools: { weather },
});

Run mastra dev for the local playground at localhost:4111.

Tips & gotchas

• Workflow input/output schemas must line up between chained steps, or .then() won't type-check. Use .map() to reshape between mismatched steps.
• Suspended workflows need persistent storage (e.g. @mastra/libsql or PgStore) — in-memory state is lost on restart.
• Semantic recall requires a vector store and an embedder configured on Memory; setting one without the other silently disables recall.
• For edge deploys, prefer LibSQL/Turso or HTTP-based stores; native Postgres drivers may not run in some serverless runtimes.

FAQ

Can I use Claude or Gemini instead of OpenAI? Yes — any Vercel AI SDK provider works. Swap openai(...) for anthropic(...) or google(...).

Workflows vs. just letting the agent call tools? Use agents for open-ended reasoning; use workflows when you need deterministic ordering, branching, parallelism, or audited human approval.

How do I expose an agent over HTTP? mastra dev/mastra build generate a server with REST routes per agent and workflow; deploy the output to Node or an edge platform.