知 Zhihu EEAI Notes

2026/07/06

Koog 教程：JetBrains 给 Kotlin/JVM 做的 AI Agent 框架，适合把 Agent 放回主工程栈

Koog 是 JetBrains 开源的 Kotlin/JVM AI Agent Framework，支持多平台、MCP、图工作流、记忆、模型切换、OpenTelemetry、Spring Boot 与 Ktor 集成。

KoogKotlinAI AgentJetBrainsMCP

这次从 GitHub 新项目里挑的是 JetBrains/koog。它不是又一个 Python Agent 框架，而是 JetBrains 面向 Kotlin/JVM 生态做的 AI Agent Framework：用 Kotlin DSL 写 Agent，支持 JVM、JS、WasmJS、Android、iOS，能接 OpenAI、Anthropic、Google、DeepSeek、OpenRouter、Ollama、Bedrock 等模型，还把 MCP、记忆、向量检索、OpenTelemetry、Spring Boot、Ktor、图工作流和持久化放进了同一套路线。

这类项目值得写，是因为 AI Agent 工程长期被 Python/TypeScript 主导，而很多企业后端、Android 应用、金融系统、内部平台仍然是 JVM 和 Kotlin/Java。Koog 的信号很明确：Agent 不只属于脚本和 Demo，它开始进入 JVM 应用的主工程栈。

Koog 适合解决什么问题

如果只是想写一个聊天机器人，用任何 SDK 都能做。但一旦需求变成“在现有 Kotlin 服务里嵌入一个能调用工具、有记忆、可观测、能容错的 Agent”，问题就不一样了。你需要的不只是模型 API 封装，而是运行时、状态、工具、错误恢复、追踪和业务框架集成。

Koog 的定位正好在这里。它强调 idiomatic Kotlin：Agent、工具、工作流、模型切换都用 Kotlin 方式表达，而不是把 Python 思维硬搬到 JVM。对 Spring Boot、Ktor、Android 或 Kotlin Multiplatform 团队来说，这比额外维护一套 Python Agent 服务更自然。

第一步：装进 Kotlin 项目

官方 README 给出的 JVM 使用方式很直接。Gradle Kotlin DSL：

dependencies {
    implementation("ai.koog:koog-agents:0.5.0")
}

Maven 项目可以用：

<dependency>
  <groupId>ai.koog</groupId>
  <artifactId>koog-agents-jvm</artifactId>
  <version>0.5.0</version>
</dependency>

JVM 侧要求 JDK 17+。如果是已有项目，注意显式对齐 kotlinx-coroutines 和 kotlinx-serialization 版本，避免依赖树里被别的库拉偏。

最小 Agent 示例

Koog 的最小示例是创建一个 AIAgent，传入模型 executor、system prompt 和模型名，再调用 run：

fun main() = runBlocking {
    val apiKey = System.getenv("OPENAI_API_KEY")

    val agent = AIAgent(
        executor = simpleOpenAIExecutor(apiKey),
        systemPrompt = "You are a helpful assistant. Answer user questions concisely.",
        llmModel = OpenAIModels.Chat.GPT4o
    )

    val result = agent.run("Summarize what this service does for a new developer.")
    println(result)
}

真正落地时，不建议一开始就把它接到生产接口。先放在本地命令行或内部管理端，跑通模型 key、日志、错误处理和 token 成本，再接业务工具。

第二步：把工具做成受控能力

Agent 有价值，通常不是因为它会聊天，而是因为它能调用工具。对 Kotlin 后端来说，工具可以是查订单、读配置、生成报表、调用内部 HTTP API、检索文档、检查构建状态。关键是工具边界要清楚：输入类型、输出结构、权限、超时、审计都要先定义。

建议第一批只开放只读工具。例如：根据订单号查状态、根据用户 ID 查最近登录、根据错误码查知识库。等只读链路稳定后，再考虑写操作，而且写操作必须有人确认或接审批流。

图工作流：别让 Agent 变成一坨 while 循环

Koog 支持 graph workflows。它的意义是把 Agent 行为拆成节点和边：先理解输入，再查工具，再判断是否需要更多上下文，再生成回复，必要时进入人工处理。相比把所有逻辑塞进一个 prompt，图结构更容易测试、追踪和回滚。

一个实用的客服排障工作流可以这样设计：分类问题 → 检索知识库 → 查询用户状态 → 判断是否涉及账务/权限 → 普通问题自动回复 → 高风险问题交给人工。每个节点都可以记录输入输出，出错也更容易定位。

模型切换和历史压缩

Koog 的特性里有两点适合长任务：LLM switching 和 intelligent history compression。前者允许在不同模型之间切换或路由，后者用于长对话里的上下文压缩。实际工程里，这两个能力很关键：便宜模型处理分类和格式化，强模型处理复杂推理；历史压缩则避免对话越长越贵、越慢、越不稳定。

但压缩一定要可观测。压缩摘要如果丢了关键约束，Agent 会看起来“突然失忆”。最好把压缩前后摘要、工具调用、模型选择都接入 OpenTelemetry 或至少打结构化日志。

MCP 与企业集成

Koog 支持 Model Context Protocol 工具，这意味着它可以接入越来越多 MCP Server，而不是每个外部系统都重新写一套工具适配。对企业团队来说，MCP 的价值在于标准化工具入口：GitHub、数据库、文档、工单、浏览器、监控系统，都可以通过相似协议暴露给 Agent。

同时，Koog 与 Spring Boot、Ktor 的集成方向也重要。很多团队并不想单独部署一个 Agent 服务，而是希望把 Agent 放进已有后端里，复用认证、日志、权限、配置中心和发布流程。

生产化检查清单

  • 先用只读工具跑通闭环，不要直接开放写库、转账、删数据等能力。
  • 所有模型调用、工具调用、异常和人工接管都要有日志。
  • 为每个工具设置超时、重试和错误返回格式。
  • 区分开发、预发、生产模型 key 和工具权限。
  • 把 token 成本、响应时间、失败率放进监控。
  • 对长对话启用历史压缩时，保留可追溯摘要。

结论

Koog 的看点不是“又能写 Agent 了”，而是把 Agent 带回 Kotlin/JVM 主工程栈。它适合那些已经有 Spring Boot、Ktor、Android 或 Kotlin Multiplatform 基础设施的团队：不必为了 Agent 额外维护一套 Python 服务，也能获得工具调用、图工作流、记忆、MCP、模型切换和可观测能力。真正上线时，别从炫技 Demo 开始，要从只读工具、可观测日志和明确权限边界开始。