> ## Documentation Index
> Fetch the complete documentation index at: https://agentcontrol-abhi-agent-control-auth-contract-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Google ADK

> Integrate Agent Control guardrails with Google ADK using the packaged plugin, callbacks, or decorators.

Complete guide to integrating Agent Control safety guardrails with Google Agent Development Kit (ADK) applications.

## Overview

Agent Control supports three Google ADK integration patterns:

1. **Plugin pattern** - Recommended packaged integration using `AgentControlPlugin`
2. **Callback pattern** - Lower-level manual wiring with ADK lifecycle hooks
3. **Decorator pattern** - Tool-only protection using Agent Control's `@control()` decorator

The packaged plugin should be your default choice. It gives you framework-native model and tool protection with the least boilerplate, while callbacks and decorators remain useful for advanced or narrower use cases.

## Quick Decision Guide

| Pattern   | Best for                                              | Model protection | Tool protection | Setup complexity | Code changes required                                             | Step registration                                                      | Execution modes              |
| --------- | ----------------------------------------------------- | ---------------- | --------------- | ---------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------- |
| Plugin    | Default ADK integration with minimal code changes     | Yes              | Yes             | Low              | Attach one plugin to your ADK app                                 | `plugin.bind(root_agent)` can discover and register LLM and tool steps | Server or SDK-local          |
| Callbacks | Manual lifecycle control and custom callback behavior | Yes              | Yes             | Medium           | Wire ADK lifecycle hooks and shape replacement responses yourself | Manual registration alongside your callback wiring                     | Server or SDK-local (manual) |
| Decorator | Explicit tool-only protection                         | No               | Yes             | Low to medium    | Wrap each protected tool with `@control()`                        | Automatic for decorated tool functions                                 | Server or SDK-local          |

## Install

Install the Python SDK with Google ADK support:

```bash theme={null}
pip install "agent-control-sdk[google-adk]"
```

## Plugin Pattern

Use `AgentControlPlugin` when you want the attach-once, framework-native ADK path.

### What the plugin gives you

* pre/post-model guardrails through the ADK model callback lifecycle
* pre/post-tool guardrails through the ADK plugin lifecycle
* optional `plugin.bind(root_agent)` for step discovery and registration
* the same app code working with server-side or sdk-local control execution

### Example

```python theme={null}
import agent_control
from agent_control.integrations.google_adk import AgentControlPlugin
from google.adk.agents import LlmAgent
from google.adk.apps import App

agent_control.init(
    agent_name="google-adk-plugin",
    agent_description="Google ADK app protected by Agent Control",
)

root_agent = LlmAgent(
    name="root_agent",
    model="gemini-2.5-flash",
    tools=[get_current_time, get_weather],
)

plugin = AgentControlPlugin(agent_name="google-adk-plugin")
plugin.bind(root_agent)

app = App(name="my_agent", root_agent=root_agent, plugins=[plugin])
```

### Use the plugin when

* you want the recommended ADK integration path
* you need both model and tool protection
* you want to avoid manual callback wiring
* you want one integration that can run with either server-side or sdk-local controls

[Google ADK Plugin example](/examples/google-adk-plugin)

## Callback Pattern

Use ADK callbacks when you want direct control over each lifecycle hook and are comfortable wiring the integration manually.

### What callbacks give you

* model-stage protection through `before_model_callback` and `after_model_callback`
* tool-stage protection through `before_tool_callback` and `after_tool_callback`
* explicit conversion of Agent Control decisions into ADK-friendly replacement responses
* server-side or sdk-local execution depending on the evaluation helper you call from those hooks

### Use callbacks when

* you need custom lifecycle behavior around each callback stage
* you want full manual control over payload shaping and response handling
* you are already committed to callback-based ADK wiring

[Google ADK Callbacks example](/examples/google-adk-callbacks)

## Decorator Pattern

Wrap tool functions with `@control()` when you only need tool protection and want explicit guarded functions in application code.

### What decorators give you

* pre/post-tool validation on decorated ADK tools
* automatic step registration from decorated functions
* optional sdk-local execution without changing agent code

### Use decorators when

* you only need tool protection
* you want explicit, per-tool protection in code
* you do not need model-stage checks

[Google ADK Decorator example](/examples/google-adk-decorator)

## Execution Modes

### Server-side

* centralized controls, runtime updates, and auditability
* available with the plugin, callbacks, and decorator patterns
* the callbacks example in this repo uses server execution by design, but the callback pattern itself is not limited to server execution

### SDK-local

* lower latency and offline-friendly evaluation after controls are fetched
* available with the plugin and decorator patterns directly, and with callbacks when your callback implementation routes through Agent Control's local-aware evaluation helpers
* useful when you want to keep ADK app code unchanged while changing where controls run

## Recommended Starting Point

If you are starting fresh with Google ADK, begin with the packaged plugin:

* it is the least invasive integration
* it covers both model and tool stages
* it keeps callbacks and response shaping inside the packaged integration instead of your app code

Move to callbacks only when you need custom lifecycle behavior that the packaged plugin does not expose. Use decorators when tool-only protection is enough.

## Related Docs

* [Google ADK Plugin example](/examples/google-adk-plugin)
* [Google ADK Callbacks example](/examples/google-adk-callbacks)
* [Google ADK Decorator example](/examples/google-adk-decorator)