Model Armor plugin for ADK¶

Supported in ADKPython v2.8.0

Model Armor is a Google Cloud service that inspects text for prompt injection and jailbreak attempts, harmful content, and sensitive data. You define what to look for in a server-side policy called a template, and the service returns a verdict for each piece of text you send it. The ModelArmorPlugin class ships with ADK and calls that service from the model callbacks. It screens user input before the model sees it and model output before or during delivery, replacing matched content with a safe message.

Use cases¶

Prompt injection and jailbreak defense: Screen every user turn against a prompt template before the model acts on it, so a detected attempt is blocked instead of the agent obeying it.
Sensitive data and harmful content filtering: Screen model output against a response template to catch answers that leak data or breach content policy before delivery.
Uniform policy across agents: Register one plugin on the App and every agent it runs inherits the same screening, including live voice agents.

Prerequisites¶

A Google Cloud project with the Model Armor API enabled, and at least one template created. See the Model Armor documentation.
Application Default Credentials with access to Model Armor, set up with gcloud auth application-default login.
ADK >= 2.8.0

Installation¶

pip install 'google-adk[gcp]'

There is no separate model-armor extra. The plugin ships with ADK, and the gcp extra supplies the google-cloud-modelarmor client it needs.

Use with agent¶

Register the plugin on an App with the templates it should screen against:

from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.integrations.model_armor import ModelArmorConfig
from google.adk.integrations.model_armor import ModelArmorPlugin

agent = LlmAgent(
    model="gemini-flash-latest",
    name="screened_agent",
    instruction="You are a helpful assistant.",
)

app = App(
    name="model_armor_demo",
    root_agent=agent,
    plugins=[
        ModelArmorPlugin(
            config=ModelArmorConfig(
                prompt_template_name=(
                    "projects/my-project/locations/us-central1/templates/my-prompt-template"
                ),
                response_template_name=(
                    "projects/my-project/locations/us-central1/templates/my-response-template"
                ),
            )
        )
    ],
)

Template names must be full resource paths in the form projects/{project}/locations/{location}/templates/{template}. The plugin reads the location out of the path to pick a regional endpoint, so both templates must live in the same region. A short name or a mismatched pair raises ValueError when you construct the plugin.

Each template is optional, and setting only one screens only that direction:

config = ModelArmorConfig(
    prompt_template_name=(
        "projects/my-project/locations/us-central1/templates/my-prompt-template"
    ),
)

Screening covers the most recent user content and the model's reply. Tool results reach the request as a function_response part, which the plugin skips.

Configuration¶

Option	Default	Description
`prompt_template_name`	`None`	Template used to screen user input. Unset means input is not screened.
`response_template_name`	`None`	Template used to screen model output. Unset means output is not screened.
`input_blocked_message`	See below	Replacement text shown when user input is blocked.
`output_blocked_message`	See below	Replacement text shown when model output is blocked.
`block_on_screening_failure`	`True`	Whether to block content that could not be screened.

Both messages default to "I'm sorry, but I can't help with that request.", and you must set at least one template name or the config raises a validation error.

Screening fails when the Model Armor call raises, or when the service returns anything other than a SUCCESS verdict. The default blocks unscreened content. Set block_on_screening_failure=False to keep the agent answering while Model Armor is unavailable.

A blocked turn carries custom_metadata['model_armor_blocked'], so an application can tell a policy block from a real answer.