Koog
JetBrains 出品的 Kotlin/JVM agent 框架(Apache-2.0,4.6k★):用类型安全的 Kotlin DSL 定义图式工作流,内置重试与状态持久化、历史压缩、多模型热切换、MCP 与 A2A/ACP 协议、OpenTelemetry 导出与 RAG 记忆,目标覆盖 JVM、JS、WasmJS、Android 与 iOS。
这是什么?适合谁?
Koog 是 JetBrains/koog(Apache-2.0)——一个用 Kotlin 写 agent 的框架,不是 agent 产品。它要解决的问题很具体:JVM 生态里写 agent,通常要么自己拼 HTTP 调用,要么把 Python 框架包一层;Koog 给的是「类型安全的 Kotlin DSL + 可复现的工作流图 + 企业侧要的那几件配套(重试、持久化、可观测性、多模型切换)」。
它把自己标成 JetBrains incubator 项目,主分支是 develop,稳定模块 1.3.0、实验模块 1.3.0-beta。核心抽象是 AIAgent:你给它一个 prompt executor(接哪家模型)、一个模型、可选的一套策略图与工具,它就能跑一次对话或一条多节点工作流。
适合谁:写 Kotlin/Java 后端、需要把 agent 嵌进现有 JVM 服务的团队;要把「多步 agent 流程」画成图并能断点续跑、失败重试的工程场景;已经在用 Spring Boot 或 Ktor、不想为一套 agent 逻辑再引一个 Python 服务的人;需要把 trace 直接送进 Langfuse / W&B Weave / Datadog 的团队。
不适合谁:只想快速试个 prompt 的个人用户(直接用 CLI 更快);非 JVM 技术栈的团队(虽然有 JS/WasmJS 目标,但生态与文档重心在 JVM);要求 GA 级 API 稳定性承诺的生产系统(incubator 阶段)。
准备工作
- JDK 17+:官方 Quickstart 的硬要求,低于 17 直接编不过。
- Kotlin 2.2.0+(文档)与 2.3.10 显式设置(仓库 README):两处口径不同,见「踩坑 1」。稳妥做法是照仓库
gradle/libs.versions.toml里的版本走。 - Gradle 8.0+ 或 Maven 3.8+:两个构建工具都给了依赖片段。
- 一个模型凭据:
OPENAI_API_KEY/ANTHROPIC_API_KEY/GOOGLE_API_KEY/DEEPSEEK_API_KEY/OPENROUTER_API_KEY/BEDROCK_API_KEY/MISTRAL_API_KEY任选其一,或用本机 Ollama。 - 成本预期:框架免费,成本全在模型调用;图表式工作流一次任务可能触发多个节点、每个节点一次(或多次)模型调用,先按单节点测成本再放大。
快速上手:从依赖到第一个 agent
Step 1 — 加依赖(Gradle Kotlin DSL)
dependencies {
implementation("ai.koog:koog-agents:1.3.0") // 稳定
implementation("ai.koog:koog-agents-additions:1.3.0-beta") // 实验,可选
}
用 Maven 时 artifactId 要带 -jvm 后缀:koog-agents-jvm 与 koog-agents-additions-jvm。仓库要在 mavenCentral()。
Step 2 — 配 API key
export OPENAI_API_KEY=your-api-key # macOS / Linux / Git Bash
setx OPENAI_API_KEY "your-api-key" # Windows(新开终端生效)
Step 3 — 写第一个 agent
fun main() = runBlocking {
val apiKey = System.getenv("OPENAI_API_KEY")
?: error("The API key is not set.")
val agent = AIAgent(
promptExecutor = MultiLLMPromptExecutor(OpenAILLMClient(apiKey)),
llmModel = OpenAIModels.Chat.GPT4o
)
val result = agent.run("Hello! How can you help me?")
println(result)
}
Step 4 — 跑起来,确认拿到回答
一次 agent.run(...) 就是一轮对话;输出是一段普通字符串。到这里说明依赖、密钥、模型三者都通了。
Step 5 — 换成你要用的模型供应商
把 OpenAILLMClient 换成 AnthropicLLMClient / GoogleLLMClient 等,模型常量换成对应的 AnthropicModels.Opus_4_1、GoogleModels.Gemini2_5Pro。Koog 的卖点之一是中途换模型不丢上下文:MultiLLMPromptExecutor 支持在运行中重新路由到另一家。
初级用法
- 单 agent 跑任务:
AIAgent(promptExecutor, systemPrompt, llmModel)三件套就够;需要工具时挂ToolRegistry,需要多轮记忆时挂 chat memory 特性。 - 用现成策略:
predefined-agent-strategies里有无状态、有状态、流式等常用装配,先抄一个再改,比从空图开始快。 - 本地模型试水:先用 Ollama 起一个模型,再把 executor 指向它,把「框架跑不通」和「模型答不好」两类问题分开。
高级玩法
- 图式工作流:
graph-based-agents让你定义节点、边与条件分支,能把「抓取 → 抽取 → 校验 → 重试 → 汇总」这类流程画成可测试的结构;custom-strategy-graphs讲怎么定制,parallel-node-execution讲并行节点,AIAgentStorage做节点间类型安全的键值传参。 - 状态持久化 + 重试:
agent-persistence允许在执行中的检查点保存/恢复 agent 状态,官方把它和内置重试一起归为「可靠性」能力——长流程 agent 不必一次跑完,断了能续。 - 可观测性:
features/open-telemetry导出 span,官方给了 Langfuse、W&B Weave 与 Datadog 三类 exporter 的配置说明;features/tracing是框架自带的追踪能力,本地调试更快。 - 协议接入:
model-context-protocol(MCP)把外部工具的 MCP server 变成 agent 工具;a2a是 Agent-to-Agent 协议实现,ACP让 agent 能以标准客户端协议对外服务。 - 知识检索:官方提供基于向量嵌入与 RAG 的记忆/知识检索能力,适合把内部文档接进 agent,而不是把长文档塞进 prompt。
小技巧
- Kotlin 版本冲突时,别改
libs.versions.toml里的协同库版本(coroutines 1.10.2、serialization 1.10.0、datetime 0.7.1),先对齐 Kotlin 本身。 - 只有 Gradle 片段省了
-jvm后缀;Maven 片段必须写koog-agents-jvm,复制混用是最常见的「依赖解析失败」。 - 想快速验证「是不是模型的问题」,把同一个 prompt 先用
OpenAIModels.Chat.GPT4o跑一遍,再换目标供应商跑一遍,两者都差才是 prompt 的问题。 runBlocking是官方示例的入口写法;在 Spring/Ktor 里请换成对应的协程作用域,不要阻塞请求线程。- 稳定模块与 beta 模块分两个依赖坐标,升级时分别锁版本:
1.3.0与1.3.0-beta不是同一个稳定性承诺。 - 需要 nightly 构建时,加 JetBrains Grazie 的 Maven 仓库,版本形如
[next-major]-develop-[date]-[time]。
常见踩坑
踩坑 1:按文档把 Kotlin 设成 2.2.0,构建却过不去。
现象:依赖解析或编译报版本不匹配。原因:官方 Quickstart 写 Kotlin 2.2.0+,而仓库 README 同时写「Kotlin 2.3.10 or higher should be set explicitly」。解法:以仓库 gradle/libs.versions.toml 的实际版本为准,两处文档口径不一致是当前状态。
踩坑 2:Maven 依赖照抄 Gradle 片段,报找不到 artifact。
现象:ai.koog:koog-agents 在 Maven 里解析失败。原因:Maven 片段的 artifactId 是 koog-agents-jvm。解法:Gradle 用 koog-agents,Maven 用 koog-agents-jvm,两套别混。
踩坑 3:把 beta 模块当稳定 API 用在生产。
现象:升级一个补丁版本后接口变了。原因:koog-agents-additions 现在是 1.3.0-beta,官方明确 beta 模块 API 可能变化。解法:只把 beta 用在可替换的功能上,稳定路径锁 1.3.0;升级前读 VERSIONING.md。
踩坑 4:clone 了默认分支却对不上示例代码。
现象:README 里的示例在你本地编译不过。原因:仓库默认分支是 develop,发布走 main,两分支的示例与 CI 徽章都不同。解法:确认你在哪个分支、用哪个版本号,必要时按 release tag 取代码。
踩坑 5:以为它是 GA 产品,按 SLA 排期。 现象:上线后发现 API 还在演进。原因:README 顶部标的是 JetBrains incubator 项目。解法:把它当「可用的孵化期框架」——锁版本、留替换层、别把核心业务逻辑深度耦合进 beta 模块。
踩坑 6:图式工作流一次任务烧掉远超预期的 token。 现象:单次任务成本远高于「一次对话」。原因:每个节点都是一次模型调用,条件分支与并行节点会再放大;历史压缩能省,但不是免费。解法:先用两三个节点的小图测单次成本,再决定要不要上并行与自反思节点。
常见问题 FAQ
Q1:必须用 Kotlin 吗?Java 项目能用吗?
A:能用。官方 README 说的是「idiomatic Kotlin and Java API」,Quickstart 同时给了 Kotlin 与 Java 的 AIAgent.builder() 写法。但文档、示例与社区讨论以 Kotlin 为主。
Q2:支持哪些模型供应商?
A:Quickstart 列出 OpenAI、Anthropic、Gemini、DeepSeek、OpenRouter、Bedrock、Mistral,以及本机 Ollama。框架层用 MultiLLMPromptExecutor 统一入口,运行中可以换供应商且保留历史。
Q3:能跑在 Android 或 iOS 上吗?
A:官方支持 JVM、JS、WasmJS、Android 与 iOS 目标(Kotlin Multiplatform)。README 另有一处写「currently supports the JVM, JS, WasmJS and iOS targets」——移动端以 Android/iOS 小节与示例为准。
Q4:和 Spring Boot / Ktor 怎么配合?
A:官方把「与 Spring Boot、Ktor 集成」列为 enterprise-ready 能力,属于在既有服务里嵌 agent 的推荐路径;具体装配看 docs.koog.ai 的对应页面。
Q5:生产可用吗?
A:分层看:稳定模块 1.3.0 有语义化版本承诺,beta 模块与部分特性仍在演进,项目本身是 incubator。适合「愿意锁版本、能承受少量 API 变更」的团队。
Q6:出问题去哪问?
A:官方 Slack 频道(docs.koog.ai 有入口)与 YouTrack 的 KG 项目;issue tracker 也指向 YouTrack,不在 GitHub Issues。
进阶学习建议
- 顺着文档目录学最省力:先
agents/basic-agents与agents/functional-agents建立两种心智模型(图式 vs 循环式),再读custom-strategy-graphs与nodes-and-components——这两页决定你能把流程画多细。 - 可靠性三件套按顺序读:
features/agent-persistence(检查点与恢复)→features/chat-memory(多轮记忆)→predefined-agent-strategies(现成策略如何选)。读完后拿你自己的一条慢流程做「断点续跑」实验,比看十篇介绍有用。 - 可观测性从
features/tracing起步,再把features/open-telemetry的 Langfuse exporter 接上:Koog 的价值一半在「能看见 agent 每一步在干什么」,不上 trace 等于只用了一半。 - 要用外部工具就读
model-context-protocol与built-in-tools;要做 agent 间协作读a2a与 ACP 相关页。API 细节查 api.koog.ai。 - 想贡献代码先读
CONTRIBUTING.md与VERSIONING.md,注意默认分支是develop。
免责声明
本文基于官方文档和公开资料整理,AI辅助生成,MagicNetWorld 尚未完成独立实测。
文中依赖坐标、版本号、JDK/Kotlin 要求与能力清单均取自仓库 README 与 docs.koog.ai 的 Quickstart 页面(核验日期 2026-11-09);本站未安装 Koog、未运行任何示例工程,也未验证任一模型供应商的连通性。
参考链接
📊 评分与标签
核验口径:已按现行口径通过,待按新证据契约复核 · 证据状态:仅公开资料 · 核验日期:
评分说明
总分 7.8/10 · S_入选
核验日期:2026-11-09。评价对象是 JetBrains/koog(Apache-2.0)这套 Kotlin/JVM agent 框架,按「开发者自建 agent 的工程底座」评价。依据是仓库 README、docs.koog.ai 的 Quickstart 与文档目录、GitHub 公开读数;本站未创建 Kotlin 工程、未运行任何示例,能力描述全部来自官方文档。
评分依据可追溯至公开来源,每项分数均有明确理由与数据支撑;分数衡量的是「框架能力面、上手成本与维护活跃度」,不是对运行时性能或稳定性的实测结论。
📊 可观测社区指标(采集日期:2026-11-09)
- GitHub 仓库页:4,654 stars、509 forks、159 watchers,Apache-2.0,主语言 Kotlin,创建于 2025-05-01。
- 最近提交:2026-10-28T17:04Z(北京时间 2026-10-29 01:04),距采集日约 11 天,
develop分支持续更新。 - 稳定版本 1.3.0,实验模块 1.3.0-beta(Maven Central:
ai.koog:koog-agents)。 - 官方入口:文档、API 参考、Slack 频道与 YouTrack 的 KG 项目。
🤖 Agent 能力:1.7/2.0
框架该有的原语基本齐了,而且不是「各做一半」:图式工作流(自定义策略图、并行节点、节点间类型安全的 AIAgentStorage 传参)、内置重试、检查点式 agent 持久化与恢复、历史压缩(长对话省 token)、多模型热切换且保留历史、流式输出与并行工具调用、工具注册与调用。
扣分两处:没有内置的「评测/回归」体系,你要自己搭验证闭环;官方示例与最佳实践仍以简单对话为主,复杂图的工程样板偏少。
- 竞品对比 1(Agno):Python 生态的 agent 运行时,多模态与内存抽象更成熟;Koog 的差异化在「JVM 原生 + 类型安全的图」。
- 竞品对比 2(OpenAI Agents SDK):以 handoff、guardrail、tracing 三件套为核心,接入面偏 OpenAI;Koog 在 provider 中立与多平台目标上更宽。
🖐️ 易用性:0.9/1.5
对 Kotlin/JVM 开发者是「贴脸」的:Gradle 一行依赖、AIAgent(...) 三件套、agent.run("...") 就能跑;文档站结构清晰,Quickstart 直接给了 OpenAI / Anthropic / Gemini 三套可复制示例,还配了 Java 版本。
扣分集中在门槛:只面向 Kotlin/JVM(其它语言只能隔着 JVM 用);JDK 17+、Kotlin 版本、Gradle/Maven 版本三重前置;官方两处文档对 Kotlin 版本口径不一致(Quickstart 写 2.2.0+,README 写 2.3.10 显式设置);Maven 片段要先改 artifactId 后缀。非 JVM 团队几乎无法「先试试」。
- 竞品对比 1(Mastra):TypeScript 团队
npx create-mastra起步,前端/全栈背景上手更快;Koog 要求 Kotlin 工程基础。 - 竞品对比 2(Agno):
pip install agno后十几行就能跑一个带工具的 agent,Python 侧的「五分钟出结果」体验更顺。
🔌 生态集成:1.7/2.0
集成面是它的强项:Spring Boot 与 Ktor 官方支持(在既有服务里嵌 agent 的主路径);MCP 接外部工具、A2A 做 agent 间协作、ACP 让 agent 以标准客户端协议对外;模型侧覆盖 OpenAI、Anthropic、Google、DeepSeek、OpenRouter、Bedrock、Mistral 与本地 Ollama;可观测性直接对接 OpenTelemetry,官方给了 Langfuse、W&B Weave、Datadog 三类 exporter。
扣分:与 Java 生态更早的 agent 方案(LangChain4j、Spring AI)相比,第三方教程与社区示例少;多平台目标里 JS/WasmJS/iOS 的实战案例明显少于 JVM。
- 竞品对比 1(Google ADK):官方主打多语言(Python/Java)与 Google Cloud 侧集成;Koog 的云中立性更强,但云厂商配套(托管运行时、评测服务)缺失。
- 竞品对比 2(CrewAI):以角色化多 agent 协作为卖点,社区模板多;Koog 更偏「单 agent 工作流引擎」,协作能力靠 A2A/ACP 协议层补。
👥 社区支持:1.2/1.5
JetBrains 出品、incubator 项目身份明确;4,654 stars / 509 forks 是「有真实使用、但不是现象级」的量级,watchers 159 与 star 比例正常(约 29:1);文档站更新到 2026 年,Slack 与 YouTrack 是官方支持通道;develop 分支 10 月底仍在提交。
扣分:GitHub Issues 关闭、问题走 YouTrack,社区可见的问答沉淀较少;中文资料基本为零;项目仍在孵化期,社区规模会直接限制「遇到怪问题有人踩过」的概率。
- 竞品对比 1(Agno):star 与社区体量更大,答案与示例更容易搜到;Koog 的社区小而集中,问题更容易被官方看到。
- 竞品对比 2(Mastra):TypeScript 社区活跃度更高,Discord 讨论密集;Koog 靠 JetBrains 的官方渠道(Slack/YouTrack)承担支持。
💡 创新程度:1.2/1.5
三个值得记的点:Kotlin 多平台(同一套 agent 逻辑面向 JVM/JS/WasmJS/Android/iOS,这在 agent 框架里少见);运行中换模型且保留历史(把「按成本/能力动态路由」做成一等能力);图 + 检查点的组合(可恢复的长流程 agent,而不是只能一口气跑完的链)。
扣分:单个概念(图式工作流、状态持久化、OTel 导出)在 agent 框架里都不算首创,创新主要在语言生态与组合完成度。
- 竞品对比 1(Mastra):创新在工作流 DSL 与前端工具链打通;Koog 的创新在跨平台目标与 JVM 侧企业配套。
- 竞品对比 2(Google ADK):创新在 A2A 协议与云侧托管组合;Koog 在协议层跟进(ACP/A2A),但缺少托管侧产品化。
🔒 稳定性:1.1/1.5
工程纪律可查:语义化版本、稳定与 beta 模块分开发布、VERSIONING.md 明确承诺范围、CI 有 checks/heavy-tests/ollama-tests 三套 workflow、依赖版本集中在 libs.versions.toml;Apache-2.0 对商用友好。
扣分:incubator 身份意味着项目可能被调整方向;稳定模块才到 1.3.0,API 演进仍在进行;develop 与 main 的分支习惯(默认 develop)会让「拉最新代码」与「拉稳定代码」混淆;本文核验时未抽样 issue 响应速度。
- 竞品对比 1(OpenAI Agents SDK):厂商维护、发布节奏与文档同步更紧;Koog 的分支与模块版本需要使用者自己分辨。
- 竞品对比 2(CrewAI):迭代快、破坏性变更也曾出现;Koog 用「稳定/beta 双坐标」把变更半径写清楚了,这点更透明。
🏷️ 标签说明
- 开源免费:Apache-2.0,代码公开、可商用。来源:仓库 LICENSE
- Kotlin:以 Kotlin DSL 定义 agent 与工作流,官方口号是「idiomatic Kotlin」。来源:README Overview
- JVM:面向后端服务,支持 Spring Boot / Ktor 集成。来源:README Key features
- 多平台:JVM、JS、WasmJS、Android 与 iOS 目标。来源:README Supported targets
- JetBrains:JetBrains 孵化的开源项目,支持走官方 Slack 与 YouTrack。来源:README Useful links
局限与声明
- 本站未创建 Kotlin 工程、未编译或运行任何 Koog 示例,也未验证任一 provider 的连通性;能力清单来自 README 与 docs.koog.ai。
- 4,654 stars / 509 forks / 159 watchers 为 2026-11-09 仓库页读数,最后提交 2026-10-28T17:04Z;这些数字会变化。
- 未核实:图式工作流在高并发下的实际表现、检查点恢复的边界条件、各 exporter 的接入成本。
- 项目处于 incubator 阶段,API 可能演进;引用本页做技术选型时请以官方
VERSIONING.md与当期文档为准。
来源核实
- ✅ 已核对:仓库 README — 2026-11-09 读取,依赖片段、支持目标、能力清单、LLM 供应商、许可证逐项比对
- ✅ 已核对:Quickstart — JDK 17+、Kotlin 2.2.0+、Gradle 8.0+/Maven 3.8+、七家 provider 的环境变量、Kotlin/Java 双示例
- ✅ 已核对:文档目录 llms.txt — 图式 agent、功能代理、持久化、MCP、A2A、OpenTelemetry 等页面标题与入口
- ✅ 已核对:GitHub 仓库页指标与最近提交时间 — 2026-11-09 读数为 4,654 stars、509 forks、159 watchers,最后提交 2026-10-28T17:04Z
- ⚠️ 未实测:Gradle/Maven 依赖解析、示例编译、模型调用、持久化与 trace 导出 — 仅文档核验
同分类推荐
开源框架 分类下的其他 Agent