Technical Guide | Healthcare

    Enforcing PHI policy in Google ADK agents with before_tool_callback and after_tool_callback

    Use before_tool_callback to inspect the arguments the model chose and to allow the call, rewrite the arguments, or block it before the tool runs. Use after_tool_callback to inspect what the tool returned and to allow, redact or replace the result before the model sees it. Write one decision record at each hook, and make both hooks fail closed. Callbacks give you an enforcement point inside one application. They do not give you consistent enforcement across every agent and tool.

    What each decision record should capture

    • Timestamp, agent identifier, session identifier and the acting user or service identity
    • Tool name and hook (before or after), with a reference to the arguments or response rather than their raw content
    • Decision: allow, redact or block, with the policy rule and policy version that produced it
    • Categories of PHI detected and counts of fields modified or removed
    • Error or timeout state of the policy check, and whether the fail-closed path was taken
    • Any override, with the approver identity, tied to your workforce sanction policy

    Why the tool boundary is the right place to enforce PHI policy

    In a healthcare agent, the model decides which tool to call and what to pass it. A scheduling lookup might receive a patient name and date of birth. An EHR tool might return a full encounter note. Both directions can carry electronic protected health information, which the HIPAA Security Rule protects when it is created, received, used or maintained by a covered entity or business associate.

    Prompt instructions such as "never pass identifiers to tools" are requests to the model, not controls. Reviewing transcripts afterward shows what happened but cannot stop it. The tool boundary is the one place where the arguments and the result exist as structured data, so it is where a deterministic check can run.

    Google ADK exposes this boundary through two hooks. before_tool_callback runs after the model has chosen a tool and arguments, and before the tool executes. after_tool_callback runs after the tool returns, and before the result is handed back to the model. Together they give you an input gate and an output gate around every tool call.

    Pre-call policy in before_tool_callback: allow, modify or block

    The callback receives the tool, the model-chosen arguments and the tool context. The return value controls execution. Returning nothing lets the call proceed with the arguments as they stand, including any you modified in place. Returning a result object short-circuits the call: the tool does not run, and your object is treated as the tool's result.

    That maps directly onto three policy decisions.

    Allow: the arguments contain only identifiers the tool is permitted to receive for this agent and purpose. Return nothing and record the decision.

    Redact or minimize: the arguments contain more than the tool needs, for example a full name where a internal patient token would do. Rewrite the arguments, then allow.

    Block: the arguments contain PHI the tool must not receive, or the tool is not permitted for this context. Return a structured refusal as the result, so the model gets a clear signal and the tool never executes.

    For detection, choose by argument shape. Schema-based field checks work best for typed arguments such as an MRN or date of birth field. Pattern matching and entity recognition are needed for free-text arguments such as a search query or note body. An allow-list of tools and permitted fields per agent is stricter than a deny-list of patterns, because it fails toward refusal when the model invents a new argument. Treat these as design options and measure their accuracy on representative payloads before relying on them.

    Post-call policy in after_tool_callback: filter what the model sees

    The post-call hook receives the same tool and arguments, plus the tool's response. Returning nothing passes the original response to the model. Returning a replacement object substitutes it. This is where result-side policy lives, because EHR, claims and scheduling tools often return far more than the task requires.

    Allow: the response contains only fields appropriate for the agent's purpose.

    Redact: remove or mask specific fields, or tokenize identifiers so the model can reason about a record without seeing the raw value. Field-level filtering against a known response schema is more reliable than scanning text, but nested objects, lists and free-text clinical notes still need content inspection.

    Block: replace the whole response with a refusal when the result cannot be safely filtered, for instance when it is malformed, unexpectedly large, or contains content types the policy does not understand.

    Redacting after the call does not undo the access. The tool already ran and the data already left the source system. The post-call hook controls what enters the model context, and from there what may be echoed to a user, stored in session state or passed to another tool. Pair it with a pre-call check so that the least data possible is requested in the first place.

    Failure modes and fail-closed behavior

    A policy hook that errors is a decision point too. If the check throws, times out or receives a payload it cannot parse, the safe default is to block: return a refusal from the pre-call hook, and replace the result in the post-call hook. Failing open turns every classifier outage into a PHI exposure. Fail-closed is a design choice you implement, so wrap the hook body explicitly and test the behavior rather than assuming it.

    Test the awkward inputs deliberately: exceptions inside the check, very large responses, nested objects, non-text content, and arguments the model constructs in unexpected formats. Record the observed behavior for your ADK version as engineering findings, and rerun those tests when you upgrade.

    Over-blocking has a cost as well. Organizations that are actors under information blocking rules should review blocking policies against the applicable exceptions with counsel. Organizations that are not HIPAA covered entities or business associates, such as some health app makers, may fall under the FTC Health Breach Notification Rule instead, which is a separate legal question.

    Limits of in-process callbacks, and enforcement in the execution path

    Callbacks are application code. They enforce policy only where a developer registered them, in the version of the code that was deployed. In a larger estate that creates practical questions. Is the same hook attached to every agent, including sub-agents and agents built by other teams? Is each tool invocation path covered? Does the policy version match across services, and who can change it? Each team that copies a redaction function also owns its drift. The evidence is only as complete as the callbacks that wrote it, and it sits in many places in different formats.

    These are reasons to treat callbacks as one enforcement layer rather than the whole control. Verify coverage for your ADK version by testing each agent topology you run, and keep policy definitions and evidence storage outside individual agent codebases.

    Trussed approaches this by enforcing policy in the execution path across models, agents, tools and MCP servers: allow, redact, block, rate limit, or escalate for human approval, applied to individual interactions and tool calls. Enforcement is at runtime, not reviewed after the fact, and each decision produces audit-ready evidence mapped to HIPAA, including 164.312(b) audit controls. Trussed runs in production with healthcare and pharma organizations, and can be deployed self-managed in the customer cloud with configurable retention and data residency. Callbacks you write in ADK remain useful alongside it as application-level checks.

    PHI policy points in the ADK tool lifecycle

    Model proposes a call

    The model selects a tool and its arguments, which may include patient identifiers.

    before_tool_callback

    Inspect arguments. Allow, modify or block before the tool executes.

    Tool executes

    EHR, claims or scheduling system returns a result, possibly with clinical records.

    after_tool_callback

    Inspect the result. Allow, redact or replace it before it reaches the model.

    Decision record

    Each allow, redact or block outcome is written as durable evidence.

    Enforce PHI policy at every tool call and keep the evidence

    Talk to our team about enforcing policy in the execution path for agents and tools, and about the audit-ready evidence each decision produces.

    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.