|
| 1 | +# Gemini Code Assistant Context |
| 2 | + |
| 3 | +This document provides context for the Gemini Code Assistant to understand the "Agent Development Kit (ADK) for Java" project. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +The "Agent Development Kit (ADK) for Java" is an open-source, code-first toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control. It allows developers to define agent behavior, orchestration, and tool use directly in Java code, enabling robust debugging, versioning, and deployment. |
| 8 | + |
| 9 | +The project is a multi-module Maven project with the following key modules: |
| 10 | + |
| 11 | +* **core**: The core module contains the main logic of the ADK. It includes the following key components: |
| 12 | + * **`BaseAgent`**: The abstract base class for all agents. It defines the basic properties of an agent, such as its name, description, and sub-agents. It also defines the `runAsync()` and `runLive()` methods, which are the entry points for running an agent. |
| 13 | + * **`LlmAgent`**: The primary implementation of a `BaseAgent`. It can be configured with a model, instructions, tools, and sub-agents. |
| 14 | + * **`BaseSessionService`**: An interface for managing sessions. It provides methods for creating, retrieving, listing, and deleting sessions, as well as listing and appending events to a session. |
| 15 | + * **`Runner`**: The main class for running agents. It takes a `BaseAgent`, a `BaseArtifactService`, a `BaseSessionService`, and a `BaseMemoryService` as input. It provides `runAsync()` and `runLive()` methods for running the agent. |
| 16 | + * **Core Runtime**: The core runtime of the ADK is responsible for orchestrating the execution of agents. It uses the `Runner` to run the agent and the `BaseSessionService` to manage the session. |
| 17 | +* **dev**: This module contains the development UI for testing, evaluating, and debugging agents. It includes a Spring Boot-based web server that can be used to debug agents developed using ADK. |
| 18 | + |
| 19 | + **Agent Loading:** |
| 20 | + |
| 21 | + The `dev` module provides a flexible mechanism for loading agents into the ADK Web Server through the `AgentLoader` interface. This interface has two implementations: |
| 22 | + |
| 23 | + * **`AgentStaticLoader`**: This loader takes a static list of pre-created agent instances. It's ideal for production environments or when you have a fixed set of agents. |
| 24 | + * **`CompiledAgentLoader`**: This loader scans a directory for pre-compiled agent classes. It identifies agents by looking for a `public static` field named `ROOT_AGENT` of type `BaseAgent`. This is useful for development environments where you want to automatically discover and load agents. |
| 25 | +* **maven_plugin**: This module provides a Maven plugin for the ADK. The plugin provides the `google-adk:web` goal, which starts the ADK Web Server with user-provided agents. The plugin can be configured with the following parameters: |
| 26 | + |
| 27 | + * `agents`: The fully qualified class name of an `AgentLoader` implementation or a path to a directory containing agent configurations. |
| 28 | + * `port`: The port number for the web server. |
| 29 | + * `host`: The host address to bind the web server to. |
| 30 | + * `hotReloading`: Whether to enable hot reloading of agent configurations. |
| 31 | + * `registry`: The fully qualified class name of a custom `ComponentRegistry` subclass. |
| 32 | + |
| 33 | + The `maven_plugin` module also includes the `ConfigAgentLoader` class, which is an implementation of the `AgentLoader` interface that loads agents from YAML configuration files. It scans a source directory for subdirectories containing a `root_agent.yaml` file. Each subdirectory is treated as an agent, and the folder name is used as the agent identifier. The `ConfigAgentLoader` also supports hot-reloading. |
| 34 | + |
| 35 | + |
| 36 | +## Building and Running |
| 37 | + |
| 38 | +The project is built using Maven. Use the `./mvnw` wrapper script for all commands. |
| 39 | + |
| 40 | +### Maven Commands |
| 41 | + |
| 42 | +* **Build the entire project**: |
| 43 | + |
| 44 | + ```shell |
| 45 | + ./mvnw clean install |
| 46 | + ``` |
| 47 | + |
| 48 | +* **Run tests**: |
| 49 | + |
| 50 | + ```shell |
| 51 | + ./mvnw test |
| 52 | + ``` |
| 53 | + |
| 54 | +* **Format code**: |
| 55 | + |
| 56 | + ```shell |
| 57 | + ./mvnw fmt:format |
| 58 | + ``` |
| 59 | + |
| 60 | +* **Skip tests during build**: |
| 61 | + |
| 62 | + ```shell |
| 63 | + ./mvnw clean install -DskipTests |
| 64 | + ``` |
| 65 | + |
| 66 | +## Development Workflow |
| 67 | + |
| 68 | +### Running the Development UI |
| 69 | + |
| 70 | +The development UI provides an interactive chat interface for testing and debugging agents. It can be started using the Maven plugin: |
| 71 | + |
| 72 | +* **Using an `AgentLoader` class**: |
| 73 | + |
| 74 | + ```shell |
| 75 | + mvn google-adk:web -Dagents=com.example.MyAgentLoader.INSTANCE -Dport=8000 |
| 76 | + ``` |
| 77 | + |
| 78 | +* **Using a config directory (YAML-based agents)**: |
| 79 | + |
| 80 | + ```shell |
| 81 | + mvn google-adk:web -Dagents=path/to/config/dir |
| 82 | + ``` |
| 83 | + |
| 84 | +* **With hot reloading disabled**: |
| 85 | + |
| 86 | + ```shell |
| 87 | + mvn google-adk:web -Dagents=... -DhotReloading=false |
| 88 | + ``` |
| 89 | + |
| 90 | +Once started, the dev UI is available at `http://localhost:8000` (or the specified port). |
| 91 | + |
| 92 | +## Development Conventions |
| 93 | + |
| 94 | +* **Coding Style**: The project follows the Google Java Style Guide. The `fmt-maven-plugin` is used to format the code automatically. |
| 95 | + * **Import Style**: Always use import statements instead of fully qualified class names in code. Prefer `import com.google.adk.agents.InvocationContext;` over using `com.google.adk.agents.InvocationContext` directly in the code. |
| 96 | +* **Testing**: The project uses JUnit 5 for testing. Tests are located in the `src/test/java` directory of each module. |
| 97 | +* **Contributing**: Contributions are welcome. Please see the `CONTRIBUTING.md` file for more information. |
0 commit comments