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_agentraises at construction for an agent that can run something the callback never sees: an agent with acode_executor(model-written code runs outside the tool path), anLlmAgentsubclass, 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.