Technical guide: architecting AI with Mastra, Next.js, and TypeScript

// src/mastra/index.tsimport { Mastra } from '@mastra/core';import { PinoLogger } from '@mastra/loggers';import { MastraCompositeStore } from '@mastra/core/storage';import { WorkflowsPG, ScoresPG, PgVector } from '@mastra/pg';import { MemoryLibSQL } from '@mastra/libsql';import { weatherAgent } from './agents/weather-agent';import { weatherWorkflow } from './workflows/weather-workflow';const storage = new MastraCompositeStore({  id: 'composite',  domains: {    memory:    new MemoryLibSQL({ url: 'file:./local.db' }),    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL! }),    scores:    new ScoresPG({ connectionString: process.env.DATABASE_URL! }),  },});export const mastra = new Mastra({  agents:    { weatherAgent },  workflows: { weatherWorkflow },  storage,  vectors:   { pg: new PgVector({ connectionString: process.env.DATABASE_URL! }) },  logger:    new PinoLogger({ name: 'Mastra', level: 'info' }),  server:    { port: 4111, host: '0.0.0.0', timeout: 30_000 },  // mcpServers, observability, scorers, processors, gateways, bundler...});

import { Agent } from '@mastra/core/agent';import { Memory } from '@mastra/memory';import { LibSQLStore } from '@mastra/libsql';import { weatherTool } from '../tools/weather';export const weatherAgent = new Agent({  id:   'weather-agent',  name: 'Weather Agent',  description: 'Responde sobre clima.',  instructions: 'Você é um assistente de clima. Use weatherTool quando preciso.',  model: 'openai/gpt-5.1',            // Mastra Model Router — "provider/model"  tools: { weatherTool },  memory: new Memory({    storage: new LibSQLStore({ url: 'file:./agent.db' }),    options: { lastMessages: 10, workingMemory: { enabled: true } },  }),});// .generate() — resposta completa, retorna { text, toolCalls, toolResults, steps, usage }const res = await weatherAgent.generate('Clima em Tóquio?', {  memory: { resource: 'user-123', thread: 'conv-42' },});// .stream() — token-a-token via MastraModelOutputconst stream = await weatherAgent.stream('Planeje meu dia');for await (const chunk of stream.textStream) process.stdout.write(chunk);

import { Memory } from '@mastra/memory';import { PgStore, PgVector } from '@mastra/pg';import { OpenAIEmbedder } from '@mastra/openai';const memoryPg = new Memory({  storage: new PgStore({ connectionString: process.env.DATABASE_URL! }),  vector:  new PgVector({ connectionString: process.env.DATABASE_URL! }),  embedder: new OpenAIEmbedder({ model: 'text-embedding-3-small' }),  options: {    lastMessages: 20,    semanticRecall: {      topK: 5,      messageRange: { before: 2, after: 1 },      scope: 'resource',      indexConfig: { type: 'hnsw', metric: 'dotproduct', m: 16, efConstruction: 64 },    },    workingMemory: {      enabled: true,      template: '# User\n- First Name:\n- Last Name:',      scope: 'resource',    },    generateTitle: true,  },});

import { createWorkflow, createStep } from '@mastra/core/workflows';import { z } from 'zod';const approvalStep = createStep({  id: 'approval',  inputSchema:   z.object({ amount: z.number(), needsApproval: z.boolean() }),  outputSchema:  z.object({ approved: z.boolean(), message: z.string() }),  suspendSchema: z.object({ reason: z.string(), amount: z.number() }),  resumeSchema:  z.object({ approved: z.boolean(), approver: z.string() }),  execute: async ({ inputData, resumeData, suspend, bail }) => {    if (!inputData.needsApproval) return { approved: true, message: 'Auto' };    if (resumeData?.approved === false) {      return bail({ approved: false, message: 'Rejected' });    }    if (resumeData?.approved === undefined) {      return await suspend({ reason: 'Human approval required', amount: inputData.amount });    }    return { approved: true, message: `Approved by ${resumeData.approver}` };  },});export const paymentWorkflow = createWorkflow({  id: 'payment-workflow',  inputSchema:  z.object({ amount: z.number(), userId: z.string() }),  outputSchema: z.object({ approved: z.boolean(), message: z.string() }),  retryConfig:  { attempts: 5, delay: 2000 },})  .then(analyzePurchase)  .then(approvalStep)  .then(executePayment)  .commit();// Suspensão transparenteconst run = await paymentWorkflow.createRunAsync();const result = await run.start({ inputData: { amount: 5000, userId: 'u1' } });if (result.status === 'suspended') {  // runId salvo em fila, notifique aprovador}// Retomada (mesmo ou outro processo, pelo runId)const resumed = await paymentWorkflow.createRunAsync({ runId });await resumed.resume({ resumeData: { approved: true, approver: 'mgr@acme' } });

export const routingAgent = new Agent({  id: 'routing-agent',  instructions: 'Rede de pesquisadores e escritores.',  model: 'openai/gpt-5.4',  agents:    { researchAgent, writingAgent },  workflows: { cityWorkflow },  tools:     { weatherTool },  memory:    new Memory({ storage: new LibSQLStore({ url: 'file:./mastra.db' }) }),});const result = await routingAgent.network('Clima em Tóquio e atividade sugerida.');for await (const chunk of result) {  if (chunk.type === 'network-execution-event-step-finish') console.log(chunk.payload.result);}

// (a) String Model Router (recomendado)model: 'openai/gpt-5.4'model: 'anthropic/claude-4-5-sonnet'model: 'google/gemini-2.5-pro'// (b) Instância SDK direta (quando precisa de tipagem rigorosa)import { openai } from '@ai-sdk/openai';model: openai('gpt-4o')// (c) Fallbacks automáticos cross-providermodel: [  { model: 'openai/gpt-5',                maxRetries: 3 },  { model: 'anthropic/claude-4-5-sonnet', maxRetries: 2 },  { model: 'google/gemini-2.5-pro',       maxRetries: 2 },]// (d) Dinâmico por requestmodel: ({ requestContext }) =>  requestContext.task === 'complex' ? 'anthropic/claude-4-5-sonnet' : 'openai/gpt-5-mini'

// Consumir MCPs externosimport { MCPClient } from '@mastra/mcp';export const mcp = new MCPClient({  id: 'main-mcp',  servers: {    filesystem: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'] },    github:     { url: new URL('https://api.githubcopilot.com/mcp/'),                  requestInit: { headers: { Authorization: `Bearer ${process.env.GH_PAT}` } } },  },});export const researchAgent = new Agent({  id: 'research', model: 'openai/gpt-4o',  tools: await mcp.getTools(),      // estático  // ou dinâmico por request: const toolsets = await mcp.listToolsets();});// Expor Mastra como MCPimport { MCPServer } from '@mastra/mcp';const server = new MCPServer({  id: 'my-mcp-server', name: 'My MCP Server', version: '1.0.0',  description: 'Expõe Mastra via MCP.',  tools:     { weatherTool },  agents:    { weatherAgent },       // gera tool ask_weatherAgent  workflows: { cityWorkflow },       // gera tool run_cityWorkflow});server.startStdio();

my-nextjs-agent/├── src/│   ├── app/│   │   ├── api/chat/route.ts        # Route Handler streaming│   │   ├── chat/page.tsx            # UI client│   │   ├── actions/weather.ts       # Server Actions│   │   └── layout.tsx│   ├── mastra/│   │   ├── index.ts                 # new Mastra({...})│   │   ├── agents/weather-agent.ts│   │   ├── tools/weather-tool.ts│   │   ├── workflows/│   │   └── memory.ts│   └── lib/schemas.ts               # Zod compartilhado├── next.config.ts                   # serverExternalPackages: ['@mastra/*']└── .env.local                       # OPENAI_API_KEY, DATABASE_URL

// next.config.tsimport type { NextConfig } from 'next';const nextConfig: NextConfig = {  serverExternalPackages: ['@mastra/*'],  // impede o bundler de empacotar binários nativos};export default nextConfig;

// src/app/actions/weather.ts'use server';import { z } from 'zod';import { mastra } from '@/mastra';import { revalidatePath } from 'next/cache';const WeatherInput = z.object({  city: z.string().min(1).max(100),  units: z.enum(['metric', 'imperial']).default('metric'),});export type WeatherState =  | { status: 'idle' }  | { status: 'success'; text: string; toolCalls: unknown[] }  | { status: 'error'; message: string; fieldErrors?: Record<string, string[]> };export async function getWeather(_prev: WeatherState, formData: FormData): Promise<WeatherState> {  const parsed = WeatherInput.safeParse({    city: formData.get('city'),    units: formData.get('units') ?? 'metric',  });  if (!parsed.success) {    return { status: 'error', message: 'Entrada inválida',             fieldErrors: parsed.error.flatten().fieldErrors };  }  try {    const result = await mastra.getAgent('weatherAgent').generate(      `Weather in ${parsed.data.city}? Units: ${parsed.data.units}.`,      { memory: { thread: 'weather-thread', resource: 'public' } },    );    revalidatePath('/weather');    return { status: 'success', text: result.text, toolCalls: result.toolCalls ?? [] };  } catch (err) {    console.error('[getWeather]', err);    return { status: 'error', message: 'Falha ao consultar o agente.' };  }}

'use client';import { useActionState } from 'react';import { getWeather, type WeatherState } from '@/app/actions/weather';export default function WeatherPage() {  const [state, formAction, pending] = useActionState(getWeather, { status: 'idle' } as WeatherState);  return (    <form action={formAction}>      <input name="city" required />      <select name="units"><option value="metric">°C</option><option value="imperial">°F</option></select>      <button disabled={pending}>{pending ? 'Consultando...' : 'Ver clima'}</button>      {state.status === 'success' && <pre>{state.text}</pre>}      {state.status === 'error' && <p>{state.message}</p>}    </form>  );}

// src/app/api/chat/route.tsimport { handleChatStream } from '@mastra/ai-sdk';import { toAISdkV5Messages } from '@mastra/ai-sdk/ui';import { createUIMessageStreamResponse } from 'ai';import { NextResponse } from 'next/server';import { mastra } from '@/mastra';export const maxDuration = 60;        // 300 default com Fluid; até 800 em Proexport const runtime = 'nodejs';      // OBRIGATÓRIO — Mastra não suporta Edgeexport async function POST(req: Request) {  const params = await req.json();  const stream = await handleChatStream({    mastra,    agentId: 'weatherAgent',    params: {      ...params,      memory: { thread: params.threadId ?? 'default', resource: params.resourceId ?? 'anon' },    },  });  return createUIMessageStreamResponse({ stream });}// Hidrata histórico no mountexport async function GET() {  const memory = await mastra.getAgentById('weatherAgent').getMemory();  const res = await memory?.recall({ threadId: 'default', resourceId: 'anon' });  return NextResponse.json(toAISdkV5Messages(res?.messages ?? []));}

export async function POST(req: Request) {  const { messages } = await req.json();  const stream = await mastra.getAgent('weatherAgent').stream(messages, {    format: 'aisdk',                  // AI SDK v5 compat    memory: { thread: 'demo', resource: 'user-1' },    abortSignal: req.signal,          // propaga cancelamento até o LLM  });  return stream.toUIMessageStreamResponse();   // ou .toDataStreamResponse() (v4), .toTextStreamResponse()}

import { MastraClient } from '@mastra/client-js';const client = new MastraClient({  baseUrl: process.env.MASTRA_API_URL ?? 'http://localhost:4111',  retries: 3, backoffMs: 300,});export async function POST(req: Request) {  const { messages } = await req.json();  const response = await client.getAgent('weatherAgent').stream({    messages, threadId: 'demo', resourceId: 'user-1',  });  return new Response(response.body, {    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache, no-transform',               'X-Accel-Buffering': 'no' },  });}

'use client';import { useEffect, useState } from 'react';import { useChat } from '@ai-sdk/react';import { DefaultChatTransport, type ToolUIPart } from 'ai';export default function ChatPage() {  const [input, setInput] = useState('');  const { messages, setMessages, sendMessage, stop, status } = useChat({    transport: new DefaultChatTransport({      api: '/api/chat',      // Com Mastra Memory: envie APENAS a última mensagem + identifiers      prepareSendMessagesRequest({ messages, body }) {        return { body: { ...body,          messages: [messages[messages.length - 1]],          threadId: 'default-thread', resourceId: 'user-1',        }};      },    }),  });  useEffect(() => {    fetch('/api/chat').then(r => r.json()).then(setMessages).catch(() => {});  }, [setMessages]);  return (    <div>      {messages.map(m => (        <div key={m.id}>          {m.parts?.map((part, i) => {            if (part.type === 'text')      return <p key={i}>{part.text}</p>;            if (part.type === 'reasoning') return <details key={i}><summary>Thinking</summary>{part.text}</details>;            if (part.type?.startsWith('tool-')) {              const p = part as ToolUIPart;              // Estados: 'input-streaming' → 'input-available' → 'output-available' | 'output-error'              switch (p.state) {                case 'input-available':  return <Skeleton key={i} />;                case 'output-available': return <ToolCard key={i} output={p.output} />;                case 'output-error':     return <ErrorCard key={i} text={p.errorText} />;              }            }            return null;          })}        </div>      ))}      <input value={input} onChange={e => setInput(e.target.value)} />      <button onClick={() => { sendMessage({ text: input }); setInput(''); }}>Send</button>      {status === 'streaming' && <button onClick={stop}>⏹ Stop</button>}    </div>  );}

// Turso (LibSQL remoto)new LibSQLStore({ url: process.env.TURSO_URL!, authToken: process.env.TURSO_TOKEN })// Postgres (Neon, Supabase, Vercel Postgres)new PostgresStore({ connectionString: process.env.DATABASE_URL! })// Upstash Redisnew UpstashStore({ url: process.env.UPSTASH_URL!, token: process.env.UPSTASH_TOKEN! })

npx mastra build --dir src/mastra    # gera .mastra/output/ (Hono bundle)node --import=./.mastra/output/instrumentation.mjs .mastra/output/index.mjs

FROM node:22-alpine AS builderWORKDIR /appCOPY package*.json ./ && RUN npm ciCOPY src ./src && COPY tsconfig.json ./RUN npx mastra buildFROM node:22-alpine AS runnerWORKDIR /appRUN addgroup -g 1001 -S nodejs && adduser -S mastra -u 1001COPY --from=builder --chown=mastra:nodejs /app/.mastra/output ./.mastra/outputUSER mastraEXPOSE 4111HEALTHCHECK --interval=30s CMD wget -qO- http://localhost:4111/api/health || exit 1CMD ["node", "--import=./.mastra/output/instrumentation.mjs", ".mastra/output/index.mjs"]

import { VercelDeployer } from '@mastra/deployer-vercel';export const mastra = new Mastra({  deployer: new VercelDeployer({ studio: true, maxDuration: 600, memory: 1536, regions: ['gru1', 'iad1'] }),});

// ❌ Quebra em GPT-5 strict modeconst bad = z.object({ details: z.string().optional() });// ✅ Corretoconst good = z.object({ details: z.string().nullable().describe('null se ausente') });

export const AgentActionSchema = z.discriminatedUnion('type', [  z.object({ type: z.literal('search'), query: z.string() }),  z.object({ type: z.literal('answer'), text: z.string(), confidence: z.number().min(0).max(1) }),  z.object({ type: z.literal('escalate'), reason: z.string(), severity: z.enum(['low','medium','high']) }),]);

import { createTool } from '@mastra/core/tools';import { z } from 'zod';export const githubRepoTool = createTool({  id: 'get-github-repo-info',  description: 'Fetch basic insights for a public GitHub repository',  inputSchema: z.object({    owner: z.string().describe('GitHub username or organization'),    repo:  z.string().describe('Repository name'),  }),  outputSchema: z.object({    stars:   z.number(),    forks:   z.number(),    issues:  z.number(),    license: z.string().nullable(),    lastPush: z.string(),    description: z.string().nullable(),  }),  execute: async ({ context, runtimeContext }) => {    //              ^ { owner: string; repo: string } inferido    const res = await fetch(`https://api.github.com/repos/${context.owner}/${context.repo}`);    if (res.status === 404) throw new Error(`Not found`);    const d = await res.json();    return {      stars: d.stargazers_count, forks: d.forks_count, issues: d.open_issues_count,      license: d.license?.name ?? null, lastPush: d.pushed_at, description: d.description,    };    // Incompatibilidade com outputSchema é erro em compile-time E runtime  },});

export type SupportCtx = { 'user-tier': 'free'|'pro'|'enterprise'; language: 'en'|'pt-BR' };execute: async ({ runtimeContext }) => {  const tier = runtimeContext.get('user-tier') as SupportCtx['user-tier'];  const limit = tier === 'enterprise' ? 100 : tier === 'pro' ? 25 : 5;  ...}

const result = await agent.generate('Who won 2012?', {  structuredOutput: {    schema: ElectionResultSchema,    errorStrategy: 'fallback',                  // 'strict' | 'warn' | 'fallback'    fallbackValue: { winner: 'Unknown', year: 0, party: 'Other' },    jsonPromptInjection: true,                  // obrigatório: Gemini 2.5 + tools  },});result.object.winner;  // string, totalmente tipado

const stream = await agent.stream('...', { structuredOutput: { schema } });for await (const partial of stream.objectStream) {  // DeepPartial<T> — campos chegando incrementalmente}const final = await stream.object;   // T validado

import { generateText, Output, tool, stepCountIs } from 'ai';const { output } = await generateText({  model: 'openai/gpt-5.2',  tools: { weather: tool({ inputSchema: z.object({ location: z.string() }), execute: async () => ({...}) }) },  output: Output.object({ schema: RecipeSchema }),  stopWhen: stepCountIs(5),  prompt: '...',});

import { AI_NoObjectGeneratedError } from 'ai';try { const { object } = await generateObject({ ... }); return object; }catch (err) {  if (AI_NoObjectGeneratedError.isInstance(err)) console.error('No object', err.text, err.cause);  if (err instanceof z.ZodError) console.error('Zod failed', err.issues);  throw err;}

const scrapeStep = createStep({  id: 'scrape',  inputSchema:  z.object({ url: z.string().url() }),  outputSchema: z.object({ url: z.string().url(), markdown: z.string() }),  execute: async ({ inputData }) => ({ url: inputData.url, markdown: await fetch(inputData.url).then(r=>r.text()) }),});const summarizeStep = createStep({  id: 'summarize',  inputSchema: scrapeStep.outputSchema,  outputSchema: z.object({ library: z.string(), latestVersion: z.string(), breakingChanges: z.array(z.string()) }),  execute: async ({ inputData, mastra }) => {    const res = await mastra.getAgent('summarizer').generate(inputData.markdown, {      structuredOutput: { schema: z.object({ library: z.string(), latestVersion: z.string(), breakingChanges: z.array(z.string()) }) },    });    return res.object;  },});export const changelogWorkflow = createWorkflow({  id: 'changelog', inputSchema: z.object({ url: z.string().url() }), outputSchema: summarizeStep.outputSchema,}).then(scrapeStep).then(summarizeStep).commit();

const workflow = createWorkflow({  id: 'tiered', inputSchema, outputSchema,  requestContextSchema: z.object({ userTier: z.enum(['free','pro','enterprise']), locale: z.string() }),});

// Implícito — o agent loop já implementa ReActexport const researchAgent = new Agent({  instructions: `Follow ReAct loop: THOUGHT → ACTION (call one tool) → OBSERVATION.                 Repeat until confident. Never invent facts.`,  model: 'openai/gpt-4o',  tools: { searchDocsTool },});await researchAgent.generate('Qual a diferença entre suspend() e bail()?', { maxSteps: 8 });

export const ReActStepSchema = z.object({  thought: z.string().describe('Reasoning about next step'),  action: z.discriminatedUnion('type', [    z.object({ type: z.literal('tool_call'), toolName: z.string(), args: z.record(z.string(), z.unknown()) }),    z.object({ type: z.literal('final_answer'), answer: z.string(), confidence: z.number().min(0).max(1) }),  ]),});

const plannerAgent = new Agent({  id: 'planner', instructions: 'Break goal into 3-7 concrete, tool-executable steps.',  model: 'anthropic/claude-sonnet-4',});const executorAgent = new Agent({  id: 'executor', instructions: 'Execute a single plan step. Use tools. Return terse result.',  model: 'openai/gpt-4o-mini', tools: { /* ... */ },});const planStep = createStep({  id: 'plan', inputSchema: z.object({ goal: z.string() }),  outputSchema: z.object({ goal: z.string(), plan: z.array(z.object({    id: z.string(), description: z.string(), dependsOn: z.array(z.string()).default([]),  })) }),  execute: async ({ inputData, mastra }) => {    const res = await mastra.getAgent('plannerAgent').generate(`Goal: ${inputData.goal}`, {      output: z.object({ plan: z.array(/* ... */) }),    });    return { goal: inputData.goal, plan: res.object.plan };  },});export const planAndExecuteWorkflow = createWorkflow({  id: 'plan-exec', inputSchema: z.object({ goal: z.string() }), outputSchema: z.object({ results: z.array(z.any()) }),})  .then(planStep)  .map(async ({ inputData }) => inputData.plan)  .foreach(executeStep, { concurrency: 3 })  .commit();

workflow  .then(generateDraft)  .dowhile(    createStep({      id: 'eval-refine',      execute: async ({ inputData, state }) => {        const scorer = createAnswerRelevancyScorer({ model: 'openai/gpt-4o-mini' });        const { score } = await scorer.run({ input: state.prompt, output: inputData.draft });        if (score >= 0.85) return { ...inputData, done: true, score };        const refined = await refinerAgent.generate(/* with feedback */);        return { ...inputData, draft: refined.text, done: false, score };      },    }),    async ({ inputData }) => !inputData.done,  )  .commit();

export const githubIssueTool = createTool({  id: 'github-create-issue',  inputSchema: z.object({    repo: z.string().regex(/^[\w-]+\/[\w-]+$/),    title: z.string().min(1).max(256),    body: z.string().max(65_536).optional(),    labels: z.array(z.string()).max(100).default([]),  }),  outputSchema: z.object({ number: z.number(), url: z.string().url() }),  execute: async ({ context, tracingContext }) => {    const span = tracingContext?.currentSpan?.startSpan('github.api.call');    try {      const res = await fetch(`https://api.github.com/repos/${context.repo}/issues`, {        method: 'POST',        headers: { Authorization: `Bearer ${process.env.GITHUB_TOKEN}`, 'Content-Type': 'application/json' },        body: JSON.stringify({ title: context.title, body: context.body, labels: context.labels }),        signal: AbortSignal.timeout(10_000),      });      if (!res.ok) throw new Error(`GitHub ${res.status}: ${await res.text()}`);      const data = await res.json();      return { number: data.number, url: data.html_url };    } finally { span?.end(); }  },});

export const getUserTool = createTool({  id: 'get-user', inputSchema: z.object({ userId: z.string().uuid() }),  outputSchema: z.object({ id: z.string(), email: z.string(), plan: z.enum(['free','pro','enterprise']) }).nullable(),  execute: async ({ context }) => {    const db = drizzle(process.env.DATABASE_URL!);    const [row] = await db.select().from(users).where(eq(users.id, context.userId)).limit(1);    return row ?? null;  },});

// Padrão "return estruturado" — melhor para o loop ReActoutputSchema: z.union([  z.object({ success: z.literal(true),  data: z.object({ /* ... */ }) }),  z.object({ success: z.literal(false), error: z.object({ code: z.string(), message: z.string() }) }),]),

import { PinoLogger } from '@mastra/loggers';export const mastra = new Mastra({  logger: new PinoLogger({    name: 'Mastra', level: process.env.LOG_LEVEL ?? 'info',    mixin() { return { traceId: getCurrentTraceId(), service: 'ai-api', env: process.env.NODE_ENV }; },  }),});

import { DefaultExporter } from '@mastra/observability';import { LangfuseExporter } from '@mastra/langfuse';export const mastra = new Mastra({  observability: {    default: { enabled: true },    configs: {      langfuse: {        serviceName: 'prod-agents',        exporters: [new LangfuseExporter({          publicKey: process.env.LANGFUSE_PUBLIC_KEY!, secretKey: process.env.LANGFUSE_SECRET_KEY!,          baseUrl: process.env.LANGFUSE_BASE_URL,        })],        sampling: { type: 'ratio', probability: 0.1 },   // 10% em prod      },      debug: { exporters: [new DefaultExporter()], sampling: { type: 'always' } },    },    configSelector: (ctx) => ctx.runtimeContext?.get('supportMode') ? 'debug' : 'langfuse',  },});

import { createAnswerRelevancyScorer, createToxicityScorer, createHallucinationScorer } from '@mastra/evals/scorers/llm';export const supportAgent = new Agent({  id: 'support', model: 'openai/gpt-4o',  scorers: {    relevancy:     { scorer: createAnswerRelevancyScorer({ model: 'openai/gpt-4o-mini' }), sampling: { type: 'ratio', rate: 0.2 } },    hallucination: { scorer: createHallucinationScorer({ model: 'openai/gpt-4o-mini' }),   sampling: { type: 'ratio', rate: 1.0 } },    toxicity:      { scorer: createToxicityScorer({ model: 'openai/gpt-4o-mini' }),        sampling: { type: 'ratio', rate: 1.0 } },  },});

import { runEvals } from '@mastra/core/evals';describe('Support Agent', () => {  it('meets quality thresholds', async () => {    const result = await runEvals({      target: supportAgent,      data: [{ input: 'How to cancel?', groundTruth: 'cancellation policy' }],      scorers: [relevancyScorer, hasSourcesScorer],      concurrency: 3,    });    expect(result.scores['answer-relevancy']).toBeGreaterThanOrEqual(0.8);  });});

┌──────────────────────────────────────────────────────────────┐│  Next.js App Router (Node runtime)                           ││  ├─ Route Handlers (streaming, useChat)                      ││  └─ Server Actions (síncrono, forms)                         │├──────────────────────────────────────────────────────────────┤│  Mastra (embedded ou standalone)                             ││  ├─ Agents (ReAct implícito) + agent.network()               ││  ├─ Workflows (.then/.parallel/.branch/.foreach/.dountil)    ││  ├─ Tools (createTool + Zod) + MCP (client + server)         ││  └─ Memory (threads/resources, semanticRecall, workingMemory)│├──────────────────────────────────────────────────────────────┤│  Storage: MastraCompositeStore                               ││  ├─ memory: LibSQL (dev) / Postgres (prod)                   ││  ├─ workflows: Postgres (snapshots persistentes)             ││  ├─ scores: Postgres                                         ││  └─ vectors: pgvector / Pinecone / Upstash                   │├──────────────────────────────────────────────────────────────┤│  LLM: Vercel AI SDK v5/v6                                    ││  ├─ openai/gpt-5.x, anthropic/claude-4-5-sonnet,             ││  │  google/gemini-2.5-pro                                    ││  └─ Fallbacks automáticos cross-provider                     │├──────────────────────────────────────────────────────────────┤│  Observabilidade                                             ││  ├─ PinoLogger (structured)                                  ││  ├─ OTel tracing → Langfuse/Braintrust/SigNoz                ││  └─ Scorers async (relevancy, hallucination, toxicity)       │├──────────────────────────────────────────────────────────────┤│  Deploy                                                      ││  ├─ Vercel (Fluid Compute, maxDuration: 800s Pro)            ││  ├─ VPS (mastra build → node + PM2)                          ││  └─ Docker (multi-stage, Alpine, healthcheck)                │└──────────────────────────────────────────────────────────────┘