Koog Agent Framework
Build recoverable, observable AI agents in Kotlin and Java across multiplatform applications.
- Source repo
- JetBrains/koog
- Stars
- ★ 4.7k
- Last updated
- 11d ago
- License
- Apache-2.0
- Primary language
- Kotlin
- FA score
- 58/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A Kotlin backend team building a JVM service that calls OpenAI, Anthropic, or another listed model provider through AIAgent.
- Not a fit if
- Projects stuck below JDK 17 or Kotlin 2.3.10
- Developers who want a Python-based agent stack
- Source review
- 58/100 · Major gaps
What does this agent do, and when should you use it?
Koog is a JetBrains framework for building AI agents with idiomatic Kotlin and a Java API, targeting JVM, JS, WasmJS, Android, and iOS. Developers compose model calls, tool interactions, and complex flows through a type-safe Kotlin DSL, AIAgent, and graph-based workflows. The framework lists Google, OpenAI, Anthropic, DeepSeek, OpenRouter, Ollama, and Bedrock as supported LLM providers, with model switching or routing that adapts existing conversation history. Its runtime features include retries, persistence-based restoration at execution points, history compression, streaming responses, and parallel tool calls. It also documents integrations for Spring Boot, Ktor, MCP, ACP, vector embeddings/RAG, and OpenTelemetry exporters for W&B Weave and Langfuse.
An application creates an AIAgent with a promptExecutor, systemPrompt, and llmModel; the documented example uses MultiLLMPromptExecutor(OpenAILLMClient(apiKey)) and OpenAIModels.Chat.GPT4o. It then calls agent.run("Hello! How can you help me?"), receives a result, and prints it with println. Koog supports agents interacting with tools and graph-based workflows, can use MCP tools, and can build ACP-compliant agents for standardized client applications. For longer-running work, it provides built-in history compression, retries, and persistence that restores agent state at specified execution points.
- A Kotlin backend team building a JVM service that calls OpenAI, Anthropic, or another listed model provider through AIAgent.
- A product team sharing agent implementation across JVM, JS, WasmJS, Android, and iOS with Kotlin Multiplatform.
- A Spring Boot or Ktor team embedding tool calls, graph workflows, and streamed model responses in an existing service.
- A workflow owner who needs retry handling and restoration from specific execution points after failures.
- An integration team exposing MCP tools or building an ACP-compliant agent that communicates with standardized client applications.
- A knowledge-product team retaining and retrieving information between conversations with vector embeddings and RAG.
How do you install or deploy this agent?
For JVM use, run on JDK 17 or later. Existing projects should explicitly use Kotlin 2.3.10 or later and include mavenCentral(). With Gradle Kotlin DSL: dependencies { implementation("ai.koog:koog-agents:1.1.1"); implementation("ai.koog:koog-agents-additions:1.1.1-beta") }. Maven coordinates are ai.koog:koog-agents-jvm:1.1.1 and ai.koog:koog-agents-additions-jvm:1.1.1-beta.
How do you use this agent?
Set an API-key environment variable for the selected provider; the documented example reads OPENAI_API_KEY. Create AIAgent(promptExecutor = MultiLLMPromptExecutor(OpenAILLMClient(apiKey)), systemPrompt = "You are a helpful assistant. Answer user questions concisely.", llmModel = OpenAIModels.Chat.GPT4o), then call agent.run("Hello! How can you help me?") inside runBlocking and print the returned value. Other listed providers require their corresponding client, model configuration, and credentials; the supplied example does not provide complete code for those configurations.
What are this agent's strengths and limitations?
- Kotlin Multiplatform support spans JVM, JS, WasmJS, Android, and iOS, allowing agent logic to be shared across targets.
- Retries, persistence-based restoration, and history compression are built-in runtime features for failure handling and long conversations.
- The documented provider set is broad, and Koog explicitly supports switching or routing LLMs while adapting existing history.
- MCP, ACP, Spring Boot, Ktor, RAG, and observability integrations connect the framework to common JVM application patterns.
- JVM adoption requires JDK 17 or later, while existing projects must explicitly meet the Kotlin 2.3.10-or-later requirement.
- Cloud-model use requires the relevant provider API key; pricing, quotas, and credential-management practices are not documented in the supplied material.
- The complete quickstart only shows OpenAI, not the client and model setup for every listed provider.
- Only W&B Weave and Langfuse are explicitly named for observability; other telemetry backends and deployment details are not described.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Koog Agent Framework This agent | 58 · Major gaps | FrameworkFree + model costs | ★ 4.7k | 11d ago | Kotlin | OpenAI API · Claude API |
| ai4j — Java AI Agentic SDK | 60 · Some gaps | Library / SDKFree + model costs | ★ 439 | 26d ago | Java | OpenAI API · Claude API |
| Oh My Pi | 68 · Some gaps | CLIFree + model costs | ★ 38k | today | TypeScript | Codex · OpenAI API · Claude API |
| Embabel Agent Framework | 31 · Major gaps | FrameworkFree + model costs | ★ 4.5k | 2d ago | Kotlin | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The documentation describes external interaction through tools, MCP, LLM providers, and environment variables, and advises against hardcoding keys. This supports data-flow visibility and basic secret handling. Least-privilege and tool-safety guidance is mostly stated in AGENTS.md; the supplied core implementation does not establish authorization boundaries, sensitive-data protections, or revocation mechanisms, so these criteria receive limited credit. The supplied Java A2A example binds publicly to 0.0.0.0 and enables push capability, while the excerpt shows no deployment safeguards or user-confirmation flow. No red-line evidence is present.
The README claims retries, persistence-based recovery, and history compression, and points to CI and test workflows; the supplied A2A workflow lists several TCK categories, but this review does not claim that tests passed. Platform descriptions differ across the packet: the README overview mentions Android, its later target list omits it, and AGENTS.md is not fully consistent either. The quickstart gives a clear error when an API key is absent, and the sample skills instruct the agent to report script failures, which supports basic failure messaging; framework-level failure handling is not shown.
The README targets Kotlin and Java developers and describes JVM, JS, WasmJS, and iOS use, multiple LLM providers, MCP, ACP, RAG, tools, and graph workflows. This gives strong audience and scenario coverage. Tool and environment abstractions and modular features provide some capability boundaries, but the supplied material does not fully define the framework's permission and capability scope. The two supplied SKILL.md files have specific triggers, but they are samples and do not establish framework-wide trigger behavior. Gradle, Maven, environment-variable key setup, and local Ollama instructions cover common environments.
The README, Quickstart, project-structure notes, installation snippets, and Kotlin/Java documentation examples provide usable entry points. The Apache-2.0 text is included, and the README describes semantic versioning and shows stable and beta dependency examples. Version information is useful, but the examples' versions and stability descriptions are not fully tied to the supplied code revision; a detailed limitations list and complete change history are not shown. Contribution guidance, YouTrack, and Slack provide maintenance paths, but ownership and maintenance commitments remain broad. Publisher identity is unknown as specified and is not penalized.
The materials describe framework-level value through graph workflows, typed tools, streaming, persistence, observability, and multiple model integrations. The quickstart offers adaptable Kotlin and Java examples and Gradle and Maven setup. The examples require external API keys or services, and the supplied code sample cannot establish the configuration and operating costs or realized benefits of the broad feature set, so cost-benefit receives moderate credit.
Several README feature claims have partial counterparts in the Quickstart, module descriptions, sample skills, or workflow configuration; installation, license, and versioning claims also have concrete file support. Cross-source support exists, but platform descriptions conflict, and some capabilities appear only in overview or development guidance rather than demonstrated core implementation. The materials do little to label facts separately from inference, so this criterion is not full marks. No build or independent test was executed for this static review.
- The README and AGENTS.md do not list supported platforms consistently; verify the relevant modules and release artifacts for your target platform.
- Tools and the A2A example can interact with external services or listen on a publicly bound address; verify permissions, authentication, data handling, and network exposure before deployment.
- The sample skills pass user requests to named scripts; the supplied material does not show script-level isolation or input-validation implementations.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/koog)<a href="https://followagents.com/en/agents/koog"><img src="https://followagents.com/badge/koog.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Improvements - Newest models from every provider: Added ready-made LLModel definitions — with correct capabilities, context windows, and pricing — for the latest models, so they no longer have to be hand-written: Anthropic (Sonnet_5, Opus_5, Opus_4_8), OpenAI (GPT5_6Sol, GPT5_6Terra, GPT5_6Luna), Google (Gemini3_5FlashLite, Gemini3_6Flash, Gemini3_7Flash), Bedrock (Claude 5 Opus/Sonnet, Claude 4.8 Opus, Amazon Nova 2 Lite), DashScope (QWEN3_5_PLUS, QWEN3_7_MAX, QWEN3_8_MAX), DeepSeek (DeepSeekV4FlashVisionExp), Mistral (Ministral 3B/8B/14B), Ollama (`QWEN_3_ …View on GitHub ↗ -
Release notes excerpt
Major Features Agent Skills - New skills module: Support for the [Agent Skills specification](https://agentskills.io/specification) — discover skill repositories (SkillsDiscovery), model them as Skill objects, and generate skills-catalog prompts for progressive disclosure and activation. The catalog formatter emits XML, YAML, or JSON. Documented in docs/docs/skills.md (#1383, #2160) Amazon Bedrock AgentCore Runtime …View on GitHub ↗ -
Release notes excerpt
Major Features - Spring AI 2.0 integration: New set of Koog starters for Spring Boot 4+ / Spring AI 2.0 ([KG-851](https://youtrack.jetbrains.com/issue/KG-851), #2149) - Spring WebClient support: Added Spring WebClient as a KoogHttpClient implementation, and removed @Experimental annotations from the now-stable HTTP client APIs/modules ([KG-820](https://youtrack.jetbrains.com/issue/KG-820), #2065) …View on GitHub ↗
FAQ
Is Koog limited to OpenAI models?
What credential does the quickstart require?
How does it address failed runs?
Is it a hosted chat product?
Thanks — we use this to improve the page.