Integrate an AI Agent into the Chat Widget

AI Agents currently support Mastra. Additional providers are coming soon.

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):

Minimal example (tools + 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/*
});

Local run & test

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.

Option A: Quick tunnel (development)

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.

Option B: Vercel serverless (Edge/Node)

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

Option C: Docker container

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

Optional: Security hardening

You now have a public base URL to use in the Dashboard.

Step 3

Configure in CometChat

Open Dashboard

Open the CometChat Dashboard.

Navigate

Go to your App → AI Agents.

Add agent

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

(Optional) Enhancements

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

Enable

Save and ensure the agent toggle shows Enabled.

Step 4

Attach Agent in Chat Builder (No‑Code)

Open Chat Builder

Launch Chat Builder from the Dashboard.

Select or create variant

Choose an existing Widget Variant or create a new one.

Enable agent

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

(Optional) Identity

Set display name & avatar so users recognize the agent.

Save variant

Save to persist the agent attachment.

Step 5 (Optional)

Frontend Actions & Tools

Define actions

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

Map to tools

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

Handle on frontend (optional)

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

Step 6

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 & 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):

Include script (<head>)

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

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

Check	How
Agent appears	Open widget → new conversation / agent entry available
Basic reply	Send a prompt → response under a few seconds
Tool logic works	Ask for ingredient substitution / recipe (Chef example)
Error free	Browser 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

Issue	Fix
Agent not listed	Confirm it’s enabled in Dashboard + variant saved
404 from Mastra	Endpoint path or agent key mismatch
Timeout	Expose via a tunnel or deploy to a public host
Tool not invoked	Ensure tool ID referenced in agent instructions & code
Auth error	Re-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

Legacy

Advanced

Integrate an AI Agent into the Chat Widget

Prerequisites

Step 1

Create / Verify Your Mastra Agent

Step 2

Deploy / Expose Your Agent

Step 3

Configure in CometChat

Step 4

Attach Agent in Chat Builder (No‑Code)

Step 5 (Optional)

Frontend Actions & Tools

Step 6

Customize in Chat Builder

Step 7

Export & Embed

Step 8

Verify

Troubleshooting

Next Steps

Legacy

Advanced

​Prerequisites

​Step 1

​Create / Verify Your Mastra Agent

​Step 2

​Deploy / Expose Your Agent

​Step 3

​Configure in CometChat

​Step 4

​Attach Agent in Chat Builder (No‑Code)

​Step 5 (Optional)

​Frontend Actions & Tools

​Step 6

​Customize in Chat Builder

​Step 7

​Export & Embed

​Step 8

​Verify

​Troubleshooting

​Next Steps

Prerequisites

Step 1

Create / Verify Your Mastra Agent

Step 2

Deploy / Expose Your Agent

Step 3

Configure in CometChat

Step 4

Attach Agent in Chat Builder (No‑Code)

Step 5 (Optional)

Frontend Actions & Tools

Step 6

Customize in Chat Builder

Step 7

Export & Embed

Step 8

Verify

Troubleshooting

Next Steps