Building a Medical Symptom Checker agent with Mastra and CometChat

A step-by-step guide to building a Medical Symptom Checker Agent using Mastra and CometChat. This tutorial walks through how to analyze free-text symptoms, determine urgency levels, route users to the right medical professional, and escalate to a human representative when needed. You’ll also learn how to plug the entire workflow into CometChat’s AI Agents so the symptom checker can operate naturally inside a chat experience.

Shrinithi Vijayaraghavan • Nov 26, 2025

When users describe symptoms, they need fast and safe guidance whether that means basic home-care advice, seeing a nurse or doctor, or immediate emergency escalation. But sometimes, even the best AI-powered triage model needs to hand off the conversation to a human representative.

In this tutorial, you’ll build a Mastra-powered Medical Symptom Checker with Human Handoff, which analyzes free-form symptom descriptions, evaluates urgency, routes users to the right specialist agent, and escalates to a human rep when needed. You’ll also connect it to CometChat AI Agents so users can interact naturally through chat.

What You’ll Build

By the end of this tutorial, you’ll have:

  • A Symptom Checker LLM agent that analyzes symptoms

  • A set of specialist sub-agents (nurse, doctor, emergency, human rep)

  • Automatic detection of urgency levels

  • High-risk and escalation logic

  • A /generate API endpoint that CometChat can call

  • Optional human handoff inside chat UI

How the System Works

This symptom-checker system works like an automated medical triage front desk. Users describe symptoms, the agent analyzes severity based on keywords, assigns urgency, and then routes the case to the correct provider- nurse, doctor, or emergency. If symptoms are unclear, unusual, or critical, the tool escalates to a human representative.

Each specialist is implemented as a small LLM agent with focused instructions. The routing is handled by a Mastra tool, and the workflow glues everything together into a single /generate endpoint.

Step 1: Create the Symptom Checker Agent

This step sets up the main agent responsible for reading user symptoms and determining next steps. It defines the tone, instructions, safety disclaimers, and routing expectations. This is the agent that CometChat will ultimately call.

File: src/mastra/agents/symptom-checker-agent.ts

This agent uses the symptomCheckerTool to actually route requests.

Step 2: Define Provider + Human Rep Agents

Each provider agent is small and dedicated to a single purpose. The symptom checker never makes final decisions, it delegates to one of these specialists depending on the user's symptoms. This modular design keeps the system flexible and easy to extend.

Nurse Practitioner Agent

src/mastra/agents/nurse-practitioner-agent.ts

code:

Doctor Agent

src/mastra/agents/doctor-agent.ts

code:

Emergency Agent

src/mastra/agents/emergency-agent.ts

code:

Human Representative Agent

src/mastra/agents/human-rep-agent.ts

code:

Step 3: Implement the Symptom Checker Tool

The tool is the heart of triage. It analyzes symptoms, checks for urgency keywords, and determines which specialist agent should handle the case. This is also where human handoff logic lives.

File: src/mastra/tools/symptom-checker-tool.ts

code:

This exact logic determines routing and escalation.

Step 4: Build the Triage Workflow

The workflow wraps the tool logic in a clean execution pipeline. When the API endpoint is called, Mastra runs this workflow, which then calls the symptom checker tool.

File: src/mastra/workflows/symptom-checker-workflow.ts

code:

Step 5: Register Agents and Workflows

This step tells Mastra which agents/workflows to expose as API endpoints. Without registration, the system wouldn't know what to deploy.

File: src/mastra/index.ts

code:

This automatically generates:

POST /api/agents/symptomCheckerAgent/generate

Step 6: Run the Agent Locally

Running locally ensures everything works before you integrate with CometChat. Mastra provides Swagger UI to help you test routing behavior and escalation paths.

Visit:

Step 7: Test the System

Before going live, simulate real symptoms. Test mild, moderate, severe, and unclear cases to confirm routing, urgency detection, and human handoff.

Mild symptoms

Emergency

Doctor-level

Step 8: Connect to CometChat

Once your agent is running, integrating with CometChat takes only a few steps. CometChat simply forwards user messages to your Mastra /generate endpoint and displays your agent’s response.

Inside CometChat Dashboard → AI Agents:

  • Provider: Mastra

  • Agent ID: symptomCheckerAgent

  • Deployment URL: your public /generate endpoint

Then attach this agent in Chat Builder and test in live preview.

Conclusion

You’ve now built a complete Medical Symptom Checker with Human Handoff powered by Mastra. It can analyze symptoms, detect urgency, escalate to humans, and integrate seamlessly with CometChat.

You can extend this system with:

  • Symptom severity scoring

  • Insurance eligibility checks

  • Appointment scheduling

  • Medical content search

  • Patient education modules

Shrinithi Vijayaraghavan

Creative Storytelling , CometChat

Shrinithi is a creative storyteller at CometChat who loves integrating technology and writing and sharing stories with the world. Shrinithi is excited to explore the endless possibilities of technology and storytelling combined together that can captivate and intrigue the audience.