Patients often struggle to understand what to do when they have symptoms, mild concerns, or general questions around everyday healthcare. “Is this fever dangerous?” “What’s the right way to treat nausea?” “Should I go to urgent care or wait it out?” These aren’t questions that always need a doctor but they do need trustworthy, sourced guidance.
In this tutorial, you’ll build an intelligent Patient FAQ Agent powered by Mastra.
This agent reads a user’s question, searches your curated medical knowledge files, retrieves the most relevant excerpts, and responds concisely with a medical disclaimer and a clean “Sources:” list. And because it only answers when explicitly tagged, it fits perfectly into chat products like CometChat AI Agents, where safety, clarity, and precision matter.
What You’ll Build
By the end of this tutorial, you’ll have a Mastra-based agent that:
Understands patient questions and extracts relevant intent
Retrieves verified medical information from your knowledge/medical folder
Generates short, patient-friendly answers with disclaimers
Includes file-based citations at the end of every response
Exposes an API endpoint that CometChat can call directly
It’s a simple but powerful example of retrieval-augmented generation (RAG)- ideal for healthcare chat experiences where accuracy and safety matter.
How the System Works
Think of this agent as a help desk nurse inside a chat window.
It doesn’t improvise advice. It pulls answers strictly from your curated library.
The moment a user writes something like:
@agent What should I do if I have a high fever?
…the agent quietly performs a series of steps:
Looks for relevant content inside your knowledge base
Extracts the top matching excerpts
Feeds those excerpts into the LLM to generate a concise answer
Adds a small medical disclaimer
Outputs a short “Sources:” section listing the files used
Behind the scenes, the docs retriever, the ingestion tool, and the main agent work together to ensure the response is grounded, safe, and easy to trust.
Step 1: Creating the Patient FAQ Agent
This step focuses on defining the main AI agent. It establishes the agent’s name, model, tools, and how it interacts with the rest of your system.
This is the “face” of your healthcare FAQ assistant.
File: src/mastra/agents/patient-faq-agent.ts
Here’s the core of the agent:
What this agent does:
It registers itself under the name patient-faq, which automatically maps to /api/agents/patient-faq/generate.
It uses docsRetriever: a tool specifically designed to pull excerpts from your knowledge folder.
It uses an OpenAI model but relies heavily on retrieved context to avoid hallucinations.
This agent is intentionally lightweight as it delegates retrieval to tools, content to your knowledge folder, and safety instructions to the prompt you’ll configure.
Step 2: Adding the Retrieval Tools
Retrieval is the heart of this system.
Your agent is only as good as its ability to scan, match, and return relevant medical excerpts.
Mastra handles retrieval using tools, which act like callable mini-functions that the agent can invoke during a conversation.
The Docs Retriever
File: src/mastra/tools/docs-retriever.ts
const results = allHits.slice(0, maxResults).map(h => ({
file: h.file,
excerpt: h.excerpt,
score: Number(h.score.toFixed(3)),
}));
return { results, sources: results.map(r => r.file), query, namespace };
This tool:
Loads documents from knowledge/<namespace>
Tokenizes + scores them
Returns the best excerpts and a list of source filenames
The Ingestion Tool
File: src/mastra/tools/ingest-sources.ts
const content = # Patient FAQ Text\n\n${s};
await fs.writeFile(fpath, content, "utf8");
This tool:
Accepts URLs, files, or raw text
Normalizes content
Stores it under knowledge/<namespace>
Together, these tools ensure your FAQ agent has a clean, structured knowledge base to reference at all times.
Step 3: Understanding the Knowledge Base
Your knowledge folder is the brain of the operation.
Location: knowledge/medical/
The ZIP you uploaded includes sample files such as:
general-patient-faq.md
common-symptoms-guide.md
emergency-care-guide.md
These markdown documents contain the clinically relevant information your agent retrieves and cites.By adding more files or updating existing ones, you can expand your agent’s coverage instantly.
Step 4: Server Routing and API Endpoints
To make the agent accessible, Mastra exposes tool routes and agent routes through an auto-generated API.
Core API Routes
File: src/mastra/server/routes.ts
export const apiRoutes = [
{ method: 'POST', path: '/api/tools/ingestSources', handler: ingestSourcesHandler },
{ method: 'POST', path: '/api/tools/searchDocs', handler: searchDocsHandler },
];
The Search Route
const res = await docsRetriever.execute({
input: { query, namespace, maxResults },
});
The Ingest Route
const result = await ingestSources.execute({
context: { sources, files, namespace, allowInsecureTLS },
});
These routes let you:
Upload new healthcare content
Preview search results
Test document retrieval independently
The agent itself lives at:
POST /api/agents/patient-faq/generate
Mastra handles that automatically when the agent is registered.
Step 5: Registering Everything with Mastra
Your final setup involves tying the agent + tools + routes into a single Mastra runtime.
File: src/mastra/index.ts
export const mastra = new Mastra({
agents: { 'patient-faq': patientFaqAgent },
server: {
build: { swaggerUI: true },
apiRoutes,
},
});
Once registered, Mastra automatically exposes:
POST /api/agents/patient-faq/generate
This is the endpoint that CometChat will call later.
Step 6: Running the Agent Locally
Before connecting to CometChat, make sure everything works end-to-end.
npm install
npx mastra dev
Your API will be available here:
http://localhost:4111/api
Open Swagger UI at:
http://localhost:4111/swagger-ui
Try an ingestion job, then a live question.
Step 7: Testing the Agent
Here are some sample curl commands to verify retrieval + reasoning:
Routine health question
curl -X POST http://localhost:4111/api/agents/patient-faq/generate \
-H "Content-Type: application/json" \
-d '{
"messages": [
{ "role": "user", "content": "@agent What should I do if I have a high fever?" }
],
"toolParams": { "namespace": "medical" }
}'
Ingest sample files
curl -X POST http://localhost:4111/api/tools/ingestSources \
-H "Content-Type: application/json" \
-d '{
"files": [
"knowledge/medical/general-patient-faq.md",
"knowledge/medical/common-symptoms-guide.md",
"knowledge/medical/emergency-care-guide.md"
],
"namespace": "medical"
}'
Ingest text directly
curl -X POST http://localhost:4111/api/tools/ingestSources \
-H 'Content-Type: application/json' \
-d '{
"sources": ["Q: What is normal BP? A: Usually under 120/80 mmHg."],
"namespace": "medical"
}'
These tests confirm:
Your ingestion works
Retrieval returns excerpts
The agent answers with disclaimers + sources
Step 8: Connecting to CometChat
This final step puts your agent directly into a real messaging environment.
In your CometChat Dashboard:
Go to AI Agents → Add Agent
Set:
Provider: Mastra
Agent ID: patient-faq
Deployment URL: your public /generate endpoint
Enable the agent
Open Chat Builder
Attach the Patient FAQ Agent to the chat experience
Test it in the live preview.
Now users can simply type:
@agent What should I do for mild nausea?
…and get a retrieved, cited, safe response instantly.
Wrapping Up
You’ve now built a complete Patient FAQ healthcare agent powered by Mastra and integrated seamlessly with CometChat. It retrieves from your curated medical guides, cites sources, and provides safe, concise suggestions all via a simple chat interface.
You can extend this system by:
Adding more medical content
Adding symptom triage tools
Introducing multi-agent workflows
Improving retrieval using embeddings
Enforcing stricter safety rules through prompting
Whenever you update your healthcare content, just re-run ingestion and your agent becomes smarter instantly.
Shrinithi Vijayaraghavan
Creative Storytelling , CometChat