How to Build a claims processing Agent Using LangGraph in Python for wealth management

A claims processing agent for wealth management takes a client claim, classifies it, gathers the right policy and account context, checks it against rules, and routes it to approval, rejection, or human review. It matters because in wealth management you are not just moving tickets—you are handling regulated decisions that affect client trust, auditability, and compliance.

Architecture

• •

  Ingress layer

  • •Accepts claim payloads from API, CRM, or case management systems.
  • •Normalizes fields like client ID, account ID, claim type, amount, jurisdiction, and supporting documents.
• •

  Context retrieval

  • •Pulls policy terms, account metadata, KYC/AML flags, transaction history, and prior claim outcomes.
  • •Keeps retrieval scoped to approved data sources with residency-aware routing.
• •

  Decision engine

  • •Uses deterministic checks for eligibility, thresholds, and policy exclusions.
  • •Uses an LLM only where classification or summarization is needed.
• •

  Human review gate

  • •Routes ambiguous or high-risk claims to an operations analyst.
  • •Captures reviewer decisions for audit and future tuning.
• •

  Audit and trace layer

  • •Stores every state transition, decision input, and tool result.
  • •Produces a defensible record for compliance teams and regulators.
• •

  Output adapter

  • •Writes final status back to the claims system.
  • •Generates a concise explanation for internal users and client-facing summaries where allowed.

Implementation

1. •Define the state model

Use a typed state object so every node in the graph knows what it can read and write. For claims workflows, keep the state explicit: claim data in, retrieved context in the middle, final decision out.

from typing import TypedDict, Optional, Literal
from langgraph.graph import StateGraph, START, END

class ClaimState(TypedDict):
    claim_id: str
    client_id: str
    jurisdiction: str
    claim_type: str
    amount: float
    policy_text: Optional[str]
    risk_flag: bool
    decision: Optional[Literal["approve", "reject", "review"]]
    rationale: Optional[str]

2. •Add deterministic nodes first

In wealth management you want hard rules before model calls. Use plain Python functions for policy checks and routing logic so the workflow is explainable and easy to audit.

def load_policy(state: ClaimState) -> dict:
    # Replace with approved internal retrieval source
    policy_text = "Claims above $10k require review. AML-flagged clients require review."
    return {"policy_text": policy_text}

def evaluate_rules(state: ClaimState) -> dict:
    high_value = state["amount"] > 10000
    aml_flagged = state["client_id"].startswith("AML")
    risk_flag = high_value or aml_flagged

    if risk_flag:
        return {
            "risk_flag": True,
            "decision": "review",
            "rationale": "Policy threshold or client risk profile requires manual review."
        }

    return {
        "risk_flag": False,
        "decision": "approve",
        "rationale": "Claim passed deterministic eligibility checks."
    }

3. •Build the LangGraph workflow

StateGraph is the core API here. Add nodes with add_node, wire them with add_edge, then compile the graph into an executable app.

def finalize(state: ClaimState) -> dict:
    # Persist to your case system here.
    return {
        "rationale": f"{state['rationale']} | Logged for audit.",
    }

graph = StateGraph(ClaimState)
graph.add_node("load_policy", load_policy)
graph.add_node("evaluate_rules", evaluate_rules)
graph.add_node("finalize", finalize)

graph.add_edge(START, "load_policy")
graph.add_edge("load_policy", "evaluate_rules")
graph.add_edge("evaluate_rules", "finalize")
graph.add_edge("finalize", END)

app = graph.compile()

result = app.invoke({
    "claim_id": "CLM-1001",
    "client_id": "C12345",
    "jurisdiction": "US-NY",
    "claim_type": "fee_reimbursement",
    "amount": 12500.0,
})
print(result)

4. •Add conditional escalation for ambiguous cases

For production claims processing you need branching. LangGraph supports this with add_conditional_edges, which is cleaner than stuffing all logic into one node.

def route_claim(state: ClaimState) -> str:
    return "human_review" if state["decision"] == "review" else "finalize"

def human_review(state: ClaimState) -> dict:
    # Human analyst sees policy_text + rationale + supporting docs.
    return {
        "rationale": f"Escalated for manual review under {state['jurisdiction']} controls."
    }

graph = StateGraph(ClaimState)
graph.add_node("load_policy", load_policy)
graph.add_node("evaluate_rules", evaluate_rules)
graph.add_node("human_review", human_review)
graph.add_node("finalize", finalize)

graph.add_edge(START, "load_policy")
graph.add_edge("load_policy", "evaluate_rules")
graph.add_conditional_edges("evaluate_rules", route_claim)
graph.add_edge("human_review", END)
graph.add_edge("finalize", END)

app = graph.compile()

Production Considerations

• •

  Auditability

  • •Log every node input/output with immutable timestamps.
  • •Keep rationale text tied to rule versions so compliance can reconstruct decisions later.
• •

  Data residency

  • •Route EU client claims to EU-hosted storage and inference endpoints.
  • •Do not send personally identifiable information or account details to non-approved external services.
• •

  Guardrails

  • •Use deterministic rules for thresholds, sanctions screening flags, jurisdiction checks, and exclusion clauses.
  • •Restrict LLM use to summarization or classification of already-approved text.
• •

  Monitoring

  • •Track approval rate, manual review rate, false positives on escalations, and average time per node.
  • •Alert on drift in claim mix by jurisdiction or product line; that usually shows up before a compliance issue does.

Common Pitfalls

1. •

   Putting legal judgment into the model path

   • •Don’t ask the LLM to decide eligibility from scratch.
   • •Keep legal/policy interpretation in explicit rules reviewed by compliance.
2. •

   Using a loose state schema

   • •If your state is just a generic dict with no structure, you will ship broken workflows fast.
   • •Define a TypedDict or Pydantic model so each node has clear contracts.
3. •

   Skipping human escalation paths

   • •Wealth management claims often have edge cases: deceased clients, cross-border accounts, beneficiary disputes.
   • •Build conditional routing to human review from day one instead of bolting it on later.
4. •

   Ignoring evidence retention

   • •A final decision without attached inputs is useless during an audit.
   • •Persist source documents, rule version IDs, node outputs, and reviewer actions alongside the claim record.

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.