aiyoplane-google-adk

AEAP Composition Boundary Adapter for Google ADK.

A thin wrapper that attaches the AEAP Runtime Decision Point (RDP) to Google ADK's tool invocation surface. Consequential tool executions — including code execution and sandboxed environment operations — produce independently verifiable Execution Receipts.

pip install aiyoplane-google-adk

Why Google ADK + AEAP

Google ADK already reaches into agent runtime code execution and sandboxed environments. Those are prime AEAP territory: code execution, external API calls, cloud resource mutations, and economic actions are all consequential and benefit from the "before this crosses the boundary, authorize it" property AEAP provides. ADK owns the runtime; AEAP owns the authorization semantics at the consequential-execution boundary. Clean architectural separation.

See the AEAP specification §9.

Minimal usage — decorator

from google.adk.agents import Agent
from aiyoplane_mcp_authz import create_aiyo_mcp_authz, create_local_rdp
from aiyoplane_google_adk import aiyo_tool, BlockedByPolicy, EscalationRequired

policy = {
    "rules": [
        {"action_type": "code_execution", "language": "python", "effect": "allow"},
        {"action_type": "code_execution", "effect": "escalate"},
    ]
}

authz = create_aiyo_mcp_authz(
    rdp=create_local_rdp(policy=policy),
    tool_config={
        "run_code": {"aiyo_gated": True, "action": {"type": "code_execution"}},
    },
)

@aiyo_tool(
    authz=authz,
    tool_name="run_code",
    intent_builder=lambda kw: {
        "type": "code_execution",
        "language": kw["language"],
        "code_hash": compute_hash(kw["code"]),
    },
)
def run_code(language: str, code: str) -> str:
    """Execute code in a sandbox."""
    return sandbox_exec(language, code)

agent = Agent(
    name="coder",
    model="gemini-1.5-pro",
    tools=[run_code],
    instruction="Help the user execute code safely.",
)

Minimal usage — function form

from aiyoplane_google_adk import wrap_tool_function

def run_code(language: str, code: str) -> str:
    return sandbox_exec(language, code)

guarded = wrap_tool_function(
    run_code,
    authz=authz,
    tool_name="run_code",
    intent_builder=lambda kw: {"type": "code_execution", "language": kw["language"]},
)

Composition Boundary — what the adapter actually does

1. Intent construction via intent_builder(tool_kwargs).
2. RDP evaluation via aiyoplane-mcp-authz.
3. Verdict composition. ALLOW → inner function runs; ESCALATE → EscalationRequired; BLOCK → BlockedByPolicy.
4. Fail-closed default on every ambiguous condition.

Local vs. hosted RDP

from aiyoplane_mcp_authz import create_local_rdp, create_hosted_rdp

# Development:
authz = create_aiyo_mcp_authz(rdp=create_local_rdp(policy=policy), tool_config={...})

# Production:
authz = create_aiyo_mcp_authz(
    rdp=create_hosted_rdp(api_key="aiyo_live_..."),
    tool_config={...},
)

API reference

aiyo_tool(*, authz, tool_name, intent_builder, attach_receipt=False)

Decorator form.

wrap_tool_function(fn, *, authz, tool_name, intent_builder, attach_receipt=False)

Function form.

Exceptions

• AiyoGoogleADKError, AdapterConfigError, BlockedByPolicy, EscalationRequired

License

Apache License 2.0.

Links

• AEAP specification: https://github.com/aiyoplane/aeap
• Underlying implementation: aiyoplane-mcp-authz
• Trust surface: https://aiyoplane.com/trust
• Issues: https://github.com/aiyoplane/google-adk/issues

Google, Google ADK, Gemini, and Google Cloud are trademarks of Google LLC. This package is an independent AEAP Composition Boundary Adapter and is not affiliated with or endorsed by Google LLC.

Verify First. Execute Second.