How to Build a KYC verification Agent Using CrewAI in TypeScript for healthcare

A KYC verification agent for healthcare checks whether a patient, provider, or payer identity is valid before sensitive workflows continue. In practice, that means verifying documents, matching demographic data, flagging inconsistencies, and producing an audit trail that supports compliance requirements like HIPAA, local data residency rules, and internal access controls.

Architecture

• •

  Intake layer

  • •Receives the KYC request: name, DOB, address, government ID metadata, insurance member ID, or provider credentials.
  • •Normalizes the payload before it reaches the agent.
• •

  Verification tools

  • •Calls external services for identity validation, document authenticity checks, address validation, and sanctions/PEP screening where required.
  • •In healthcare, this often includes payer eligibility APIs and provider registry lookups.
• •

  CrewAI agents

  • •One agent handles identity matching.
  • •A second agent handles compliance review and exception handling.
  • •A third agent can produce the final decision summary and audit notes.
• •

  Task orchestration

  • •Breaks KYC into deterministic steps: extract facts, verify against sources, assess risk, decide pass/fail/manual review.
  • •This keeps the workflow explainable for auditors.
• •

  Audit and logging

  • •Stores input hashes, tool calls, decisions, timestamps, and reviewer notes.
  • •Do not log raw PHI unless your retention policy explicitly allows it.
• •

  Decision output

  • •Returns a structured result: approved, rejected, or manual_review.
  • •Includes reasons and evidence references for downstream systems.

Implementation

1) Install the TypeScript dependencies

Use the TypeScript package for CrewAI plus a schema validator for structured outputs.

npm install @crewai/crewai zod dotenv
npm install -D typescript tsx @types/node

Set your environment variables:

CREWAI_API_KEY=your_key
OPENAI_API_KEY=your_llm_key

2) Define the KYC result schema

For healthcare, keep the output structured so your workflow engine can route cases without parsing free text.

import { z } from "zod";

export const KycResultSchema = z.object({
  status: z.enum(["approved", "rejected", "manual_review"]),
  riskScore: z.number().min(0).max(100),
  reasons: z.array(z.string()),
  evidence: z.array(
    z.object({
      source: z.string(),
      referenceId: z.string().optional(),
      match: z.boolean(),
    })
  ),
});

export type KycResult = z.infer<typeof KycResultSchema>;

3) Build agents, tasks, and crew

This pattern uses CrewAI’s core classes: Agent, Task, and Crew. The important part is keeping each task narrow so you can prove why a case was approved or escalated.

import "dotenv/config";
import { Agent, Task, Crew } from "@crewai/crewai";
import { KycResultSchema } from "./kyc-schema.js";

const identityAgent = new Agent({
  role: "Healthcare Identity Verifier",
  goal: "Verify patient or provider identity against supplied records and external evidence",
  backstory:
    "You validate healthcare identities with strict attention to compliance, auditability, and minimal data exposure.",
});

const complianceAgent = new Agent({
  role: "Healthcare Compliance Reviewer",
  goal: "Review verification findings for HIPAA-sensitive handling and escalation criteria",
  backstory:
    "You assess whether the verification result meets policy requirements and whether manual review is needed.",
});

const kycTask = new Task({
  description:
    "Verify the healthcare identity package. Check demographic consistency, document validity signals, and any mismatch indicators. Return a concise decision with reasons.",
  expectedOutput:
    "A JSON object matching the KycResult schema with status, riskScore, reasons, and evidence.",
  agent: identityAgent,
});

const reviewTask = new Task({
  description:
    "Review the initial verification result. If there are unresolved mismatches or compliance concerns such as missing consent or residency issues, escalate to manual review.",
  expectedOutput:
    "A final JSON object matching the KycResult schema.",
  agent: complianceAgent,
});

export async function runKycVerification(input: {
  fullName: string;
  dateOfBirth: string;
  address: string;
  idNumber?: string;
}) {
  const crew = new Crew({
    agents: [identityAgent, complianceAgent],
    tasks: [kycTask, reviewTask],
    verbose: true,
    process: "sequential",
    memory: false,
    outputSchema: KycResultSchema,
  });

  const result = await crew.kickoff({
    fullName: input.fullName,
    dateOfBirth: input.dateOfBirth,
    address: input.address,
    idNumber: input.idNumber ?? null,
    jurisdiction: "healthcare",
    policyHints: [
      "Minimize PHI exposure",
      "Escalate if confidence is low",
      "Do not retain raw document images in logs",
    ],
  });

  return result;
}

4) Expose it behind an API endpoint

In production you usually call this from a patient onboarding service or provider enrollment workflow.

import express from "express";
import { runKycVerification } from "./kyc-agent.js";

const app = express();
app.use(express.json());

app.post("/kyc/verify", async (req, res) => {
  const result = await runKycVerification(req.body);

  if (result.status === "manual_review") {
    return res.status(202).json(result);
  }

  return res.status(200).json(result);
});

app.listen(3000);

Production Considerations

• •

  Keep PHI out of prompts unless necessary

  Send only the minimum fields required for verification. Hash identifiers where possible and use tokenized references for document images or external records.

• •

  Enforce data residency at the tool layer

  If your healthcare data must stay in-region, make sure every tool call points to region-bound services. The model can reason anywhere; your data cannot.

• •

  Log decisions, not raw content

  Store task inputs as redacted payloads plus hashes. Keep timestamps, model version, tool versions, confidence scores, and reviewer overrides for auditability.

• •

  Add hard guardrails around escalation

  Auto-route to manual review when there is a mismatch on name/DOB/address combinations, expired documents, missing consent artifacts, or suspicious duplicate identities.

Common Pitfalls

1. •

   Treating healthcare KYC like consumer onboarding

   • •Consumer flows tolerate fuzzy matches.
   • •Healthcare needs stricter thresholds because bad identity resolution can expose PHI to the wrong person.
   • •Fix it by using explicit rejection/escalation rules and auditable thresholds.
2. •

   Logging sensitive fields in verbose mode

   • •verbose: true is useful during development.
   • •In production it can leak PHI into logs if you are not careful.
   • •Fix it by redacting request bodies before kickoff and disabling noisy logs in regulated environments.
3. •

   Letting one agent make every decision

   • •A single broad agent is hard to audit and harder to tune.
   • •Fix it by splitting verification and compliance into separate tasks so each step has a clear responsibility.
4. •

   Ignoring jurisdiction-specific rules

   • •Healthcare identity checks vary by country and sometimes by state or province.
   • •Fix it by passing jurisdiction metadata into the crew and routing to region-specific policies before final approval.

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.