Development Environment

Relevant source files

• contrib/langchain4j/pom.xml
• contrib/samples/configagent/pom.xml
• contrib/samples/helloworld/pom.xml
• core/pom.xml
• dev/browser/index.html
• dev/browser/main-W7QZBYAR.js
• dev/browser/polyfills-B6TNHZQ6.js
• dev/pom.xml
• maven_plugin/pom.xml
• pom.xml
• tutorials/city-time-weather/pom.xml

The ADK development environment provides tooling for rapid agent iteration, testing, and debugging. The google-adk-dev module includes a Spring Boot development server, an Angular-based browser UI, agent auto-discovery, and testing infrastructure. This page provides an overview of the development tooling ecosystem; detailed documentation for each component is available in the following sub-sections:

• Development Server - Spring Boot server architecture and service configuration
• Agent Loading and Resolution - Agent discovery mechanisms and YAML preprocessing
• Browser Development UI - Angular UI, WebSocket communication, and agent visualization
• Telemetry and Observability - OpenTelemetry integration and distributed tracing
• Maven Plugin - Build integration and development server goals
• Testing Infrastructure - TestLlm, ReplayPlugin, and test utilities

For production deployment patterns, see Deployment Patterns.

Development Mode vs Production Mode

The ADK supports distinct operational modes optimized for different use cases:

Aspect	Development Mode	Production Mode
Entry Point	mvn exec:java or mvn google-adk:run	AdkWebServer.start(agents...)
Agent Loading	CompiledAgentLoader (auto-discovery)	AgentStaticLoader (explicit)
Agent Discovery	Scans source/build directories for ROOT_AGENT fields	Pre-created agent instances passed programmatically
Session Service	InMemorySessionService	Pluggable (e.g., Firestore)
Artifact Service	InMemoryArtifactService	Pluggable (e.g., Cloud Storage)
Memory Service	InMemoryMemoryService	Pluggable (e.g., Vertex Memory)
Hot Reload	Supported (YAML config monitoring)	Not applicable
Dev UI	Included at /dev-ui	Optional
Configuration	Zero-configuration for quick start	Explicit service configuration

Development mode prioritizes developer experience with automatic discovery and in-memory implementations. Production mode provides deterministic initialization and pluggable service implementations for persistence and scalability.

Sources: dev/src/main/java/com/google/adk/web/AdkWebServer.java42-175 tutorials/city-time-weather/README.md19-62

AdkWebServer Architecture

The development server is a Spring Boot application that provides web endpoints, agent execution, and the development UI.

The AdkWebServer class serves as both a Spring Boot application class and a programmatic server launcher. It configures service beans, web resource handlers, and integrates with the agent loading system.

Sources: dev/src/main/java/com/google/adk/web/AdkWebServer.java42-175

Service Bean Configuration

The server provides singleton beans for core services with in-memory implementations:

• BaseSessionService (dev/src/main/java/com/google/adk/web/AdkWebServer.java52-57): Returns InMemorySessionService for conversation state management
• BaseArtifactService (dev/src/main/java/com/google/adk/web/AdkWebServer.java65-69): Returns InMemoryArtifactService for file storage
• BaseMemoryService (dev/src/main/java/com/google/adk/web/AdkWebServer.java77-81): Returns InMemoryMemoryService for memory management
• ObjectMapper (dev/src/main/java/com/google/adk/web/AdkWebServer.java89-92): Configures Jackson with ADK standard settings

These in-memory implementations provide zero-configuration setup for development. Production deployments can replace these beans with persistent implementations.

Sources: dev/src/main/java/com/google/adk/web/AdkWebServer.java52-92

Web Resource Configuration

The server maps static resources and view controllers:

The resource handler (dev/src/main/java/com/google/adk/web/AdkWebServer.java98-126) serves static content from either:

1. The directory specified by adk.web.ui.dir system property
2. The classpath resource browser/ (default)

The view controller configuration (dev/src/main/java/com/google/adk/web/AdkWebServer.java132-137) redirects the root path to the dev UI and forwards dev UI requests to index.html.

Sources: dev/src/main/java/com/google/adk/web/AdkWebServer.java98-137

Agent Loading Strategies

The ADK provides two agent loading strategies through the AgentLoader interface:

Sources: dev/src/main/java/com/google/adk/web/AgentLoader.java22-77 dev/src/main/java/com/google/adk/web/CompiledAgentLoader.java47-377 dev/src/main/java/com/google/adk/web/AgentStaticLoader.java30-67

CompiledAgentLoader: Auto-Discovery

CompiledAgentLoader automatically discovers agents by scanning directories for compiled classes containing ROOT_AGENT fields. It is enabled by default or when adk.agents.loader=compiled.

Discovery Algorithm:

1. Start with the configured sourceDir from AgentLoadingProperties
2. Check if the directory is a Maven/Gradle project (has target/classes or similar)
3. If yes, scan the build output directory directly
4. If no, treat each subdirectory as an agent unit
5. For each agent unit, locate the build output directory from buildOutputDirs
6. Create a URLClassLoader for the build output directory
7. Walk all .class files in the directory
8. Use reflection to find public static fields named ROOT_AGENT of type BaseAgent
9. Extract the agent name and create a memoized supplier
10. Register the agent supplier in the agent map

Configuration Properties:

Property	Default	Description
adk.agents.source-dir	.	Base directory to scan for agents
adk.agents.build-output-dirs	["target/classes", "build/classes/java/main", "build/classes"]	Build output directories to search

Example Directory Structure:

source-dir/
├── target/classes/           # Maven build output (scanned if exists)
│   └── com/example/
│       └── MyAgent.class     # Contains ROOT_AGENT field
├── agent1/                   # Agent unit directory
│   └── target/classes/
│       └── Agent1.class
└── agent2/                   # Agent unit directory
    └── build/classes/
        └── Agent2.class

Thread Safety: Uses Suppliers.memoize() to ensure each agent is created only once when first requested. The agent map is immutable after construction.

Sources: dev/src/main/java/com/google/adk/web/CompiledAgentLoader.java47-377 dev/src/main/java/com/google/adk/web/config/AgentLoadingProperties.java22-44

AgentStaticLoader: Programmatic Registration

AgentStaticLoader takes pre-created agent instances and registers them by name. This is used when calling AdkWebServer.start(agents...) or when adk.agents.loader=static.

The loader stores agents in an ImmutableMap<String, BaseAgent> keyed by agent name (dev/src/main/java/com/google/adk/web/AgentStaticLoader.java44-46). The loadAgent() method performs a direct map lookup without reflection or dynamic loading.

Example Usage:

This approach:

1. Sets adk.agents.loader=static system property (dev/src/main/java/com/google/adk/web/AdkWebServer.java155)
2. Creates a Spring ApplicationContextInitializer (dev/src/main/java/com/google/adk/web/AdkWebServer.java163-171)
3. Registers an AgentStaticLoader instance as a singleton bean before context refresh
4. Starts the Spring application

Thread Safety: The agent map is immutable after construction, making this loader fully thread-safe for concurrent access.

Sources: dev/src/main/java/com/google/adk/web/AgentStaticLoader.java30-67 dev/src/main/java/com/google/adk/web/AdkWebServer.java153-174

Starting the Development Server

Using CompiledAgentLoader (Auto-Discovery)

Start the server with automatic agent discovery:

This executes AdkWebServer.main() which:

1. Sets the WebSocket buffer size to 10MB (dev/src/main/java/com/google/adk/web/AdkWebServer.java146-147)
2. Starts Spring Boot with SpringApplication.run() (dev/src/main/java/com/google/adk/web/AdkWebServer.java148)
3. Activates CompiledAgentLoader by default (or when adk.agents.loader=compiled)
4. Scans the source directory for agent classes with ROOT_AGENT fields

Sources: dev/src/main/java/com/google/adk/web/AdkWebServer.java144-150 tutorials/city-time-weather/README.md21-33

Using AgentStaticLoader (Programmatic)

Start the server with explicit agent instances:

Run with:

The start() method:

1. Sets adk.agents.loader=static to disable CompiledAgentLoader (dev/src/main/java/com/google/adk/web/AdkWebServer.java155)
2. Sets WebSocket buffer size (dev/src/main/java/com/google/adk/web/AdkWebServer.java156-158)
3. Creates a custom ApplicationContextInitializer (dev/src/main/java/com/google/adk/web/AdkWebServer.java163-171)
4. Registers AgentStaticLoader as a singleton bean with the provided agents
5. Starts the Spring application

Sources: dev/src/main/java/com/google/adk/web/AdkWebServer.java153-174 tutorials/city-time-weather/src/main/java/com/google/adk/tutorials/CityTimeWeather.java98-100

Configuration Options

System Property	Default	Description
adk.agents.loader	compiled	Agent loader type: compiled or static
adk.agents.source-dir	.	Source directory for CompiledAgentLoader
adk.web.ui.dir	(classpath)	Directory for dev UI static resources
server.port	8080	HTTP server port
org.apache.tomcat.websocket.DEFAULT_BUFFER_SIZE	10485760 (10MB)	WebSocket buffer size

Sources: dev/src/main/java/com/google/adk/web/AdkWebServer.java49-50 dev/src/main/java/com/google/adk/web/AdkWebServer.java146-147 dev/src/main/java/com/google/adk/web/config/AgentLoadingProperties.java26-27

Telemetry and Observability

The Telemetry utility class provides OpenTelemetry-based tracing for agent execution, capturing LLM interactions, tool calls, and data flow.

Key Tracing Functions:

Function	Purpose	Key Attributes
traceToolCall()	Records tool invocation arguments	tool_call_args (JSON)
traceToolResponse()	Records tool execution results	event_id, tool_response, invocation_id, session_id
traceCallLlm()	Records LLM request/response pairs	llm_request, llm_response, gen_ai.request.model, invocation_id, session_id, event_id
traceSendData()	Records data sent to agent/model	data (JSON), invocation_id, session_id
traceFlowable()	Manages OpenTelemetry scope for RxJava Flowables	Scope lifecycle via doFinally

LLM Request Filtering:

The buildLlmRequestForTrace() method (core/src/main/java/com/google/adk/Telemetry.java121-140) filters the LLM request before tracing to exclude binary data:

• Includes: model, config (generation config), contents (text parts only)
• Excludes: Parts with inlineData (binary content like images/audio)

This reduces trace payload size while preserving essential debugging information.

RxJava Scope Management:

traceFlowable() (core/src/main/java/com/google/adk/Telemetry.java256-266) ensures OpenTelemetry context propagation across RxJava async boundaries:

1. Activates the span context with spanContext.makeCurrent()
2. Creates the Flowable with active scope
3. Uses doFinally() to close the scope when the stream terminates (success, error, or cancellation)
4. Ends the span after scope closure

This pattern is necessary because RxJava Flowables execute lazily—operators run at subscription time, not construction time. Using try-with-resources would close the scope before subscription, breaking span parent-child relationships.

Sources: core/src/main/java/com/google/adk/Telemetry.java44-267

Development Workflow

The typical development workflow uses auto-discovery for rapid iteration:

Key Features:

1. Zero Configuration: No explicit agent registration required
2. Hot Reload: YAML configuration changes are detected (for config-based agents)
3. Instant Feedback: Changes to agent code are reflected after recompilation
4. Browser UI: Interactive testing without writing API clients
5. Telemetry: All traces exported to Dev UI for debugging

Sources: dev/src/main/java/com/google/adk/web/AdkWebServer.java144-150 dev/src/main/java/com/google/adk/web/CompiledAgentLoader.java89-109 tutorials/city-time-weather/README.md1-64