Google Agent Development Kit Security: Callbacks, Tool Auth, Plugins and A2A Controls

An agent built with Google's Agent Development Kit (ADK) acts through its tools, so the identity each tool uses and the checks that run before each tool call decide what the agent can actually do. ADK is an open source framework for building agents in Python, TypeScript, Go, Java and Kotlin, and it gives developers several enforcement points: tool authentication schemes, the ToolContext, agent, model and tool callbacks, runner-level plugins, Tool Confirmation and the Agent2Agent (A2A) integration. This guide explains how to use those controls to secure ADK agents in your own code, from credentials and guardrails to MCP toolsets, remote agents and telemetry. It is written for engineers and security reviewers taking ADK agents to production. Hosting on Google Cloud's managed runtime is covered separately in the Vertex AI Agent Engine security guide; this page stays at the framework level.

This is an independent guide from NHI Mgmt Group, based on Google's public ADK documentation as of November 2026. It is not sponsored or reviewed by Google. Product features change, so confirm settings against Google's current ADK documentation.

Key takeaways

• Choose agent auth or user auth per tool. ADK's safety guidance separates tools that act as the agent's own identity (for example a service account) from tools that act as the controlling user through OAuth, and one agent can mix both.
• Put policy where the model cannot change it. Tools receive model-set arguments and a developer-set ToolContext; enforce limits such as allowed tables from the context, not from the prompt.
• Register guardrails as plugins on the runner. Plugin callbacks run before agent, model and tool callbacks and apply to every agent the runner manages, which makes them the right place for organisation-wide policy.
• Keep long-lived credentials out of session state. ADK recommends an authentication manager such as Google Cloud Agent Identity, or a secrets manager, with only short-lived tokens in session memory.
• Treat MCP servers and remote A2A agents as untrusted input. Use tool_filter, per-user header_provider credentials, Tool Confirmation for destructive calls, and connect only to servers and agents you trust.

How identity and access work in ADK

ADK has no user directory of its own. An ADK application is a Runner (or, in Python, an App) that executes agents, which call models and tools. Access to anything outside the process happens through tools, and each tool authenticates using a scheme you configure. The ADK safety documentation describes two strategies, and the choice is made per tool, not per agent.

Tools that need credentials are configured with an AuthScheme (how the API expects credentials, for example API key, HTTP bearer, OAuth2 or OpenID Connect) and an initial AuthCredential, whose auth_type includes API_KEY, OAUTH2, OPEN_ID_CONNECT and SERVICE_ACCOUNT. OpenAPI toolsets, Google API toolsets and custom function tools all accept auth_scheme and auth_credential at initialisation. For the wider design questions behind this choice, see the Agent Identity and Access Guide.

Where to store credentials

The ADK authentication page warns that storing access tokens, and especially refresh tokens, directly in session state can be risky depending on the session backend and SessionService implementation. It lists four options in order of preference:

1. Authentication manager service (recommended for production): a service that stores keys and secrets and acquires, refreshes and stores OAuth tokens. ADK integrates with Google Cloud Agent Identity through GcpAuthProvider, registered once with CredentialManager.register_auth_provider() and installed with the google-adk[agent-identity] extra. The integration page marks it as a preview release and lists audit logging of credential access among its uses. See the Google Cloud Agent Identity guide.
2. Secrets manager: long-lived credentials and refresh tokens stay in a service such as Google Cloud Secret Manager; session memory holds only short-lived access tokens or references.
3. Local encrypted storage: for less sensitive applications, with keys held in a key management service.
4. In-memory secrets: credentials held in InMemorySessionService, which the docs restrict to early development and testing.

For local work the docs say to keep API keys and client secrets in a .env file excluded from version control, and for interactive three-legged OAuth or OIDC, to store tokens against an authenticated user identifier in an encrypted database.

Admin roles and privileged access

In a framework, privilege sits with whoever controls the code paths that every request passes through. In ADK those are the runner's plugin list, global instructions, tool definitions and the deployment surface. Treat changes to them as privileged changes.

• Plugin list: plugins registered on the Runner or App run before object-level callbacks, and if a plugin callback returns a value other than None, the agent, model or tool callback is skipped. In Python ADK runs plugins in list order and stops at the first that returns a value; each plugin needs a unique name. Review plugin order like firewall rule order and require code review for changes.
• Instructions from outside the code: McpInstructionProvider can fetch agent instructions from an MCP server. The ADK docs caution that such instructions directly control agent behaviour; restrict this to MCP servers you operate and protect the connection credentials.
• Destructive tools: wrap them with FunctionTool(..., require_confirmation=True), or pass a function that decides per call, so a person or supervising system approves before execution. Advanced confirmation uses tool_context.request_confirmation() with a hint and a JSON-serialisable payload. As of November 2026 the docs mark Tool Confirmation as experimental and list the session services it works with, so check that list against your session backend before you rely on it. See the Human-in-the-Loop for AI Agents Guide.
• Developer UI: the ADK docs state that ADK Web is for development and debugging only and is not meant for production deployments. Serve production agents through your own service or a managed runtime and set --allow_origins to the exact origins you need when using the API server.
• Code execution: model-generated code needs a sandbox. ADK documents server-side code execution on Google Cloud and the Code Executor integrations; if you build your own executor, the docs recommend hermetic environments with no network access and full cleanup between executions. See the AI Agent Sandboxing and Code Execution Guide.

Guardrails: callbacks, plugins and in-tool policy

ADK's safety page lists the sources of risk it is designed against: ambiguous instructions, prompt injection and jailbreaks from users, and indirect prompt injection through tool use. It offers layered guardrails, summarised below.

The docs recommend plugins for security policies that are not specific to one agent, because a plugin configured once applies to every agent that uses the runner. Prebuilt and documented options include the Model Armor plugin, which queries the Model Armor API at chosen points of execution; a Gemini as a Judge pattern that screens user input, tool input and output and agent responses with a small, fast model; a PII redaction plugin on the before tool hook; and Tool Call Integrity, which signs each function call stored in the session with a secret key and runs a tool only when the signature verifies (the docs note that tools run as workflow nodes are not checked). For background on screening layers, see the AI Guardrails and AI Firewalls Guide.

Decision guidance: put the hardest limits inside the tool, because callbacks depend on registration and model screening is probabilistic. Use a plugin when the same rule should cover every agent; use an agent callback when the rule depends on that agent's state. A small team with one agent can start with in-tool policy and a single logging plugin; a platform team serving many agent teams should ship a shared plugin set and make its presence a deployment check.

One more control from the ADK safety page is easy to miss: escape model output before rendering it in a browser. An indirect prompt injection can make the model emit an image tag or link that sends session content to an outside site when the UI renders it.

Integrations, API tokens and service accounts

MCP toolsets

McpToolset connects ADK agents to MCP servers over stdio or HTTP. The ADK advanced MCP page maps production needs to parameters:

Stdio servers run as local subprocesses with the agent's privileges, so pin the package version and run them in a constrained environment. More on MCP trust is in the MCP Security Guide.

A2A remote agents

ADK exposes an agent over A2A with to_a2a(root_agent), which generates an agent card in memory, or with adk api_server --a2a and your own agent card; a client consumes it as a RemoteA2aAgent. The ADK docs recommend A2A when the other agent is a separate service, maintained by another team or organisation, or written in another language, and local sub-agents when agents share memory or are internal code organisation. From a security view, that is the boundary: a remote agent is an external system. Serve it over TLS behind authentication, review the agent card you publish (it describes skills to anyone who can fetch /.well-known/agent-card.json), and treat responses from a remote agent like tool output that may carry injected instructions. See the A2A Protocol Security Guide.

Model and API keys

Give each agent and environment its own model credentials and tool identities. On Google Cloud, prefer attached service accounts and Application Default Credentials over key files, grant read-only roles where the tool only reads, and keep VPC Service Controls perimeters around the data the agent touches; the ADK safety page notes that perimeters keep API calls inside the perimeter but are coarse, so tool guardrails are still needed. See the VPC Service Controls Guide.

Logging and detection

ADK implements the OpenTelemetry Semantic Conventions for GenAI and emits OTLP, so traces and logs go to any OTLP backend through the standard OTEL_EXPORTER_OTLP_* variables, or to Google Cloud Trace with --otel_to_cloud. By default prompt content is elided from logs. OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT turns content capture on, and the docs warn it records full prompts and responses that may include PII, so in production leave it off or apply data handling policies. The Debug Logging plugin writes complete invocation details to a YAML file and belongs in development only. See OpenTelemetry GenAI Semantic Conventions for Security Teams.

Signals worth alerting on:

• Guardrail blocks: a before tool callback or plugin returning a block result, grouped by tool and user.
• Tool calls outside the expected set for an agent, or calls to a tool removed by tool_filter.
• Tool Confirmation requests rejected or left unanswered.
• Tool Call Integrity verification failures, which indicate tampered session history.
• on_tool_error_callback spikes, often the first sign of a model probing a tool's limits.
• Credential access events from the authentication manager or secrets manager outside the agent's normal pattern.

Metrics: share of production agents with the shared security plugin set registered (target 100 percent); share of write-capable tools behind confirmation or in-tool policy; number of long-lived secrets in code, environment files or session state (target zero); blocked tool calls per thousand calls, trended; and median time from a guardrail alert to triage.

Hardening baseline

Roll out in this order, testing each step in a staging runner before production:

1. Inventory: list every agent, tool, MCP toolset and remote A2A agent, with the identity each tool uses and what it can write.
2. Credentials: move secrets to an authentication manager or secrets manager; remove refresh tokens from session state; replace developer keys with per-agent identities.
3. In-tool policy: add ToolContext-driven limits to every tool that writes, deletes, spends money or reads sensitive data.
4. Plugins: register a shared plugin set (logging, input and output screening, PII redaction) on every runner. Run screening in observe mode first by logging decisions without returning a block, review false positives, then enforce.
5. Confirmation: turn on require_confirmation for destructive tools and MCP tools.
6. MCP and A2A: apply tool_filter, move credentials to header_provider, and put authentication in front of every exposed A2A endpoint.
7. Telemetry: export traces and logs, confirm content capture is off in production, and build the alerts above.
8. Evaluate: add adversarial cases (direct and indirect injection) to ADK evaluation sets and rerun them on every release.

Rollback: plugins and callbacks are code, so ship them behind configuration flags and keep the previous release deployable. If an enforcing guardrail blocks legitimate work, switch that rule back to observe mode rather than removing the plugin.

Common misconfigurations

• Agent auth for a multi-user agent: one service account with access to all customers' data, and no in-tool check that the current user may see the record requested.
• Refresh tokens in session state: tokens stored in a database-backed session service that many components can read. Move them to an authentication manager or secrets manager.
• Guardrails on one agent only: a before tool callback added to the root agent while sub-agents call the same tools unchecked. Use a runner plugin.
• Plugin order not reviewed: a caching or logging plugin earlier in the list returns a value and the security plugin never runs.
• Whole MCP server exposed: every tool on a filesystem or database server available to the model, with credentials in connection parameters, when tool_filter and header_provider would narrow both.
• Development settings in production: ADK Web, in-memory secrets, Debug Logging or message content capture left on after launch.

Practitioner checklist

• Record for each tool whether it uses agent auth or user auth, and why.
• Store credentials in an authentication manager or secrets manager; keep only short-lived tokens in sessions.
• Enforce hard limits inside write-capable tools from developer-set ToolContext policy.
• Register a reviewed security plugin set on every production runner and check its order.
• Turn on require_confirmation for destructive tools, including MCP tools.
• Apply tool_filter and header_provider to every McpToolset; connect only trusted servers.
• Put authentication and TLS in front of every A2A endpoint and review the published agent card.
• Escape model output in every UI that renders it.
• Keep ADK Web, Debug Logging and message content capture out of production.
• Export OpenTelemetry traces and alert on guardrail blocks and integrity failures.

Standards and references

• Google ADK: Safety and Security for AI Agents
• Google ADK: Authenticating with tools
• Google ADK: Plugins
• Google ADK: Types of Callbacks
• Google ADK: Get action confirmation for ADK Tools
• Google ADK: Advanced MCP integration patterns
• Google ADK: Introduction to A2A
• Google ADK: Agent activity logging

Related NHI Mgmt Group resources: Securing Agent Frameworks Guide, Vertex AI Agent Engine security guide, Prompt Injection Guide, AI Agent Observability and Incident Response Guide.