---
name: mastra-typescript-agents
description: "Build production TypeScript agents with Mastra — agents, tools, workflows, RAG, and memory on Node and edge. Production Mastra: define Agents with model routing via the Vercel AI SDK, typed tools with createTool and Zod schemas, and durable control flow using createWorkflow with .then/.branch/.parallel/.dotWhile and suspend/resume. Covers Memory (working memory, semantic recall, threads/resources), RAG pipelines with chunkers, embeddings and pgvector/Pinecone vector stores, agent networks and the .stream/.generate APIs, plus evals, OpenTelemetry tracing, and deployment to Node, Vercel, and Cloudflare Workers."
license: MIT
---

# Mastra Agent Builder

Scaffold and ship production agents in TypeScript with [Mastra](https://mastra.ai), 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

```bash
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
```

```ts
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.