Google ADK security guide

How do you secure Google ADK?

To secure Google ADK, screen text before the runner starts and register a before-tool callback that can skip the tool. JavaScript uses guardPlugin on the Runner. Python uses guard_plugin on the Runner, or guard_tool on the agent when you hold the agent instead. Authorize resources inside the tool service and use a server-resolved identity for the actor and for per-user limits. Consume the runner's event stream when testing; creating an iterator alone does not execute a run.

Use this guide on Google Agent Development Kit (ADK) 2.x: TypeScript @google/adk and Python google-adk.

ADK builds an LlmAgent from a model, an instruction, and a list of tools. The runner drives the loop: the model reads user text, decides to call a FunctionTool, and ADK executes that tool. Prompt injection is when untrusted text – a pasted ticket, a retrieved document, a tool result from an earlier turn – steers that decision toward a side effect you never intended.

Arcjet Guard is a runtime policy layer for AI agents. You define rules – prompt-injection detectors, rate limits, PII checks, allowlists – and a published remote policy, and Guard allows or denies inbound text and tool calls before side effects run. JavaScript examples use @arcjet/guard/google-adk/v2. Python examples use arcjet.guard.google_adk from arcjet[google-adk]. Pick one language. Don't mix the two adapters on one agent.

This page is Google ADK, not Google GenAI (@google/genai). HTTP request protection on a route never sees runAsync or run_async, so a WAF in front of the app doesn't cover any of this.

Use this checklist to review your application:

• Patch and lock dependencies. Stay on ADK 2.x and import the versioned JavaScript path.
• Keep model keys off the client and out of session state.
• Screen user text with a direct guard() call before the runner.
• Don't treat confirmation, or ADK SecurityPlugin, as a policy gate.
• Gate every tool call before it runs. Put the Runner plugin first in plugins.
• Deny by returning the deny dict. Never throw or raise. Never return undefined, None, or {} on error.
• Pass actor and typed inputs from server state when a remote policy needs them. Never from a model-produced argument.
• Correlate on an ID you own. Never on an ADK-generated one.
• Catch issues in the editor and in CI before they ship.

For the Guard helpers used in the examples, see the Google ADK agent guard.

How do Google ADK's built-in controls compare with Arcjet Guard?

ADK can pause for a person and it can run its own SecurityPlugin. Neither is a remote policy that denies a tool before execute runs.

The Runner plugin fails closed. If Guard cannot be evaluated, the callback returns the deny dict with reason: "ERROR" instead of calling the tool. A direct guard() call still fails open, which is why inbound screening also checks hasFailedOpen() / has_failed_open().

How do you keep Google ADK dependencies safe?

Apply patches on a schedule you actually keep, and out of band for a critical advisory. Commit a lockfile so every environment installs the same graph, and turn on Dependabot, Renovate, or an equivalent bot for npm. Run npm audit in CI and fail on known high-severity issues you haven't waived.

@google/adk is an optional peer of @arcjet/guard (>=2 <3), not a dependency of it. If ADK is already in your project at that range, install @arcjet/guard on its own so your existing pins don't move. The JavaScript integration requires Node.js 22.21 or later, or Node.js 24.5 or later. It does not support the 23.x line.

1
npm install @arcjet/guard @google/adk

Import from the versioned path. The version segment is the ADK major, and there is no unversioned alias – @arcjet/guard/google-adk does not resolve.

1
import { guardPlugin, googleAdkContext } from "@arcjet/guard/google-adk/v2";

Python installs the extra, which depends on google-adk>=2.0.0,<3. CPython 3.10 or later.

1
pip install "arcjet[google-adk]"

1
from arcjet.guard.google_adk import google_adk_context, guard_plugin, guard_tool

Pin the ADK package so a 3.x major can't land under that import. An ADK major is the thing most likely to move the tool-call callback contract, and the JavaScript adapter path is versioned precisely so the mismatch is a resolution error rather than a silently skipped gate. See trivial packages and dependency confusion.

How do you manage Google ADK secrets?

Model credentials – GOOGLE_API_KEY, a Vertex AI service account, ARCJET_KEY – belong on the server, loaded at process start. Launch one Arcjet client at module scope and reuse it, rather than constructing one per request. Python sync servers (Flask, Django) use launch_arcjet_sync instead of launch_arcjet.

1
import { launchArcjet } from "@arcjet/guard";
2

3
export const arcjet = launchArcjet({ key: process.env.ARCJET_KEY! });

Don't put credentials in ADK session state. Session state is read back into model context on later turns, which makes it reachable by anything that can influence the transcript. It is for caller-owned identifiers – a conversation ID, a tenant ID – not secrets.

Don't log raw tool arguments or the raw prompt. Tool arguments are model-generated from user text, so they carry whatever the user put in. See storing secrets in environment variables and redacting sensitive data from logs.

How do you screen inbound Google ADK text?

Neither adapter exports an inbound helper. Screen in application code before runner.runAsync or runner.run_async, while the user's text is still a string you control and not yet part of the agent's turn history. The Python call is in How do you secure Google ADK in Python?.

Direct guard() fails open: if Guard can't be evaluated, the call returns ALLOW. That means an ALLOW on its own is not proof the rules ran. Gate on decision.hasFailedOpen() when this call site must fail closed. On a deny, don't call runAsync at all.

1
import { detectPromptInjection } from "@arcjet/guard";
2
import { googleAdkContext } from "@arcjet/guard/google-adk/v2";
3
import { arcjet } from "./arcjet.js";
4

5
const inbound = detectPromptInjection();
6
const appContext = { sessionId: conversationId };
7

8
const decision = await arcjet.guard({
9
  label: "message.received",
10
  rules: [inbound(userText)],
11
  ...googleAdkContext(appContext),
12
});
13

14
if (decision.conclusion === "DENY" || decision.hasFailedOpen()) {
15
  throw new Error("message blocked");
16
}

Note the field name. A direct guard() call takes label. A framework wrapper such as guardPlugin takes action for the same slug. Passing label to a wrapper is a type error, and passing action to guard() won't name the event.

A clean inbound score does not authorize a tool call. Inbound screening decides whether the model sees the prompt; it says nothing about whether the refund tool may run. That is the second control, and it is separate. See prompt injection detection.

Why isn't requestConfirmation a Google ADK security policy?

ADK can pause a run and wait for a person. requireConfirmation on a tool and requestConfirmation in a handler are human-in-the-loop confirmation. Python spells the same controls require_confirmation and request_confirmation. They're useful when someone must review context, and they are not a policy gate: they ask, they don't decide, and nothing evaluates a rule.

This is the same trap under different names across frameworks – LangChain humanInTheLoopMiddleware, Strands event.interrupt(), Genkit interrupt(), OpenAI needsApproval, Mastra requireApproval, TanStack needsApproval, Cloudflare Think needsApproval, Claude canUseTool. There is no approval helper on either ADK adapter.

ADK's own SecurityPlugin is likewise not the Arcjet policy gate. Don't wire Arcjet into it, and don't express a denial by pausing for a human. Policy sits on the before-tool callback only. See human approval is not a security policy and needsApproval and interrupt() are not a policy.

How do you gate Google ADK tool calls?

JavaScript has no guardTool. Wrapping FunctionTool.execute is the wrong gate, because ADK's skip point is the Runner callback, not the handler. The gate is guardPlugin, a BasePlugin you pass on new Runner({ plugins }) or new InMemoryRunner({ plugins }). Python's guard_tool is a before_tool_callback, not a handler wrap. That section is below.

Its beforeToolCallback returns one of two things. A deny dict – an ArcjetDenialResult – skips the tool, and execute never runs. undefined executes the tool. It never throws.

Put it first in the plugin list. beforeToolCallback uses the first dictionary any plugin returns. If another plugin returns a dict ahead of Arcjet, Guard never runs and the gate is silently gone.

1
import { localDetectSensitiveInfo, tokenBucket } from "@arcjet/guard";
2
import { guardPlugin } from "@arcjet/guard/google-adk/v2";
3
import { FunctionTool, InMemoryRunner, LlmAgent } from "@google/adk";
4
import { z } from "zod";
5
import { arcjet } from "./arcjet.js";
6

7
// Resolve authenticatedUser from the server session before constructing tools.
8
const lookupLimit = tokenBucket({
9
  bucket: "lookups",
10
  refillRate: 10,
11
  intervalSeconds: 60,
12
  maxTokens: 10,
13
});
14
const detectPii = localDetectSensitiveInfo({
15
  deny: ["EMAIL", "PHONE_NUMBER", "IP_ADDRESS", "CREDIT_CARD_NUMBER"],
16
});
17

18
const lookupOrderInput = z.object({
19
  orderNumber: z.string(),
20
  note: z.string(),
21
});
22

23
const lookupOrder = new FunctionTool({
24
  name: "lookup_order",
25
  description: "Look up an order by number",
26
  parameters: lookupOrderInput,
27
  execute: ({ orderNumber, note }) => ({
28
    orderNumber,
29
    note,
30
    status: "shipped",
31
  }),
32
});
33

34
const agent = new LlmAgent({
35
  name: "order_agent",
36
  model: "gemini-flash-latest",
37
  instruction: "Look up orders with lookup_order.",
38
  tools: [lookupOrder],
39
});
40

41
const runner = new InMemoryRunner({
42
  agent,
43
  appName: "orders",
44
  plugins: [
45
    guardPlugin(arcjet, {
46
      action: "order.looked-up",
47
      sessionId: conversationId,
48
      onGuardError: "deny",
49
      // Server session, resolved before the run. Never a tool argument.
50
      actor: authenticatedUser.id,
51
      rules: ({ toolName, input }) => {
52
        if (toolName !== "lookup_order") {
53
          return [];
54
        }
55
        const { orderNumber, note } = lookupOrderInput.parse(input);
56
        return [
57
          lookupLimit({ key: authenticatedUser.id, requested: 1 }),
58
          detectPii(note),
59
        ];
60
      },
61
    }),
62
  ],
63
});

guardPlugin is Runner-wide, so rules receives { toolName, input } for every tool the agent calls. Branch on toolName and return [] for the tools you aren't scoring. The guard call still happens, which is what puts the decision in the Console; returning [] only means you submitted no SDK rules for it.

Re-parse input with the tool's own schema rather than trusting its shape. The model produced those arguments, so they are untrusted input in the same sense the prompt was.

Key a per-user rate limit on authenticatedUser.id, resolved by your server before the run. The model supplies orderNumber, so it is a resource selector, not a trusted identity; changing it must not reset the caller's budget. Authorize access to the selected order in the tool service.

Scan the free-text fields – a note, a reason, a body. An opaque orderNumber or tool-call ID won't trip email, phone, card, or IP detection, so passing it to localDetectSensitiveInfo adds cost and no coverage. That helper runs on a local model backend, so the text never leaves your process. See detecting and redacting PII in LLM inputs and outputs.

What does a Google ADK denial look like?

On DENY the original tool never runs and the model receives an ArcjetDenialResult. This is a returned value, not a thrown error – a throw is the wrong envelope, and ADK will surface it as a crash instead of a result the model can read.

1
import type { ArcjetDenialResult } from "@arcjet/guard/google-adk/v2";
2

3
const denial: ArcjetDenialResult = {
4
  arcjetDenied: true,
5
  reason: "RATE_LIMIT", // or PROMPT_INJECTION, SENSITIVE_INFO, ERROR
6
  message:
7
    "Arcjet denied this call (RATE_LIMIT). It may be retried after 30 seconds.",
8
  retryable: true,
9
  retryAfterSeconds: 30,
10
};

Rate-limit policy denials can set retryable: true with retryAfterSeconds. Prompt-injection and sensitive-information denials must not be retried. An unavailable evaluation is a separate case: the helper returns reason: "ERROR" with a five-second retry hint. Bound retries in application code and never retry by bypassing the guard.

guardPlugin defaults to onGuardError: "deny". When Guard can't be evaluated, the callback returns the deny dict with reason: "ERROR", retryable: true, and retryAfterSeconds: 5. It never throws on that path, and it never returns undefined – returning undefined on an error would execute the tool without a decision, which is the failure mode the default exists to prevent.

Set onGuardError: "allow" only where executing without a complete security decision is genuinely acceptable, such as a lookup whose data is safe to disclose even without a Guard decision. Remember that direct guard() still fails open regardless, which is why the inbound example gates on hasFailedOpen().

Python guard_tool and guard_plugin use the same deny dict. Return None to execute. Never return {}: an empty mapping is falsy in ADK's callback chain, so the tool would run. They default to on_guard_error="deny", never raise, and never return None on that error path.

How do you secure Google ADK in Python?

The Python adapter is arcjet.guard.google_adk. It is not @arcjet/guard/google-adk/v2. Don't pass guardPlugin from the JavaScript package to a Python Runner, and don't pass guard_plugin the other way.

guard_plugin is the Runner-wide gate. Pass it first on InMemoryRunner or Runner plugins. action defaults to {tool_name}.invoked. guard_tool assigns LlmAgent.before_tool_callback. It is not a FunctionTool wrap, and action is required. Plugins run first. Attaching both to the same tools calls Guard twice. If you must stack, list the guard_tool names in exclude on guard_plugin only.

The rules callable receives the tool-call envelope: model-produced arguments plus tool_name. Read call["order_number"], not call["input"]. Key a limit on the authenticated user id you resolved before the run. order_number selects a resource. It is not an identity, and it is not an actor.

1
import os
2

3
from google.adk.agents import LlmAgent
4
from google.adk.runners import InMemoryRunner
5
from google.adk.tools import FunctionTool
6
from google.genai import types
7
from arcjet.guard import (
8
    DetectPromptInjection,
9
    LocalDetectSensitiveInfo,
10
    TokenBucket,
11
    launch_arcjet,
12
)
13
from arcjet.guard.google_adk import google_adk_context, guard_plugin
14

15
arcjet = launch_arcjet(key=os.environ["ARCJET_KEY"])
16

17
lookup_limit = TokenBucket(
18
    refill_rate=10,
19
    interval_seconds=60,
20
    max_tokens=10,
21
    bucket="lookups",
22
)
23
detect_pii = LocalDetectSensitiveInfo()
24
inbound = DetectPromptInjection()
25

26

27
def lookup_order(order_number: str, note: str) -> dict:
28
    """Look up an order by number."""
29
    return {"order_number": order_number, "note": note, "status": "shipped"}
30

31

32
async def run_agent(conversation_id: str, user_text: str, authenticated_user_id: str):
33
    app_context = {"session_id": conversation_id}
34
    derived = google_adk_context(app_context)
35
    decision = await arcjet.guard(
36
        label="message.received",
37
        rules=[inbound(user_text)],
38
        correlation_id=derived.correlation_id,
39
    )
40
    if decision.conclusion == "DENY" or decision.has_failed_open():
41
        raise RuntimeError("message blocked")
42

43
    def plugin_rules(call):
44
        if call["tool_name"] != "lookup_order":
45
            return []
46
        return [
47
            lookup_limit(key=authenticated_user_id, requested=1),
48
            detect_pii(call["note"]),
49
        ]
50

51
    agent = LlmAgent(
52
        name="order_agent",
53
        model="gemini-flash-latest",
54
        instruction="Look up orders with lookup_order.",
55
        tools=[FunctionTool(lookup_order)],
56
    )
57
    runner = InMemoryRunner(
58
        agent=agent,
59
        app_name="orders",
60
        plugins=[
61
            guard_plugin(
62
                guard=arcjet,
63
                action="order.looked-up",
64
                session_id=conversation_id,
65
                on_guard_error="deny",
66
                actor=authenticated_user_id,
67
                rules=plugin_rules,
68
            )
69
        ],
70
    )
71
    return runner.run_async(
72
        user_id=authenticated_user_id,
73
        session_id=conversation_id,
74
        new_message=types.Content(
75
            role="user",
76
            parts=[types.Part.from_text(text=user_text)],
77
        ),
78
    )

When you hold the agent and not the Runner, assign guard_tool on before_tool_callback and do not also register guard_plugin for those tools.

1
from arcjet.guard.google_adk import guard_tool
2

3
agent = LlmAgent(
4
    name="order_agent",
5
    model="gemini-flash-latest",
6
    instruction="Look up orders with lookup_order.",
7
    tools=[FunctionTool(lookup_order)],
8
    before_tool_callback=guard_tool(
9
        guard=arcjet,
10
        action="order.looked-up",
11
        session_id=conversation_id,
12
        actor=authenticated_user_id,
13
        rules=lambda call: (
14
            [lookup_limit(key=authenticated_user_id, requested=1)]
15
            if call["tool_name"] == "lookup_order"
16
            else []
17
        ),
18
    ),
19
)

google_adk_context reads correlation_id, then session_id, then conversation_id. Camel-case aliases are also read. It never mints an id, and it never reads trace_id, an ADK-generated invocation_id, or session.id.

How do remote policies read the actor and inputs?

actor and inputs are optional on guardPlugin, guard_tool, and guard_plugin. Omit them and a remote rule that declares those names never fires. A resolver that throws is a guard error and follows the fail-closed default.

Derive actor from authenticated application state. A policy can be conditioned on it, so a model that controls the actor can leave its own policy scope. Tool arguments are model-produced. Narrow them before you read a field, and return nothing for a tool the policy does not cover.

JavaScript builds each input with policyInput.server.* or policyInput.local.*. Plain values are rejected. The adapter does not discover arguments for you.

1
import { policyInput } from "@arcjet/guard";
2
import { guardPlugin } from "@arcjet/guard/google-adk/v2";
3
import { arcjet } from "./arcjet.js";
4

5
const guarded = guardPlugin(arcjet, {
6
  action: ({ toolName }) => `${toolName}.invoked`,
7
  actor: authenticatedUser.id,
8
  inputs: ({ toolName, input }) => {
9
    if (toolName !== "sendEmail") return {};
10
    const { recipient, body } = input as { recipient: string; body: string };
11
    return {
12
      recipient: policyInput.server.string(recipient),
13
      allowed_recipients: policyInput.server.stringList(
14
        authenticatedUser.allowedRecipients,
15
      ),
16
      body: policyInput.local.string(body),
17
    };
18
  },
19
});

Python builds each input with server_input.* or local_input.*. The envelope is the arguments plus tool_name.

1
from arcjet.guard import local_input, server_input
2
from arcjet.guard.google_adk import guard_tool
3

4
guarded_send_email = guard_tool(
5
    guard=arcjet,
6
    action="email.sent",
7
    actor=authenticated_user_id,
8
    inputs=lambda call: {
9
        "recipient": server_input.string(call["recipient"]),
10
        "allowed_recipients": server_input.string_list(allowed_recipients),
11
        "body": local_input.string(call["body"]),
12
    },
13
)

The policy these calls feed declares recipient as a SERVER string, allowed_recipients as a SERVER string list, and body as a LOCAL string, then denies a recipient that isn't on the list:

1
package arcjet.guard
2

3
import rego.v1
4

5
deny contains "external-recipient" if {
6
  not input.values.recipient in input.values.allowed_recipients
7
}

allowed_recipients is application state, not a field the model supplied. See remote policies for the contract.

How do you correlate a Google ADK run?

googleAdkContext reads a caller-owned ID from the object you pass: correlationId first, then sessionId, then conversationId. It never mints an ID.

It deliberately ignores every ADK-generated value – traceId, an ADK-generated invocationId, toolContext.sessionId, and session.id. ADK will generate a session or invocation ID when you omit one, and joining decisions on an auto-generated value produces a Sequence that looks correlated but groups unrelated runs. If you didn't pass an ID, the call is uncorrelated, which is the honest outcome. Don't derive one from a generated value to fill the gap.

Put the same ID on runAsync and on guardPlugin, so the inbound decision and every tool decision land on one Sequence. Python puts that ID on run_async(session_id=...) and as session_id on guard_tool or guard_plugin. google_adk_context reads correlation_id, then session_id, then conversation_id, plus the camel-case aliases.

1
// After the inbound check, use a session created for this authenticated user.
2
for await (const event of runner.runAsync({
3
  userId: authenticatedUser.id,
4
  sessionId: conversationId,
5
  newMessage: { parts: [{ text: userText }] },
6
})) {
7
  void event; // Forward permitted events to the caller.
8
}

A run that pauses on requestConfirmation resumes through a later runAsync. Pass the same caller-owned ID on that resume call, or the second half of the conversation detaches from the first. The confirmation payload itself is not a correlation source.

Don't call createAgentContext inside an ADK callback.

How do the editor and CI catch Google ADK security bugs?

Turn on TypeScript strict, ESLint, and secret scanning in the editor. Trunk, Semgrep, TruffleHog, and Gitleaks all have editor plugins and CI jobs. Run the same scanners in CI that you run locally – an editor warning that isn't a CI failure gets ignored.

Fail the build on secrets in the diff and on known vulnerable dependencies. TypeScript catches the adapter mistakes that matter most here: label passed to guardPlugin, an unversioned @arcjet/guard/google-adk import, or a rules callback that destructures input without parsing it. Python review should reject a git URL pin, a guard_tool stacked on the same tools as guard_plugin, and a deny path that returns {}.

What automation won't catch is plugin ordering. Nothing type-checks that guardPlugin or guard_plugin sits first in plugins, and a Guard that never runs looks exactly like a Guard that always allows. Make that a review item, and verify it against a real denial rather than inferring it from the absence of a side effect.

How do you verify the gate actually fires?

A missing decision is not a denial. If the model asks a clarifying question instead of calling the guarded tool, nothing is sent, no guard call happens, and no decision is returned. From the outside that is indistinguishable from a working gate, because in both cases the side effect didn't happen.

Read the decision in the Arcjet Console or your logs rather than concluding from the absence of a side effect. Two things make a test agent cooperative: a system prompt telling it to complete the request without follow-up questions, and one telling it to quote retrieved values verbatim. A model that helpfully masks a card number itself leaves the rule nothing to detect, and Guard then correctly allows – which reads as a broken rule when it isn't.

Check the three failure modes explicitly. Confirm a denial when a rate limit is exhausted, confirm a denial when a free-text argument carries PII, and confirm the tool doesn't run when Guard is unreachable and onGuardError is "deny". See functional testing of security rules.

Use deterministic Guard responses and a handler call counter. A DENY or unavailable evaluation must leave the counter at zero; an authorized ALLOW must call the handler once. Also test another tenant's resource identifier: application authorization must still refuse access even when Guard allows.

Use a fake model that requests a known tool so the test actually exercises beforeToolCallback. Consume the runAsync event iterator. Repeat with another plugin before and after Guard, and assert both the decision and handler call count; plugin ordering must not turn a blocked call into an executed one.

What do you do after this guide?

Confirm each item against one sensitive run: a prompt that asks for a refund, an authored lookup that includes a free-text note, and a second plugin in the list to prove ordering behaves as you expect.

Then apply AI agent runtime security for the sequence, budget, and identity controls that aren't ADK-specific, enforce token spend budgets for the cost side of an agent loop that can call tools repeatedly, and the Cloudflare Think security guide if the agent runs on Think rather than ADK.