Google ADK Governance Adapter — PolicyEvaluator implementation ready for testing

[imran-siddique]

Following the discussion on google/adk-python#4764 about governance callbacks for ADK agents, we've shipped an initial implementation.

What's new

New package: adk-agentmesh (source)

Implements the PolicyEvaluator protocol from @sunilp's GovernancePlugin proposal (#4897), backed by our toolkit's policy engine:

• ADKPolicyEvaluator — YAML-configurable policy engine for ADK agents
• GovernanceCallbacks — wires into ADK's before/after tool/agent callbacks
• DelegationScope — monotonic scope narrowing for sub-agent delegation
• Structured audit events — AuditEvent + AuditHandler protocol with pluggable sinks

ADK Lifecycle Mapping

ADK Hook	Governance Check
before_tool_callback	Policy evaluation, rate limiting, tool blocking, approval escalation
after_tool_callback	Audit logging
before_agent_callback	Delegation scope + depth check
after_agent_callback	Delegation audit

Quick Start

from adk_agentmesh import ADKPolicyEvaluator, GovernanceCallbacks

evaluator = ADKPolicyEvaluator.from_config('examples/policies/adk-governance.yaml')
callbacks = GovernanceCallbacks(evaluator)

Sample policy: examples/policies/adk-governance.yaml

Looking for feedback

1. Does the PolicyEvaluator interface align with what @sunilp and @aeoess proposed?
2. Any additional ADK lifecycle hooks we should cover?
3. Should this ship as a standalone PyPI package or stay as a contrib integration?

cc @sunilp @aeoess @razashariff — would love your input since you drove the design discussion on the ADK side.

33 tests passing. Community preview — feedback welcome.

[sunilp]

Thanks @imran-siddique — this is fast execution, and the fact that you built it around the PolicyEvaluator protocol is exactly the interoperability outcome I was hoping for.

On your three questions:

1. Interface alignment — the lifecycle mapping table looks right. before_tool_callback → policy evaluation and before_agent_callback → delegation scope check is the same mapping I used in the GovernancePlugin. Two things to verify:

• Does ADKPolicyEvaluator return a PolicyDecision with structured reason + evaluator name? That's important for audit — you need to know which policy engine denied a call and why, not just pass/fail.
• Does the delegation scope enforce monotonic narrowing? (i.e., a sub-agent's scope must be a subset of its parent's — it can never escalate). This is the core invariant in both LDP and the GovernancePlugin.

2. Additional hooks — the four you have (before/after for tool and agent) cover the critical path. Two additions worth considering:

• before_model_send — for prompt-level governance (PII detection before the prompt hits the LLM, cost budget checks before inference). The GovernancePlugin doesn't cover this yet either, but it's the natural next enforcement point.
• Error callbacks (on_tool_error, on_agent_error) — for audit completeness. You want the audit trail to capture failures, not just successes.

3. Packaging — standalone PyPI package. It decouples your release cycle from the toolkit's, and makes adoption easier for teams that want ADK governance without the full AGT stack. Same reasoning behind keeping the GovernancePlugin in google/adk-python-community rather than bundling it.

One concrete suggestion: if both adk-agentmesh and the GovernancePlugin ship with compatible PolicyEvaluator interfaces, users could swap backends without changing their ADK integration code. Worth aligning the return types (PolicyDecision schema) so an APS-backed evaluator, an AGT-backed evaluator, and a simple YAML evaluator are all drop-in replacements.

Happy to test once it's on PyPI.

[imran-siddique]

Thanks @sunilp -- really thoughtful feedback. Let me address each point:

1. Interface alignment

• Yes, ADKPolicyEvaluator returns PolicyDecision with structured reason, matched_rule (which policy triggered), verdict (allow/deny/escalate), and metadata dict. The audit trail captures which rule denied and why.
• Yes, DelegationScope.narrow() enforces monotonic narrowing -- child tools must be subset of parent, max_tool_calls can only decrease, max_depth decrements, and read_only is sticky. This is tested in the suite.

2. Additional hooks -- great suggestions:

• before_model_send -- agreed, natural next enforcement point. We have prompt injection detection and PII redaction that would slot in here. Will add once ADK exposes this hook.
• on_tool_error / on_agent_error -- good call for audit completeness. Will add to next iteration.

3. Packaging -- agreed, standalone PyPI package (adk-agentmesh).

On PolicyDecision schema alignment -- key insight. If we align return types, any PolicyEvaluator backend (APS, AGT, YAML, LDP) becomes a drop-in replacement. Happy to adjust fields to match what you and @aeoess have. Will publish to PyPI and share here once it's up.

[aeoess]

@imran-siddique — congrats on shipping this. Concrete answers to your three questions:

1. PolicyEvaluator interface alignment

Yes, it aligns well. I just posted APS's full PolicyDecision schema on google/adk-python#4910 for comparison. The core fields map cleanly:

• verdict → we use permit/deny/narrow, you use allow/deny/escalate. Semantically equivalent. Either naming works.
• reason → identical
• matched_rule → APS has principlesEvaluated[] (array of principle IDs), which is richer but collapses to a single rule reference trivially

The one structural difference: APS wraps the decision in an Ed25519 signature as part of a 3-artifact chain (intent → decision → receipt). For the common interface, I proposed a minimal PolicyDecision with a metadata: dict for protocol-specific extensions like signatures. Your YAML engine produces the decision; APS can wrap it with the cryptographic layer. Clean separation.

2. Additional lifecycle hooks

Two suggestions:

• before_model_send — you mentioned this in your #4764 reply. APS would use this for prompt injection detection and data-terms compliance checking. We just shipped Module 36A (Data Source Registration & Access Receipts, 894 tests) which adds terms enforcement at the data access boundary. The before_model_send hook is where you'd check whether the data entering the model context is permitted under the source's terms.
• When sunilp's mandatory callback tier (#4910) ships, the governance hooks should move to Phase 2 (mandatory). This is the main gap today — your callbacks can be silently bypassed by an earlier plugin returning non-None.

3. Standalone PyPI

Standalone. Three reasons: (a) composability — users should be able to pip install adk-agentmesh without pulling the full AGT, (b) versioning independence — ADK's release cycle shouldn't gate your governance updates, (c) ecosystem signal — a standalone package that appears in pip search for "adk governance" is discoverability you lose inside a monorepo.

Would be interested in testing APS as an alternative backend for your ADKPolicyEvaluator. The mapping: your before_tool_callback calls APS's evaluateIntent(), which returns a signed PolicyDecision. Your after_tool_callback calls APS's recordDataAccess() for the audit trail. The policy engine swaps out; the ADK integration stays the same.

[kinthaiofficial]

Great to see a governance adapter for ADK. The PolicyEvaluator protocol is the right abstraction — declarative YAML policies evaluated before tool execution is cleaner than embedding governance logic in every agent.

From running governance middleware for 31 agents in production (KinthAI, built on OpenClaw):

The Most-Triggered Policy: Budget Enforcement

In our deployment, budget checks outnumber access-control checks 10:1. Every tool call gets: "does this agent have enough remaining budget?" We use pessimistic allocation (deduct ceiling before execution, credit back after). This turns economic limits into hard governance boundaries — no amount of clever prompting bypasses remaining_budget < estimated_cost.

If the PolicyEvaluator supports custom policy types, budget enforcement should be a first-class built-in:

policies:
  - type: budget_enforcement
    mode: pessimistic
    hierarchy: [namespace, user, agent, conversation]

Details: Your AI Agent Needs a Wallet

Delegation Chain Context in Policy Evaluation

For multi-agent ADK deployments, the policy engine needs the full delegation chain (parent → child → grandchild) to evaluate capability narrowing. A sub-agent spawned by a high-trust orchestrator should have different policies than the same agent spawned by an untrusted external caller. The PolicyEvaluator should accept a delegation chain hash alongside the tool call context.

Behavioral Drift Detection

Beyond per-action static policies, we track KL divergence on each agent's action distribution. An agent that shifts from 90% reads to 50% writes triggers an alert even when every action passes policy. The audit trail from the governance adapter is the perfect data source for this.

More: What We Learned Running 221 Agents