This document introduces the Google Agent Development Kit (ADK) for Java, a framework for building, testing, and deploying AI agents. It covers the framework's purpose, architecture, module structure, and core abstractions.
For initial setup and quickstart instructions, see Getting Started. For detailed architectural diagrams and system interactions, see Architecture Overview.
The Agent Development Kit (ADK) is an open-source, code-first toolkit for building, evaluating, and deploying advanced AI agents. The framework provides:
BaseAgent hierarchy supporting LLM-powered agents (LlmAgent), control flow agents (SequentialAgent, ParallelAgent, LoopAgent), and hierarchical agent trees with transfer mechanismsRunner orchestrates agent invocation with InvocationContext, managing session state, artifacts, and memory through pluggable service interfacesFunctionTool wraps Java methods as LLM-callable tools, McpToolset integrates Model Context Protocol servers, AgentTool enables agents to invoke other agentsBaseLlmFlow orchestrates LLM interaction loops with request/response processing pipelines (RequestProcessor, ResponseProcessor)BaseLlm abstraction with Gemini implementation, supporting streaming responses and live audioPluginManager provides 13 lifecycle hooks (before/after run/agent/model/tool, on event/error) for extensibilitygoogle-adk-dev module with Spring Boot server, browser UI, hot reload, and agent visualizationBaseSessionService (in-memory, Vertex AI, Firestore), BaseArtifactService (file storage), BaseMemoryService (semantic search)ConfigAgentUtils and ComponentRegistry for component resolutionThe ADK architecture separates agent logic from infrastructure concerns, enabling developers to focus on agent behavior while the framework handles execution orchestration, tool invocation, session persistence, and LLM provider integration.
Sources: pom.xml20-28 core/pom.xml26-28 core/src/main/java/com/google/adk/runner/Runner.java66-67 core/src/main/java/com/google/adk/agents/BaseAgent.java42-43
The project is organized as a multi-module Maven build with the following structure:
Module Purposes:
| Module | Artifact ID | Purpose |
|---|---|---|
| Core | google-adk | BaseAgent, Runner, BaseLlmFlow, FunctionTool, Gemini, session/artifact/memory services |
| Dev | google-adk-dev | Spring Boot server with HTTP/WebSocket endpoints, Angular dev UI, agent visualization, dynamic compilation |
| Maven Plugin | google-adk-maven-plugin | Maven goal google-adk:run for launching dev server from project agents |
| LangChain4j | google-adk-langchain4j | Bridge to LangChain4j ChatLanguageModel and tool ecosystem |
| Spring AI | google-adk-spring-ai | Spring Boot auto-configuration and integration |
| Firestore Session | google-adk-firestore-session-service | FirestoreSessionService for Google Cloud Firestore persistence |
| A2A | google-adk-a2a | Agent-to-Agent communication protocol implementation |
| A2A Webservice | google-adk-a2a-webservice | REST service for exposing agents via A2A protocol |
Sources: pom.xml29-41 core/pom.xml26-28 dev/pom.xml24-26 maven_plugin/pom.xml12-15 contrib/langchain4j/pom.xml27-29
System Architecture: Concept to Code Mapping
Sources: core/src/main/java/com/google/adk/runner/Runner.java66-67 core/src/main/java/com/google/adk/agents/BaseAgent.java42-43 core/src/main/java/com/google/adk/agents/InvocationContext.java40-41 core/src/main/java/com/google/adk/flows/llmflows/Functions.java65-66
Core Classes and Their Roles:
| Class | Location | Key Methods | Role |
|---|---|---|---|
Runner | runner/Runner.java:67 | runAsync(), runLive(), findAgentToRun() | Orchestrates agent execution, manages session lifecycle, invokes plugins |
BaseAgent | agents/BaseAgent.java:43 | runAsync(), runLive(), findAgent(), findSubAgent() | Abstract base for all agents, defines execution contract |
LlmAgent | agents/LlmAgent.java | builder(), fromConfig(), runAsyncImpl() | LLM-powered agent with instructions, tools, sub-agents |
InvocationContext | agents/InvocationContext.java:41 | builder(), session(), agent(), runConfig() | Execution environment: session, services, configuration |
BaseLlmFlow | flows/llmflows/BaseLlmFlow.java | run(), runLive() | Orchestrates LLM interaction loop with request/response processing |
Functions | flows/llmflows/Functions.java:66 | handleFunctionCalls(), handleFunctionCallsLive() | Tool execution dispatcher, manages function call/response cycle |
FunctionTool | tools/FunctionTool.java | create(), runAsync(), callLive() | Wraps Java methods as LLM-callable tools with schema generation |
BaseTool | tools/BaseTool.java | runAsync(), name(), longRunning() | Interface for all tools callable by LLM |
BaseSessionService | sessions/BaseSessionService.java | getSession(), appendEvent(), createSession() | Interface for session persistence (in-memory, Vertex AI, Firestore) |
PluginManager | plugins/PluginManager.java | beforeRunCallback(), afterRunCallback(), etc. | Manages 13 lifecycle callback hooks for extensibility |
ConfigAgentUtils | agents/ConfigAgentUtils.java | fromConfig(), fromYaml() | Loads agents from YAML configuration files |
ComponentRegistry | utils/ComponentRegistry.java | register(), resolveAgentClass(), resolveToolClass() | Maps string references to agent/tool/toolset classes |
Sources: core/src/main/java/com/google/adk/runner/Runner.java66-67 core/src/main/java/com/google/adk/agents/BaseAgent.java42-43 core/src/main/java/com/google/adk/agents/InvocationContext.java40-41 core/src/main/java/com/google/adk/flows/llmflows/Functions.java65-66
The ADK supports two complementary approaches for defining agents:
Agents are constructed using the builder pattern with type-safe fluent API. This approach provides compile-time validation and IDE code completion:
Key Builder Methods:
name(String) - Unique agent identifier (required)description(String) - One-line capability description for delegation decisionsinstruction(String) or instruction(Provider<String>) - Static or dynamic instructionsmodel(String) - Model name resolved via ComponentRegistrymodel(BaseLlm) - Direct BaseLlm instancetools(Object...) - Mix of BaseTool, BaseToolset, or string referencessubAgents(List<BaseAgent>) - Child agents for hierarchical delegationbeforeToolCallback(List<BeforeToolCallback>) - Pre-tool execution hooksafterToolCallback(List<AfterToolCallback>) - Post-tool execution hooksdisallowTransferToParent(boolean) - Control transfer up agent treedisallowTransferToPeers(boolean) - Control transfer to sibling agentsAgents are defined declaratively in YAML files and loaded via ConfigAgentUtils. This approach enables configuration without recompilation:
Configuration Loading Process:
ConfigAgentUtils.fromConfig(String configPath) reads YAML filesnake_case to camelCase for Python compatibilityBaseAgentConfig, inspects agentClass fieldLlmAgentConfig, etc.) based on agent typeComponentRegistry resolves string references:
model: "gemini-1.5-flash" → Gemini instancetools: [{name: "my_tool"}] → FunctionTool instancessub_agents: [{config_path: "..."}] → recursive loadingLlmAgent.fromConfig(LlmAgentConfig, configAbsPath) to construct agentComponent Resolution Rules:
ComponentRegistry resolves components by trying multiple naming conventions:
"MyTool" → MyTool.class"tool:MyTool" → MyTool.class"com.example.MyTool" → com.example.MyTool.classComponentRegistry.register()Sources: core/src/main/java/com/google/adk/agents/LlmAgent.java149-559 core/src/main/java/com/google/adk/agents/ConfigAgentUtils.java139-170 core/src/main/java/com/google/adk/agents/LlmAgentConfig.java24-145 core/src/main/java/com/google/adk/agents/BaseAgentConfig.java21-157
The ADK supports distinct deployment modes optimized for different stages of development:
Mode Comparison:
| Aspect | Development Mode | Production Mode |
|---|---|---|
| Entry Point | mvn exec:java or dev main class | AdkWebServer.start() programmatically |
| Agent Loading | CompiledAgentLoader - auto-discovers ROOT_AGENT fields | AgentStaticLoader - explicit registration |
| Services | In-memory implementations | Pluggable (Firestore, Cloud Storage, etc.) |
| Hot Reload | Yes - monitors YAML changes | No |
| Browser UI | Yes - interactive testing | Optional |
| Use Case | Local development, tutorials | Production deployment |
Maven Plugin Mode provides a hybrid approach:
google-adk:runAgentStaticLoader for deterministic loadingSources: dev/pom.xml24-26 maven_plugin/pom.xml12-15 contrib/samples/helloworld/pom.xml29-34 contrib/samples/configagent/pom.xml26-36
The ADK integrates with several key technologies and libraries:
LLM Providers:
| Provider | Dependency | Usage |
|---|---|---|
| Gemini | google-genai (version 1.32.0) | Primary LLM integration via GeminiLlm class |
| Anthropic | anthropic-java (version 1.4.0) | Claude integration via Vertex AI |
Frameworks:
| Framework | Dependency | Usage |
|---|---|---|
| Spring Boot | spring-boot-dependencies (version 3.4.1) | Dev server, web endpoints, auto-configuration |
| RxJava | rxjava (version 3.1.5) | Reactive streams for agent execution |
| Project Reactor | reactor-core (version 3.7.0) | Alternative reactive implementation |
Tools & Protocols:
| Component | Dependency | Usage |
|---|---|---|
| MCP SDK | mcp (version 0.14.0) | Model Context Protocol for external tool servers |
| Jackson | jackson-databind (version 2.19.0) | JSON/YAML serialization, schema generation |
| OpenTelemetry | opentelemetry-bom (version 1.49.0) | Distributed tracing and observability |
Development:
| Tool | Dependency | Usage |
|---|---|---|
| Docker Java | docker-java (version 3.3.6) | Container management for MCP servers |
| Eclipse JDT | ecj (version 3.41.0) | Java compilation in dev server |
| JUnit | junit-bom (version 5.11.4) | Testing framework |
Sources: pom.xml43-75 core/pom.xml32-192 dev/pom.xml29-112
Agent execution produces a reactive stream of Event objects representing the agent's interactions with the LLM and tools:
Agent Execution Flow: Runner to Event Stream
Event Structure:
Event.content() returns Optional<Content> with text parts and function call/response partsEvent.author() identifies the agent that generated the eventEvent.invocationId() links events to the originating Runner.runAsync() callEvent.actions() returns EventActions containing:
stateDelta() - Map of state changes to merge into sessionartifactUpdates() - List of artifact modificationsrequestedToolConfirmations() - Tool calls requiring user confirmationlongRunningToolIds() - Set of pending async tool executionsEvent.branch() identifies position in agent hierarchy (e.g., "root.specialist.helper")Reactive Stream Characteristics:
Flowable<Event> (RxJava 3) for asynchronous, backpressured event processingBaseSessionService.appendEvent()PluginManager.onEventCallback()Sources: core/src/main/java/com/google/adk/runner/Runner.java357-556 core/src/main/java/com/google/adk/agents/BaseAgent.java205-249 core/src/main/java/com/google/adk/flows/llmflows/Functions.java134-191
For hands-on usage:
For specific subsystems:
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.
