How to Build a policy Q&A Agent Using CrewAI in TypeScript for healthcare

A policy Q&A agent for healthcare answers staff questions about coverage, eligibility, prior authorization, HIPAA handling, claim rules, and internal SOPs without making people dig through PDFs or intranet pages. It matters because bad policy answers in healthcare create real operational risk: denied claims, delayed care, compliance exposure, and inconsistent guidance across teams.

Architecture

• •

  Policy document loader

  • •Pulls from approved sources only: plan documents, SOPs, clinical guidelines, HR policy docs.
  • •Normalizes PDFs, DOCX, and HTML into text chunks with source metadata.
• •

  Retrieval layer

  • •Uses vector search over policy chunks so the agent can ground every answer in current documents.
  • •Keeps citations tied to document name, section, and effective date.
• •

  CrewAI orchestration

  • •A Crew coordinates specialized Agents:
    • •one for policy retrieval
    • •one for answer synthesis
    • •one for compliance review
  • •This keeps the final response constrained and auditable.
• •

  Guardrail layer

  • •Blocks unsupported medical advice.
  • •Detects PHI leakage and routes sensitive cases to human review.
• •

  Audit logging

  • •Stores question, retrieved sources, answer, model version, timestamps, and reviewer outcome.
  • •Needed for healthcare compliance reviews and incident investigation.

Implementation

1) Install CrewAI for TypeScript and set up your project

Use the TypeScript SDK and a model provider that is approved for your environment. In healthcare, that usually means an enterprise deployment with the right security posture and data processing terms.

npm install @crewai/typescript zod dotenv

Create a minimal entry point:

import "dotenv/config";
import { Agent, Crew, Task } from "@crewai/typescript";

const openAiKey = process.env.OPENAI_API_KEY;
if (!openAiKey) throw new Error("OPENAI_API_KEY is required");

2) Define specialized agents for retrieval, drafting, and compliance

Don’t use one general-purpose agent to do everything. In healthcare policy workflows, separation of duties makes the output easier to test and audit.

import { Agent } from "@crewai/typescript";

const retriever = new Agent({
  role: "Healthcare Policy Retriever",
  goal: "Find the most relevant policy passages with exact citations",
  backstory: "You only use approved internal healthcare policy documents.",
});

const drafter = new Agent({
  role: "Policy Answer Drafter",
  goal: "Draft a concise answer grounded only in retrieved policy text",
  backstory: "You cite sources and never invent policy details.",
});

const complianceReviewer = new Agent({
  role: "Healthcare Compliance Reviewer",
  goal: "Check the draft for HIPAA risk, unsupported medical advice, and missing citations",
  backstory: "You flag anything that needs human review before release.",
});

3) Create tasks that force grounded answers

The key pattern is: retrieve first, draft second, review last. That sequence prevents the model from freewheeling on a vague user question.

import { Task } from "@crewai/typescript";

const retrieveTask = new Task({
  description:
    "Given the user's question about healthcare policy, identify the top relevant policy excerpts with document names, section numbers, and effective dates.",
  expectedOutput:
    "A structured list of excerpts with citations and a short relevance note for each.",
  agent: retriever,
});

const draftTask = new Task({
  description:
    "Using only the retrieved excerpts, answer the user's question in plain English. Include citations inline.",
  expectedOutput:
    "A direct answer with citations and a note when escalation to human review is required.",
  agent: drafter,
});

const reviewTask = new Task({
  description:
    "Review the drafted answer for compliance issues. Flag PHI exposure, unsupported clinical advice, or missing citations.",
  expectedOutput:
    "Approved or rejected response plus specific remediation notes.",
  agent: complianceReviewer,
});

4) Run the crew and return an auditable result

This is the part you wire into your API route or service handler. Keep your logs outside the model output so you can store them in an audit system.

import { Crew } from "@crewai/typescript";

async function answerPolicyQuestion(question: string) {
  const crew = new Crew({
    agents: [retriever, drafter, complianceReviewer],
    tasks: [retrieveTask, draftTask, reviewTask],
    verbose: true,
  });

  const result = await crew.kickoff({
    inputs: {
      question,
      jurisdiction: "US",
      domain: "healthcare benefits policy",
    },
  });

  return result;
}

answerPolicyQuestion(
  "Does this plan require prior authorization for outpatient MRI scans?"
).then((result) => {
  console.log(JSON.stringify(result));
});

In production you should wrap this with:

• •source filtering by document version
• •a PHI detector before kickoff
• •post-processing to enforce citation presence
• •storage of question, answer, sources, model, and review_status

Production Considerations

• •

  Deployment

  • •Keep policy indexes in-region if you have data residency requirements.
  • •Use private networking to your LLM provider where possible.
  • •Separate dev/test/prod corpora so stale policies never bleed into production answers.
• •

  Monitoring

  • •Track citation coverage rate.
    • •If answers are missing citations too often, retrieval quality is broken.
  • •Log escalation frequency.
    • •A spike usually means either ambiguous policies or bad prompt design.
  • •Store reviewer overrides so you can measure where the agent disagrees with compliance staff.
• •

  Guardrails

  • •Reject questions that request diagnosis or treatment recommendations.
  • •Mask or block PHI before it reaches external model endpoints.
  • •Require human approval for high-risk topics like behavioral health disclosures, minors’ records, substance use treatment data, and appeals denials.
• •

  Auditability

  • •Persist every retrieved chunk ID and document version.
    • •You need this when legal or compliance asks why the system answered a certain way.
    • •Keep retention aligned with your healthcare records policy.

Common Pitfalls

1. •

   Letting the agent answer from memory instead of retrieved policy text

   • •Fix it by making retrieval a separate task and rejecting outputs without citations.
   • •In healthcare this is non-negotiable because stale knowledge creates bad operational guidance.
2. •

   Ignoring document versioning

   • •Policy changes weekly in some organizations.
   • •Always attach effective date and version ID to every chunk so old rules don’t contaminate answers.
3. •

   Sending PHI straight into the model

   • •Add a pre-processing step that redacts member IDs, names, dates of birth, claim numbers, and chart references when they are not needed.
   • •If the question requires patient-specific context, route it to a compliant workflow with proper access controls instead of a generic Q&A agent.
4. •

   Skipping human escalation paths

   • •Some questions should never be auto-answered.
   • •Build explicit fallback rules for ambiguous coverage disputes, legal interpretations of consent rules, and anything touching protected mental health data.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.