Building AI agents with Mastra: An implementation guide for integrating into enterprise systems in custom development

"We want to incorporate AI agents into our business systems, but we lack the budget to rewrite everything in Python"—this is a classic dilemma for enterprises running systems built on TypeScript and Node.js. Adopting the Python ecosystem centered around LangChain and LlamaIndex creates a language boundary with existing systems that drives up maintenance overhead.

Mastra tackles this problem directly. In April 2026, gihyo.jp began its serialization titled "Let's Build an AI Agent Using Mastra," causing interest in Mastra to surge across TypeScript custom development teams. In this article, we outline key implementation patterns when adopting Mastra in custom client projects.

Mastra architecture: The four pillars

Mastra's most notable characteristic is that it consolidates the following four capabilities into a single SDK:

Compared to cobbling together LangGraph, LangSmith, and LlamaIndex independently, having everything unified in a single SDK dramatically reduces the learning curve, which is an enormous advantage in custom development.

Basic patterns for custom client projects

Minimal configuration for agent definition

import { Agent } from '@mastra/core';
import { openai } from '@ai-sdk/openai';

export const supportAgent = new Agent({
  name: 'support-agent',
  instructions: `
    あなたは弊社のカスタマーサポートエージェントです。
    顧客の問い合わせを受け、CRM・配送 API を呼び出して応答します。
    破壊的操作は禁止し、必要なら人間に引き継いでください。
  `,
  model: openai('gpt-5.5'),
  tools: { lookupCustomer, checkShipping, createTicket },
  memory: new RedisMemory({ url: process.env.REDIS_URL }),
});

The key is to explicitly specify "what is permitted" and "what is forbidden" in instructions. As discussed in our guardrails article for client projects, constraints applied at the system prompt level serve as an effective baseline defense.

Modeling business processes with workflows

Business flows that cannot be handled by an agent alone are orchestrated using workflows.

import { Workflow, Step } from '@mastra/core';

export const orderCancellation = new Workflow({
  name: 'order-cancellation',
  triggerSchema: z.object({ orderId: z.string() }),
})
  .step(new Step({
    id: 'fetch',
    execute: async ({ data }) => fetchOrder(data.orderId),
  }))
  .step(new Step({
    id: 'validate',
    execute: async ({ context }) => {
      if (context.fetch.status === 'shipped') {
        throw new Error('Already shipped');
      }
    },
  }))
  .step(new Step({
    id: 'cancel',
    execute: async ({ context }) => cancelOrder(context.fetch.id),
  }))
  .step(new Step({
    id: 'notify',
    execute: async ({ context }) => notifyCustomer(context.fetch.email),
  }))
  .commit();

Because you can declaratively define retries, timeouts, and parallel execution per step, it fits naturally as a workflow definition tool for enterprise systems. Even when custom development clients ask to "implement the business flowchart exactly as drawn," the diagram maps almost 1:1 to a Mastra workflow.

Integrating into existing Node.js business systems

Mastra is designed as a pure TypeScript library that runs on Node.js 18+, allowing it to be retrofitted into existing Express, NestJS, or Fastify servers.

// Express の既存ルーターに Mastra Agent を差し込む例
app.post('/api/support/chat', async (req, res) => {
  const result = await supportAgent.generate({
    messages: req.body.messages,
    threadId: req.user.id,
  });
  res.json(result);
});

While Python-based LangChain setups typically require running FastAPI in a separate process or container and calling it via internal API, Mastra executes entirely within the same process. This is a major advantage when modernizing business systems for small and medium-sized enterprises.

Integrating RAG pipelines

RAG pipelines for ingesting internal knowledge can also be completed entirely within Mastra.

import { MastraVector } from '@mastra/core';
import { pineconeStore } from '@mastra/pinecone';

const vector = new MastraVector({
  store: pineconeStore({ apiKey: process.env.PINECONE_KEY, index: 'kb' }),
  embeddings: openai.embedding('text-embedding-3-large'),
});

await vector.upsert([
  { id: 'doc-1', text: '..., metadata: { source: 'manual.pdf' } },
]);

// Agent で参照
export const supportAgent = new Agent({
  // ...
  tools: { searchKnowledge: vector.tool('searchKnowledge') },
});

As noted in our article on multimodal embedding rerankers, a three-stage architecture of embedding, reranking, and citation has become the de facto standard for RAG. In Mastra, you can insert reranking directly as a custom tool.

Evals: The key to establishing quality assurance in custom development

When delivering AI agents in custom development projects, the greatest hurdle is "how to measure quality." Mastra's Eval feature enables automated evaluation against datasets.

import { evaluate } from '@mastra/evals';

const result = await evaluate({
  agent: supportAgent,
  dataset: './evals/support-qa.jsonl',
  metrics: ['answer-relevancy', 'faithfulness', 'context-precision'],
});

console.log(result.summary);
// { answerRelevancy: 0.87, faithfulness: 0.92, contextPrecision: 0.81 }

Integrating this into CI establishes continuous evaluation, including regression detection. Being able to guarantee an Eval score above a set threshold in client contracts provides quantitative acceptance criteria, minimizing disputes upon delivery.

Pitfalls: Issues we encountered in the field

Here are three pitfalls we ran into when adopting Mastra in production projects:

1. Forgetting to persist memory

The default memory for @mastra/core is in-memory. When deploying to production, this must be swapped for Redis, Postgres, or Firestore. Forgetting to replace the in-memory store after the PoC led to an incident where conversation histories disappeared upon server restart.

2. Uncontrolled workflow state growth

Accumulating too much state in context across workflow steps causes token consumption to balloon. Extract and pass only the necessary fields between steps using wrapper utilities from the start.

3. Dataset creation costs for evaluations

While Evals are powerful, curating evaluation datasets requires significant labor. We always include "manually labeling 200 items from historical inquiry logs" as an initial scope item in our project estimates.

Summary: A framework well worth trying first in TypeScript custom development

When adding AI agents to TypeScript-based business systems, Mastra's strength lies in consolidating everything into a single SDK. For projects at small and mid-sized enterprises where you want to avoid both migration costs to Python and the operational overhead of managing separate processes, Mastra deserves consideration as a top candidate.

We provide custom development services covering architecture design, PoC development, production builds, and evaluation infrastructure setup for business systems powered by Mastra. If you want to integrate AI into existing Node.js business systems or migrate a Python-based PoC to TypeScript, feel free to reach out via our inquiry form.

Sources

• gihyo.jp — Part 1: Let's build an AI agent using Mastra
• Mastra — Documentation
• GitHub — mastra-ai/mastra