Google ADK for Java 1.0.0: Production Agent Architecture and Safety Guide

Google’s Agent Development Kit for Java 1.0.0 is more than a Java wrapper around a model API. It gives Java teams a code-first agent runtime with tool calling, application-wide plugins, event compaction, human approval checkpoints, persistent sessions, and Agent2Agent (A2A) interoperability. The practical question is not whether Java can call an LLM; it is where ADK should own orchestration and where ordinary Java code should remain in control.

This guide explains the 1.0.0 architecture, a safe starting path, the features that matter in production, and the limitations to test before committing a service to it.

What ADK for Java 1.0.0 actually adds

Google announced ADK for Java 1.0.0 on March 30, 2026. Independent coverage from InfoQ and Heise confirms the release and its main direction: a Java-native agent framework with an application/plugin model, external tools, and agent collaboration.

The core building blocks are:

• LlmAgent for model-backed reasoning and tool selection.
• App as the top-level application container.
• Plugin implementations for cross-cutting logging, instructions, and context controls.
• Runner for executing agents and coordinating services.
• Session, memory, and artifact services for state that must survive a single request.
• Tool confirmation for actions that require human approval.
• A2A support for exposing or consuming remote agents.

That separation is useful for Java systems because it keeps business integrations in typed code while giving the model a constrained set of capabilities. It is also a security boundary: a prompt should describe what an agent may do, but authorization must still be enforced by the tool implementation and surrounding service.

The runtime architecture

ADK’s Java design places the model inside a larger application rather than making the model call the whole application directly. Plugins can observe or modify behavior across an agent hierarchy, while services own persistence and artifacts.

The important design choice is that the App is the policy and lifecycle boundary. A logging or guardrail callback attached to one agent can be easy to forget when the application grows. A plugin gives the team one place to apply that concern across the hierarchy.

Installation and prerequisites

Use Java 17 or newer, Maven, and a Gemini API key or another model configuration supported by the current ADK documentation. Start from the official Java quickstart and confirm the dependency version in Google’s repository rather than copying an old blog snippet.

A minimal Maven dependency uses the com.google.adk group and the google-adk artifact. Pin the version in your own dependency-management policy; do not use a floating version for a production agent.

1<dependency>
2  <groupId>com.google.adk</groupId>
3  <artifactId>google-adk</artifactId>
4  <version>1.0.0</version>
5</dependency>

The exact transitive dependencies and compatible model clients can change between releases. Run the sample from the repository, then lock the resolved dependency tree in CI before adding tools that can mutate customer data.

A small Java agent with a typed tool

The following pattern is intentionally narrow: the model can request a time lookup, but the Java method remains the source of truth for the result. Replace the sample tool with a real service only after adding authentication, input validation, rate limits, and audit logging.

1import com.google.adk.agents.LlmAgent;
2import com.google.adk.tools.FunctionTool;
3
4public final class TimeAgent {
5  public static String currentTime(String city) {
6    if (city == null || city.isBlank()) {
7      throw new IllegalArgumentException("city is required");
8    }
9    return "Return the time from a trusted timezone service for: " + city;
10  }
11
12  public static LlmAgent build() {
13    return LlmAgent.builder()
14        .name("time-agent")
15        .description("Answers time questions using a bounded lookup tool")
16        .instruction("Use the time tool for timezone questions. Do not invent times.")
17        .model("gemini-2.5-flash")
18        .tools(FunctionTool.create(TimeAgent.class, "currentTime"))
19        .build();
20  }
21}

Treat this as an API-shape example, not a promise that every future ADK release keeps identical builders. Verify the current signatures against the ADK Java source and samples before compiling.

Plugins are the production control plane

ADK Java 1.0.0 introduces an App container that can hold application-wide plugins. Google’s announcement highlights logging, context filtering, and global instructions as built-in examples. This matters because agent behavior is distributed: a root agent can call sub-agents, and each can call tools.

A useful policy is to make plugins responsible for observability and safe defaults, while tools remain responsible for authorization:

Do not put secrets into global instructions. Prompts are not a secret store, and logs may capture model inputs, tool arguments, or outputs. Redact credentials and personal data before emitting structured events.

Event compaction and long-running sessions

Long-running agents accumulate events: user messages, tool calls, tool results, intermediate reasoning metadata, and final responses. Passing all of that history into every model call increases cost and can make the agent less reliable.

ADK Java exposes event-compaction configuration so a service can retain recent events while summarizing older ones. The official announcement describes controls such as compaction intervals, overlap, token thresholds, retention size, and a summarizer. The right values depend on your workload; benchmark with representative tool payloads rather than a short chat demo.

A safe operational sequence is:

1. Record the uncompressed event count and token estimate.
2. Compact only after preserving the tool-call/result pairs required for replay or audit.
3. Store the summary with a schema version.
4. Test that the agent still knows tenant, permission, and workflow state after compaction.
5. Keep the original audit record outside the model context when regulatory retention applies.

Compaction reduces model context; it does not replace durable application state. Order IDs, approval decisions, entitlement data, and security events belong in a database or event store.

Human-in-the-loop for risky tools

A tool that sends money, changes access, deletes data, or publishes content should not rely on the model to ask politely for permission. ADK’s ToolConfirmation flow lets a tool pause execution, request approval, and resume with an explicit confirmation payload.

Use confirmation as one layer in a wider control design:

• The backend checks the authenticated principal and tenant.
• The tool validates arguments against server-side policy.
• The UI shows the exact action, target, and side effects.
• The approval is bound to a short-lived request identifier.
• The backend re-checks authorization after approval and before commit.
• The decision is written to an immutable audit stream.

This prevents a common mistake: treating a confirmation dialog as proof that the requested operation was authorized. It is evidence of user intent, not a substitute for authorization.

A2A and external tools

ADK Java 1.0.0 includes native support for the Agent2Agent protocol, allowing agents built with different frameworks or languages to collaborate through a defined interface. It also includes tools for grounding, URL context, code execution, and computer interaction patterns.

Remote-agent integration expands the attack surface. Before consuming an A2A agent or external tool, establish:

• Which identity and tenant context crosses the boundary.
• Whether the remote side can call tools of its own.
• What data is sent in prompts, metadata, and artifacts.
• How timeouts, retries, and partial failures are handled.
• Whether remote responses are treated as untrusted input.

For MCP or other tool protocols, use allowlists, narrow schemas, outbound network controls, and per-tool budgets. Do not expose a general-purpose shell or unrestricted HTTP client to a production agent.

ADK Java compared with a direct model SDK

Choose ADK when the application genuinely needs agent orchestration, tool lifecycle, state, or approvals. For a small extraction endpoint, a direct model client with structured output is usually easier to test and operate.

Common failure modes

The agent calls a tool with unsafe arguments

Validate every argument in Java, reject unexpected fields, and enforce authorization in the service called by the tool. The model’s instruction is not a security control.

Context grows until latency becomes unpredictable

Measure event and tool payload sizes. Enable compaction deliberately, summarize only what can be safely summarized, and keep durable facts outside the prompt.

A remote agent leaks tenant data

Propagate a scoped identity, not a raw access token. Filter fields before transmission and log the destination, purpose, and policy decision.

A dependency update silently changes behavior

Pin ADK and model-client versions, run contract tests against tool schemas, and test denied approvals, retries, malformed outputs, and expired sessions.

A code executor becomes a server escape hatch

Use a strict sandbox, read-only filesystems where possible, resource limits, network egress policy, and separate execution identities. Keep code execution disabled unless the product requirement is explicit.

A practical adoption checklist

For an intermediate Java team, the lowest-risk path is:

1. Build a read-only agent with one typed tool.
2. Add structured logging and request correlation IDs.
3. Write tool-level authorization and schema tests before adding autonomy.
4. Add session persistence and compaction using synthetic long conversations.
5. Introduce ToolConfirmation for one reversible but consequential action.
6. Test A2A or external tools behind a mock service first.
7. Pin dependencies and deploy with explicit model names and budgets.
8. Run failure drills: timeout, duplicate tool call, denial, partial response, and provider outage.

For broader context, compare this design with the site’s AI agent stacks guide, the MCP security threat-modeling guide, and the OpenTelemetry GenAI observability guide.

Agent request and approval sequence

The following sequence shows where the model stops and deterministic application code takes over:

This is an original explanatory diagram based on the documented ADK control flow; it is not an official Google architecture figure.

FAQ

Is ADK for Java 1.0.0 a Spring AI replacement?

No. It is an agent development framework with its own runtime and abstractions. It can coexist with Java application frameworks and Spring-based systems, but evaluate integration, dependency ownership, and operational support before replacing an established stack.

Does ADK make an agent secure by default?

No. It provides useful hooks such as plugins and tool confirmation, but authorization, secret handling, sandboxing, tenant isolation, and network policy remain application responsibilities.

When should Java developers avoid ADK?

Avoid it for a simple single-call feature where a direct model SDK, structured output, and ordinary service code solve the problem with less operational complexity.

Can ADK agents collaborate with non-Java agents?

Yes, the release includes A2A support for cross-framework collaboration. Verify protocol version, authentication, task semantics, and failure behavior for the exact endpoints you plan to use.

Conclusion

ADK for Java 1.0.0 is most compelling when an enterprise Java service needs more than model calls: typed tools, shared plugins, durable context, approval pauses, and collaboration with remote agents. Its best architectural lesson is also its clearest boundary: let the model handle language and judgment, but keep authorization, state transitions, and irreversible side effects in deterministic Java services.

The release is officially documented in Google’s announcement, with implementation material in the ADK Java repository and the official Java getting-started documentation. Independent context is available from InfoQ and Heise.