java-ai-agents/koog/README.md

koog

Companion code for Koog: JetBrains' Kotlin AI Agent Framework on the JVM, Your First Agent with Tools in Java on ankurm.com. One agent with two tools, the same agent as an explicit strategy graph with a plain-Java node in front of the model, and the Spring Boot starter around it.

There is no OpenAI key here. ScriptedOpenAIServer is a local HTTP server that speaks the chat-completions format and answers from a script, and Koog's real OpenAILLMClient is pointed at it. The agent loop, the tool definitions Koog derives, the argument parsing and the HTTP calls all run for real; the model is the one scripted part. What a real model would decide is not tested here.

mvn test -pl koog              # rewrites output/01..06
koog/scripts/kotlin-bom-trap.sh   # rewrites output/07 (run from the repository root, after mvn test)

File	Role
ServiceTools	Two tools on a ToolSet: @Tool, @LLMDescription, customName
OpsAgents	The first agent, the redacting graph strategy, the Mermaid diagram
OpsService, OpsController, OpsApplication	Spring Boot: the starter's openAIExecutor bean and an agent built per request
ScriptedOpenAIServer, TestExecutors	The stand-in model endpoint and an executor pointed at it
FirstAgentTest	output/01: what Koog sends, request by request
StrategyGraphTest	output/02: the graph, and a secret that never reaches the model
FailureModesTest	output/03, output/04: tool errors, bad arguments, unknown tools, the iteration cap, running an agent twice
SpringBootStarterTest	output/05, output/06: the beans the starter registers, and startup with no API key
scripts/kotlin-bom-trap.sh	output/07: the NoClassDefFoundError when Spring Boot's BOM keeps Kotlin on 1.9.25

The pom.xml imports the Kotlin BOMs before the Spring Boot BOM on purpose; the comment there explains why.

Verified against ai.koog:koog-agents-jvm 1.3.0 and ai.koog:koog-spring-boot-starter 1.3.0-beta (beta), Spring Boot 3.5.16, Kotlin 2.3.10, JDK 25, JUnit 6.1.3.