axonflow-google-adk-plugin
AxonFlow governance plugin for Google Agent Development Kit (ADK).
Register AxonFlowPlugin once on a Runner and every model call and every
tool call across every agent on that Runner is governed by AxonFlow
policies: pre-check, deny short-circuit, audit trail, PII redaction on tool
I/O, and HITL approval on platforms before v11.0.0.
Install
pip install axonflow-google-adk-plugin
Requires google-adk[mcp]>=2.0.0 and axonflow>=9.3.0 (AxonFlow Python SDK).
Quickstart (5 lines)
from google.adk.runners import InMemoryRunner
from google.adk.agents import LlmAgent
from axonflow_adk import AxonFlowPlugin
agent = LlmAgent(model="gemini-2.0-flash", name="loan_desk", instruction="...")
runner = InMemoryRunner(
agent=agent,
app_name="loan_desk",
plugins=[AxonFlowPlugin(
endpoint="http://localhost:8080",
client_id="loan-desk",
client_secret="secret-from-axonflow",
)],
)
Hook → AxonFlow endpoint mapping
| ADK hook | AxonFlow call | Deny shape |
|---|---|---|
before_model_callback |
pre_check |
LlmResponse with policy-denial text |
after_model_callback |
audit_llm_call |
never blocks (audit only) |
before_tool_callback |
check_tool_input |
{"error": "[AxonFlow] <reason>"} |
after_tool_callback |
check_tool_output |
redacted dict OR {"error": ...} on hard deny |
on_tool_error_callback |
audit_tool_call |
never blocks (audit only) |
on_user_message_callback |
no-op (v1) | n/a |
The on_user_message_callback hook is intentionally a no-op in v1 — returning
non-None Content there would silently replace the user's message, which is
the wrong tool for governance.
What a governed call does when it does not return an allow (a rejected credential, a quota, a server error, no answer) is in Failure semantics.
Failure semantics
A governed call is pre_check (before the model), check_tool_input (before a
tool) or check_tool_output (after a tool). When one does not return an allow,
what happens depends on one question: did the platform ANSWER?
| What happened | Model call | Tool call | Tool result | Setting |
|---|---|---|---|---|
| The platform answered with a policy deny | denied with the reason | denied with the reason | withheld, or replaced by the platform's masked content | none |
| The platform answered with an error: a rejected credential (401), a quota (429), a server error (5xx), or an answer that cannot be read | denied, with the error the SDK reports | denied | withheld | none: fail_open does not apply |
No answer: the connection failed, the call timed out (call_timeout_seconds, default 5s), or the circuit breaker is open |
proceeds ungoverned, with a WARNING notice | proceeds ungoverned, with a WARNING notice | passed through, with a WARNING notice | fail_open=True (the default); fail_open=False denies all three |
from axonflow_adk.plugin import AxonFlowPluginConfig
# Deny the call when AxonFlow cannot be reached, instead of running it ungoverned.
AxonFlowPlugin(endpoint=..., client_id=..., client_secret=...,
config=AxonFlowPluginConfig(fail_open=False))
- The notice. Every call that proceeds ungoverned logs a WARNING on the
axonflow_adk.pluginlogger, for exampleAxonFlow check_tool_input got no answer (ConnectError: All connection attempts failed); the call proceeds UNGOVERNED because fail_open is True. With no logging configured, Python prints WARNING records to stderr. - Why a 401, a 429 and a 5xx are treated alike. The
axonflowSDK reports them as the same error on the tool checks, without the HTTP status, so the plugin cannot tell them apart. A server error that answers therefore denies too; it is never read as an allow. That includes a load balancer or proxy in front of an AxonFlow that is down: its 502 or 503 is an answer, so calls are denied even withfail_open=True, which covers only a platform that cannot be reached at all. - A broken answer is not "no answer". An answer the server cuts off by
closing the connection partway, a connection it closes after the request
without answering, a port that does not speak HTTP, a proxy that refuses the
request and a malformed endpoint URL all deny. Two network failures follow
fail_openinstead: a connection that cannot be made at all (refused, DNS, TLS), because the plugin cannot tell a wrong host from an outage, and a connection reset (RST), even partway through an answer. - The cost of that strictness. A server or proxy that closes an idle keep-alive connection just as the SDK reuses it produces "server disconnected without sending a response", and that call is denied. The SDK keeps httpx's default 5-second keep-alive expiry, so this can happen in front of a server or proxy whose own keep-alive timeout is 5 seconds or less.
- The circuit breaker (default: open after 5 consecutive failures, recover after 30s; HALF_OPEN admits exactly one probe) counts only calls that got no answer. A refusal never opens the breaker, so a platform that refuses keeps being asked, and its refusals are never turned into ungoverned calls.
- The audit hooks (
audit_llm_call,audit_tool_call) never block.
Platform requests per tool call
One agent turn that calls one tool makes seven requests to AxonFlow (measured
through a real ADK Runner against AxonFlow v11.0.0):
| Request | Count | What it is for |
|---|---|---|
POST /api/policy/pre-check |
2 | one per model call: the call that chooses the tool, and the call that answers with its result |
POST /api/audit/llm-call |
2 | the audit record of each model call |
POST /api/v1/mcp/check-input |
1 | the tool's arguments, before the tool runs |
POST /api/v1/mcp/check-output |
1 | the tool's result, before the model sees it |
POST /api/v1/audit/tool-call |
1 | the audit record of the tool call |
Each governs or records a different model call or tool step, so none is dropped. Every one counts against any request rate or quota your deployment enforces, such as a Community SaaS Free-tier limit: size an agent's tool-call rate at a seventh of that request limit.
HITL approval flow — 4-step (platforms before v11.0.0)
AxonFlow v11.0.0 and later never hold a call on the planes this plugin drives. An approval-requiring call is refused with a
block_reasonbeginningapproval_required:("... refused rather than held"), and the plugin denies it like any other policy deny: no HITL row is created and nothing is polled, whateverenable_hitl_pollingis set to. The flow below applies to earlier platforms, which answer the exactrequire_approvalsentinel.
When a pre-v11 platform evaluates a policy to require_approval, the plugin
runs the full 4-step HITL flow by default (enable_hitl_polling=True):
before_model_callback / before_tool_callback
│
├─ STEP 1 — gate (pre_check / check_tool_input)
│ returns blocked, BlockReason == "require_approval"
│
├─ STEP 2 — POST /api/v1/hitl/queue
│ plugin calls client.create_hitl_request(request=HITLCreateInput(...))
│ returns approval_id (uuid)
│
├─ STEP 3 — GET /api/v1/hitl/queue/{approval_id}
│ polled every approval_poll_interval_seconds (default 2s);
│ local consecutive-failure counter (NOT the shared
│ breaker) so a polling outage can't disable governance
│ for other in-flight calls
│
└─ STEP 4 — terminal state:
├─ "approved" → return None (let LLM / tool proceed)
├─ "rejected" | "expired" → return deny short-circuit
├─ N consecutive poll failures → deny
└─ time > approval_max_wait_seconds → deny
The plugin's before_model_callback and before_tool_callback both run
this flow. Detection is an exact-string match against the pre-v11
require_approval sentinel. Substring matching previously false-positived
on any policy whose reason text contained the word "approval".
The 4-step flow fails closed: a queue row that cannot be created, a poll that keeps failing, a rejection, an expiry and a wait that runs out all deny. Approvals are safety-critical; defaulting to "allow" on an AxonFlow outage during an approval gate would defeat the gate.
Approving / rejecting out-of-band
When step 2 returns an approval_id, the plugin emits a single INFO log:
axonflow hitl AWAITING APPROVAL: request_id=<uuid>; approve via
POST /api/v1/hitl/queue/<uuid>/{approve|reject}
The reviewer (UI, Slack bot, internal portal) posts the decision via:
# Approve
curl -X POST $AXONFLOW_ENDPOINT/api/v1/hitl/queue/<approval_id>/approve \
-H 'Content-Type: application/json' \
-d '{"reviewer_id":"compliance","reviewer_email":"compliance@bank.example"}'
# Reject (same shape)
curl -X POST $AXONFLOW_ENDPOINT/api/v1/hitl/queue/<approval_id>/reject \
-H 'Content-Type: application/json' \
-d '{"reviewer_id":"compliance","reviewer_email":"compliance@bank.example"}'
Opting out — deny-fast mode
Set enable_hitl_polling=False on the config to short-circuit
require_approval immediately without enqueuing a row. The host app
then drives its own approval workflow.
Authenticating in enterprise mode
ADK does not carry a first-class user_token concept. To propagate the
end-user identity AxonFlow's enterprise-mode policy enforcement requires,
set state["axonflow_user_token"] to a valid JWT on the session BEFORE
calling runner.run_async(...):
session = runner.session_service.create_session(
app_name="loan_desk", user_id="cust-001", session_id="sess-A",
)
session.state["axonflow_user_token"] = generate_axonflow_jwt(user_id="cust-001")
For community mode (no tenant signing key), leave the state key
unset; the plugin will use config.default_user_token (default
"anonymous").
A rejected token is a 401, and a 401 denies every governed model and tool call (see Failure semantics).
MCP toolset helper
from google.adk.agents import LlmAgent
from axonflow_adk import axonflow_mcp_toolset
agent = LlmAgent(
model="gemini-2.0-flash",
name="postgres_governed",
instruction="Answer questions about the production DB.",
tools=[axonflow_mcp_toolset(
endpoint="http://localhost:8080",
client_id="my-app",
client_secret="secret",
)],
)
Client identification
Every call this helper makes carries X-Axonflow-Client: google-adk-plugin/<version>, so AxonFlow can tell ADK adoption apart from any other caller. The version comes from the installed package's own metadata.
What this is and is not. It is attribution on a request the platform already receives — no additional request is made, and this integration sends no heartbeat or telemetry ping of its own. It is never used for authentication: the platform authenticates on the Authorization header, so a missing or mangled value cannot fail a call. Nothing about your prompts, tool arguments, policy data, or identity is added.
The header is applied after extra_headers, so a caller cannot make this integration claim to be something else.
Run the example
pip install axonflow-google-adk-plugin
export GOOGLE_API_KEY=...
export AXONFLOW_ENDPOINT=http://localhost:8080
export AXONFLOW_CLIENT_ID=loan-desk
export AXONFLOW_CLIENT_SECRET=...
python -m examples.loan_disbursement_agent
# or: python examples/loan_disbursement_agent.py
Tests
pip install -e ".[dev]"
pytest tests/ -v
Documentation
Full integration guide: docs.getaxonflow.com/docs/integration/google-adk
License
MIT. See LICENSE.
Metadata
Release files for axonflow-google-adk-plugin 1.4.0
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 |
|---|---|---|---|---|
| axonflow_google_adk_plugin-1.4.0.tar.gz | 55.0 kB | Without provenance | Details for axonflow_google_adk_plugin-1.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| axonflow_google_adk_plugin-1.4.0-py3-none-any.whl | Python 3 | none | any | Details for axonflow_google_adk_plugin-1.4.0-py3-none-any.whl |
Total release size: 90.3 kB
Release files / axonflow_google_adk_plugin-1.4.0.tar.gz
| Download URL | axonflow_google_adk_plugin-1.4.0.tar.gz |
|---|---|
| Size | 55.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1a86001a5deed1d6e81ffce3017e2bef3e6243e1e6901fbb6bd30e8e796b7abd
|
|
BLAKE2b-256 checksum How to use checksums |
1452b25263963bec79828892621ab513a4c1419381b03662bc4fbfc4aa67c192
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.14
|
Release files / axonflow_google_adk_plugin-1.4.0-py3-none-any.whl
| Download URL | axonflow_google_adk_plugin-1.4.0-py3-none-any.whl |
|---|---|
| Size | 35.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c452d81c3e031343c857611397d11af13b5f22ba2c61b350b778423a24a21e18
|
|
BLAKE2b-256 checksum How to use checksums |
89586f89ecb5190ee2394bd09d66a87d0629701adaa56d697c3696937b53a2eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.14
|
Security for axonflow-google-adk-plugin 1.4.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.