Using with Assistant UI

Create Standalone Mastra Server

Set up your directory structure. A possible directory structure could look like this:

• project-root
  • mastra-server
    • src
    • package.json
  • nextjs-frontend

Bootstrap your Mastra server:

npx create-mastra@latest

This command will launch an interactive wizard to help you scaffold a new Mastra project, including prompting you for a project name and setting up basic configurations. Follow the prompts to create your server project.

You now have a basic Mastra server project ready. You should have the following files and folders:

• src
  • mastra
    • index.ts
    • agents
      • weather-agent.ts
    • tools
      • weather-tool.ts
    • workflows
      • weather-workflow.ts

Compatibility Fix

Currently, to ensure proper compatibility between Mastra and Assistant UI, you need to setup server middleware. Update your /mastra/index.ts file with the following configuration:

export const mastra = new Mastra({
  //mastra server middleware
  server:{
  middleware: [{
    path: '/api/agents/*/stream',
    handler: async (c,next)=>{
    
      const body = await c.req.json();
  
      if ('state' in body && body.state == null) {
        delete body.state;
        delete body.tools;
      }
  
       c.req.json = async() => body;
  
      return next()
    }
  }]
 },
});

This middleware ensures that when Assistant UI sends a request with state: null and tools: {} in the request body, we remove those properties to make the request work properly with Mastra.

Run the Mastra Server

Run the Mastra server using the following command:

npm run dev

By default, the Mastra server will run on http://localhost:4111. Your weatherAgent should now be accessible via a POST request endpoint, typically http://localhost:4111/api/agents/weatherAgent/stream. Keep this server running for the next steps where we’ll set up the Assistant UI frontend to connect to it.

Initialize Assistant UI

Create a new assistant-ui project with the following command.

npx assistant-ui@latest create

Configure Frontend API Endpoint

The default Assistant UI setup configures the chat runtime to use a local API route (/api/chat) within the Next.js project. Since our Mastra agent is running on a separate server, we need to update the frontend to point to that server’s endpoint.

Find the useChatRuntime hook in the assistant-ui project, typically at app/assistant.tsx and change the api property to the full URL of your Mastra agent’s stream endpoint:

const runtime = useChatRuntime({
    api: "http://localhost:4111/api/agents/weatherAgent/stream",
});

Now, the Assistant UI frontend will send chat requests directly to your running Mastra server.

Run the Application

You’re ready to connect the pieces! Make sure both the Mastra server and the Assistant UI frontend are running. Start the Next.js development server:

npm run dev

You should now be able to chat with your agent in the browser.