Create an AI Agent with Mastra (CometChat)

What you’ll build

A Mastra agent with tools/actions
The same agent connected to CometChat (Agent ID + Deployment URL)
A customized chat experience using Chat Builder
An export to React UI Kit code or Chat Widget for integration

Prerequisites

A CometChat account and an app: Create App
A Mastra agent (ID + public Deployment URL) — follow Mastra’s quickstart:
Mastra Quickstart

Step 1

Create your CometChat app

Create or open an app

Copy credentials

Note your App ID, Region, and Auth Key (needed if you export the Chat Widget later).

Step 2

Connect your Mastra Agent

Navigate to AI Agent → Get Started and then AI Agents → Add Agent.

Choose provider

Select Mastra.

Basic details

Provide:

Name and optional Icon
(Optional) Greeting and Introductory Message
(Optional) Suggested messages

Mastra configuration

Paste the following from your Mastra deployment:

Mastra Agent ID
Deployment URL (public URL that CometChat can reach)

Save & enable

Click Save, then ensure the agent’s toggle is ON in AI Agents list.

Tip: If you update your Mastra agent later (prompts, tools, routing), you won’t need to re-connect it in CometChat—just keep the Agent ID and Deployment URL the same.

Step 3 (Optional)

Define Frontend Actions (Optional)

Add an action

Go to AI Agent → Actions and click Add to create a frontend action your agent can call (e.g., “Open Product,” “Start Demo,” “Book Slot”).

Define fields

Include:

Display Name — Shown to users (e.g., “Open Product Page”).
Execution Text — How the agent describes running it (e.g., “Opening product details for the user.”).
Name — A unique, code‑friendly key (e.g., open_product).
Description — What the tool does and when to use it.
Parameters — JSON Schema describing inputs (the agent will fill these).

Validate inputs (schema)

Example parameters JSON:

{
  "type": "object",
  "required": ["productId"],
  "properties": {
    "productId": {
      "type": "string",
      "description": "The internal product ID to open"
    },
    "utm": {
      "type": "string",
      "description": "Optional tracking code"
    }
  }
}

Handle in your UI

At runtime, listen for tool calls and execute them client‑side (e.g., route changes, modals, highlights).

Step 4

Customize in Chat Builder

Open variant

From AI Agents click the variant (or Get Started) to enter Chat Builder.

Customize & Deploy

Select Customize and Deploy.

Adjust settings

Theme, layout, features; ensure the Mastra agent is attached.

Preview

Use live preview to validate responses & any tool triggers.

Step 5

Export & Integrate

Choose how you’ll ship the experience (Widget or React UI Kit export).

No Code - Widget

The Mastra agent from Step 2 is included automatically in exported variants—no extra code needed for basic conversations.

Decide delivery mode

Pick Chat Widget (fastest) or export React UI Kit for code-level customization.

Widget path

Open Chat Builder → Get Embedded Code → copy script + credentials.

React UI Kit path

Export the variant as code (UI Kit) if you need deep theming or custom logic.

Verify agent inclusion

Preview: the Mastra agent should appear without extra config.

Step 6

Deploy & Secure (Reference)

Define an agent with tools

Minimal agent definition. (Adjust imports per current Mastra release.)

// mastra/agent.ts
import { defineAgent } from "mastra";

export const supportAgent = defineAgent({
  name: "My Agent 1",
  instructions: `You are a helpful support agent for Acme. Use tools when appropriate.`,
  tools: [
    {
      name: "open_product",
      description: "Open a product by ID in the UI",
      parameters: {
        type: "object",
        required: ["productId"],
        properties: { productId: { type: "string" } }
      }
    }
  ]
});

Expose a public HTTP endpoint

// server.ts
import express from "express";
import { supportAgent } from "./mastra/agent";

const app = express();
app.use(express.json());

app.post("/mastra/agent", async (req, res) => {
  const { messages } = req.body;
  const result = await supportAgent.respond({ messages });
  res.json(result);
});

app.listen(process.env.PORT || 3000, () => {
  console.log("Mastra agent running");
});

Run & Deploy Your Mastra Agent

Local Development

npx mastra dev starts local API (commonly http://localhost:4111/api).
Custom Express route? Keep path consistent in production.

Quick test (replace AGENT_ID):

curl -X POST http://localhost:4111/api/agents/AGENT_ID/generate \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"ping"}]}'

Temporary Public Tunnel

ngrok http 4111
cloudflared tunnel --url http://localhost:4111
loca.lt --port 4111

Append route (e.g. /api/agents/chef/generate) to the forwarded HTTPS URL.

Production Patterns

Serverless: Single API route invoking the agent.
Container: Long‑lived Express/CLI process; add health checks.
Edge: Keep tools stateless; externalize persistence.

Vercel Example

// api/agents/chef/generate.ts
import type { VercelRequest, VercelResponse } from '@vercel/node'
import { chefAgent } from '../../mastra/agents/chef-agent'

export default async function handler(req: VercelRequest, res: VercelResponse) {
  if (req.method !== 'POST') return res.status(405).json({ error: 'Method not allowed' })
  try {
    const { messages } = req.body || {}
    const result = await chefAgent.respond({ messages })
    return res.status(200).json(result)
  } catch (e:any) {
    return res.status(500).json({ error: e.message || 'Agent error' })
  }
}

Security

Rate limit by IP + user.
Add auth (Bearer / JWT) for non-public agents.
Log tool calls (id, latency) for observability.

CometChat Mapping

Use the final HTTPS URL + path for Deployment URL and the agent key (e.g. chef) for Mastra Agent ID.

Deploy & copy IDs

Test your setup

Enable the agent

In AI Agents, ensure your Mastra agent shows Enabled.

Preview in Chat Builder

Open Chat Builder and start a preview session.

Validate conversation

Send a message; confirm the agent responds.

Test actions

Trigger a Frontend Action and verify your UI handles the tool call.

Troubleshooting

Agent not responding

Tool call not executed

Auth issues in exports

Next steps

Add more Actions

Localize & theme

Analytics & observability

​What you’ll build

​Prerequisites

​Step 1

​Create your CometChat app

​Step 2

​Connect your Mastra Agent

​Step 3 (Optional)

​Define Frontend Actions (Optional)

​Step 4

​Customize in Chat Builder

​Step 5

​Export & Integrate