​

Build Your Patient FAQ Agent with Mastra

Create a Mastra Patient FAQ Agent that answers general healthcare questions from your curated medical knowledge, then connect it to CometChat.

​

What You’ll Build

• A Mastra agent specialized for healthcare FAQs (patient-faq).
• Retrieves answers from your knowledge/<namespace> folder and cites sources.
• Short, patient-friendly responses with medical disclaimers.
• Optional integration into CometChat chats.

​

Prerequisites

• Node.js installed
• Mastra framework
• OpenAI API key in .env as OPENAI_API_KEY
• A CometChat app (optional for chat integration)

​

Quick links

• Repo: patient-faq-agent
• Quickstart: Patient FAQ Agent Quickstart
• Swagger UI (local): http://localhost:4111/swagger-ui
• Knowledge folder: knowledge
• Local API base: http://localhost:4111/api

​

How it works

• Ingests sources (URLs, files, or raw text) into a local knowledge folder per namespace using the ingestSources tool. Normalized content is stored under knowledge/<namespace>.
• Retrieves relevant snippets with the docsRetriever tool. It scans your knowledge/<namespace> content, ranks results, and returns excerpts with file names as sources.
• Generates answers using only retrieved context. The agent includes medical disclaimers and appends a concise “Sources” list.
• Handles errors defensively. Server utilities sanitize errors before returning responses.

​

Setup

npm install

​

Project Structure

• Environment & runtime
  • package.json
  • tsconfig.json
  • README.md
• Agent
  • src/mastra/agents/patient-faq-agent.ts
  • src/mastra/agents/index.ts (if present)
• Tools
  • src/mastra/tools/docs-retriever.ts
  • src/mastra/tools/ingest-sources.ts
  • src/mastra/tools/index.ts
• Server
  • src/mastra/index.ts
  • src/mastra/server/routes.ts
  • src/mastra/server/routes/ingest.ts
  • src/mastra/server/routes/searchDocs.ts
  • src/mastra/server/util/safeErrorMessage.ts
• Knowledge base (sample)
  • knowledge/medical/general-patient-faq.md
  • knowledge/medical/common-symptoms-guide.md
  • knowledge/medical/emergency-care-guide.md

​

Step 1 - Create the Agent

• Agent file: src/mastra/agents/patient-faq-agent.ts
• Docs retriever tool: src/mastra/tools/docs-retriever.ts
• Knowledge folder: knowledge/medical

• Set name to “patient-faq” so the API path is /api/agents/patient-faq/*.
• Answer from retrieved docs only and include medical disclaimers.
• End every response with a short “Sources:” list.
• Register docsRetriever.

​

Step 2 - Register the Agent in Mastra

• Ensure the agent is registered with key “patient-faq” → API path /api/agents/patient-faq/*.
• Swagger UI is enabled via server.build.swaggerUI=true.

​

Step 3 - Run the Agent

• POST /api/tools/ingestSources — ingest URLs/files/text into knowledge/<namespace>
• POST /api/tools/searchDocs — retrieve relevant snippets from knowledge/<namespace>
• POST /api/agents/patient-faq/generate — chat with the agent

​

Step 4 - Deploy the API

• Swagger UI (local)
• Ensure the public route: /api/agents/patient-faq/generate is reachable.

​

Step 5 - Configure in CometChat

For more on CometChat AI Agents, see the docs: Overview · Instructions · Custom agents

​

Step 6 - Customize in Chat Builder

​

Step 7 - Integrate

No Code - Widget

React UI Kit

Pre Built UI Components

Note: The Mastra Patient FAQ agent you connected earlier is already part of the exported configuration, so your end-users can chat with that agent immediately.

​

Step 8 - Test Your Setup

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" }
  }'

# 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"
  }'

# URLs
curl -X POST http://localhost:4111/api/tools/ingestSources \
  -H 'Content-Type: application/json' \
  -d '{
    "sources": ["https://example.com/medical-guidelines"],
    "namespace": "medical"
  }'

# Inline text
curl -X POST http://localhost:4111/api/tools/ingestSources \
  -H 'Content-Type: application/json' \
  -d '{
    "sources": ["Q: What is a normal blood pressure? A: Typically < 120/80 mmHg."],
    "namespace": "medical"
  }'

​

Security & production checklist

• Protect endpoints with auth (API key/JWT) and restrict CORS to trusted origins.
• Add rate limiting and request size limits to ingestion and generate routes.
• Validate inputs: enforce allowed namespaces, URL/file whitelists, and payload schemas.
• Monitor logs and errors; sanitize responses using server utilities.
• Keep your OpenAI key server-side only; never expose it to the client.

​

Troubleshooting

• Agent talks too much: tighten instructions to answer concisely from docs and include disclaimers.
• No results: ensure /knowledge contains .md/.mdx/.txt files or your ingestion job populated the store.
• Not visible in chat: verify the agent is added and enabled in CometChat.
• 404 / Agent not found: check that the server registers the agent with key patient-faq.
• PDF ingestion issues: install pdf-parse if needed; use allowInsecureTLS only in trusted environments.

​

Next Steps

• Add tools like summarize-doc, triage-symptom, or link-to-source.
• Use embeddings + chunking for better retrieval.
• Restrict answers to whitelisted folders or domains.
• Inspect and try endpoints via Swagger UI (/swagger-ui).
• Set up CI/CD in your own repo as needed.