Modern healthcare systems can be confusing for patients. Should they see a general practitioner for their symptoms? Do they need a specialist? Would a nurse practitioner be enough? And what about urgent situations? In this tutorial, you’ll build an intelligent Healthcare Appointment Coordinator Agent using Mastra that handles exactly these challenges.
The agent reads patient requests, determines the right type of healthcare provider, schedules an appointment, and returns a concise summary including routing, scheduling status, and urgency level. Even better, it only responds when explicitly tagged making it perfect for integrating into real chat environments like CometChat AI Agents.
What You’ll Build
By the end of this tutorial, you’ll have a Mastra-based agent that:
Analyzes patient requests and understands medical intent
Routes the user to a GP, specialist, nurse practitioner, or emergency care
Schedules realistic appointment times
Returns structured, easy-to-parse output
Exposes an API endpoint that CometChat can call directly
It’s a practical example of how Mastra agents can coordinate multi-step workflows across multiple specialized agents.
How the System Works
The coordinator agent acts like a triage desk. It waits silently until someone mentions @agent, and once invoked, it parses the user’s message to detect symptoms, urgency, and provider type.
Based on this analysis, it routes the request to the right sub-agent:
GP Agent → Routine checkups, general symptoms
Specialist Agent → Cardiology, dermatology, neurology, etc.
Nurse Practitioner Agent → Vaccinations, minor issues
Emergency Agent → Chest pain, severe symptoms
Each sub-agent is responsible for generating a realistic appointment response.
Once the correct agent handles the request, the workflow returns a neat JSON-like result summarizing the final outcome.
Step 1: Creating the Coordinator Agent
This step focuses on defining the main agent responsible for coordinating all appointments. It sets up the agent’s behavior, including when it should respond and what kind of logic it should follow. This agent becomes the face of the entire system.
Let’s start with the main agent: src/mastra/agents/appointment-coordinator-agent.ts
Here’s the core of the agent:
The instructions define its behavior:
It should reply only when called with @agent
It must analyze user intent
It determines urgency
It routes and schedules automatically
It includes non-medical-advice disclaimers
This helps keep interactions predictable and safe.
Step 2: Provider Agents
The provider agents are lightweight and specialized. Each one handles scheduling for a specific healthcare professional. The coordinator delegates every request to one of these agents depending on what's appropriate.
Each provider agent is a small, focused LLM-based assistant.
General Practitioner Agent
general-practitioner-agent.ts
Specialist Agent
specialist-agent.ts
Nurse Practitioner Agent
nurse-practitioner-agent.ts
Emergency Scheduler
emergency-scheduler-agent.ts
These agents are intentionally simple, they specialize in one thing each, which keeps the system flexible.
Step 3: Routing Logic via Tools
This step defines the actual decision-making engine. The tool reads the user’s request, performs basic analysis, and decides which provider agent should handle it. This keeps all the routing logic in one clean, editable place.
The coordinator doesn’t decide everything by itself. Instead, it relies on a tool that analyzes user input and selects the best provider.
File: src/mastra/tools/appointment-coordinator-tool.ts
This tool encapsulates the triage logic:
Emergencies → Emergency agent
Specific symptoms → Specialist
Routine or mild issues → GP or NP
If you ever want smarter routing, this is the place to improve it.
Step 4: The Scheduling Workflow
The workflow acts as the glue between the coordinator agent and the routing tool. It wraps the routing logic inside a proper workflow that Mastra can execute and track. This step ensures that all requests follow the same execution pipeline.
Appointments are actually scheduled through a dedicated workflow.
File: src/mastra/workflows/appointment-scheduling-workflow.ts
This workflow receives the user message, hands it to the routing tool, and returns whatever appointment or emergency response the selected agent generates.
Step 5: Registering Your Agents
This step wires your agents and workflows into the Mastra runtime. Without this, Mastra wouldn’t know what to expose as API endpoints. Registering makes everything available via /generate routes.
Now everything needs to be wired into the Mastra runtime.
File: src/mastra/index.ts
Once registered, Mastra automatically exposes:
POST /api/agents/appointmentCoordinatorAgent/generate
This is also the endpoint you will use later inside CometChat.
Step 6: Running the Agent Locally
Before integrating with CometChat, you must ensure the agent works locally. Running the dev server spins up your API routes and allows you to test the coordinator logic end-to-end.
From your project root:
npm install
npm run dev
Your API should now be live at:
API Base: http://localhost:4113/api
You can now send real scheduling requests.
Step 7: Testing the Agent
Testing ensures the agent’s routing and scheduling logic works as expected. Before integrating with CometChat, use curl or Swagger to simulate real patient messages and verify the behavior.
Try a few sample curl commands.
Routine checkup (GP)
Specialist consultation
Flu shot (NP)
Step 8: Connecting to CometChat
This final step links your Mastra agent to CometChat so real users can interact with it inside chat interfaces. CometChat sends the user’s message to your Mastra endpoint and displays the agent’s reply — no code changes required.
Integrating Mastra agents with CometChat is straightforward.
Open the CometChat Dashboard.
Go to AI Agents → Add Agent.
Set:
Provider: Mastra
Agent ID: appointmentCoordinatorAgent
Deployment URL: your public /generate endpoint
Enable the agent.
Inside Chat Builder, attach this agent to your chat experience and test it in the live preview. From that moment on, your users can simply open the chat and say:
@agent I need to book a dermatologist appointment.
And the system will take care of the rest.
Wrapping Up
You’ve now built a complete multi-agent healthcare coordinator powered by Mastra and Cometchat. It smartly identifies the right provider, schedules appointments, and returns structured responses all while integrating seamlessly with CometChat for real-time chat experiences.
Shrinithi Vijayaraghavan
Creative Storytelling , CometChat