Koog Agent Framework
Build recoverable, observable AI agents in Kotlin and Java across multiplatform applications.
- Source repo
- JetBrains/koog
- Stars
- ★ 4.6k
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Kotlin
- FA score
- 27/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformOpenAI API · Claude API
- You'll need
- Typical use
- A Kotlin backend team building a JVM service that calls OpenAI, Anthropic, or another listed model provider through AIAgent.
- Main limitation
- JVM adoption requires JDK 17 or later, while existing projects must explicitly meet the Kotlin 2.3.10-or-later requirement.
- Source review
- 27/100 · Major gaps 8 safety controls not found
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 | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Koog Agent Framework This agent | 27 · Major gaps | ★ 4.6k | today | Kotlin | OpenAI API · Claude API |
| ai4j — Java AI Agentic SDK | 52 · Major gaps | ★ 429 | 4d ago | HTML | OpenAI API · Claude API |
| Oh My Pi | 54 · Major gaps | ★ 33k | today | TypeScript | Codex · OpenAI API · Claude API |
| Embabel Agent Framework | 0 · Major gaps | ★ 4.5k | today | Kotlin | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: the repository provides no permission model, user confirmation mechanism, data flow transparency, sensitive data handling, dependency security audit, external effect control, rollback mechanism, or source attribution. All trust-related criteria are unsupported, hence score 0.
Evidence shows: README claims multiplatform and reliability features, but no implementation details or test evidence. Dependency availability: declares Maven Central and Gradle dependencies, but no version pinning or dependency verification. Failure messages: no error handling or user feedback mechanism. Thus, self-consistency scores 1 (partial claims), dependency availability scores 1 (partial claims), failure messages scores 0.
Evidence shows: README clearly identifies target audience (JVM/Kotlin developers) and multiple use cases (backend, Android, iOS, etc.), score 2. Capability boundaries: lists supported LLM providers and platforms, but no explicit limits or boundaries, score 1. Trigger precision: no trigger mechanism or precise control provided, score 0. Environment fit: provides JVM, JS, WasmJS, Android, iOS targets, score 2.
Evidence shows: README provides clear information architecture (overview, features, quickstart, usage), score 2. Install notes detailed (Gradle, Maven), score 2. Naming stability: mentions semantic versioning, but no specific version history, score 1. Examples and FAQ: provides quickstart example, but no FAQ, score 2. Known limitations: none mentioned, score 0. License: Apache-2.0, score 2. Versioning and changelog: mentions VERSIONING.md, but no content, score 1. Maintenance responsibility: provides Slack and YouTrack support, but no explicit maintainers, score 1.
Evidence shows: Output usability: provides API reference and docs, but no actual output examples, score 1. Marginal value: provides multiple features (multiplatform, reliability, history compression, etc.), score 2. Cost-benefit: no performance or resource consumption data, score 1.
Evidence shows: Claim traceability: README claims not backed by implementation or test evidence, score 1. Cross-source corroboration: provides CI status and test workflows, but no independent verification, score 1. Fact-inference separation: does not distinguish facts from inferences, score 0.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- The repository provides no security or permission documentation; assess risks before use.
- Claims in README lack implementation details and test evidence; verify by inspecting source and tests.
- No known limitations mentioned; potential issues may be hidden.