CtrlK
BlogDocsLog inGet started
Tessl Logo

jbaruch/koog

Koog 1.2 idioms, gotchas, and scaffolding skills for Kotlin agents on the JVM

71

Quality

89%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

module-coordinates.mdrules/

alwaysApply:
Yes

Module Coordinates

Use 1.2, not 1.0, and never 0.x

  • All Koog artifacts ship under group ai.koog. The current umbrella is ai.koog:koog-agents:1.2.0 (released 2026-08-28)
  • Never mix 0.x with 1.x — the API surface diverged at 1.0 (factory functions, planner module split, HTTP transport decoupling) and a mixed graph fails at link time
  • 1.0 → 1.2 is source-compatible for the graph DSL: subgraphWithTask, subgraphWithVerification, CriticResult, ToolSet, MCP and memory all survive unchanged. The only removal is PromptAugmenter.SECTION_SEPARATOR, in a beta module
  • The hosted Maven snippet on docs.koog.ai/quickstart/ lags the release. Don't copy it — check repo1.maven.org/maven2/ai/koog/koog-agents/maven-metadata.xml

Two version lines. This is the single biggest source of "could not find"

The umbrella is 1.2.0. A large and growing set of modules publishes only on the -beta line, at 1.2.0-beta. 1.2.0 does not exist for them, and 1.2.0-beta does not exist for the umbrella. Getting this backwards is the most common build failure on this framework.

ModuleCoordinate
umbrellaai.koog:koog-agents:1.2.0
additionsai.koog:koog-agents-additions:1.2.0-beta
MCP clientai.koog:agents-mcp:1.2.0-beta
CLI agentsai.koog:agents-cli:1.2.0-beta
Agent Skillsai.koog:skills:1.2.0-beta
Google clientai.koog:prompt-executor-google-client:1.2.0-beta
simple executorsai.koog:prompt-executor-llms-all:1.2.0-beta
long-term memoryai.koog:agents-features-longterm-memory:1.2.0-beta
file/dir toolsai.koog:agents-ext:1.2.0-beta
plannerai.koog:agents-planner:1.2.0-beta
Ktor pluginai.koog:koog-ktor:1.2.0-beta
Spring Boot starterai.koog:koog-spring-boot-starter:1.2.0-beta
MCP serverai.koog:agents-mcp-server:1.2.0-beta
A2Aai.koog:a2a-core / -client / -server:1.2.0-beta
vector RAGai.koog:rag-vector:1.2.0-beta
Redis prompt cacheai.koog:prompt-cache-redis:1.2.0-beta

Stable line (1.2.0), for contrast: koog-agents, agents-test, rag-base, embeddings-base/-llm, agents-features-opentelemetry, -snapshot, -trace, -tokenizer, -sql, -event-handler, -persistence-jdbc, -chat-history-jdbc, -chat-memory-sql, prompt-cache-files, prompt-executor-cached, prompt-tokenizer, http-client-ktor.

Note that the split does not follow "core vs satellite": agents-features-chat-history-jdbc is stable while agents-features-chat-history-aws is beta, and the planner moved onto the beta line after 1.0. Query the metadata; do not pattern-match on the name.

When a Koog dependency fails to resolve, check the version line before anything else. Query the module's own maven-metadata.xml; do not assume it tracks the umbrella.

The umbrella does NOT bundle every provider

koog-agents:1.2.0 pulls the clients for OpenAI, Anthropic, Bedrock and Ollama. It does not pull Google.

  • For Gemini you must add both prompt-executor-google-client and prompt-executor-llms-all (the latter is where simpleGoogleAIExecutor lives), both at 1.2.0-beta
  • Symptom when you forget: Unresolved reference 'google' and Unresolved reference 'simpleGoogleAIExecutor' while AIAgent itself resolves fine

Gradle takes the bare coordinate; only Maven takes -jvm

  • Gradle → bare coordinate (ai.koog:agents-mcp:1.2.0-beta). Gradle Module Metadata resolves the JVM variant
  • Maven → -jvm suffix (koog-agents-jvm, agents-mcp-jvm, …)

Do not add -jvm to a Gradle coordinate.

Package locations that are not where you would guess

Verified by compiling against 1.2.0. Each of these produces an Unresolved reference that looks like a missing dependency but is a wrong import.

SymbolActual packageNotes
subgraphWithTask, subgraphWithVerification, CriticResultai.koog.agents.ext.agentShips inside agents-core (umbrella), NOT the standalone agents-ext artifact
forwardTo—A member of the strategy builder. Do not import it; importing fails
fromProcess, defaultStdioTransportai.koog.agents.mcpTop-level JVM-only extensions on the McpToolRegistryProvider object. Import by name; importing only the provider does not bring them into scope
McpServerInfoai.koog.agents.mcp.metadataNot ai.koog.agents.mcp
TextDocumentai.koog.rag.baseAn interface (content/id/metadata), not a data class. It has no constructor — implement it
SimilaritySearchStrategyai.koog.agents.longtermmemory.retrieval.searchNot under rag.base.storage.search
ReadFileTool, ListDirectoryToolai.koog.agents.ext.tool.fileIn the standalone agents-ext beta artifact
JVMFileSystemProviderai.koog.rag.base.files
tool event fields—ToolCallStartingContext exposes toolName / toolArgs, not tool.name
ToolRegistry.tools—Returns List<ToolBase<*, *>>, not List<Tool<*, *>>

JDK and tooling minima

  • JDK 17 minimum. Gradle must run on a JDK its version supports — Gradle 8.4 on JDK 25 is out of range; pin org.gradle.java.home or upgrade Gradle
  • Kotlin 2.3.10 or later. Earlier versions fail at consume time with binary version of its metadata is 2.3.0, expected version is 2.1.0
  • Android consumers must set android.useAndroidX=true

rules

agent-construction.md

module-coordinates.md

README.md

tile.json