The Agent Development Kit (ADK) is an open-source Java framework for building, evaluating, and deploying AI agents. It provides a code-first toolkit for creating multi-turn conversational AI systems that integrate with LLMs, execute tools, and maintain session state.
Sources: core/pom.xml26-28 pom.xml25-27
| Capability | Core Classes | Description |
|---|---|---|
| Multi-Provider LLM | BaseLlm, Gemini, LangChain4j adapter | Unified interface for Google Gemini, Anthropic Claude, OpenAI, Azure OpenAI, Ollama |
| Tool Integration | FunctionTool, BaseTool | Convert Java methods to LLM functions via FunctionTool.create() with automatic schema generation |
| Agent Hierarchies | LlmAgent, AgentTool, AutoFlow | Multi-agent systems with parent-child delegation and automatic transfer |
| Session Management | BaseSessionService, InMemorySessionService | Conversation state persistence with in-memory and Firestore implementations |
| MCP Integration | McpToolset, McpSessionManager | Connect to Model Context Protocol servers via SSE/Stdio/HTTP |
| Plugin System | BasePlugin, PluginManager | 12 callback hooks for custom logic injection at execution stages |
| Live Streaming | BaseLlmConnection, LiveRequestQueue | Bidirectional streaming via runLive() for real-time audio/video |
| Development Tools | AdkWebServer, CompiledAgentLoader | Spring Boot server with Angular UI and hot-reload |
| Observability | Telemetry, OpenTelemetry SDK | Automatic span creation for agent, LLM, and tool execution |
Sources: core/pom.xml32-192 pom.xml29-41 core/src/main/java/com/google/adk/flows/llmflows/BaseLlmFlow.java63-87
The ADK implements a modular, layered architecture separating concerns across eight major subsystems:
| Component | Key Classes | File Locations |
|---|---|---|
| Agent Execution | Runner, InvocationContext | core/src/main/java/com/google/adk/runner/ |
| Agent Types | LlmAgent, SequentialAgent, LoopAgent | core/src/main/java/com/google/adk/agents/ |
| Flow Engine | BaseLlmFlow, AutoFlow, SingleFlow | core/src/main/java/com/google/adk/flows/llmflows/ |
| Request Processing | AgentTransfer, RequestProcessor | core/src/main/java/com/google/adk/flows/llmflows/AgentTransfer.java |
| Tool System | FunctionTool, BaseTool, McpToolset | core/src/main/java/com/google/adk/tools/ |
| Model Abstraction | BaseLlm, Gemini, LangChain4j adapter | core/src/main/java/com/google/adk/models/ |
| Plugin System | BasePlugin, PluginManager, LoggingPlugin | core/src/main/java/com/google/adk/plugins/ |
| Services | BaseSessionService, ComponentRegistry | core/src/main/java/com/google/adk/services/ |
| Development Server | AdkWebServer, CompiledAgentLoader | dev/src/main/java/com/google/adk/web/ |
Sources: pom.xml29-41 core/pom.xml32-192 core/src/main/java/com/google/adk/flows/llmflows/BaseLlmFlow.java63
The ADK is organized as a multi-module Maven project with the parent POM managing dependency versions via Bill of Materials (BOM) imports:
| Artifact ID | Purpose | Key Dependencies |
|---|---|---|
google-adk | Core framework: agents, flows, tools, models | google-genai, anthropic-java, mcp, docker-java, opentelemetry-api, rxjava |
google-adk-dev | Development server with Angular UI | google-adk, spring-boot-starter-web, spring-boot-starter-websocket, graphviz-java, ecj |
google-adk-maven-plugin | Maven plugin for google-adk:run goal | google-adk, google-adk-dev, maven-plugin-api |
google-adk-langchain4j | Multi-provider LLM adapter | google-adk, langchain4j-core |
google-adk-spring-ai | Spring AI integration | google-adk, spring-ai-core |
firestore-session-service | Cloud session persistence | google-adk, google-cloud-firestore |
google-adk-a2a | Agent-to-agent communication | google-adk-dev |
The parent POM at pom.xml77-107 imports four BOMs for version management: Google Cloud (libraries-bom:26.53.0), OpenTelemetry (opentelemetry-bom:1.49.0), Spring Boot (spring-boot-dependencies:3.4.1), and LangChain4j (langchain4j-bom:1.8.0).
Sources: pom.xml29-41 pom.xml77-278 core/pom.xml26 dev/pom.xml24-26 maven_plugin/pom.xml12-15 contrib/langchain4j/pom.xml27-29
The simplest way to create and run an agent is demonstrated in the CityTimeWeather tutorial at tutorials/city-time-weather/src/main/java/com/google/adk/tutorials/CityTimeWeather.java29-101:
Two approaches are available:
Approach 1: Automatic Discovery via CompiledAgentLoader
The CompiledAgentLoader at dev/src/main/java/com/google/adk/web/CompiledAgentLoader.java79-109 scans target/classes for fields named ROOT_AGENT and automatically registers them.
Approach 2: Programmatic Start via AgentStaticLoader
The AdkWebServer.start() method at dev/src/main/java/com/google/adk/web/AdkWebServer.java153-174 registers the provided agent via AgentStaticLoader.
Open http://localhost:8080/dev-ui to access the Angular-based development interface.
Sources: tutorials/city-time-weather/src/main/java/com/google/adk/tutorials/CityTimeWeather.java29-101 tutorials/city-time-weather/README.md1-65 dev/src/main/java/com/google/adk/web/AdkWebServer.java153-174 dev/src/main/java/com/google/adk/web/CompiledAgentLoader.java79-109
The LlmAgent class uses a fluent builder pattern:
| Method | Resolves To | Example |
|---|---|---|
.name(String) | Agent identifier in ComponentRegistry | .name("weather_agent") |
.model(String) | Lookup in LlmRegistry.getLlm() | .model("gemini-2.0-flash") |
.instruction(String) | System instruction in LlmRequest | .instruction("You are a helpful assistant") |
.tools(BaseTool...) | Available tools in BaseLlmFlow | .tools(FunctionTool.create(MyClass.class, "myMethod")) |
.subAgents(BaseAgent...) | Child agents for delegation | .subAgents(timeAgent, weatherAgent) |
Sources: tutorials/city-time-weather/src/main/java/com/google/adk/tutorials/CityTimeWeather.java31-42
Three AgentLoader implementations discover and register agents:
System Property Configuration:
| Property | Value | Implementation |
|---|---|---|
adk.agents.loader | compiled (default) | CompiledAgentLoader - scans target/classes for ROOT_AGENT fields |
adk.agents.loader | static | AgentStaticLoader - requires AdkWebServer.start(agent) |
adk.agents.loader | yaml | AgentYamlHotLoader - loads from agent.yaml with hot-reload |
adk.agents.source-dir | $PWD | Source directory for CompiledAgentLoader |
Sources: dev/src/main/java/com/google/adk/web/AgentLoader.java22-77 dev/src/main/java/com/google/adk/web/CompiledAgentLoader.java79-109 dev/src/main/java/com/google/adk/web/AgentStaticLoader.java30-67
The ADK provides a comprehensive development environment built on Spring Boot with automatic agent discovery and a browser-based UI:
| Feature | Implementation | Purpose |
|---|---|---|
| Automatic Discovery | CompiledAgentLoader at dev/src/main/java/com/google/adk/web/CompiledAgentLoader.java79-109 | Scans target/classes for ROOT_AGENT fields |
| Hot Reload | Eclipse Compiler (ECJ) at dev/pom.xml79-82 | Runtime code compilation for rapid iteration |
| Browser UI | Angular application served from classpath:/browser/ | Real-time chat interface, agent visualization, session history |
| WebSocket Streaming | Spring WebSocket support at dev/pom.xml58-60 | Bidirectional real-time event streaming |
| GraphViz Visualization | graphviz-java at dev/pom.xml76-78 | Agent hierarchy graph rendering |
| In-Memory Services | Default implementations at dev/src/main/java/com/google/adk/web/AdkWebServer.java52-81 | No external dependencies for development |
The google-adk-maven-plugin at maven_plugin/pom.xml12-15 provides convenient commands:
Sources: dev/src/main/java/com/google/adk/web/AdkWebServer.java42-150 dev/pom.xml24-112 maven_plugin/pom.xml12-15 dev/src/main/java/com/google/adk/web/CompiledAgentLoader.java79-109
The ADK provides automatic conversion of Java methods into LLM-callable function tools:
From tutorials/city-time-weather/src/main/java/com/google/adk/tutorials/CityTimeWeather.java79-96:
Tool registration at tutorials/city-time-weather/src/main/java/com/google/adk/tutorials/CityTimeWeather.java39-42:
| Tool Type | Purpose | Example |
|---|---|---|
FunctionTool | Wraps Java methods with automatic schema generation | FunctionTool.create(MyClass.class, "myMethod") |
GoogleSearchTool | Integrates Google Custom Search API | Requires API key and search engine ID |
LoadArtifactsTool | Loads files from BaseArtifactService | Used for retrieving uploaded files |
SaveArtifactsTool | Saves files to BaseArtifactService | Used for persisting generated content |
AgentTool | Delegates execution to sub-agents | Created automatically for agents in subAgents() |
McpToolset | Discovers and executes MCP server tools | Connects via stdio, SSE, or HTTP |
Sources: tutorials/city-time-weather/src/main/java/com/google/adk/tutorials/CityTimeWeather.java39-96
The ADK integrates OpenTelemetry for distributed tracing with automatic span creation throughout the execution lifecycle:
The Telemetry class at core/src/main/java/com/google/adk/Telemetry.java44-267 provides static methods for capturing execution context:
| Method | Purpose | Key Span Attributes |
|---|---|---|
traceCallLlm() | Captures LLM request/response at core/src/main/java/com/google/adk/Telemetry.java150-182 | gen_ai.request.model, gcp.vertex.agent.llm_request, gcp.vertex.agent.llm_response |
traceToolCall() | Captures tool invocation arguments at core/src/main/java/com/google/adk/Telemetry.java69-83 | gcp.vertex.agent.tool_call_args (JSON serialized) |
traceToolResponse() | Captures tool execution results at core/src/main/java/com/google/adk/Telemetry.java92-111 | gcp.vertex.agent.tool_response, gcp.vertex.agent.event_id |
traceSendData() | Captures data sent to LLM at core/src/main/java/com/google/adk/Telemetry.java191-223 | gcp.vertex.agent.data (history or new content) |
traceFlowable() | Manages OpenTelemetry scope for RxJava at core/src/main/java/com/google/adk/Telemetry.java256-266 | Ensures context propagation across async boundaries |
The ADK imports the OpenTelemetry BOM at pom.xml87-93 to manage consistent versions:
Core dependencies at core/pom.xml168-186:
opentelemetry-api: Core tracing APIopentelemetry-sdk: SDK implementationopentelemetry-exporter-otlp: OTLP protocol exporteropentelemetry-sdk-logs: Log integrationopentelemetry-sdk-trace: Trace SDKSources: core/src/main/java/com/google/adk/Telemetry.java44-267 core/pom.xml168-186 pom.xml87-93
The core module's primary external dependencies:
| Dependency | Purpose | Configuration |
|---|---|---|
google-genai | Gemini API client | core/pom.xml70-72 |
anthropic-java | Anthropic Claude API client | core/pom.xml34-40 |
mcp | Model Context Protocol SDK | core/pom.xml58-60 |
docker-java | Docker integration for MCP servers | core/pom.xml50-56 |
opentelemetry-api | Observability and tracing | core/pom.xml168-186 |
rxjava | Reactive streams for event emission | core/pom.xml155-157 |
jackson-databind | JSON serialization | core/pom.xml92-94 |
guava | Immutable collections and utilities | core/pom.xml83-86 |
Sources: core/pom.xml32-192 pom.xml77-278
The ADK provides a complete framework for building AI agents in Java with:
LlmAgent.Builder or YAML configurationBaseLlm abstraction supporting Gemini, Anthropic, OpenAI, and custom providersFunctionTool.create()Runner API, or containerized deploymentThe modular architecture separates concerns across eight layers (Client, Web Server, Orchestration, Agent, Flow Engine, Tool, Model, Services), enabling both rapid prototyping during development and scalable production deployments.
Sources: core/pom.xml26-28 pom.xml25-27 dev/src/main/java/com/google/adk/web/AdkWebServer.java42-93
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.