JetBrains Koog: a Kotlin agent framework for JVM, Android and iOS teams

What Koog solves for Kotlin and Java teams

Most agent frameworks assume Python or TypeScript. A JVM service that wants an agent either calls out to a separate process or wraps a Python library. Koog takes the other route: it is a Kotlin framework, with a Java API as well, so the agent lives in the same process, build and deployment pipeline as the rest of the application. The README describes it as "a Kotlin-based framework designed to build and run AI agents entirely in idiomatic Kotlin and Java API".

The repository layout backs that claim. There are top-level modules for Spring Boot (koog-spring-boot-starter), Ktor (koog-ktor), Spring AI (koog-spring-ai, koog-spring-ai-v2) and an AWS Bedrock agent runtime (koog-bedrock-agentcore-runtime). Examples cover Java and Kotlin variants of both Spring Boot and Spring AI, plus a Compose app, a JS example and notebooks. That is a framework aimed at teams that already run a JVM backend, not at people prototyping in a notebook and stopping there.

The target audience is narrower than "anyone building agents". If your services are Kotlin with Gradle and you want tool calls, streaming and multi-provider LLM routing without leaving the type system, Koog is written for you. If your team is Python-first, the framework's main advantage, staying inside the JVM, does not apply.

How Koog agents actually run

The quickstart in the README shows the core shape. An AIAgent is constructed from a prompt executor, a system prompt and a model. The executor is where provider routing happens: the example passes MultiLLMPromptExecutor wrapping OpenAILLMClient, and the comment notes Anthropic, Google and OpenRouter as alternatives. A call to agent.run returns the result as a string in that example.

The README lists graph-based workflows as the mechanism for complex behaviour. Instead of a single prompt loop, you define nodes and edges and let execution follow the graph, which is how branching and multi-step tool use get expressed. Around that, the framework documents built-in retries and agent persistence, which the README describes as the ability to "restore the agent state at specific points during execution". Persistence is what makes a long-running agent survive a process restart rather than restarting the conversation.

Two more mechanisms matter for cost and context. History compression is described as built in, aimed at token usage in long conversations. And LLM switching is documented as changing provider mid-conversation without losing history, which is useful when a cheap model handles routing and an expensive one handles the hard turns. Tracing and OpenTelemetry exporters (W&B Weave, Langfuse) are listed for observability, and MCP and ACP integration are listed for tool and client interop.

Adding Koog to a Gradle build and running a first agent

Start with the requirements the README states: JDK 17 or higher on the JVM, and Kotlin 2.3.10 or higher set explicitly in existing projects. Then add the dependency. The README gives this Kotlin DSL snippet for build.gradle.kts:

dependencies {
    implementation("ai.koog:koog-agents:1.2.0")
    implementation("ai.koog:koog-agents-additions:1.2.0-beta")
}

Note the version split: the main artifact is 1.2.0 while the additions artifact is published as 1.2.0-beta. The README also requires mavenCentral() in your repository list. Maven users get a different artifact name, koog-agents-jvm, with the same version, plus koog-agents-additions-jvm at 1.2.0-beta.

With the dependency resolved, the README's quickstart is the smallest real program. It reads an API key from the environment, so export OPENAI_API_KEY before running:

fun main() = runBlocking {
    val apiKey = System.getenv("OPENAI_API_KEY")

    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(OpenAILLMClient(apiKey)),
        systemPrompt = "You are a helpful assistant. Answer user questions concisely.",
        llmModel = OpenAIModels.Chat.GPT4o
    )

    val result = agent.run("Hello! How can you help me?")
    println(result)
}

What you should see is the model's reply printed to standard output. If the key is missing, the client cannot authenticate; the README's comment is the only setup note it gives for credentials. From here, the practical next step is one of the examples directories rather than the docs, since examples/simple-examples and examples/spring-boot-kotlin show a working build around the same API.

Where Koog gets in your way

The Kotlin version requirement is the first real constraint. Existing projects must set Kotlin 2.3.10 or higher explicitly, and the README points to gradle/libs.versions.toml for the exact transitive set (kotlinx-coroutines 1.10.2, kotlinx-serialization 1.10.0, kotlinx-datetime 0.7.1). A codebase pinned to an older Kotlin, or one that has not yet moved to JDK 17, cannot adopt Koog without an upgrade first. That is a migration, not a dependency line.

The second constraint is the beta artifact. koog-agents-additions ships at 1.2.0-beta while the core is at 1.2.0. If the feature you need lives in additions, you are depending on a beta, and the README does not describe what the beta designation covers or when it ends.

The third is maturity signalling. The README carries a JetBrains incubator project badge, and the repository is a JetBrains open source project rather than a long-supported product line. The last push to the develop branch was on 2026-09-07, so the code is moving, but movement is not the same as a support commitment. The README also does not document rollback of persisted agent state, and it does not describe what happens to in-flight runs during a version upgrade. If your agent holds long-lived state, those gaps matter more than the feature list.

Finally, the framework is the wrong tool if you want an agent that is not part of a JVM or Kotlin Multiplatform application. The multi-target story (JVM, JS, WasmJS, Android, iOS) only pays off if you are already building with Kotlin Multiplatform.

Koog compared with Spring AI

Spring AI is the obvious comparison for a JVM team, and the two take different routes. Spring AI is a Spring project: the unit of work is a Spring bean, configuration lives in application properties, and the surrounding machinery is auto-configuration. Koog is a Kotlin framework first, with a Spring Boot starter (koog-spring-boot-starter) and Spring AI bridges (koog-spring-ai, koog-spring-ai-v2) layered on top. The repository's examples directory includes spring-ai-java, spring-ai-kotlin, spring-boot-java and spring-boot-kotlin, which suggests the project expects to sit alongside Spring rather than replace it.

The practical difference is where agent logic lives. With Spring AI, orchestration tends to be expressed through Spring abstractions and the surrounding application. With Koog, the README describes graph-based workflows as the way to design "complex agent behaviors", so the control flow of the agent is a first-class object in the framework, independent of the DI container. If you want the agent's branching visible as a graph in your own code, Koog's model is more direct. If you want everything wired by Spring Boot conventions and your team already knows those conventions, Spring AI asks less of you.

The second difference is target reach. Spring AI is a JVM story. Koog lists JVM, JS, WasmJS, Android and iOS, so a Kotlin Multiplatform team that needs the same agent on Android and in a browser has a path that Spring AI does not offer.

Licence, maintenance and the cost of upgrading

Koog is licensed under Apache-2.0, with the licence text at LICENSE.txt. For most teams that means permissive use with the usual obligations around notices and attribution; the repository does not add a separate commercial tier in what the README describes, so there is no licence key or seat to buy. This is not legal advice, and the Apache-2.0 text is the authority.

Maintenance is where you should read carefully. The last push to the default branch was on 2026-09-07, and releases are frequent: 1.0.0 on 2026-05-21, 1.1.1 on 2026-07-20, 1.2.0 on 2026-08-28. The README says the framework "is stable and follows semantic versioning" and points to VERSIONING.md for details, so the project states its own compatibility policy. Read that file rather than assuming what semantic versioning covers for an incubator project.

The upgrade cost is mostly the toolchain. Because existing projects must set Kotlin 2.3.10 or higher, a Koog upgrade can pull your Kotlin version with it, and the transitive kotlinx libraries are pinned in gradle/libs.versions.toml. Budget for a Kotlin upgrade as part of any Koog upgrade, and check VERSIONING.md for what the project promises across minor versions. The README does not describe a deprecation window or a long-term support branch.

Editorial conclusion

Adopt Koog if you are a Kotlin or Java team that wants agents inside an existing Spring Boot or Ktor service and can move to Kotlin 2.3.10 with JDK 17. Do not adopt it if your stack is Python or TypeScript, or if you need a multi-year support commitment; the project is a JetBrains incubator project. Before committing, verify the Kotlin version in your build, confirm that ai.koog:koog-agents:1.2.0 resolves from Maven Central, and read VERSIONING.md for what semantic versioning covers.

Frequently asked questions

Official sources

1. JetBrains/koog on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases