Mastra - TypeScript AI Agent Framework Cheatsheet
Mastra ist ein Open-Source-TypeScript-Framework für AI Agents und Workflows, gebaut vom Team hinter Gatsby. Während die meisten Agent-Frameworks Python-first sind, zielt Mastra auf das JavaScript/TypeScript-Ökosystem mit voller Type-Safety: Agents mit Tools und Memory, dauerhafte Workflows, die als Graphs ausgedrückt werden mit Branching und Suspend/Resume, RAG Primitives, built-in Evals und ein lokales Dev Playground zum Iterieren von Agents im Browser.
Installation
| Methode | Befehl |
|---|
| Create a Project | npm create mastra@latest |
| Add to Existing | npm install @mastra/core |
| Dev Server | npm run dev (Playground bei localhost:4111) |
| Model Provider | npm install @ai-sdk/openai (nutzt Vercel AI SDK) |
| Verifikation | Öffne das Playground |
Defining an Agent
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
export const supportAgent = new Agent({
name: "support",
instructions: "You are a concise support agent. Cite docs when possible.",
model: openai("gpt-4o"),
tools: { searchDocs },
});
const result = await supportAgent.generate("How do I rotate my API key?");
console.log(result.text);
| Methode | Tut |
|---|
.generate(input) | Führe einmal aus und gib das Ergebnis zurück |
.stream(input) | Streame Tokens/Steps |
tools | Typed Tools, die der Agent aufrufen kann |
memory | Persistente Konversations-Memory |
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
export const searchDocs = createTool({
id: "search-docs",
description: "Search the product documentation",
inputSchema: z.object({ query: z.string() }),
outputSchema: z.object({ results: z.array(z.string()) }),
execute: async ({ context }) => {
return { results: await search(context.query) };
},
});
Zod-Schemas geben End-to-End Type-Safety — die Tool-Calls des Agenten sind validiert und typed auf beiden Seiten.
Workflows (Durable Graphs)
import { createWorkflow, createStep } from "@mastra/core/workflows";
const fetchData = createStep({ id: "fetch", execute: async () => ({ ... }) });
const analyze = createStep({ id: "analyze", execute: async ({ inputData }) => ({ ... }) });
export const pipeline = createWorkflow({ id: "pipeline" })
.then(fetchData)
.then(analyze)
.commit();
| Feature | Zweck |
|---|
.then() | Sequenzielle Steps |
.branch() | Conditional Paths |
.parallel() | Concurrent Steps |
.dowhile() / .foreach() | Loops über Daten |
| Suspend/Resume | Pause für Human Input, später fortsetzen |
| Durable Execution | Überlebt Restarts |
Memory
| Typ | Nutze |
|---|
| Conversation History | Aktuelle Turns im Kontext |
| Semantic Recall | Vector Search über vergangene Nachrichten |
| Working Memory | Persistente Fakten über den User |
| Storage Adapters | LibSQL, Postgres, Upstash |
RAG Primitives
| Piece | Stellt zur Verfügung |
|---|
| Document Chunking | Split Docs mit konfigurierbaren Strategien |
| Embeddings | Via den AI SDK Providern |
| Vector Stores | pgvector, Pinecone, Qdrant, Chroma |
| Retrieval Tool | Wire Retrieval in einen Agent als Tool |
Evals & Observability
| Fähigkeit | Notiz |
|---|
| Built-in Evals | Answer Relevancy, Faithfulness, Toxicity, Bias |
| Custom Scorers | Definiere deine eigenen Metriken |
| Tracing | OpenTelemetry-kompatible Traces |
| Playground | Inspiziere Agent Runs, Tools und Memory lokal |
Deployment
| Ziel | Notiz |
|---|
| Node Server | mastra build erzeugt einen deploybaren Server |
| Vercel / Cloudflare / Netlify | Offizielle Deployer |
| Serverless | Workflows entworfen für stateless Hosts |
Mastra vs Andere Agent Frameworks
| Aspekt | Mastra | LangGraph | CrewAI |
|---|
| Language | TypeScript | Python | Python |
| Workflows | Durable Graph + Suspend/Resume | Stateful Graph | Role-basierte Crews |
| Type Safety | Strong (Zod End-to-End) | Python Typing | Python Typing |
| Am besten für | TS/JS Teams, Web Apps | Komplexe Stateful Agents | Multi-Agent Role Play |
Das TypeScript-Pendant zu LangGraph; vergleich mit CrewAI und AutoGen für Python.
Ressourcen
