Skip to main content

recusal-google-adk

The Recusal gate for Google ADK: every tool call an agent proposes is judged by your policy before the tool runs, and a refused call never runs.

This is a separate distribution from recusal. The kernel has zero runtime dependencies and a frozen compatibility perimeter; this package carries the ADK dependency and its own version, so an ADK release never forces a release of the kernel.

Install it from PyPI:

pip install recusal-google-adk

Requires Python 3.11+ (the ADK's minimum), recusal>=0.14.0 and google-adk>=2.13.0. It is tested on every pull request against exactly google-adk==2.13.0 with google-genai==2.34.0, and weekly against the newest releases.

Use

from google.adk.agents import LlmAgent
from recusal import Finding
from recusal_google_adk import gated_agent


def policy(tool_name, tool_input):
    sql = tool_input.get("sql", "")
    if tool_name == "run_sql" and sql.lstrip().upper().startswith("DELETE"):
        return [Finding.fail("no_deletes", severity="CRITICAL", message="DELETE is not allowed")]
    return []


agent = gated_agent(LlmAgent(name="assistant", model=model, tools=[run_sql]), policy)

gated_agent returns a copy of the agent with the gate appended as the last before-tool callback, and gates its sub_agents and the agent behind every AgentTool the same way. A refused call is answered to the model as {"error": reason}. The tool does not run. A policy that raises refuses the call (fail closed).

The gate prepares the invocation the way the ADK will (defaults completed, values validated), judges a detached copy, and the tool runs with exactly what was judged.

For an app whose agents you do not build yourself, RecusalPlugin(policy) is the same gate as a runner plugin: InMemoryRunner(agent, plugins=[RecusalPlugin(policy)]). Plugin callbacks run before any agent's own, so the plugin judges a call only when nothing it cannot see runs after it. If the executing agent has another before-tool callback, or a later plugin overrides before_tool_callback, it refuses the call and names the fix.

Put every decision on the record

from recusal.audit import AuditLog
from recusal_google_adk import audited_agent

log = AuditLog(path="decisions.jsonl")
agent = audited_agent(LlmAgent(name="assistant", model=model, tools=[run_sql]), policy, log)

audited_plugin(policy, log) is the plugin form. Each call a gate sees, allowed or refused, is one hash-chained entry labeled google_adk.before_tool_callback with the ADK's function call id and a SHA-256 fingerprint of the arguments (never the arguments). If the log cannot be written the call is refused. Check the log with recusal audit verify decisions.jsonl.

The audited forms are the plain ones with a recording passed in, so there is one decision path.

What the gate refuses, and what it does not see

  • gated_agent raises at construction for an agent that can run something the callback never sees: an agent with a code_executor (model-written code runs outside the tool path), an LlmAgent subclass, or an agent class it does not know how to gate.
  • Refused before the policy runs: a tool that is not a stock FunctionTool, a signature that cannot be judged by name, an unknown or missing parameter, and arguments that do not validate.
  • Not on the audit log: a call another before-tool callback answered before the gate ran. The tool did not run either.

Compatibility

This package is outside the kernel's frozen perimeter (STABILITY.md, Integrations). Its public names are the ones in recusal_google_adk.__all__. When an ADK release changes what the callback is handed, this package gets a release and the kernel does not.

A runnable offline demonstration, with a scripted model and no API key, is examples/google_adk_gate.py and examples/google_adk_audit.py.

Metadata

Release files for recusal-google-adk 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for recusal-google-adk 0.1.1
File Size Uploaded Provenance Actions
recusal_google_adk-0.1.1.tar.gz 15.3 kB With provenance Details for recusal_google_adk-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for recusal-google-adk 0.1.1
File Interpreter ABI Platform Actions
recusal_google_adk-0.1.1-py3-none-any.whl Python 3 none any Details for recusal_google_adk-0.1.1-py3-none-any.whl

Total release size: 30.3 kB

Release files / recusal_google_adk-0.1.1.tar.gz

Download URL recusal_google_adk-0.1.1.tar.gz
Size 15.3 kB
Tags Source
SHA-256 checksum
How to use checksums
23b19bda6763d58b9fd46b71696cca6870b6644783a0c01fec21878f4aad9c81
BLAKE2b-256 checksum
How to use checksums
5f16ce66202a4b592821b4cbd9eb960b62cc349eb441e093681d5d32059dd087
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / recusal_google_adk-0.1.1-py3-none-any.whl

Download URL recusal_google_adk-0.1.1-py3-none-any.whl
Size 15.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5425e0869b3a08e8cc81dbc5b623bdbe3a5515fda70d71e865f6eb9fc5ce0b2e
BLAKE2b-256 checksum
How to use checksums
ee1b88d8cdad70dc94e52f5afac65db7503783694049972e7e478093822a5d0e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for recusal-google-adk 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for recusal_google_adk-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page