Modern healthcare onboarding is surprisingly fragmented. A patient wants to begin care, but clinics often ask them to repeat information across forms, upload documents multiple times, verify identity, check insurance eligibility, and still call support to confirm what’s next. For many patients, the process feels less like a welcome experience and more like a scavenger hunt.
In this tutorial, you’ll build a Patient Onboarding Workflow Agent, a guided assistant that helps patients move through onboarding step-by-step, verifies their documents, checks insurance, and returns workflow status in real time. And because this agent can be connected to CometChat, patients can complete onboarding right inside a chat experience they’re already familiar with.
Let’s break down how this system works and then walk through building it from scratch.
What You’ll Build
By the end of this tutorial, you will have:
A Mastra agent named patient-onboarding that guides users through onboarding steps.
A workflow that handles:
Starting onboarding
Collecting patient info
Updating insurance details
Processing documents (OCR, ID extraction)
Verifying identity and insurance
Running compliance checks
Returning onboarding status
A companion workflow-manager agent (optional) for next-step recommendations.
A full REST API exposing endpoints such as /api/onboarding/initiate, /api/onboarding/:id/process-document, and more.
A CometChat integration where your agent becomes available inside any chat UI.
How the system works
Think of this onboarding agent as a workflow guide sitting at a digital front desk. When a user says, “@agent help me start onboarding,” it takes them through a structured flow:
Initiate the onboarding session → Create a record
Collect basic patient info
Collect & verify insurance details
Process uploaded ID documents (OCR → identity extraction)
Verify identity and insurance eligibility
Run compliance checks
Return onboarding status and next steps
Tools inside the agent do the heavy lifting, while the REST routes maintain state and ensure the process stays orderly. This setup helps you separate responsibilities cleanly—logic stays in the agent, while workflow state lives in your API.
Step 1: Creating the Onboarding Agent
This step establishes the “brain” of your onboarding system. The agent defines how the assistant behaves, how it interacts with users, and which tools it can access. By requiring users to mention the agent explicitly (e.g., @agent), you prevent accidental triggers and make the agent feel more intentional and controlled.
File:
src/mastra/agents/onboarding-agent.ts
Code snippet
Here, you’re defining what the agent should do and how it should behave. The tools you attach give it additional capabilities beyond simple conversation, such as reading documents or validating insurance information.
Step 2: Adding Verification Tools
Tools allow your agent to perform actions rather than just generate text. These tools handle activities like OCR extraction, identity validation, and insurance eligibility checks. By isolating these behaviors into separate tools, the agent remains modular, testable, and easier to extend if requirements evolve.
File:
src/mastra/tools/verification-tools.ts
Code snippet
Each tool represents a step in the onboarding journey. Your agent can dynamically call them whenever the user reaches that part of the process, making the conversation richer and more interactive.
Step 3: Workflow Routes (REST API)
These endpoints form the backbone of your onboarding system. They allow the agent and any external UI to update patient information, move the workflow forward, and retrieve status. Separating workflow steps into individual routes improves reliability and gives you more transparency when debugging.
File:
src/mastra/server/routes/onboarding.ts
Code snippet
The remaining routes follow the same pattern, allowing you to store insurance info, process documents, and run verifications. This structure ensures that every onboarding stage is fully traceable and can be triggered independently.
Step 4: Server Setup & API Registration
This is where everything comes together. The agent, tools, routes, and core Mastra runtime become part of a single API. This wiring ensures your agent endpoints and workflow endpoints live under the same /api namespace, giving you a unified service boundary.
File:
src/mastra/server/routes.ts
router.use("/onboarding", onboardingRoutes);
router.use("/agents", agentRoutes);
And your main entry point:
File:
src/mastra/index.ts
const mastra = createMastra({
agents: { onboarding: onboardingAgent },
});
app.use("/api", createExpressRouter(mastra));
At this point, your backend is fully assembled every endpoint and every agent is now live and reachable.
Step 5: Registering the Agent in Mastra
Mastra automatically generates routes and agent metadata for you. This means you don’t manually wire up /api/agents/patient-onboarding/generate—it appears the moment you register the agent. This makes development smoother and reduces boilerplate.
Once registered, you should see:
/api/agents/patient-onboarding/generate
You can also view all active agents:
/api/agents
This helps confirm everything is wired correctly before testing the workflow end-to-end.
Step 6: Running the Project Locally
This step ensures your environment is up and running for local development. Mastra includes a built-in Swagger UI, which makes exploring and testing your workflow APIs straightforward—even for non-technical teammates.
Install dependencies
npm install
Start dev server
npm run dev
Your API is now available at:
http://localhost:4111/api
Open Swagger UI
http://localhost:4111/swagger-ui
From here, you can click through every route, inspect schemas, and try requests without writing a single line of code.
Step 7: Testing the Agent
Testing both the agent endpoint and workflow routes ensures that your logic and your APIs work end-to-end. You can start with conversational testing and then move into structured workflow validation.
Chat with your agent
Start onboarding
Update patient info
Testing each route validates that your workflow state updates correctly and that your agent is referencing the right endpoints during conversations.
Step 8: Connecting to CometChat
This step brings your agent into a real chat application. Once connected, your users can interact with the onboarding flow naturally as if they were messaging a front desk assistant.
1. Go to CometChat Dashboard → AI Agents
Enter:
Provider: Mastra
Agent ID: patient-onboarding
Deployment URL: https://your-domain.com/api/agents/patient-onboarding/generate
2. Customize in Chat Builder
Chat Builder lets you:
Theme the interface
Add your onboarding assistant
Preview the entire experience in real time
This step ensures that your agent feels native to the product you’re embedding it into.
Wrapping Up
You’ve now built a complete Patient Onboarding Workflow Agent one capable of guiding patients, processing documents, verifying identity and insurance, and reporting status in real time. The workflow is modular, conversational, and flexible enough to extend into more complex healthcare use cases.
What you can build next
Add database-backed onboarding sessions
Add human handoff to a nurse or admin
Introduce appointment scheduling after onboarding
Add push/email notifications for missing steps
Configure guardrails or moderation via CometChat
Shrinithi Vijayaraghavan
Creative Storytelling , CometChat