Crea un agente en TypeScript con Mastra para soporte técnico

Crea tu primer agente en TypeScript con Mastra

Tiempo estimado de lectura: 6 min

Crear tu primer agente en TypeScript con Mastra es la forma más práctica de evitar la fragmentación entre Node.js y microservicios Python. Si tu stack es TypeScript, mantener todo en el mismo lenguaje reduce latencia, elimina fricciones en despliegue y preserva tipos end-to-end. En las siguientes secciones veremos qué es Mastra, su arquitectura y un ejemplo práctico listo para ejecutar.

Resumen rápido (lectores con prisa)

Crea tu primer agente en TypeScript con Mastra: por qué importa y cuándo usarlo

Mastra es un framework nativo en TypeScript para construir agentes y flujos de IA. Su ventaja principal no es solo técnica: es contractual. Al integrar Zod para la validación de esquemas como parte del runtime, convierte las llamadas del LLM en contratos verificables, no en texto libre que “parece correcto”. Documentación: mastra.ai/docs. Repositorio: github.com/mastra-ai/mastra.

Úsalo cuando quieras:

No es la solución si necesitas capacidades avanzadas aún no soportadas por Mastra; evalúa la madurez del proyecto antes de producción.

Arquitectura mínima: Agent, Tool y Model

Divide responsabilidades desde el inicio:

Esa separación permite testing unitario de herramientas y garantiza que la lógica de negocio no quede oculta en un prompt.

Paso a paso: ejemplo práctico (Agente de soporte técnico)

Instalación rápida

mkdir mastra-agent && cd mastra-agent
npm init -y
npm install @mastra/core zod
npm install -D typescript @types/node tsx
npx tsc --init
export OPENAI_API_KEY="tu_api_key"

1) Define la herramienta (Tool)

Controla exactamente qué parámetros acepta el LLM:

// src/tools/check-service.ts
import { createTool } from '@mastra/core';
import { z } from 'zod';

export const checkServiceTool = createTool({
  id: 'check-service-status',
  description: 'Consulta el estado operativo de un servicio interno por nombre.',
  inputSchema: z.object({
    service: z.enum(['api', 'database', 'frontend']),
  }),
  execute: async ({ context }) => {
    // Reemplaza por consultas reales a monitorización/DB
    const statuses = { api: 'degraded', database: 'operational', frontend: 'operational' };
    return { service: context.service, status: statuses[context.service], checkedAt: new Date().toISOString() };
  },
});

2) Instancia el agente

Define instrucciones claras (system prompt) que actúen como contrato operativo:

// src/agent.ts
import { Agent } from '@mastra/core/agent';
import { checkServiceTool } from './tools/check-service';

export const supportAgent = new Agent({
  name: 'TechSupportAgent',
  instructions: `
    Eres un ingeniero de soporte de nivel 1.
    Antes de concluir que un servicio está caído, INVÓCAME la herramienta de estado.
    Responde con datos y recomendaciones técnicas claras.
  `,
  model: { provider: 'OPENAI', name: 'gpt-4o-mini' },
  tools: { checkServiceTool },
});

3) Ejecuta el flujo

Ejecuta el agente y deja que Mastra coordine modelo y tools:

// src/main.ts
import { supportAgent } from './agent';

async function main() {
  const prompt = 'Los usuarios reportan lentitud. ¿Está la API bien?';
  const res = await supportAgent.generate(prompt);
  console.log(res.text);
}

main().catch(console.error);

Lanza con npx tsx src/main.ts. Mastra coordina al LLM y las herramientas: si el modelo decide invocar checkServiceTool, el framework valida el input con Zod, ejecuta la función y alimenta la respuesta final.

Reglas prácticas para llevar esto a producción

1. Observabilidad desde el día 0: logs estructurados en cada invocación de tool (request id, input validado, tiempo, resultado).

2. Errores como datos: las herramientas deben devolver errores tipados que el agente pueda razonar y comunicar (no lanzar excepciones sin contexto).

3. Testing aislado: tests unitarios para execute y tests de integración para la orquestación. No confundas velocidad con cobertura.

4. CI/CD: bloquea merges que introduzcan nuevas dependencias sin revisión de licencia/reputación. En entornos corporativos, valida paquetes recomendados por LLMs.

5. Ownership y ADRs: cualquier herramienta crítica debe tener un Architecture Decision Record que explique por qué existe y cómo se prueba.

Para guiar verificaciones de seguridad y dependencia sigue prácticas de NIST/OWASP (por ejemplo: owasp.org).

Conclusión: Mantén el criterio humano donde importa

Mastra te da la ergonomía de TypeScript y contratos verificables con Zod. Eso reduce alucinaciones estructurales y acelera integración en stacks web. Pero la ganancia real viene cuando aplicas disciplina: diseño previo, validación estricta, observabilidad y pruebas. Implementa el agente, mide cómo toma decisiones y exige que cualquier acción en producción esté documentada y testeada. En la próxima entrega de Dominicode mostraremos cómo añadir memoria persistente y encadenar múltiples tools para workflows complejos.

Dominicode Labs

Si trabajas en automatización, agentes o workflows y quieres ejemplos prácticos y guías operativas, consulta Dominicode Labs. Encontrarás recursos que complementan patrones de diseño y pruebas para agentes en producción.

FAQ