Frontend Tools

What is this?

Frontend tools enable you to define client-side functions that your Mastra agent can invoke, with execution happening entirely in the user's browser. When your agent calls a frontend tool, the logic runs on the client side, giving you direct access to the frontend environment.

This can be utilized to let your agent control the UI, generative UI, or for Human-in-the-loop interactions.

In this guide, we cover the use of frontend tools for generative UI.

When should I use this?

Use frontend tools when you need your agent to interact with client-side primitives such as:

• Reading or modifying React component state
• Accessing browser APIs like localStorage, sessionStorage, or cookies
• Triggering UI updates or animations
• Interacting with third-party frontend libraries
• Performing actions that require the user's immediate browser context

Implementation

import { useFrontendTool } from "@copilotkit/react-core"

export function Page() {
  // ...

  useFrontendTool({
    name: "sayHello",
    description: "Say hello to the user",
    parameters: [
      {
        name: "name",
        type: "string",
        description: "The name of the user to say hello to",
        required: true,
      },
    ],
    handler({ name }) {
      // Handler returns the result of the tool call
      return { currentURLPath: window.location.href, userName: name };
    },
    render: ({ args }) => {
      // Renders UI based on the data of the tool call
      return (
        <div>
          <h1>Hello, {args.name}!</h1>
          <h1>You're currently on {window.location.href}</h1>
        </div>
      );
    },
  });

  // ...
}

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

export const myAgent = new Agent({
  name: "My Agent",
  instructions: "You are a helpful assistant!",
  model: openai("gpt-4o"),
});

// Frontend tools are automatically available to the agent
// through the AG-UI protocol when registered with useFrontendTool