This document provides an introduction to the ADK (Agent Development Kit) Java repository, explaining its purpose, core architecture, and module structure. For detailed information about specific subsystems, refer to the following pages:
The Agent Development Kit (ADK) is an open-source, code-first Java framework for building, evaluating, and deploying AI agents with large language model (LLM) integration. The framework provides abstractions for agent orchestration, multi-turn conversations, tool execution, and session management, enabling developers to create sophisticated agentic systems that can interact with external services and other agents.
Sources: core/pom.xml28 pom.xml27
ADK organizes AI agent development around five primary abstractions:
The BaseAgent abstraction represents an autonomous unit that processes user input and generates responses. Agents can be composed hierarchically through the subAgents relationship, enabling modular agent design and delegation patterns. The primary implementation is LlmAgent, which uses language models for decision-making.
Sources: core/src/main/java/com/google/adk/agents/BaseAgent.java40-456
The Runner class orchestrates agent execution and manages the lifecycle of an invocation. It coordinates session state, artifact persistence, memory services, and plugin execution. Each agent invocation creates an InvocationContext that carries execution state through the agent hierarchy.
Sources: core/src/main/java/com/google/adk/runner/Runner.java66-787 core/src/main/java/com/google/adk/agents/InvocationContext.java42-578
The BaseLlmFlow abstraction controls how agents interact with LLMs. SingleFlow executes a single request-response cycle, while AutoFlow handles multi-turn conversations with automatic tool calling. The flow engine manages request preprocessing, LLM invocation, response processing, and tool execution.
Sources: core/src/main/java/com/google/adk/flows/llmflows/BaseLlmFlow.java63-643
Tools extend agent capabilities by executing external functions. FunctionTool wraps Java methods as tools with automatic schema generation from method signatures. BaseTool provides a general interface for custom tool implementations. Tools can be organized into BaseToolset collections, including McpToolset for Model Context Protocol integration.
Sources: core/src/main/java/com/google/adk/flows/llmflows/Functions.java63-607
BaseLlm abstracts LLM provider APIs. The framework includes Gemini for Google's Gemini models and Anthropic for Claude models. Models are resolved through LlmRegistry, which supports both direct instances and string-based lookups. BaseLlmConnection enables streaming and bidirectional communication in live mode.
Sources: core/pom.xml34-40 core/pom.xml70-72
The ADK repository is organized as a multi-module Maven project. The following diagram maps module artifacts to their primary responsibilities:
Module Descriptions:
| Module | Artifact ID | Purpose |
|---|---|---|
core | google-adk | Core framework with agents, flows, tools, models, and sessions |
dev | google-adk-dev | Spring Boot development server with WebSocket support and browser UI |
maven_plugin | google-adk-maven-plugin | Maven plugin for running agents via mvn google-adk:run |
contrib/langchain4j | google-adk-langchain4j | Bidirectional integration with LangChain4j tools and agents |
contrib/spring-ai | google-adk-spring-ai | Integration layer for Spring AI framework |
contrib/firestore-session-service | google-adk-firestore-session-service | Cloud-based session persistence using Firestore |
a2a | google-adk-a2a | Agent-to-Agent protocol client and server implementations |
contrib/samples/configagent | configagent-samples | Example agents defined via YAML configuration |
contrib/samples/helloworld | google-adk-sample-helloworld | Minimal agent example |
tutorials/city-time-weather | google-adk-tutorials-city-time-weather | Multi-agent tutorial demonstrating composition |
Sources: pom.xml29-41 core/pom.xml26 dev/pom.xml24 maven_plugin/pom.xml12 contrib/langchain4j/pom.xml27 contrib/samples/configagent/pom.xml13 contrib/samples/helloworld/pom.xml28 tutorials/city-time-weather/pom.xml27
ADK integrates with several external libraries and services. The following table lists the primary dependencies managed by the parent POM:
| Dependency | Version Property | Purpose |
|---|---|---|
google-genai | ${google.genai.version} | Google Gemini API client |
anthropic-java | ${anthropic.version} | Anthropic Claude API client |
mcp (Model Context Protocol SDK) | ${mcp.version} | External tool server integration |
spring-boot | ${spring-boot.version} | Development server framework |
opentelemetry-bom | ${otel.version} | Observability (traces, metrics, logs) |
docker-java | ${docker-java.version} | Container management for MCP servers |
jackson-databind | ${jackson.version} | JSON serialization and YAML parsing |
rxjava | ${rxjava.version} | Reactive streams for async execution |
langchain4j-bom | ${langchain4j.version} | LangChain4j integration (optional) |
Sources: pom.xml43-76 pom.xml78-283
ADK provides multiple entry points depending on the use case:
Developers can build agents programmatically using the builder pattern:
Primary classes: LlmAgent.Builder, Gemini, Anthropic, FunctionTool, BaseToolset
Sources: Referenced in tutorial applications
Agents can be defined declaratively in YAML files and loaded via ConfigAgentUtils:
Primary classes: ConfigAgentUtils, LlmAgentConfig, YamlPreprocessor, ComponentRegistry
Sources: contrib/samples/configagent/
The google-adk-dev module provides a Spring Boot server with a browser-based UI for testing agents. Run it using the Maven plugin:
The server starts on port 8080 and provides WebSocket endpoints for real-time interaction.
Primary classes: DevServer, AgentWebSocketController, ComponentRegistry
Sources: dev/pom.xml54-60 maven_plugin/pom.xml12-15
The Runner class orchestrates agent execution in production environments:
Primary classes: Runner, InvocationContext, BaseSessionService, BaseArtifactService, RunConfig
Sources: core/src/main/java/com/google/adk/runner/Runner.java66-160
ADK uses an event-driven architecture where all interactions are modeled as Event objects. Each event represents a turn in the conversation, whether from the user, the model, or a tool execution.
Event Flow:
Event with author="user"Event objects with author=agentNameEvent objectsSession via BaseSessionService.appendEvent()EventActions within events can trigger state changes, confirmations, or agent transfersKey Event Fields:
id: Unique event identifierinvocationId: Groups events from a single user requestauthor: Event creator ("user", agent name, or "model")content: Message content with parts (text, function calls, function responses)actions: State mutations, confirmations, and control flow directivesbranch: Conversation fork identifier for parallel execution pathsSources: core/src/main/java/com/google/adk/runner/Runner.java304-351 Event class referenced throughout
All agent execution in ADK is asynchronous and uses RxJava reactive types:
Flowable<Event>: Stream of events from agent executionSingle<T>: Asynchronous single-value operationsMaybe<T>: Operations that may or may not produce a valueCompletable: Fire-and-forget operationsThis enables:
flatMap, concatMap, switchIfEmpty build processing chainsSources: core/src/main/java/com/google/adk/flows/llmflows/BaseLlmFlow.java49-54 core/src/main/java/com/google/adk/runner/Runner.java53-56
ADK provides 11+ callback hooks for extending agent behavior without modifying core logic. The PluginManager combines multiple BasePlugin implementations and invokes callbacks at specific lifecycle points.
Callback Types:
| Callback | Invocation Point | Use Case |
|---|---|---|
beforeRun | Before agent starts | Authentication, validation |
afterRun | After agent completes | Cleanup, post-processing |
onUserMessage | After user input received | Input filtering, transformation |
beforeAgent | Before agent execution | Agent selection logic |
afterAgent | After agent execution | Result modification |
beforeModel | Before LLM call | Request modification, caching |
afterModel | After LLM response | Response filtering |
beforeTool | Before tool execution | Security checks, validation |
afterTool | After tool execution | Result transformation |
onEvent | After event created | Logging, analytics |
onModelError / onToolError | On errors | Error handling, retry logic |
Sources: core/src/main/java/com/google/adk/runner/Runner.java296 Plugin system referenced in Runner and BaseLlmFlow
McpToolset connects to external MCP servers via stdio, SSE, or HTTP transports. McpSessionManager manages server lifecycle and tool discovery.
Primary classes: McpToolset, McpSessionManager, McpTransport
Sources: core/pom.xml58-60
The google-adk-a2a module implements both client and server sides of the A2A protocol:
RemoteA2AAgent: Calls remote agents as if they were localA2ARemoteController: Exposes local agents as A2A servicesPartConverter, EventConverter: Bidirectional type conversionPrimary classes: RemoteA2AAgent, A2ARemoteService, PartConverter, EventConverter
Sources: pom.xml39-40
This overview establishes the foundational concepts of ADK. For implementation details, refer to the specialized pages listed at the beginning of this document.
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.