Mastra framework: agentic TypeScript 2027

npm install mastra @mastra/core @mastra/sdk

# Se usi pnpm
pnpm add mastra @mastra/core @mastra/sdk

# Installa tipo TypeScript
npm install --save-dev @types/node

# Se usi Ollama localmente (consigliato per privacy)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1:8b

# Se usi un LLM provider cloud (alternativa)
# (le chiavi API di provider cloud proprietari non sono supportate nel tuo setup)

# Redis per memory distribuita
REDIS_URL=redis://localhost:6379

import { Agent, OllamaProvider } from 'mastra';

// Inizializza il provider LLM (Ollama locale)
const llmProvider = new OllamaProvider({
  baseUrl: process.env.OLLAMA_BASE_URL || 'http://localhost:11434',
  model: process.env.OLLAMA_MODEL || 'llama3.1:8b',
});

// Crea un agente semplice
const assistant = new Agent({
  name: 'GeneralAssistant',
  description: 'Un assistente generico che risponde domande',
  llmProvider,
  systemPrompt: `Tu sei un assistente tecnico esperto.
Rispondi in modo preciso, conciso e utile.
Se non conosci la risposta, ammettilo.`,
});

// Usa l'agente
async function main() {
  const response = await assistant.run({
    input: 'Qual è la differenza tra agenti e chatbot?',
  });
  console.log('Risposta:', response);
}

main();

import { Agent, Memory } from 'mastra';

const assistant = new Agent({
  name: 'StatefulAssistant',
  description: 'Assistente con memoria conversazionale',
  llmProvider,
  memory: new Memory({
    type: 'redis',
    connectionUrl: process.env.REDIS_URL,
  }),
  systemPrompt: `Sei un assistente che ricorda il contesto della conversazione.
Usa la history per fornire risposte coerenti e personalizzate.`,
});

// Conversa con storia
async function conversation() {
  // Primo turno
  let resp1 = await assistant.run({
    input: 'Mi chiamo Marco e lavoro con TypeScript',
    userId: 'user-123',
  });
  console.log('Bot:', resp1.output);

  // Secondo turno — l'agente ricorda il nome
  let resp2 = await assistant.run({
    input: 'Quali framework mi consigli?',
    userId: 'user-123', // Stesso utente
  });
  console.log('Bot:', resp2.output);
  // Risponderà usando il contesto che Marco usa TypeScript
}

import { Agent, Tool } from 'mastra';

// Definisci un tool personalizzato
const weatherTool = new Tool({
  name: 'get_weather',
  description: 'Recupera la previsione meteo per una città',
  parameters: {
    city: {
      type: 'string',
      description: 'Nome della città',
    },
  },
  execute: async (params: { city: string }) => {
    // Simula una chiamata API
    return {
      city: params.city,
      temperature: 22,
      condition: 'Sereno',
      humidity: 65,
    };
  },
});

const databaseTool = new Tool({
  name: 'query_database',
  description: 'Esegui una query sul database interno',
  parameters: {
    query: {
      type: 'string',
      description: 'Query SQL',
    },
  },
  execute: async (params: { query: string }) => {
    // Connessione al DB (pseudocodice)
    const db = await connectToDatabase();
    return db.query(params.query);
  },
});

// Crea l'agente con i tool integrati
const smartAgent = new Agent({
  name: 'SmartAssistant',
  llmProvider,
  tools: [weatherTool, databaseTool],
  systemPrompt: `Usa i tool disponibili per rispondere alle domande.
Se ti chiedono il meteo, usa get_weather.
Se richiedono dati, usa query_database.`,
});

// L'agente decide autonomamente quale tool usare
async function queryWithTools() {
  const resp = await smartAgent.run({
    input: 'Com\'è il meteo a Milano?',
  });
  // Internamente: LLM decide di invocare get_weather
  console.log(resp.output);
}

import { Agent, RedisMemory, VectorStore } from 'mastra';

const agent = new Agent({
  name: 'MemoryAgent',
  llmProvider,
  memory: {
    conversational: new RedisMemory({
      url: process.env.REDIS_URL,
      ttl: 7 * 24 * 60 * 60, // 7 giorni
    }),
    semantic: new VectorStore({
      provider: 'qdrant', // o altra provider
      collection: 'agent-knowledge',
    }),
  },
  systemPrompt: `Usa la tua memoria per fornire risposte consapevoli del contesto.`,
});

// Quando esegui l'agente, automaticamente:
// 1. Recupera conversazione recente
// 2. Fa embedding della query
// 3. Cerca documenti simili nel VectorStore
// 4. Aumenta il prompt con il contesto recuperato

import { Agent, ReasoningLoop } from 'mastra';

const complexAgent = new Agent({
  name: 'ReasoningAgent',
  llmProvider,
  tools: [searchTool, calculateTool, validateTool],
  reasoning: new ReasoningLoop({
    maxIterations: 5,
    reflexionPrompt: `Rifletti su ciò che hai fatto.
Sei sulla strada giusta? Hai bisogno di un approccio diverso?`,
    stopCondition: (state) => {
      // L'agente si ferma quando ha una risposta fiduciaria
      return state.confidence > 0.85;
    },
  }),
});

async function complexTask() {
  const result = await complexAgent.run({
    input: 'Risolvi questo problema di ottimizzazione: ...',
    metadata: {
      complexity: 'high',
      iterationBudget: 5,
    },
  });
  console.log('Soluzione:', result.output);
  console.log('Iterazioni usate:', result.iterationCount);
}

import { Workflow, Agent } from 'mastra';

// Crea agenti specializzati
const dataAnalyst = new Agent({
  name: 'DataAnalyst',
  description: 'Specializzato in analisi dati',
  llmProvider,
  tools: [querySQLTool, plotGraphTool],
});

const researchAgent = new Agent({
  name: 'Researcher',
  description: 'Specializzato in ricerca e sintesi',
  llmProvider,
  tools: [searchWebTool, summarizeTool],
});

const reportWriter = new Agent({
  name: 'ReportWriter',
  description: 'Crea report formali',
  llmProvider,
  tools: [formatReportTool, exportPDFTool],
});

// Orchestra il workflow
const workflow = new Workflow({
  name: 'DataReportWorkflow',
  agents: [dataAnalyst, researchAgent, reportWriter],
  steps: [
    {
      agent: dataAnalyst,
      task: 'Analizza i dati di vendita Q1 2027',
      outputKey: 'analysis',
    },
    {
      agent: researchAgent,
      task: 'Ricerca context di mercato basato sull\'analisi precedente',
      inputKey: 'analysis',
      outputKey: 'research',
    },
    {
      agent: reportWriter,
      task: 'Scrivi un report formale usando analysis e research',
      inputKeys: ['analysis', 'research'],
      outputKey: 'finalReport',
    },
  ],
});

// Esegui il workflow
async function generateReport() {
  const result = await workflow.execute({
    input: { /* parametri iniziali */ },
  });
  console.log('Report generato:', result.finalReport);
}

version: '3.8'
services:
  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    environment:
      - OLLAMA_MODELS=/root/.ollama/models

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

  postgres:
    image: postgres:16
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: postgres
    volumes:
      - pg_data:/var/lib/postgresql/data

  mastra-app:
    build: .
    ports:
      - "3000:3000"
    environment:
      OLLAMA_BASE_URL: http://ollama:11434
      REDIS_URL: redis://redis:6379
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/mastra
    depends_on:
      - ollama
      - redis
      - postgres

volumes:
  ollama_data:
  redis_data:
  pg_data: