Koog(1) —— JVM 下的 Agent 框架

写在前面

如今的 Agent 是在是太火爆了。各种 Agent 应用层出不穷，但是基本都是 Python 和 Typescript 为主，这里面的主要原因还是生态。但是接下来，我将用一个系列的文章来介绍一个 Kotlin 语言的 Agent 框架 —— Koog。

一、JVM 下的 Agent 开发框架

Koog 是 JetBrains 开源的 AI Agent 框架，面向 JVM 生态设计。官方文档把它定位为面向 Kotlin 和 Java 开发者的 Agent 框架：Kotlin 开发者可以使用类型安全 DSL，Java 开发者可以使用 fluent builder 风格 API。

这篇只介绍 Koog 的官方定位、核心特性、环境要求等内容，后面的文章再展开讲解具体 Agent 类型和工作流实现。

二、Koog 和 Spring AI、LangChain4j 的对比

2.1 Koog 的能力

Koog 的首页说明，它用于构建 AI agents，主要面向 JVM 生态。它为 Kotlin 和 Java 提供一等开发体验。

Kotlin 侧，Koog 提供 idiomatic、type-safe Kotlin DSL。Java 侧，Koog 提供 dedicated、fluent builder-style API。官方文档还说明，Kotlin 开发者可以通过 Kotlin Multiplatform 将 agents 部署到 JS、WasmJS、Android 和 iOS 等目标。

在 Koog 中，Agent 不是只包装一次 LLM 调用。官方 Agents 页面把 Koog Agent 描述为结构化、类型安全的状态机。Agent 可以通过 strategy 定义工作流，通过 tools 访问外部数据和服务，通过 features 增强运行能力。

2.3 Koog 和 Spring AI、 Langchain4j 有什么区别和联系

Koog 和 Spring AI 、 LangChain4j 这三个都属于 JVM 生态的 AI 开发框架，但核心定位并不完全一样。可以参考下面的表格：

框架 核心定位 适用场景
Spring AI Spring 生态的 AI 基础设施/应用集成层 已经在使用 Spring 的系统中集成 AI 相关的能力
LangChain4j Java 生态的通用 LLM/AI 应用工具箱 独立于 Spring 的 AI 应用开发
Koog Kotlin/JVM 优先的 Agent Runtime + Agent 编排框架 AI Agent 开发

Spring AI

Spring AI 官方把自己的核心问题描述为：

Connecting your enterprise Data and APIs with AI Models.

它非常像 Spring Data、Spring Security 的设计思想：把 AI 能力变成 Spring 应用的一部分。
比如它提供 ChatClient、Model API、VectorStore、Tool Calling、MCP、RAG、ETL、Observability，以及 Spring Boot Auto Configuration / Starter。

所以如果你已经有了

Spring Boot
MySQL
Redis
Kafka
REST API
业务 Service

现在只是想加入：

+ OpenAI / Claude
+ 企业知识库
+ RAG
+ MCP
+ Tool Calling

使用 Spring AI 会非常自然。

LangChain4j

LangChain4j 的定位更像一个“大而全的 Java AI SDK / Toolbox”。它并不要求你一定使用 Spring。官方明确说它的目标是简化 LLM 与 Java 应用的集成，而且目前覆盖大量模型 Provider、Embedding Store、Memory、RAG、Tools、Agent 等能力。

Java Application
      │
      ├── LLM
      ├── Embedding
      ├── Vector Store
      ├── RAG
      ├── Memory
      ├── Tools
      └── Agents

它有一个很有 Java 味道的设计：AI Services。你可以定义：

interface Assistant {

    String chat(String message);

}

框架负责背后的 Prompt、LLM、Memory、Tool、RAG 等。官方把这种模式类比为 Spring Data JPA / Retrofit。

它更加适合独立于 Spring 的 Java/JVM 开发者。提供了一套完整的 AI 开发工具箱。

Koog

对于 Koog，不能简单理解成“JetBrains 版 LangChain4j”。Koog 更强调：

Agent 怎么运行。

JetBrains 官方现在也明确把它定位在 Agent runtime / orchestration，甚至专门说明 Koog 可以和 Spring AI 一起使用。JetBrains 当前官方甚至直接拿 Spring AI 来解释这个区别：

Spring AI focuses on model integration and infrastructure, while Koog provides an agent runtime and orchestration layer.

也就是说，可以粗略理解成：Spring AI 和 LangChain4j 解决“怎么使用 AI 能力”，而 Koog 解决“Agent 怎么思考、调用工具、执行步骤、维护状态、编排流程”。

Koog 强调的是：

Agent
 │
 ├── Strategy
 │    ├── Node A
 │    ├── Node B
 │    ├── 条件判断
 │    ├── Retry
 │    └── 并发
 │
 ├── Tools
 ├── Memory
 ├── State
 ├── Persistence
 ├── Observability
 └── LLM

Koog 支持结构化 workflow、branching、持久状态、恢复、并发执行、Tracing 等。另外，Koog 还有一个最大的差异点：Kotlin Multiplatform。除了 JVM 后端，还能面向 Android、iOS、JS、WasmJS；这是 Spring AI 和 LangChain4j 的定位里基本没有的。

Koog、Spring AI 和 LangChain4j 能力对比

维度 Koog Spring AI LangChain4j
背后 JetBrains Spring 独立开源项目
核心语言 Kotlin 优先，也支持 Java Java / Spring Java 优先，支持 Kotlin
核心定位 Agent 构建、运行、编排 企业 AI 应用基础设施 Java LLM 应用综合工具箱
LLM 抽象 ✅ ✅ 很核心 ✅ 很核心
Tool Calling ✅ 核心 ✅ ✅
RAG ✅ ✅ 很强 ✅ 很强
文档 ETL 有 ✅ ✅
Vector Store 有相关集成 ✅ 丰富 ✅ 非常丰富
Agent 核心能力 有，但不是唯一核心 ✅
工作流/图编排 强，核心方向 相对弱 有 Agentic 能力
Agent 状态/持久化 重点能力 更偏应用层组件 有相关能力
Spring Boot 可集成 原生生态 ✅ 集成
Ktor 很合适 ❌ 非重点 非重点
Android 支持 ❌ JVM 上理论可用，但非主要目标
Kotlin Multiplatform ✅ 重要优势 ❌ ❌
iOS / JS / Wasm ✅ KMP ❌ ❌

JetBrains 官方明确表示 Koog 可以构建在 Spring AI 之上，也可以独立使用。

而 LangChain4j 的覆盖范围更横向：

             LangChain4j
                  │
 ┌────────────────┼────────────────┐
 ↓                ↓                ↓
LLM              RAG             Agent
 ↓                ↓                ↓
Models        Vector DB         Tools
 ↓                ↓              Memory
Embedding      Retriever        Workflow...

三、Koog 的关键特性

Koog 的关键特性包括：

  • 符合惯用法的 Kotlin 和 Java 支持：可在类型安全的 Kotlin DSL 与专用、流畅的 Java builder API 之间选择。Java API 旨在让 Java 团队感觉自然，使用标准线程池执行器，而不是暴露协程。
  • 可靠性和容错能力：通过内置重试处理失败，并使用 Agent persistence feature 在执行过程中的特定点恢复 Agent 状态。
  • 智能历史压缩：使用先进的内置历史压缩技术，在长时间运行的对话中优化 token 使用量，同时保持上下文。
  • 企业级集成：利用与 Spring Boot 和 Ktor 等流行 JVM 框架的集成，将 Koog 嵌入到你的应用程序中。
  • 通过 OpenTelemetry exporters 实现可观测性：借助对流行可观测性提供方（W&B Weave、Langfuse）的内置支持，监控和调试应用程序。
  • LLM 切换和无缝历史适配：可在任意时刻切换到不同的 LLM，而不会丢失现有对话历史，也可在多个 LLM provider 之间重新路由。
  • 多平台开发：对于用 Kotlin 编写的 Agent，可使用 Kotlin Multiplatform 将 Agent 部署到 JVM、JS、WasmJS、Android 和 iOS 目标。
  • Model Context Protocol 集成：在 AI Agent 中使用 Model Context Protocol (MCP) 工具。
  • 知识检索和记忆：使用向量嵌入和 RAG 在对话之间保留并检索知识。
  • 强大的 Streaming API：通过流式支持和并行工具调用实时处理响应。
  • 模块化 feature 系统：通过可组合架构自定义 Agent 能力。
  • 灵活的图工作流：使用直观的基于图的工作流设计复杂 Agent 行为。
  • 自定义工具创建：通过访问外部系统和 API 的工具增强你的 Agent。
  • 全面追踪：通过详细、可配置的 tracing 调试并监控 Agent 执行。

四、稳定模块和 Beta 模块

官方 Module Versioning 页面说明，Koog 遵循 Semantic Versioning，版本格式为 X.Y.Z。稳定模块发布后，公共 API 不会在没有 major version bump 的情况下被破坏。

文档中标注为 Beta 的功能属于 1.3.0-beta 模块，API 可能在后续版本发生变化。后续文章涉及 MCP、A2A、ACP、Ktor plugin、Spring Boot integration、RAG 等内容时，会按官方文档标注 Beta 状态。

五、Koog 支持的 LLM

Koog 可与主流 LLM provider 配合使用，也支持使用 Ollama 运行本地模型。 当前支持以下 providers：

LLM provider Choose for
OpenAI（包括 Azure OpenAI Service） 具备广泛能力的高级模型。
Anthropic 长上下文和 prompt caching。
Google β 多模态处理（音频、视频）、大上下文。
DeepSeek β 具备成本效益的推理和编码。
OpenRouter 通过一次集成访问来自多个 provider 的多个模型，便于灵活使用、provider 比较和统一 API。
Amazon Bedrock AWS 原生环境、企业安全与合规、多 provider 访问。
Mistral β 欧洲数据托管、GDPR 合规。
Alibaba β（DashScope OpenAI-compatible client） 大上下文和高性价比 Qwen 模型。
Ollama 隐私、本地开发、离线运行，以及无 API 成本。

六、术语

Agent

  • Agent：一个能够与工具交互、处理复杂工作流并与用户沟通的 AI 实体。
  • LLM (Large Language Model)：为 Agent 能力提供支持的底层 AI 模型。
  • Message：Agent 系统中的通信单元，表示来自用户、助手或系统的数据。
  • Prompt：提供给 LLM 的对话历史，由来自用户、助手和系统的消息组成。
  • System prompt：提供给 Agent 的指令，用于指导其行为、定义其角色，并提供完成任务所需的关键信息。
  • Context：LLM 交互发生的环境，可访问对话历史和工具。
  • LLM session：与 LLM 交互的结构化方式，包含对话历史、可用工具以及发起请求的方法。

Agent 工作流

  • Strategy：Agent 的已定义工作流，由顺序执行的子图组成。 Strategy 定义 Agent 如何处理输入、与工具交互并生成输出。 Strategy graph 由通过边连接的节点组成，边表示节点之间的转换。

Strategy graphs

  • Graph: 由节点和边连接而成的结构，用于定义 Agent strategy 工作流。

  • Node: Agent strategy 工作流的基本构建块，表示特定操作或转换。

  • Edge: Agent graph 中节点之间的连接，用于定义操作流，通常带有条件来指定何时沿该边执行。

  • Conditions: 决定何时沿特定边执行的规则。

  • Subgraph: Agent strategy 中自包含的处理单元，拥有自己的工具集、上下文和职责。

Tools

  • Tool: Agent 可用于执行特定任务或访问外部系统的函数。Agent 知道可用工具及其参数，但不了解其实现细节。

  • Tool call: LLM 发出的请求，用于使用提供的参数运行特定工具。其作用类似于函数调用。

  • Tool descriptor: 工具元数据，包含工具名称、描述和参数。

  • Tool registry: Agent 可用工具的列表。Registry 会告知 Agent 有哪些可用工具。

  • Tool result: 运行工具后产生的输出。例如，如果工具是一个方法，结果就是其返回值。

History compression

  • History compression: 通过应用各种压缩策略来减小对话历史大小以管理 token 使用量的过程。

Features

  • Feature: 用于扩展和增强 AI Agent 功能的组件。

EventHandler feature

  • EventHandler: 一种支持监控并响应各种 Agent 事件的 feature，提供用于跟踪 Agent 生命周期、处理错误和在整个工作流中处理工具调用的钩子。

七、小结

作为 Koog 系列文章的开篇，本文只是简单介绍了 Koog 的一些基本知识。重点需要理解 Koog 的定位以及具备哪些特性，这样才能知道它适合用在什么场景。关于术语这部分，实际上是 Agent 的通用术语，后面会逐个讲解到。

总结一下：

  1. Koog 是面向 JVM 的 Agent 框架，不只是 LLM 调用 SDK。
  2. Koog 同时面向 Kotlin 和 Java 开发者。
  3. Koog 的学习路线可以从环境搭建开始，再逐步进入 Agent、Prompt、Tool、Strategy Graph 和工程化能力。

下一篇我们将从 Koog 环境搭建开始，逐步学习。

参考资料

posted @ 2026-09-30 15:00  SharpCJ  阅读(100)  评论(0)    收藏  举报