Give users the right help fast: an 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 orchestrator 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” pattern:
  • The primary agent (the orchestrator) 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 orchestrator returns the final response.
  • This keeps logic modular and makes it easy to add or refine specialist agents.
Key components (source-linked below): the orchestrator agent, specialist agents, orchestrator tool, and orchestrator 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 orchestrator + specialists

Add an orchestrator 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/orchestratorAgent/generate (see server entry).
5

Ask the orchestrator

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

Connect to CometChat

In Dashboard → AI Agents, set Provider=Mastra, Agent ID=orchestratorAgent, 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 Orchestrator Agent (browse source on GitHub):

​
Step 1 - Create the Orchestrator and Specialist Agents

src/mastra/agents/orchestrator-agent.ts (view in repo): Checklist for the orchestrator:
  • Register the agent with key “orchestratorAgent” so the API path is /api/agents/orchestratorAgent/*.
  • 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 orchestrator 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 orchestrator with key “orchestratorAgent” → API path /api/agents/orchestratorAgent/*.
  • Register specialist agents and expose only the orchestrator externally.
  • Keep config and logger settings as per the repo README.

​
Step 4 - Run the Orchestrator

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

Install dependencies

Run npm install.
2

Start the dev server

Run npx mastra dev (or npm run dev).
3

Ask the orchestrator agent

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

Observe routing

Responses end with ([routedTo] | escalated: yes/no); check logs for which specialist was chosen.
API endpoints exposed by this example:
  • POST /api/agents/orchestratorAgent/generate — chat with the orchestrator and get routed responses

​
Step 5 - Deploy the API

Ensure your public route: /api/agents/orchestratorAgent/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=orchestratorAgent, 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 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 Orchestrator agent is attached.
4

Preview

Use live preview to validate routing and responses.

​
Step 8 - Integrate

Once your Orchestrator Agent is configured, you can integrate it into your app using the CometChat No Code - Widget:
Widget

No Code - Widget

React

React UI Kit

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

Orchestrator responds

POST to /api/agents/orchestratorAgent/generate returns an answer from the chosen specialist and ends with routing metadata.
2

Agent listed

/api/agents includes “orchestratorAgent”.
3

Routing visible

Logs show which specialist handled the request.
curl -X POST http://localhost:4111/api/agents/orchestratorAgent/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 orchestrator prompts, add explicit routing criteria, or fallbacks.
  • No response: verify orchestrator and specialists are registered and reachable.
  • Agent not found: confirm the server registers the agent with key orchestratorAgent.

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