How to Build a KYC verification Agent Using LlamaIndex in Python for healthcare

A KYC verification agent for healthcare checks patient, provider, or vendor identity against approved records, validates submitted documents, and flags mismatches before they hit your downstream systems. In healthcare, this matters because identity errors create compliance risk, billing issues, and access-control failures that can expose PHI or block legitimate care.

Architecture

Build this agent as a small pipeline, not a single prompt.

• •

  Document ingestion layer

  • •Pulls PDFs, scans, IDs, licenses, insurance cards, and onboarding forms
  • •Uses SimpleDirectoryReader or a custom loader for your intake source
• •

  Indexing layer

  • •Stores extracted text in a VectorStoreIndex
  • •Lets the agent retrieve only the relevant evidence instead of dumping full documents into context
• •

  Verification tools

  • •Deterministic checks for fields like name, DOB, NPI, license number, policy ID
  • •LLM-based extraction for messy docs and exception handling
• •

  Agent orchestration

  • •Uses ReActAgent or FunctionCallingAgent to decide which verification tool to call
  • •Keeps the reasoning trace separate from the final decision
• •

  Audit and compliance layer

  • •Persists every input, retrieval result, tool call, and final decision
  • •Required for HIPAA-style auditability and internal review
• •

  Policy guardrails

  • •Enforces what the model can and cannot decide
  • •Prevents unsupported claims like “identity verified” when evidence is incomplete

Implementation

1) Install and configure the LlamaIndex stack

Use LlamaIndex with an OpenAI-compatible model provider. For healthcare workloads, keep configuration explicit so you can route traffic by region and log every request.

pip install llama-index llama-index-llms-openai llama-index-embeddings-openai pydantic

import os
from llama_index.core import Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY", "")

Settings.llm = OpenAI(model="gpt-4o-mini", temperature=0)
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")

2) Load verification documents into a vector index

This example assumes you have onboarding docs in a local folder. In production, replace this with your secure object store or document service.

from llama_index.core import SimpleDirectoryReader, VectorStoreIndex

docs = SimpleDirectoryReader(
    input_dir="./kyc_docs",
    required_exts=[".pdf", ".txt"]
).load_data()

index = VectorStoreIndex.from_documents(docs)
query_engine = index.as_query_engine(similarity_top_k=3)

The key pattern here is retrieval-first. You do not want the agent reasoning over an entire chart note archive or payer packet when it only needs the license form and identity page.

3) Define deterministic verification tools

Use plain Python for exact-match checks. LlamaIndex agents work best when you combine LLM retrieval with hard rules for compliance-sensitive fields.

from pydantic import BaseModel
from llama_index.core.tools import FunctionTool

class VerificationResult(BaseModel):
    status: str
    reason: str

def verify_name_dob(name: str, dob: str, record_name: str, record_dob: str) -> VerificationResult:
    if name.strip().lower() == record_name.strip().lower() and dob == record_dob:
        return VerificationResult(status="pass", reason="Name and DOB match authoritative record.")
    return VerificationResult(status="fail", reason="Name or DOB mismatch.")

verify_tool = FunctionTool.from_defaults(
    fn=verify_name_dob,
    name="verify_name_dob",
    description="Deterministically compare submitted name and DOB against authoritative records."
)

For healthcare KYC, this is where you keep the important logic: NPI validation, license state checks, payer ID matching, address normalization, and residency constraints.

4) Wrap retrieval plus tools in an agent

Use ReActAgent so the model can retrieve evidence and then call deterministic tools. Keep the final answer constrained to a structured outcome.

from llama_index.core.agent import ReActAgent

tools = [verify_tool]

agent = ReActAgent.from_tools(
    tools=tools,
    llm=Settings.llm,
    verbose=True,
)

prompt = """
You are a healthcare KYC verification agent.
Only use retrieved evidence and tools.
Do not claim verification unless evidence supports it.
Return:
- status: pass/fail/review
- evidence_summary
- compliance_notes
"""

response = agent.chat(
    prompt + "\n\n"
    "Verify this provider onboarding case:\n"
    "Submitted name: Dr. Maya Chen\n"
    "Submitted DOB: 1982-04-11\n"
    "Authoritative record says: Dr. Maya Chen / 1982-04-11\n"
)

print(response)

In practice, I’d split this into two stages:

• •Retrieve documents with query_engine.query(...)
• •Feed the extracted evidence into the agent only after redacting PHI not needed for KYC

That keeps your context smaller and reduces accidental disclosure.

Production Considerations

• •

  Keep PHI out of prompts unless it is required

  • •Redact medical details before calling the model
  • •Use only identity-relevant fields for KYC decisions
• •

  Log every decision path

  • •Store retrieved chunks, tool inputs/outputs, model response, timestamp, user ID, and case ID
  • •This is non-negotiable for auditability in healthcare onboarding flows
• •

  Enforce data residency

  • •Pin embeddings storage and model endpoints to approved regions
  • •Do not let document chunks cross borders if your regulatory posture forbids it
• •

  Add human review thresholds

  • •Auto-pass only when deterministic checks succeed and retrieval confidence is high
  • •Route ambiguous cases to compliance staff with full evidence attached

Common Pitfalls

1. •

   Using the LLM as the source of truth

   • •Mistake: asking the model to “decide” identity from raw text alone.
   • •Fix: make deterministic functions own exact-match checks; let LlamaIndex handle retrieval and orchestration.
2. •

   Stuffing full healthcare documents into context

   • •Mistake: passing entire PDFs or chart extracts to the model.
   • •Fix: retrieve only relevant chunks with VectorStoreIndex and redact non-essential PHI before inference.
3. •

   Skipping audit trails

   • •Mistake: storing only the final pass/fail result.
   • •Fix: persist tool calls, retrieved evidence IDs, prompts, outputs, and reviewer overrides so you can explain every decision later.

If you want this agent to survive real healthcare operations, treat it like a controlled verification system with an LLM on top—not an open-ended chatbot with access to sensitive records.

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.