Kotlin 开发者必看！JetBrains 开源 LLM 框架 Koog 快速上手指南（含示例）

Koog 是什么？

Koog 是 JetBrains 开源的一个用于 LLM（大语言模型）集成的框架。与 LangChain4j 和 Spring AI 类似，Koog 旨在简化 AI 应用的开发。

但 Koog 有其独特的定位：它专为 JVM 和 Kotlin 开发人员设计。得益于其模块化功能系统，开发者可以非常灵活地自定义代理功能。更重要的是，它原生支持 Kotlin Multiplatform (KMP)，这意味着你的同一套 LLM 逻辑代码，可以部署到 JVM、JS、WasmJS、Android 和 iOS 等多个目标平台。

本文将带你快速上手 Koog，展示如何在 Java 或 Kotlin 项目中集成 OpenAI API，并介绍如何使用 Koog Agents 构建智能代理，以及如何兼容国内大模型。

Koog 快速开始：环境配置

在开始之前，请确保你的开发环境满足以下基本要求：

• Java 17+
• Gradle 或 Maven
• LLM 提供的 API Key (如 OpenAI 或国内兼容 OpenAI 协议的 Key)

添加依赖

首先，在你的 build.gradle.kts 中添加 Koog 的依赖：

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

示例 1：直接调用 OpenAI GPT-4o

下面是一个最简单的 Koog 调用示例。我们将使用 OpenAI 的 GPT-4o 模型。通过 simpleOpenAIExecutor 快速创建一个 AI 代理，这个示例展示了 Koog 极其简洁的 API 设计。

import ai.koog.agents.core.agent.AIAgent
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    // 从环境变量获取 API 密钥
    val apiKey = System.getenv("OPENAI_API_KEY")
        ?: error("The API key is not set.")

    // 创建 agent
    val agent = AIAgent(
        promptExecutor = simpleOpenAIExecutor(apiKey),
        llmModel = OpenAIModels.Chat.GPT4o
    )

    // 运行 agent 并打印结果
    val result = agent.run("say hello lhDream!")
    println(result)
}

示例 2：自定义 Base URL (兼容其他 LLM)

在实际开发中，我们经常需要使用国内的大模型（如智谱 GLM、DeepSeek 等）或第三方中转服务。这些服务通常兼容 OpenAI 的接口协议。Koog 提供了 OpenAILLMClient，允许我们通过自定义 Base URL 来完美对接这些服务。

下面的示例展示了如何更精细地配置 LLModel，包括设置支持 JSON Schema、函数调用以及 Temperature 等高级功能：

import ai.koog.agents.core.agent.AIAgent
import ai.koog.prompt.executor.clients.openai.OpenAIClientSettings
import ai.koog.prompt.executor.clients.openai.OpenAILLMClient
import ai.koog.prompt.executor.llms.SingleLLMPromptExecutor
import ai.koog.prompt.llm.LLMCapability
import ai.koog.prompt.llm.LLMProvider
import ai.koog.prompt.llm.LLModel
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    // 从环境变量获取 API 密钥
    val apiKey = System.getenv("OPENAI_API_KEY")
        ?: error("The API key is not set.")
    // 从环境变量获取 base URL (例如: https://api.deepseek.com)
    val baseUrl = System.getenv("BASE_URL")
        ?: error("The base URL is not set.")

    // 定义模型及其能力
    val llmModel = LLModel(
        provider = LLMProvider.OpenAI,
        id = "GLM-4.7", // 或者是 "deepseek-chat"
        capabilities = listOf(
            LLMCapability.Temperature,
            LLMCapability.Schema.JSON.Standard,
            LLMCapability.Tools,
            LLMCapability.Completion,
            LLMCapability.OpenAIEndpoint.Completions,
        ),
        contextLength = 128_000,
        maxOutputTokens = 128_000,
    )

    // 创建 agent，使用自定义的 Client
    val agent = AIAgent(
        promptExecutor = SingleLLMPromptExecutor(
            OpenAILLMClient(
                apiKey = apiKey,
                settings = OpenAIClientSettings(
                    baseUrl = baseUrl
                )
            )
        ),
        llmModel = llmModel
    )

    // 运行 agent 并打印结果
    val result = agent.run("say hello lhDream!")
    println(result)
}

常见问题与技巧

Q: Koog 与 Spring AI 或 LangChain4j 有什么区别？

A: Koog 的最大优势在于其对 Kotlin Multiplatform 的原生支持。

• 如果你的项目是纯 Java 后端项目，Spring AI 或 LangChain4j 依然是生态最丰富、文档最全的选择。
• 但是，如果你需要跨平台开发（例如，你希望同时在 Android 客户端和后端服务器之间共享 LLM 调用逻辑），或者你非常喜欢 Kotlin 的语法特性，那么 Koog 是比基于 Java 的框架更合适、更现代的选择。

参考资料与扩展阅读

更多关于 Koog 的高级用法和模块化功能，请查阅官方文档：

• Koog 官方文档: docs.koog.ai

---

本文首发于 lhDream's Blog，转载请注明出处。