Mastra - Estrutura de Agente IA TypeScript

Mastra - Estrutura de Agente IA TypeScript

Mastra é uma estrutura open-source TypeScript para agentes e workflows de IA, construída pela equipe por trás do Gatsby. Onde a maioria das estruturas de agente são Python-first, Mastra visa o ecossistema JavaScript/TypeScript com segurança de tipo completa: agentes tipados com ferramentas e memória, workflows duráveis expressos como gráficos com ramificação e suspend/resume, primitivos RAG, evals integrados, e um playground de dev local para iterar em agentes no navegador.

Instalação

Método	Comando
Criar um projeto	npm create mastra@latest
Adicionar ao existente	npm install @mastra/core
Dev server	npm run dev (playground em localhost:4111)
Provedor de modelo	npm install @ai-sdk/openai (usa Vercel AI SDK)
Verificar	abra o playground

Definindo um Agente

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);

Método	Faz
.generate(input)	Executar uma vez e retornar o resultado
.stream(input)	Stream de tokens/passos
tools	Ferramentas tipadas que o agente pode chamar
memory	Memória de conversa persistente

Ferramentas

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) };
  },
});

Esquemas Zod dão segurança de tipo end-to-end — as chamadas de ferramenta do agente são validadas e tipadas em ambos os lados.

Workflows (Gráficos Duráveis)

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();

Característica	Propósito
.then()	Passos sequenciais
.branch()	Caminhos condicionais
.parallel()	Passos concorrentes
.dowhile() / .foreach()	Loops sobre dados
Suspend/resume	Pausar para entrada humana, retomar depois
Execução durável	Sobrevive a reinicializações

Memória

Tipo	Uso
Histórico de conversa	Turnos recentes em contexto
Recall semântico	Busca de vetor sobre mensagens passadas
Memória de trabalho	Fatos persistentes sobre o usuário
Adaptadores de storage	LibSQL, Postgres, Upstash

Primitivos RAG

Peça	Fornece
Chunking de documento	Divide docs com estratégias configuráveis
Embeddings	Via provedores de AI SDK
Vector stores	pgvector, Pinecone, Qdrant, Chroma
Ferramenta de recuperação	Wire recuperação em um agente como ferramenta

Evals e Observabilidade

Capacidade	Nota
Evals integrados	Relevância de resposta, fidelidade, toxicidade, viés
Scorers customizados	Defina suas próprias métricas
Tracing	Traces compatíveis com OpenTelemetry
Playground	Inspecionar runs de agente, ferramentas, e memória localmente

Deployment

Alvo	Nota
Node server	mastra build produz um servidor deployável
Vercel / Cloudflare / Netlify	Deployers oficiais
Serverless	Workflows projetados para hosts stateless

Mastra vs Outros Frameworks de Agente

Aspecto	Mastra	LangGraph	CrewAI
Linguagem	TypeScript	Python	Python
Workflows	Gráfico durável + suspend/resume	Gráfico stateful	Equipes baseadas em papel
Segurança de tipo	Forte (Zod end-to-end)	Tipagem Python	Tipagem Python
Melhor para	Times TS/JS, apps web	Agentes stateful complexos	Roleplay multi-agente

O contraparte TypeScript para LangGraph; compare com CrewAI e AutoGen para Python.

Recursos

• Official Website
• GitHub Repository
• Documentation