Full-Stack Integration

Initialize Assistant UI

Start by setting up Assistant UI in your project. Run one of the following commands:

npx assistant-ui@latest create

npx assistant-ui@latest init

This command installs necessary dependencies and creates basic configuration files, including a default chat API route.

Review Initial API Route

The initialization command creates a basic API route at app/api/chat/route.ts (or src/app/api/chat/route.ts). It typically looks like this:

import { openai } from "@ai-sdk/openai";
import { streamText } from "ai";
 
// Allow streaming responses up to 30 seconds
export const maxDuration = 30;
 
export async function POST(req: Request) {
  const { messages } = await req.json();
 
  const result = streamText({
    model: openai("gpt-4o-mini"),
    messages,
  });
 
  return result.toDataStreamResponse();
}

This default route uses the Vercel AI SDK directly with OpenAI. In the following steps, we will modify this route to integrate Mastra.

Install Mastra Packages

Add the Mastra core, memory, the AI SDK OpenAI provider packages to your project:

npm install @mastra/core@latest @mastra/memory@latest @ai-sdk/openai

Configure Next.js

To ensure Next.js correctly bundles your application when using Mastra directly in API routes, you need to configure serverExternalPackages.

Update your next.config.mjs (or next.config.js) file to include @mastra/*:

/** @type {import('next').NextConfig} */
const nextConfig = {
  serverExternalPackages: ["@mastra/*"],
  // ... other configurations
};
 
export default nextConfig;

This tells Next.js to treat Mastra packages as external dependencies on the server-side.

Create Mastra Files

Set up the basic folder structure for your Mastra configuration. Create a mastra folder (e.g., in your src or root directory) with the following structure:

/
├── mastra/
│   ├── agents/
│   │   └── chefAgent.ts
│   └── index.ts
└── ... (rest of your project)

You can create these files and folders manually or use the following commands in your terminal:

mkdir -p mastra/agents
touch mastra/index.ts mastra/agents/chefAgent.ts

These files will be used in the next steps to define your Mastra agent and configuration.

Define the Agent

Now, let's define the behavior of our AI agent. Open the mastra/agents/chefAgent.ts file and add the following code:

import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
 
export const chefAgent = new Agent({
  name: "chef-agent",
  instructions:
    "You are Michel, a practical and experienced home chef. " +
    "You help people cook with whatever ingredients they have available.",
  model: openai("gpt-4o-mini"),
});

This code creates a new Mastra Agent named chef-agent.

• instructions: Defines the agent's persona and primary goal.
• model: Specifies the language model the agent will use (in this case, OpenAI's GPT-4o Mini via the AI SDK).

Make sure you have set up your OpenAI API key as described in the Getting Started guide.

Register the Agent

Next, register the agent with your Mastra instance. Open the mastra/index.ts file and add the following code:

import { Mastra } from "@mastra/core";
 
import { chefAgent } from "./agents/chefAgent";
 
export const mastra = new Mastra({
  agents: { chefAgent },
});

This code initializes Mastra and makes the chefAgent available for use in your application's API routes.

Modify the API Route

Now, update your API route (app/api/chat/route.ts) to use the Mastra agent you just configured. Replace the existing content with the following:

import { mastra } from "@/mastra"; // Adjust the import path if necessary
 
// Allow streaming responses up to 30 seconds
export const maxDuration = 30;
 
export async function POST(req: Request) {
  // Extract the messages from the request body
  const { messages } = await req.json();
 
  // Get the chefAgent instance from Mastra
  const agent = mastra.getAgent("chefAgent");
 
  // Stream the response using the agent
  const result = await agent.stream(messages);
 
  // Return the result as a data stream response
  return result.toDataStreamResponse();
}

Key changes:

• We import the mastra instance created in mastra/index.ts. Make sure the import path (@/mastra) is correct for your project setup (you might need ~/mastra, ../../../mastra, etc., depending on your path aliases and project structure).
• We retrieve the chefAgent using mastra.getAgent("chefAgent").
• Instead of calling the AI SDK's streamText directly, we call agent.stream(messages) to process the chat messages using the agent's configuration and model.
• The result is still returned in a format compatible with Assistant UI using toDataStreamResponse().

Your API route is now powered by Mastra!

Run the Application

You're all set! Start your Next.js development server:

npm run dev

Open your browser to http://localhost:3000 (or the port specified in your terminal). You should now be able to interact with your chefAgent through the Assistant UI chat interface. Ask it for cooking advice based on ingredients you have!