Integrate an AI Agent into the Chat Widget

Add an AI Agent (Mastra) to the CometChat Chat Widget using the no‑code builder and a simple embed.

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

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.

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 [e-mail]

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

• 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 UI Kit Builder (No‑Code)

1. Open UI Kit Builder

   Launch UI Kit 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 UI Kit Builder

1. Open variant

   From AI Agents click the variant (or Get Started) to enter UI Kit 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 UI Kit 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@1.x.x/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