Skip to main content
Give users the right help fast: a coordinator/orchestrator agent that triages each request and forwards it to the best-fit specialist (billing, support, tech support, manager, or a human rep).

​
What You’ll Build

  • A Mastra coordinator/relay agent that classifies intent and routes to specialist agents.
  • Specialist agents (billing, support, tech-support, manager, human-rep).
  • A routing tool and workflow that coordinate handoffs.
  • Integration into CometChat chats.

​
Prerequisites

  • A Mastra project (npx create-mastra@latest my-mastra-app).
  • Node.js installed.
  • OpenAI API key in .env as OPENAI_API_KEY.
  • A CometChat app.

​
How it works

This example demonstrates a “multi-agent orchestration (relay)” pattern:
  • The primary agent (e.g., relay) understands the user request and decides which specialist should respond.
  • The routing tool and workflow handle the handoff, preserving context.
  • The selected specialist (billing/support/tech/manager/human-rep) answers, and the relay returns the final response.
  • This keeps logic modular and makes it easy to add or refine specialist agents.
Key components (source-linked below): the coordinator/relay agent, specialist agents, relay route tool, and relay workflow.

​
Setup

1

Prepare project

Create a Mastra app and add OPENAI_API_KEY in .env. See the repository README for exact steps.
2

Define relay + specialists

Add a relay agent and specialist agents (billing, support, tech, manager, human-rep).
3

Add routing

Implement a routing tool and workflow that determine the best specialist for a request.
4

Register in server

Register the agents and expose /api/agents/relay/generate (see server entry).
5

Ask the relay

POST to /api/agents/relay/generate with a messages array and verify routed answers.
6

Connect to CometChat

In Dashboard → AI Agents, set Provider=Mastra, Agent ID=relay, and point Deployment URL to your public generate endpoint.
7

Deploy & observe

Make the API public and monitor which specialist is selected in logs.

​
Project Structure

Core files and folders for the Multi-agent Orchestration Agent (browse source on GitHub):

​
Step 1 - Create the Relay and Specialist Agents

src/mastra/agents/relay-agent.ts (view in repo): Checklist for the relay:
  • Set name to “relay” so the API path is /api/agents/relay/*.
  • Detect intents (billing, support, tech, manager, human rep).
  • Use the routing tool/workflow to hand off.
  • Compose a concise final reply.
Specialists (configure as needed):

​
Step 2 - Routing Tool and Workflow

Ensure the coordinator/relay agent calls the tool/workflow with the correct context, and specialists are discoverable by key.

​
Step 3 - Register the Agents in Mastra

src/mastra/index.ts (view in repo):
  • Register the relay with key “relay” → API path /api/agents/relay/*.
  • Register specialist agents and expose only the relay externally.
  • Keep config and logger settings as per the repo README.

​
Step 4 - Run the Relay

Dev scripts & server details are in your repo: Expected local API base: http://localhost:4111/api
1

Install dependencies

Use the repo scripts to install dependencies.
2

Start the dev server

Run the local Mastra server as per the README.
3

Ask the orchestrator (relay) agent

POST to /api/agents/relay/generate and verify the routed specialist answers.
4

Observe routing

Check logs to see which specialist was chosen.
API endpoints exposed by this example:
  • POST /api/agents/relay/generate — chat with the relay and get routed responses

​
Step 5 - Deploy the API

Ensure your public route: /api/agents/relay/generate is reachable.

​
Step 6 - 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=relay, Deployment URL=your public generate endpoint.
4

(Optional) Routing

Adjust specialist prompts and routing rules as needed.
5

Enable

Save and ensure the agent toggle shows Enabled.
For more on CometChat AI Agents, see the docs: Overview · Instructions · Custom agents

​
Step 7 - 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 Multi-agent Orchestration (relay) agent is attached.
4

Preview

Use live preview to validate routing and responses.

​
Step 8 - Integrate

Once your Multi-agent Orchestration Agent is configured, you can integrate it into your app using the CometChat Widget Builder:
Widget

Widget Builder

React

React UI Kit

Pre Built UI Components
Note: The Orchestrator (relay) 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

1

Relay responds

POST to /api/agents/relay/generate returns an answer from the chosen specialist.
2

Agent listed

/api/agents includes “relay”.
3

Routing visible

Logs show which specialist handled the request.
curl -X POST http://localhost:4111/api/agents/relay/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "@agent I need help with my invoice charges" }
    ]
  }'

​
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, sanitize logs/responses, and monitor routing distribution.
  • Keep secrets in server-side env only; never expose them to the client.

​
Troubleshooting

  • Wrong specialist: refine relay prompts, add explicit routing criteria, or fallbacks.
  • No response: verify relay and specialists are registered and reachable.
  • Agent not found: confirm the server registers the agent with key relay.

​
Next Steps

  • Add more specialists (sales, onboarding) or escalation rules.
  • Add audit logs for routed conversations.
  • Implement handoff to a human rep based on confidence thresholds.