Build Your Frontend Actions Agent with Mastra

​

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

• OpenAI API key in .env as OPENAI_API_KEY.
• A CometChat app.

​

Quick links

• .env.example
• Repo: mastra-frontend-actions-agent Runtime & config
• package.json
• README: Project README
• tsconfig.json
• Scripts: package.json
• README.md

• src/mastra/agents/celebration-agent.ts

​

How it works

• src/mastra/tools/confetti-tool.ts
• src/mastra/tools/index.ts

• 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
• This keeps sensitive work on the server and visual effects on the client. Workflows
  • src/mastra/workflows/index.ts

• Environment
• .env.example
• Runtime & config
• package.json
• tsconfig.json
• README.md
• Agent
• src/mastra/agents/celebration-agent.ts
• Tools
• src/mastra/tools/confetti-tool.ts
• src/mastra/tools/index.ts
• Server
• src/mastra/index.ts
• Frontend sample
• widget/index.html
• Workflows
• src/mastra/workflows/index.ts

​

Step 1 - Create 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

• 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

• Scripts: package.json
• README: Project README

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

​

Step 4 - Handle frontend tools

• 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).

​

Step 5 - Deploy the API

​

Step 6 - Configure in CometChat

For more on CometChat AI Agents, see the docs: Overview · Instructions · Custom agents

​

Step 7 - Customize in Chat Builder

​

Step 8 - Integrate

No Code - Widget

React UI Kit

Pre Built UI Components

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

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.