Skip to main content

​
Prerequisites

  • CometChat app (App ID, Region, Auth Key).
  • Chat Widget variant (will produce a Widget / Variant ID).
  • A running Mastra agent endpoint (public or tunneled URL).
  • Mastra Agent ID (e.g. chef) and any required API key(s).
  • (Optional) Frontend Action definitions if you want UI‑bound behaviors.

​
Step 1 - Create / Verify Your Mastra Agent

Have a Mastra project ready (example using the “Chef” agent): 
// tools/suggest-substitute.ts & tools/recipe-from-pantry.ts (omitted for brevity)
// agents/chef-agent.ts (export chefAgent)
// mastra/index.ts
import { Mastra } from '@mastra/core/mastra';
import { chefAgent } from './agents/chef-agent';

export const mastra = new Mastra({
  agents: { chef: chefAgent } // 'chef' becomes /api/agents/chef/*
});

npx mastra dev
curl -X POST http://localhost:4111/api/agents/chef/generate \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello chef"}]}'
You now have:
  • Agent ID (e.g. chef)
  • Base URL (e.g. http://localhost:4111/api or public tunnel)

​
Step 2 - Deploy / Expose Your Agent

Choose one path so the Dashboard & Widget can reach your Mastra endpoint.
Install a tunnel & expose port 4111 (pick one):
# ngrok
ngrok http 4111

# cloudflared
cloudflared tunnel --url http://localhost:4111

# loca.lt
ssh -R 80:localhost:4111 nokey@localhost.run
Copy the public HTTPS URL (e.g. https://abc123.ngrok.io) – this becomes your Deployment URL.
Project structure (excerpt):
mastra/ (project root)
api/agents/[agent]/generate.ts  (Vercel function)
Example handler:
// api/agents/[agent]/generate.ts
import { mastra } from '../../mastra/index';

export default async function handler(req, res) {
  if (req.method !== 'POST') return res.status(405).end();
  const { agent } = req.query;
  const body = req.body;
  try {
    const response = await mastra.agents[agent].generate(body);
    res.json(response);
  } catch (e) {
    res.status(500).json({ error: e.message });
  }
}
Deploy:
vercel deploy --prod
Use the deployed base URL (e.g. https://your-app.vercel.app/api).
Add a simple Express server & Dockerfile:
// server.ts
import express from 'express';
import bodyParser from 'body-parser';
import { mastra } from './mastra';

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

app.post('/api/agents/:agent/generate', async (req, res) => {
  const agent = req.params.agent;
  try {
    const out = await mastra.agents[agent].generate(req.body);
    res.json(out);
  } catch (e) {
    res.status(500).json({ error: e.message });
  }
});

app.listen(4111, () => console.log('Mastra listening on 4111'));

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 4111
CMD ["node","dist/server.js"]
Build & run:
docker build -t mastra-agent .
docker run -p 4111:4111 mastra-agent
  • Add an auth layer (Bearer token) that the Dashboard/Widget includes.
  • Enable basic rate limiting (e.g. 60 req/min per IP).
  • Log tool invocations (duration + errors) for observability.
For fastest iteration start with a tunnel, then move to serverless or container for staging/production.
You now have a public base URL to use in the Dashboard.

​
Step 3 - Configure in CometChat

1

Open Dashboard

Open the CometChat Dashboard.
2

Navigate

Go to your App → AI Agents.
3

Add agent

Set Provider=Mastra, Agent ID=chef, Deployment URL=public base URL from Step 2.
4

(Optional) Enhancements

Add greeting, starter prompts, or map frontend actions/tools for richer UI.
5

Enable

Save and ensure the agent toggle shows Enabled.

​
Step 4 - Attach Agent in Chat Builder (No‑Code)

1

Open Chat Builder

Launch Chat Builder from the Dashboard.
2

Select or create variant

Choose an existing Widget Variant or create a new one.
3

Enable agent

In the AI / Agents panel toggle on your Mastra agent.
4

(Optional) Identity

Set display name & avatar so users recognize the agent.
5

Save variant

Save to persist the agent attachment.

​
Step 5 - Frontend Actions & Tools (Optional)

1

Define actions

In Dashboard add actions (name + optional schema) that represent UI behaviors.
2

Map to tools

Ensure Mastra tool id matches the action name for invocation context.
3

Handle on frontend (optional)

Implement handlers in custom UI or rely on widget defaults when available.

​
Step 6 - Customize in Chat Builder

1

Open variant

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

Customize & Deploy

Select Customize and Deploy.
3

Adjust settings

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

Preview & Save

Use live preview to validate responses and appearance, then save.

​
Step 7 - Export & Embed

In Chat Builder click Get Embedded Code → copy credentials:
  • App ID
  • Auth Key
  • Region
  • Variant ID
Example embed (HTML):
1

Include script (<head>)

Add script tag in document head (see snippet below).
2

Initialize (<body> end)

Add mount div + init script before closing body.
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@latest/dist/main.js"></script>

<div id="cometChatMount"></div>
<script>
  const COMETCHAT_CREDENTIALS = {
    appID:     "<YOUR_APP_ID>",
    appRegion: "<YOUR_APP_REGION>",
    authKey:   "<YOUR_AUTH_KEY>",
  };

  const COMETCHAT_USER_UID = "UID"; // Replace with your user UID

  const COMETCHAT_LAUNCH_OPTIONS = {
    targetElementID: "cometChatMount",
    isDocked: true,
    width: "700px",
    height: "500px",
    // variantID: "YOUR_VARIANT_ID",
  };

  window.addEventListener("DOMContentLoaded", () => {
    CometChatApp.init(COMETCHAT_CREDENTIALS)
      .then(() => CometChatApp.login({ uid: COMETCHAT_USER_UID }))
      .then(() => CometChatApp.launch(COMETCHAT_LAUNCH_OPTIONS))
      .catch(console.error);
  });
</script>
Replace placeholders (<YOUR_APP_ID>, etc.) with real values.

​
Step 8 - Verify

CheckHow
Agent appearsOpen widget → new conversation / agent entry available
Basic replySend a prompt → response under a few seconds
Tool logic worksAsk for ingredient substitution / recipe (Chef example)
Error freeBrowser console + Mastra logs have no unhandled errors
If responses fail, confirm the endpoint is publicly reachable and the Agent ID matches the Dashboard configuration.

​
Troubleshooting

IssueFix
Agent not listedConfirm it’s enabled in Dashboard + variant saved
404 from MastraEndpoint path or agent key mismatch
TimeoutExpose via a tunnel or deploy to a public host
Tool not invokedEnsure tool ID referenced in agent instructions & code
Auth errorRe-check Auth Key / App credentials in embed snippet

​
Next Steps

  • Add more tools (search, summarization, domain knowledge).
  • Introduce Frontend Actions for richer UI control.
  • Move from tunnel to production deployment.
  • Add analytics / observability (latency, error tracking).
Need code export (React UI Kit) instead of Widget? See the “Export & Integrate” guide in AI Agents
⌘I