This document provides a high-level introduction to the Agent Development Kit (ADK) for Java. It covers the purpose of the framework, the Maven project structure, core architectural components, and integration capabilities. For detailed information about specific subsystems, refer to their respective sections in this wiki.
The Agent Development Kit (ADK) for Java is an open-source, code-first toolkit for building, evaluating, and deploying sophisticated AI agents. It provides a structured framework for defining agent behavior, orchestration, and tool integration directly in Java code, with support for multiple LLM providers and deployment environments.
This overview covers:
For hands-on setup instructions, see Getting Started. For architectural deep-dives, see Architecture Overview.
Sources: README.md1-132 pom.xml1-609
The ADK is organized as a multi-module Maven project with a parent POM managing dependencies and build configuration. The current version is 0.8.0 (tracked in core/src/main/java/com/google/adk/Version.java25).
Module Details
| Module | Artifact ID | Purpose |
|---|---|---|
| Core | google-adk | Agent framework, runtime, tools, LLM integrations |
| Dev | google-adk-dev | Spring Boot server with browser UI and WebSocket support |
| Maven Plugin | google-adk-maven-plugin | mvn google-adk:run goal for local agent execution |
| A2A | google-adk-a2a | Agent-to-Agent protocol implementation |
| Spring AI | google-adk-spring-ai | Spring AI model abstraction integration |
| LangChain4j | google-adk-langchain4j | LangChain4j compatibility layer |
| Firestore | google-adk-firestore-session-service | Firestore-backed session persistence |
| Samples | google-adk-samples | Tutorial and example applications |
Sources: pom.xml27-38 core/pom.xml1-283 dev/pom.xml1-192 maven_plugin/pom.xml1-199 contrib/langchain4j/pom.xml1-128
The parent POM imports seven Bill of Materials (BOMs) to manage transitive dependencies consistently across all modules:
Key Direct Dependencies
| Dependency | Version | Purpose |
|---|---|---|
google-genai | 1.41.0 | Google Generative AI SDK (Gemini models) |
anthropic-java | 2.15.0 | Anthropic Claude SDK |
mcp | 0.14.0 | Model Context Protocol integration |
docker-java | 3.7.0 | Docker container management for code execution |
graphviz-java | 0.18.1 | Workflow visualization |
rxjava | 3.1.12 | Reactive streams for event processing |
Sources: pom.xml40-76 pom.xml78-288 core/pom.xml32-196
The ADK runtime centers around four primary abstractions that work together to execute agent workflows.
Component Roles
| Component | Class | Responsibility |
|---|---|---|
| Runner | Runner | Orchestrates agent execution, manages session lifecycle, applies plugins |
| Agent | BaseAgent, LlmAgent | Defines agent behavior, instruction, tools, and sub-agents |
| Session | Session | Stores conversation events and state as an immutable log |
| Session Service | BaseSessionService | Persists and retrieves sessions (in-memory, Vertex AI, Firestore) |
| Invocation Context | InvocationContext | Mutable execution state during a single agent invocation |
| LLM Flow | BaseLlmFlow | Implements the LLM interaction loop with tool calling |
Sources: README.md80-98 pom.xml27-38
The ADK supports two execution modes: async (request-response) and live (bidirectional streaming).
Execution Modes
| Mode | Method | Use Case | Return Type |
|---|---|---|---|
| Async | Runner.runAsync() | Request-response, batch processing | Flowable<Event> |
| Live | Runner.runLive() | Real-time streaming, voice interactions | Flowable<Event> with LiveRequestQueue |
Sources: High-level diagrams (Diagram 2), README.md
ADK uses an event-sourcing model where all interactions are recorded as immutable Event objects in a Session.
State Scopes
| Prefix | Scope | Lifetime | Example |
|---|---|---|---|
app: | Application-wide | Persistent across all users/sessions | app:config |
user: | User-wide | Persistent across user's sessions | user:preferences |
| (none) | Session-specific | Single conversation | current_topic |
temp: | Ephemeral | Cleared after agent run | temp:scratch |
State changes are tracked in EventActions.stateDelta() as key-value pairs. The special REMOVED sentinel value marks deletions.
Sources: High-level diagrams (Diagram 3), pom.xml1-609
ADK provides a flexible tool system for extending agent capabilities through function calling.
Tool Creation Methods
| Method | Input | Use Case |
|---|---|---|
FunctionTool.create(instance, "methodName") | Java object + method name | Expose existing Java methods |
FunctionTool.create(Class, "staticMethod") | Static method reference | Pure functions without state |
new AgentTool(agent) | Another agent | Compose agents hierarchically |
new McpToolset(config) | MCP server config | Connect to MCP tool servers |
Tools automatically generate JSON schemas for their parameters using reflection and can be synchronous or asynchronous, streaming or non-streaming.
Sources: High-level diagrams (Diagram 1), README.md31-41 core/pom.xml58-60
ADK integrates with multiple LLM providers through the BaseLlm interface.
Model Configuration
LLM models are specified via the model field in LlmAgent:
Model resolution automatically detects the provider and instantiates the appropriate BaseLlm implementation.
Sources: High-level diagrams (Diagram 4), core/pom.xml70-72 core/pom.xml34-40 README.md84-91
ADK supports pluggable session backends through the BaseSessionService interface.
Service Selection
| Service | Use Case | State Persistence | Scaling |
|---|---|---|---|
InMemorySessionService | Local development, testing | In-process memory | Single instance |
VertexAiSessionService | Production deployments | Google Cloud managed | Horizontal |
FirestoreSessionService | Custom persistence needs | Firestore database | Horizontal |
Session services are configured in the Runner:
Sources: High-level diagrams (Diagram 1), core/pom.xml42-48 pom.xml34
ADK provides a comprehensive development environment for building and testing agents locally.
Development Workflows
| Tool | Command | Purpose |
|---|---|---|
| Maven Plugin | mvn google-adk:run | Launch agent with browser UI |
| Exec Plugin | mvn exec:java | Run agent headless (programmatic) |
| Dev Server | Direct Spring Boot | Custom server configuration |
The browser UI provides:
Sources: dev/pom.xml1-192 maven_plugin/pom.xml1-199 README.md94-98 High-level diagrams (Diagram 5)
The parent POM defines three build profiles:
| Profile | Activation | Purpose |
|---|---|---|
illegal-optional-check | Manual | Enforces no Optional in method parameters |
release | Manual | Signs artifacts with GPG, generates Javadocs |
release-sonatype | Manual | Publishes to Maven Central via Sonatype |
Automated Releases
Releases are managed by release-please GitHub Action (.github/workflows/release-please.yaml1-18):
Version.java and all pom.xml filesCHANGELOG.md entries from conventional commitsSources: pom.xml479-590 .github/workflows/release-please.yaml1-18 core/src/main/java/com/google/adk/Version.java1-29
ADK includes comprehensive testing utilities:
Test Dependencies
| Library | Version | Purpose |
|---|---|---|
| JUnit Jupiter | 5.11.4 | Test framework |
| Google Truth | 1.4.5 | Fluent assertions |
| Mockito | 5.20.0 | Mock objects |
| Testcontainers | (via dependencies) | Integration testing with real services |
Tests run with JaCoCo code coverage reporting and a tree-style reporter for readable output.
Sources: pom.xml56-57 pom.xml117-122 pom.xml217-226 pom.xml442-477
ADK integrates OpenTelemetry for distributed tracing and observability.
The core module includes OpenTelemetry API and SDK (core/pom.xml172-190), enabling automatic instrumentation of:
Traces can be exported to any OpenTelemetry-compatible backend (e.g., Google Cloud Trace, Jaeger, Zipkin).
Sources: core/pom.xml172-195 pom.xml48-51 pom.xml95-101
ADK provides optional modules for integrating with external frameworks and protocols.
The google-adk-a2a module implements the A2A protocol for remote agent communication:
RemoteA2AAgent wraps remote agents as local agentsSources: pom.xml37 README.md103-108
The google-adk-spring-ai module bridges ADK with Spring AI's model abstractions, supporting:
Sources: pom.xml32 High-level diagrams (Diagram 4)
The google-adk-langchain4j module provides compatibility with LangChain4j's abstractions for seamless integration with the LangChain4j ecosystem.
Sources: pom.xml31 contrib/langchain4j/pom.xml1-128
ADK applications can be deployed in multiple ways:
Deployment Strategies
| Environment | Session Service | Artifact Storage | Scaling |
|---|---|---|---|
| Development | InMemorySessionService | Local filesystem | Single JVM |
| Docker | InMemorySessionService | Mounted volume | Container orchestration |
| Google Cloud | VertexAiSessionService | Cloud Storage | Managed auto-scaling |
| Custom | FirestoreSessionService | Cloud Storage / S3 | Application-managed |
The same agent code runs unchanged across all environments; only the session service configuration changes.
Sources: High-level diagrams (Diagram 5), core/pom.xml50-56 pom.xml89-94
The repository includes tutorial and sample applications demonstrating ADK capabilities:
| Sample | Module | Purpose |
|---|---|---|
| Hello World | google-adk-sample-helloworld | Basic agent and tool usage |
| Config Agent | configagent-samples | YAML-based agent configuration |
| City Time Weather | google-adk-tutorials-city-time-weather | Multi-tool integration example |
| Live Audio | live-audio-single-agent | Streaming audio agent |
Samples can be run with:
Or with the development UI:
Sources: contrib/samples/helloworld/pom.xml1-111 contrib/samples/configagent/pom.xml1-61 tutorials/city-time-weather/pom.xml1-52 pom.xml33-37
Refresh this wiki