Preparación del Entorno

Para comenzar con Mastra, asegúrate de tener instalado Node.js versión 20.0 o superior, un gestor de paquetes como npm o pnpm, y una clave API de un proveedor de modelos de lenguaje (por ejemplo, OpenAI, Anthropic o Google Gemini).

Crear un Proyecto

Usa el CLI oficial de Mastra para inicializar un nuevo proyecto:

npx create-mastra@latest mi-agente-ia

Una vez creado, navega al directorio del proyecto e instala las dependencias:

cd mi-agente-ia
npm install

Configuración de Variables de Entorno

Crea un archivo .env y agrega tus claves API:

OPENAI_API_KEY=tu_clave_openai
ANTHROPIC_API_KEY=tu_clave_anthropic
GOOGLE_GENERATIVE_AI_API_KEY=tu_clave_google

Creación de un Agente de IA

Definimos un agente especializado en animales felinos. Este agente usará un modelo de lenguaje grande para responder preguntas sobre especies felinas.

Definición del Agente

// src/mastra/agents/felineExpert.ts
import { openai } from '@ai-sdk/openai';
import { Agent } from '@mastra/core';
import { z } from 'zod';

const felineSchema = z.object({
 name: z.string(),
 scientificName: z.string(),
 habitat: z.string(),
 status: z.string()
});

export const felineExpert = new Agent({
 name: 'feline-expert',
 instructions: 'Eres un experto en animales felinos con conocimiento sobre su biología, hábitat y estado de conservación.',
 model: openai('gpt-4o'),
 output: felineSchema
});

Ejecutar el Agente

Desde el archivo principal, invocamos al agente para obtener información:

// src/index.ts
import { felineExpert } from './mastra/agents/felineExpert';
import { felineSchema } from './mastra/agents/felineExpert';

const main = async () => {
 try {
   const result = await felineExpert.generate('¿Cuál es el felino más en peligro de extinción?', {
     output: felineSchema
   });

   if (result?.object) {
     const data = felineSchema.parse(result.object);
     console.log('🐾 Información del felino:');
     console.log(`Nombre: ${data.name}`);
     console.log(`Nombre científico: ${data.scientificName}`);
     console.log(`Hábitat: ${data.habitat}`);
     console.log(`Estado: ${data.status}`);
   }
 } catch (error) {
   console.error('❌ Error:', error);
 }
};

main();

Configuración Principal de Mastra

Configuramos el núcleo del framework para registrar agentes y establecer opciones de registro y memoria:

// src/mastra/index.ts
import { Mastra } from '@mastra/core';
import { PinoLogger } from '@mastra/loggers';
import { felineExpert } from './agents/felineExpert';

export const mastra = new Mastra({
 agents: { 'feline-expert': felineExpert },
 logger: new PinoLogger({ name: 'Feline-App', level: 'info' }),
 memory: { type: 'in-memory' }
});

Flujos de Trabajo Autoamtizados

Los flujos de trabajo permiten encadenar acciones para automatizar tareas complejas. Aquí creamos un flujo básico de investigación:

// src/mastra/workflows/research.ts
import { Workflow } from '@mastra/core';
import { z } from 'zod';

const inputSchema = z.object({
 topic: z.string(),
 level: z.enum(['básico', 'detallado', 'completo']).default('básico')
});

export const researchWorkflow = new Workflow({
 name: 'research-flow',
 input: inputSchema,
 steps: [
   {
     id: 'gather',
     action: async (ctx) => {
       const { topic, level } = ctx.input;
       return { info: `Datos sobre ${topic} al nivel ${level}` };
     }
   },
   {
     id: 'analyze',
     action: async (ctx) => {
       const { info } = ctx.previousStepResult;
       return { summary: `Resumen de datos: ${info}` };
     }
   }
 ]
});

Estructura del Proyecto

La estructura del proyecto sigue un patrón claro:

src/
├── index.ts
├── mastra/
│   ├── index.ts
│   ├── agents/
│   ├── workflows/
├── types/
├── utils/

Pruebas y Despliegue

Ejecuta el proyecto en modo desarrollo:

npm run dev

Para producción:

npm run build
npm start

Optimización de Rendimiento

Configura opciones avanzadas para mejorar el rendimiento:

new Agent({
 model: openai('gpt-4o', { temperature: 0.7, maxTokens: 1000 }),
 stream: true,
 cache: { enabled: true, ttl: 3600 }
});

Funcionalidades Avanzadas

Integra herramientas personalizadas, como un sistema de búsqueda de clima:

import { Tool } from '@mastra/core';
import { z } from 'zod';

export const weatherTool = new Tool({
 name: 'get-weather',
 description: 'Obtiene información del clima en una ciudad',
 input: z.object({ city: z.string(), unit: z.enum(['celsius', 'fahrenheit']) }),
 execute: async ({ city, unit }) => {
   const res = await fetch(`https://api.weatherapi.com/...?q=${city}`);
   const data = await res.json();
   return { temp: data.current.temp_c, condition: data.current.condition.text };
 }
});