Implementation Guide | Healthcare

    How to Prevent PHI Exposure in LangGraph Tool Errors and Retries

    To prevent PHI exposure in LangGraph tool errors, treat every exception, upstream response and retry payload as untrusted content. Sanitize errors before they enter graph state, return fixed error classes instead of raw text, bound retries and rebuild them from validated inputs, and keep PHI out of checkpoints and logs. These fixes are necessary but depend on every tool being written correctly, so regulated teams also enforce policy in the execution path on tool calls and responses and keep audit-ready evidence for HIPAA audit controls under 164.312(b).

    1. 1

      1. Tool input

      Identifiers in parameters, which may be echoed back by the failing system.

    2. 2

      2. Exception

      Raw exception text, stack frames and upstream response bodies.

    3. 3

      3. Graph state

      Error content written to state and, if persisted, to checkpoints.

    4. 4

      4. Model context

      Error text included in the next prompt, sent to the model provider.

    5. 5

      5. Retry

      Original or rewritten payload resent to the model or a downstream tool.

    6. 6

      6. Logs and traces

      Each attempt copied into application logs and monitoring systems.

    7. 7

      Tool inputs

      Check parameters before the call is made.

    8. 8

      Tool responses and errors

      Redact or block before content reaches state, context or logs.

    9. 9

      Retry payloads

      Apply the same policy to every resend, not only the first call.

    10. 10

      Evidence

      Record each allow, redact, block or escalate decision for review.

    Questions to ask before you rely on any control

    • Does it act on tool inputs, tool responses, error strings and retry payloads, or only on final model output?
    • Can it redact or block before content reaches graph state, checkpoints, model context and logs?
    • What evidence does each decision produce, and can it be retained and reviewed for audit?
    • How are retries handled so raw payloads are not resent and each attempt is not stored as another copy of PHI?
    • How does it fit your HIPAA risk analysis and your policies for AI agents?

    Apply application-level mitigations

    HealthIT.gov guidance for healthcare APIs recommends sanitizing incoming requests and disabling messages used for debugging or error trapping, to limit exposure of information. The guidance addresses EHR APIs rather than agents, but the principle carries over directly: error detail is information, and it should not travel further than it needs to.

    The central change is to sanitize at the boundary of the tool, before anything reaches agent-visible state. Wrap each tool so that exceptions are caught inside the wrapper and converted into a small, fixed vocabulary such as timeout, not found, invalid input or upstream failure. The model needs to know what category of failure occurred and whether a retry is sensible. It does not need the text of the exception.

    Retries deserve their own design. Cap the number of attempts, use backoff, and rebuild each retry from validated, structured inputs instead of replaying a prior message. Do not let the model rewrite a failed request from raw error text. Where a record must be referenced, pass an internal opaque reference rather than the identifier.

    Finally, decide what state and checkpoints are allowed to hold. Store references and status codes, not payloads. Apply the same rule to logs: disable verbose debug output in production and scrub structured fields before they are emitted.

    • Catch exceptions inside the tool wrapper and return a fixed error class, never raw text.
    • Strip or hash identifiers from any message that must be kept for diagnosis.
    • Limit retry attempts, apply backoff, and rebuild retries from validated inputs.
    • Keep payloads out of graph state and checkpoints; store references and status.
    • Disable debug and error-trapping output in production and scrub logs at the emitter.

    Why code-level fixes are not enough

    Each of these measures is sound, and none should be skipped. The weakness is that they all depend on correct implementation in every tool, by every team, on every release. A new tool added without the wrapper, an upstream error format that changes, or a third-party client that raises its own verbose exception can reintroduce the exposure without any visible failure. Pattern-based redaction also misses identifiers that do not follow a known format, and log scrubbing happens after the content has already been written.

    Prompt instructions are a weaker control still. Telling the model to ignore or avoid repeating sensitive data does nothing about what has already been placed in state, sent to a provider or written to a log. NIST's January 2026 request for information on AI agent security lists prompt engineering, data or tool restrictions and continuous monitoring as candidate controls, and asks how far their effectiveness varies with agent scaffold software, tool use and deployment method. That is an open question, not a settled answer, so prompt instructions should not be your containment mechanism for PHI.

    There is also an evidence gap. A try/except block contains an error, but it produces no record of what was allowed, changed or stopped. When the question is how PHI handling was controlled, application code gives you behavior without proof of it.

    PHI path through a failed tool call

    Tool input

    Request parameters carry identifiers

    Exception

    Raw error, stack trace or upstream body

    Graph state

    Error string stored and persisted

    Model context

    Error text read by the model

    Retry

    Payload resent, another copy created

    Logs

    Each attempt recorded downstream

    See how enforcement and evidence work on tool calls

    Review how policy is enforced on agent tool calls and responses, and how audit-ready evidence is produced for HIPAA.

    See How Evidence Is Produced
    Next step

    How does your AI governance program compare?

    See where your program has gaps in less than 2 minutes.