mastra/Guides

Guides

Step-by-step tutorials for building specific applications

guidestutorialsquickstartmulti-agent

Guides

Step-by-step tutorials for building specific applications.

Topics

Getting Started Guides

Set up Mastra with your preferred framework.

Frameworks

  • Quickstart - Get started with Mastra CLI
  • Next.js - Use Mastra in Next.js
  • React - Use Mastra in Vite + React
  • Astro - Use Mastra in Astro
  • SvelteKit - Use Mastra in SvelteKit
  • Nuxt - Use Mastra in Nuxt
  • Express - Use Mastra in Express
  • Hono - Use Mastra in Hono
  • Electron - Use Mastra in Electron

Quickstart

Get started with Mastra in 5 minutes.

Installation

npx create-mastra@latest my-app
cd my-app
npm run dev

Create an Agent

// src/agents/my-agent.ts
import { Agent } from '@mastra/core';

export const myAgent = new Agent({
  name: 'my-agent',
  instructions: 'You are a helpful assistant.',
  model: 'gpt-4',
});

Run Your Agent

const response = await myAgent.generate('Hello!');
console.log(response.text);

Next Steps

  • Add tools to your agent
  • Set up memory
  • Create a workflow
  • Deploy your application

Multi-agent Systems

Coordinate multiple agents to work together on complex tasks.

When to Use Multi-agent Systems

  • Tasks requiring different expertise
  • Complex workflows with distinct phases
  • Parallel processing of subtasks
  • Redundant processing for reliability

Patterns

Supervisor Pattern

One agent coordinates others:

const supervisor = new Agent({
  name: 'supervisor',
  instructions: 'Coordinate specialists to answer user questions',
  model: 'gpt-4',
});

supervisor.network({
  type: 'supervisor',
  agents: [researchAgent, writerAgent, editorAgent],
});

Peer Pattern

Agents collaborate as equals:

const network = new AgentNetwork({
  agents: [agent1, agent2, agent3],
  routing: 'broadcast', // or 'direct', 'consensus'
});

Hierarchical Pattern

Multiple levels of agents:

const manager = new Agent({
  name: 'manager',
  network: {
    type: 'hierarchical',
    managers: [teamLead1, teamLead2],
    workers: [worker1, worker2, worker3, worker4],
  },
});

Communication

Direct Messaging

const response = await agent1.send({
  to: agent2,
  message: 'Process this data',
});

Broadcast

await network.broadcast({
  message: 'New task available',
  from: manager,
});

Best Practices

  • Define clear responsibilities for each agent
  • Use appropriate communication patterns
  • Implement error handling and fallbacks
  • Monitor agent performance

Agent Frameworks

Integration with AI agent frameworks.

AI SDK

Use Mastra with Vercel AI SDK.

Installation

npm install ai @mastra/core

Configuration

import { Mastra } from '@mastra/core';

export const mastra = new Mastra({
  agents: {
    myAgent: {
      name: 'my-agent',
      instructions: 'You are a helpful assistant.',
      model: 'gpt-4',
    },
  },
});

AI SDK Integration

import { generateText } from 'ai';
import { mastra } from './mastra';

const result = await generateText({
  model: mastra.languageModel('gpt-4'),
  prompt: 'Hello!',
});

Streaming

import { streamText } from 'ai';

const { textStream } = await streamText({
  model: mastra.languageModel('gpt-4'),
  prompt: 'Tell me a story',
});

for await (const chunk of textStream) {
  process.stdout.write(chunk);
}

React Hooks

import { useChat } from 'ai/react';

const { messages, send } = useChat({
  api: '/api/chat',
});

Build Your UI

UI libraries for building AI interfaces.

Topics

  • AI SDK UI - Vercel AI SDK UI
  • CopilotKit - CopilotKit integration
  • Assistant UI - Assistant UI components