adk-kotlin-setup
Skill307 starsChanged 53 days agoApache-2.0View on GitHub
Sets up ADK Kotlin: either a consumer project that depends on the published com.google.adk artifacts (Gradle or Maven coordinates, KSP wiring for the @Tool processor, Kotlin / JDK / Android floors) or a contributor checkout of the adk-kotlin repository (prerequisites, build and test commands, source-set placement, CI checks, PR rules). Use when asked to add ADK to a project, wire the KSP processor, fix an "unresolved reference" to a generated tool class, align Kotlin or JDK versions, build or test the repository, or prepare a pull request. Don't use for writing agents and tools (use adk-kotlin-agent-builder).
- Reads credentials
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adk-kotlin-agent-builderSkill
- root-only-skillSkill
- skill1Skill
- skill2Skill
- mismatchedSkill
- skill-unauthorizedSkill
- valid-skillSkill
- mismatchedSkill
- skill1Skill
- echo_skillSkill
- py_skillSkill
- cast-fireballSkill
- summon-familiarSkill
- cast-fireballSkill
- summon-familiarSkill
- translateSkill
- cast-fireballSkill
- summon-familiarSkill
- translateSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
All artifacts share the group com.google.adk and one release version (see the install snippet in README.md).
- Very specific: line 49
Put the processor on a ksp configuration, never implementation.
- Very specific: line 64
Always the Gradle wrapper, ./gradlew.
- Distinctive: line 115
Never hand-edit release versions.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ADK Kotlin Setup
Checked against main after release 1.1.0 (September 2026).
This page gives rules, not version numbers. Current values live in gradle/libs.versions.toml, the root build.gradle.kts, gradle.properties, settings.gradle.kts and .github/workflows/. Read them before quoting a number. When this page and those files disagree, the files are right.
Consumer setup
Coordinates
All artifacts share the group com.google.adk and one release version (see the install snippet in README.md). Published artifact IDs:
google-adk-kotlin-corefor the runtime, andgoogle-adk-kotlin-processorfor@Toolcode generation.google-adk-kotlin-<module>for the other JVM and multiplatform modules:webserver,integrations(pulls in everyintegrations-*module),integrations-spring,integrations-anthropic,integrations-openai,integrations-bigquery,a2a,litertlm.- The Android-only modules are published with an
-androidsuffix:google-adk-kotlin-firebase-androidandgoogle-adk-kotlin-mlkit-android. ML Kit uses a-betaversion of the shared release.
testing and the examples are not published. The artifactId in a module's build.gradle.kts is authoritative.
plugins {
kotlin("jvm") version "<your Kotlin version>"
id("com.google.devtools.ksp") version "<a KSP release that supports it>"
}
dependencies {
implementation("com.google.adk:google-adk-kotlin-core:<adk version>")
ksp("com.google.adk:google-adk-kotlin-processor:<adk version>") // only for @Tool
}Since KSP 2.3.0, KSP versions are independent of Kotlin versions; pick a KSP release that supports your compiler. Older KSP versions are named <kotlin>-<ksp> and must match the compiler exactly.
Maven cannot read Gradle Module Metadata. A module built with kotlin("multiplatform") (core among them) must be named by its JVM artifact, google-adk-kotlin-<module>-jvm; plain JVM modules have no suffix. The module's build.gradle.kts plugins block tells you which applies. Without KSP, use ReflectiveTools.fromMethod (see its KDoc) or hand-written tools.
Floors
- Kotlin 2.1 or newer. Artifacts are compiled for language and API level 2.1 whatever compiler builds them (
kotlinCompatVersionin the root build file). An app that compiles against Ktor, directly or through an ADK API whose signature uses its types (for example to mountadkApiModulein its own server or to constructVertexAiSessionServicewith its defaultHttpClient), or that usesintegrations-openaior adds the MCP Kotlin SDK (forRemoteMcpToolsetConfig) on Android, also needs a compiler that can read the Kotlin metadata of those releases (versions ingradle/libs.versions.toml); a compiler reads metadata at most one minor version newer than itself. - JDK 17 or newer; the LiteRT-LM module needs JDK 21.
- Android:
minSdkandcompileSdkareandroidMinSdk/androidCompileSdkin the root build file.
KSP wiring for @Tool
- Put the processor on a
kspconfiguration, neverimplementation. In Kotlin Multiplatform use the per-target configurations (kspJvm,kspAndroid,kspJvmTest, and so on);core/build.gradle.ktsshows the pattern. - Reference generated classes only from leaf source sets (
jvmMain,androidMain, leaf test sets).common*source sets cannot see per-platform KSP output.
For Unresolved reference to a generated tool, check in order: the KSP plugin is applied, the processor is on the right ksp* configuration, the KSP version supports your Kotlin compiler, and the referencing file is not in a common* source set.
Credentials
Prefer Vertex AI with Application Default Credentials (ADC) over API keys, which are long-lived secrets. Gemini and Claude take vertexCredentials = VertexCredentials(location = "global"), which reads the project from GOOGLE_CLOUD_PROJECT and credentials from ADC (gcloud auth application-default login). Without it, Gemini reads GOOGLE_API_KEY or GEMINI_API_KEY, and Claude reads ANTHROPIC_API_KEY. ChatCompletions reads OPENAI_BASE_URL when no base URL is passed, and OPENAI_API_KEY when neither a key nor a base URL is passed. On Android, use the Firebase AI module instead of API keys.
Contributor setup
Prerequisites
- JDK 17 and JDK 21 installed (some modules force a 21 toolchain).
- An Android SDK matching
androidCompileSdk. A full build needs it even for JVM-only changes. - Always the Gradle wrapper,
./gradlew.
gradle.properties gives the Gradle daemon a very large heap, and Kotlin compiles inside the daemon. On a smaller machine, override the daemon's heap:
./gradlew -Dorg.gradle.jvmargs="-Xmx4g -XX:MaxMetaspaceSize=1g" buildGRADLE_OPTS only sizes the client JVM, and -Pkotlin.daemon.jvmargs does nothing with the in-process compiler.
Build and test
Kotlin Multiplatform modules have no test task, so ./gradlew test passes without running their tests. Use build:
| Change | Run |
| a module | ./gradlew :google-adk-kotlin-<module>:build for it and every module that depends on it |
core or testing | ./gradlew build |
| KDoc | also ./gradlew dokkaGenerate (it fails on any KDoc warning, and build does not run it) |
| one test class while iterating | ./gradlew :google-adk-kotlin-core:jvmTest --tests "<fully.qualified.Test>", then the module build |
./gradlew :google-adk-kotlin-<module>:tasks --all lists a module's test tasks. Integration suites that need credentials or local models skip themselves unless their environment variables are set.
Where new code goes
Core is Kotlin Multiplatform with two custom intermediate source sets:
commonMain platform-neutral runtime
└─ commonJvmAndroidMain shared by JVM and Android
├─ jvmMain JVM-only (MCP, Google Cloud clients)
└─ androidMain Android-only (Room, AppSearch)- Platform-neutral code goes in
commonMain, with no JVM or Android APIs. - Code that needs
java.*, OpenTelemetry or Reactive Streams goes incommonJvmAndroidMain. - Code for one platform goes in
jvmMainorandroidMain. - Tests mirror the source sets. Shared test fixtures go in the unpublished
testingmodule.
CI
.github/workflows/ is authoritative. CI builds across a JDK matrix, runs dokkaGenerate separately, fails if the build dirtied the tree, and checks the PR's commit count and title.
Code and PR rules
- Google Kotlin Style: two-space indent, 100 columns (
ktfmt --google-style). - Apache 2.0 header on every
.ktand.ktsfile. - New tests use
runBlockingrather thanrunTest. - One commit per PR. Amend and force-push with
--force-with-leaseinstead of adding commits. - Conventional Commit PR title. PRs are squash-merged and release-please reads the title:
feat:bumps the minor version with a Features entry,fix:bumps the patch, anddocs:,test:,refactor:,chore:release nothing. Choose by what the change is. - adk-python is the source of truth for behaviour; align with it (
CONTRIBUTING.md). - Never hand-edit release versions; release-please maintains them.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

