> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build Your Frontend Actions Agent with Mastra

> Create a Mastra agent that can trigger UI actions via frontend actions/tools (e.g., confetti), then connect it to CometChat.

Give your chats superpowers: let an agent trigger visual effects and UI actions in the browser (like confetti) by returning safe, structured tool calls that your frontend handles.

***

## What You’ll Build

* A **Mastra agent** that can request frontend UI actions (tools) like confetti.
* A simple **tool registry** on the client that runs actions when the agent returns a tool call.
* An API endpoint to chat with the agent and receive tool instructions.
* Integration into **CometChat** chats.

***

## Prerequisites

Repo: [mastra-frontend-actions-agent](https://github.com/cometchat/ai-agent-mastra-examples/tree/main/mastra-frontend-actions-agent)
README: [Project README](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/README.md)
Scripts: [package.json](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/package.json)

* OpenAI API key in `.env` as `OPENAI_API_KEY`.
* A CometChat app.

***

## Quick links

Environment

* [.env.example](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/.env.example)
* Repo: [mastra-frontend-actions-agent](https://github.com/cometchat/ai-agent-mastra-examples/tree/main/mastra-frontend-actions-agent)
  Runtime & config
* [package.json](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/package.json)
* README: [Project README](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/README.md)
* [tsconfig.json](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/tsconfig.json)
* Scripts: [package.json](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/package.json)
* [README.md](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/README.md)

***

Agent

* [src/mastra/agents/celebration-agent.ts](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/src/mastra/agents/celebration-agent.ts)

## How it works

Tools

* [src/mastra/tools/confetti-tool.ts](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/src/mastra/tools/confetti-tool.ts)

* [src/mastra/tools/index.ts](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/src/mastra/tools/index.ts)

Server

* [src/mastra/index.ts](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/src/mastra/index.ts)
* The server responds with a normal chat message and a machine-readable tool call describing what to run.\
  Frontend sample
  * [widget/index.html](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/widget/index.html)
* This keeps sensitive work on the server and visual effects on the client.
  Key components (source-linked below): the agent, the `confetti` tool, server entry, and a sample widget page.

***

Scripts: [package.json](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/package.json)\
README: [Project README](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/README.md)\
See the sample: [widget/index.html](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/widget/index.html)

* Environment
* [.env.example](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/.env.example)
* Runtime & config
* [package.json](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/package.json)
* [tsconfig.json](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/tsconfig.json)
* [README.md](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/README.md)
* Agent
* [src/mastra/agents/celebration-agent.ts](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/src/mastra/agents/celebration-agent.ts)
* Tools
* [src/mastra/tools/confetti-tool.ts](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/src/mastra/tools/confetti-tool.ts)
* [src/mastra/tools/index.ts](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/src/mastra/tools/index.ts)
* Server
* [src/mastra/index.ts](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/src/mastra/index.ts)
* Frontend sample
* [widget/index.html](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/widget/index.html)

***

## Step 1 - Create the Agent

**`src/mastra/agents/celebration-agent.ts`** ([view in repo](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/src/mastra/agents/celebration-agent.ts)):

Checklist for the agent:

* Set `name` to something like **"celebration"** so the API path is `/api/agents/celebration/*`.
* Describe when to use the `confetti` tool (e.g., celebratory moments).
* Keep normal chat responses short and friendly.
* Ensure tool return format is structured and safe.

***

## Step 2 - Register the Agent in Mastra

**`src/mastra/index.ts`** ([view in repo](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/src/mastra/index.ts)):

* Register the agent with key **"celebration"** → API path `/api/agents/celebration/*`.
* Keep config and logger settings as per the repo README.

***

## Step 3 - Run the Agent

*Dev scripts & server details are in your repo:*

* Scripts: [package.json](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/package.json)
* README: [Project README](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/README.md)

Expected local API base: `http://localhost:4111/api`

<Steps>
  <Step title="Install dependencies">Use the repo scripts to install dependencies.</Step>
  <Step title="Start the dev server">Run the local Mastra server as per the README.</Step>
  <Step title="Ask the agent">POST to <code>/api/agents/celebration/generate</code> and inspect tool calls in the response.</Step>
</Steps>

API endpoints exposed by this example:

* POST `/api/agents/celebration/generate` — chat with the agent and receive frontend tool instructions

***

## Step 4 - Handle frontend tools

You’ll need a small client-side handler that:

* Reads tool calls from the agent’s response (e.g., `{ id: "confetti", args: {...} }`).
* Maps the tool ID to a function (e.g., `confetti()`), then runs it.
* Handles unknown tools safely (ignore or log).

See the sample: [widget/index.html](https://github.com/cometchat/ai-agent-mastra-examples/blob/main/mastra-frontend-actions-agent/widget/index.html)

***

## Step 5 - Deploy the API

Ensure your public route: **`/api/agents/celebration/generate`** is reachable.

***

## Step 6 - Configure in CometChat

<Steps>
  <Step title="Open Dashboard">Open the <a href="https://app.cometchat.com/" target="_blank" rel="noreferrer">CometChat Dashboard</a>.</Step>
  <Step title="Navigate">Go to your App → <b>AI Agents</b>.</Step>
  <Step title="Add agent">Set <b>Provider</b>=Mastra, <b>Agent ID</b>=<code>celebration</code>, <b>Deployment URL</b>=your public generate endpoint.</Step>
  <Step title="(Optional) Tools">If your UI uses frontend tools, ensure your app handles tool invocations.</Step>
  <Step title="Enable">Save and ensure the agent toggle shows <b>Enabled</b>.</Step>
</Steps>

> For more on CometChat AI Agents, see the docs: [Overview](/ai-agents/agent-builder/overview) · [Instructions](/ai-agents/agent-builder/instructions) · [Custom agents](/ai-agents/agent-builder/tools/overview)

***

## Step 7 - Customize in UI Kit Builder

<Steps>
  <Step title="Open variant">From <b>AI Agents</b> click the variant (or Get Started) to enter UI Kit Builder.</Step>
  <Step title="Customize & Deploy">Select <b>Customize and Deploy</b>.</Step>
  <Step title="Adjust settings">Theme, layout, features; ensure the Frontend Actions agent is attached.</Step>
  <Step title="Preview">Use live preview to validate messages and any tool triggers.</Step>
</Steps>

***

## Step 8 - Integrate

Once your Frontend Actions Agent is configured, you can integrate it into your app using the CometChat Widget Builder:

<CardGroup>
  <Card title="Widget Builder" icon={<img src="/docs/images/products/ai-agents.svg" alt="Widget" />} description="Embed / script" href="/widget/ai-agents" horizontal />

  <Card title="React UI Kit" icon={<img src="/docs/images/icons/react.svg" alt="React" />} href="https://www.cometchat.com/docs/ui-kit/react/ai-assistant-chat" horizontal>Pre Built UI Components</Card>
</CardGroup>

> **Note:** The **Frontend Actions agent** you connected in earlier steps is already part of the exported configuration, so your end-users will chat with that agent immediately.

***

## Step 9 - Test Your Setup

<Steps>
  <Step title="API generates response">POST to <code>/api/agents/celebration/generate</code> returns a message, possibly with a tool call.</Step>
  <Step title="Agent listed"><code>/api/agents</code> includes <code>"celebration"</code>.</Step>
  <Step title="Tool action works">Your UI runs the <code>confetti</code> tool when the agent requests it.</Step>
</Steps>

```bash theme={null}
curl -X POST http://localhost:4111/api/agents/celebration/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "@agent celebrate our product launch with confetti" }
    ]
  }'
```

***

## Security & production checklist

* Protect endpoints with auth (API key/JWT) and restrict CORS to trusted origins.
* Add rate limiting and request size limits to the generate route.
* Validate inputs and sanitize logs/responses server-side.
* Keep your OpenAI key in server-side env only; never expose it to the client.

## Troubleshooting

* **No tool runs**: ensure the frontend reads tool calls from the response and maps IDs to functions.
* **Agent not found**: confirm the server registers the agent with key `celebration`.
* **401/403**: verify auth headers and CORS for your deployment.

***

## Next Steps

* Add more tools (e.g., toast, highlight, modal) and map them in your UI.
* Gate tool usage by roles or contexts.
* Log tool invocations for auditing and tuning.