快速开始

本指南将帮助您开始在项目中使用 Koog。

前提条件

确保您的环境和项目满足以下要求：

JDK 17+
Kotlin 2.2.0+
Gradle 8.0+ 或 Maven 3.8+

安装 Koog

添加 Koog 包作为依赖项：

Gradle (Kotlin)Gradle (Groovy)Maven

build.gradle.kts

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

build.gradle

dependencies {
    implementation 'ai.koog:koog-agents:0.7.1'
}

pom.xml

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

夜间构建版本

开发分支的夜间构建版本会发布到 JetBrains Grazie Maven 仓库。

要使用夜间构建版本，请在构建配置中添加以下仓库： https://packages.jetbrains.team/maven/p/grazi/grazie-platform-public。

然后将您的 Koog 依赖项更新到所需的夜间版本。夜间版本遵循以下模式： [next-major-version]-develop-[date]-[time]。

您可以在此处浏览可用的夜间构建版本。

设置 API 密钥

Koog 需要来自支持的 LLM 提供商的 API 密钥，或者本地运行的 LLM。

Warning

避免在源代码中硬编码 API 密钥。请使用环境变量来存储 API 密钥。

OpenAIAnthropicGoogleDeepSeekOpenRouterBedrock

获取您的 OpenAI API 密钥并将其分配给 OPENAI_API_KEY 环境变量。

Linux/macOSWindows

export OPENAI_API_KEY=your-api-key

setx OPENAI_API_KEY "your-api-key"

获取您的 Anthropic API 密钥并将其分配给 ANTHROPIC_API_KEY 环境变量。

Linux/macOSWindows

export ANTHROPIC_API_KEY=your-api-key

setx ANTHROPIC_API_KEY "your-api-key"

获取您的 Gemini API 密钥并将其分配给 GOOGLE_API_KEY 环境变量。

Linux/macOSWindows

export GOOGLE_API_KEY=your-api-key

setx GOOGLE_API_KEY "your-api-key"

获取您的 DeepSeek API 密钥并将其分配给 DEEPSEEK_API_KEY 环境变量。

Linux/macOSWindows

export DEEPSEEK_API_KEY=your-api-key

setx DEEPSEEK_API_KEY "your-api-key"

获取您的 OpenRouter API 密钥并将其分配给 OPENROUTER_API_KEY 环境变量。

Linux/macOSWindows

export OPENROUTER_API_KEY=your-api-key

setx OPENROUTER_API_KEY "your-api-key"

生成 Amazon Bedrock API 密钥并将其分配给 BEDROCK_API_KEY 环境变量。

Linux/macOSWindows

export BEDROCK_API_KEY=your-api-key

setx BEDROCK_API_KEY "your-api-key"

=== "Mistral"获取你的 Mistral API 密钥并将其赋值给 MISTRAL_API_KEY 环境变量。

Linux/macOSWindowsOllama

export MISTRAL_API_KEY=your-api-key

setx MISTRAL_API_KEY "your-api-key"

按照 Ollama 文档中的说明，在 Ollama 中运行一个本地 LLM。

创建你的第一个 Koog 智能体

OpenAIAnthropic

以下示例使用 GPT-4o 模型，通过 OpenAI API 创建并运行一个简单的 Koog 智能体。

KotlinJava

fun main() = runBlocking {
    // 从 OPENAI_API_KEY 环境变量中获取 OpenAI API 密钥
    val apiKey = System.getenv("OPENAI_API_KEY")
        ?: error("未设置 API 密钥。")

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

    // 运行智能体
    val result = agent.run("你好！你能如何帮助我？")
    println(result)
}

// 从 OPENAI_API_KEY 环境变量中获取 OpenAI API 密钥
String apiKey = System.getenv("OPENAI_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("未设置 API 密钥。");
}

// 创建智能体
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleOpenAIExecutor(apiKey))
    .llmModel(OpenAIModels.Chat.GPT4o)
    .build();

// 运行智能体
String result = agent.run("你好！你能如何帮助我？");
System.out.println(result);

示例可能产生以下输出：

你好！我在这里为你提供所需的任何帮助。以下是我能做的一些事情：

- 回答问题。
- 解释你好奇的概念或主题。
- 为任务提供分步指导。
- 提供建议、笔记或想法。
- 协助研究或总结复杂材料。
- 撰写或编辑文本、电子邮件或其他文档。
- 为创意项目或解决方案进行头脑风暴。
- 解决问题或进行计算。

告诉我你需要什么帮助——我随时为你服务！

以下示例使用 Claude Opus 4.1 模型，通过 Anthropic API 创建并运行一个简单的 Koog 智能体。

=== "Kotlin"

fun main() = runBlocking {
    // 从 ANTHROPIC_API_KEY 环境变量获取 Anthropic API 密钥
    val apiKey = System.getenv("ANTHROPIC_API_KEY")
        ?: error("未设置 API 密钥。")

    // 创建智能体
    val agent = AIAgent(
        promptExecutor = simpleAnthropicExecutor(apiKey),
        llmModel = AnthropicModels.Opus_4_1
    )

    // 运行智能体
    val result = agent.run("你好！你能如何帮助我？")
    println(result)
}

JavaGoogleDeepSeek

// 从 ANTHROPIC_API_KEY 环境变量获取 Anthropic API 密钥
String apiKey = System.getenv("ANTHROPIC_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("未设置 API 密钥。");
}

// 创建智能体
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleAnthropicExecutor(apiKey))
    .llmModel(AnthropicModels.Opus_4_1)
    .build();

// 运行智能体
String result = agent.run("你好！你能如何帮助我？");
System.out.println(result);

示例可能产生以下输出：

你好！我可以帮助你：

- **回答问题** 并解释主题
- **写作** - 起草、编辑、校对
- **学习** - 作业、数学、学习辅导
- **解决问题** 和头脑风暴
- **研究** 和信息查找
- **一般任务** - 指导、规划、建议

你今天需要什么帮助？

以下示例使用 Gemini 2.5 Pro 模型，通过 Gemini API 创建并运行一个简单的 Koog 智能体。

KotlinJava

fun main() = runBlocking {
    // 从 GOOGLE_API_KEY 环境变量获取 Gemini API 密钥
    val apiKey = System.getenv("GOOGLE_API_KEY")
        ?: error("未设置 API 密钥。")

    // 创建智能体
    val agent = AIAgent(
        promptExecutor = simpleGoogleAIExecutor(apiKey),
        llmModel = GoogleModels.Gemini2_5Pro
    )

    // 运行智能体
    val result = agent.run("你好！你能如何帮助我？")
    println(result)
}

// 从 GOOGLE_API_KEY 环境变量获取 Gemini API 密钥
String apiKey = System.getenv("GOOGLE_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("未设置 API 密钥。");
}// 创建智能体
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleGoogleAIExecutor(apiKey))
    .llmModel(GoogleModels.Gemini2_5Pro)
    .build();

// 运行智能体
String result = agent.run("你好！你能如何帮助我？");
System.out.println(result);

该示例可能产生以下输出：

我是一个能够协助处理语言和信息任务的AI。你可以让我：

*   **回答问题**
*   **撰写或编辑文本**（邮件、故事、代码等）
*   **头脑风暴想法**
*   **总结长文档**
*   **规划事务**（如旅行或项目）
*   **作为创意伙伴**

只需告诉我你的需求

以下示例通过 DeepSeek API 使用 deepseek-chat 模型创建并运行一个简单的 Koog 智能体。

KotlinJava

fun main() = runBlocking {
    // 从 DEEPSEEK_API_KEY 环境变量获取 DeepSeek API 密钥
    val apiKey = System.getenv("DEEPSEEK_API_KEY")
        ?: error("未设置 API 密钥。")

    // 创建 LLM 客户端
    val deepSeekClient = DeepSeekLLMClient(apiKey)

    // 创建智能体
    val agent = AIAgent(
        // 使用 LLM 客户端创建提示词执行器
        promptExecutor = MultiLLMPromptExecutor(deepSeekClient),
        // 提供模型
        llmModel = DeepSeekModels.DeepSeekChat
    )

    // 运行智能体
    val result = agent.run("你好！你能如何帮助我？")
    println(result)
}

// 从 DEEPSEEK_API_KEY 环境变量获取 DeepSeek API 密钥
String apiKey = System.getenv("DEEPSEEK_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("未设置 API 密钥。");
}

// 创建 LLM 客户端
DeepSeekLLMClient deepSeekClient = new DeepSeekLLMClient(apiKey);

// 创建智能体
AIAgent<String, String> agent = AIAgent.builder()
    // 使用 LLM 客户端创建提示词执行器
    .promptExecutor(new MultiLLMPromptExecutor(deepSeekClient))
    // 提供模型
    .llmModel(DeepSeekModels.DeepSeekChat)
    .build();

// 运行智能体
String result = agent.run("你好！你能如何帮助我？");
System.out.println(result);

该示例可能产生以下输出：```

你好！我在这里协助你处理各种任务，包括回答问题、提供信息、帮助解决问题、提供创意想法，甚至只是聊天。无论你需要研究、写作、学习新知识方面的帮助，还是只想讨论某个话题，随时都可以问我——我很乐意帮忙！😊 ```

OpenRouterBedrockMistralOllama

以下示例使用 GPT-4o 模型，通过 OpenRouter API 创建并运行一个简单的 Koog 代理。

KotlinJava

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

// 创建代理
val agent = AIAgent(
    promptExecutor = simpleOpenRouterExecutor(apiKey),
    llmModel = OpenRouterModels.GPT4o
)

// 运行代理
val result = agent.run("Hello! How can you help me?")
println(result)

} ```

```java // 从 OPENROUTER_API_KEY 环境变量获取 OpenRouter API 密钥 String apiKey = System.getenv("OPENROUTER_API_KEY"); if (apiKey == null) { throw new RuntimeException("The API key is not set."); }

// 创建代理 AIAgent agent = AIAgent.builder() .promptExecutor(simpleOpenRouterExecutor(apiKey)) .llmModel(OpenRouterModels.GPT4o) .build();

// 运行代理 String result = agent.run("Hello! How can you help me?"); System.out.println(result); ```

该示例可能产生以下输出：

我可以回答问题、协助写作、解决问题、组织任务等等——只需告诉我你需要什么！

以下示例使用 Claude Sonnet 4.5 模型，通过 Bedrock API 创建并运行一个简单的 Koog 代理。

Kotlin

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

// 创建代理
val agent = AIAgent(
    promptExecutor = simpleBedrockExecutorWithBearerToken(apiKey),
    llmModel = BedrockModels.AnthropicClaude4_5Sonnet
)

// 运行代理
val result = agent.run("Hello! How can you help me?")
println(result)

} ```

=== "Java" ```java // Get the Bedrock API key from the BEDROCK_API_KEY environment variable String apiKey = System.getenv("BEDROCK_API_KEY"); if (apiKey == null) { throw new RuntimeException("The API key is not set."); }

// Create an agent
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleBedrockExecutorWithBearerToken(apiKey, new BedrockClientSettings()))
    .llmModel(BedrockModels.INSTANCE.getAnthropicClaude4_5Sonnet())
    .build();

// Run the agent
String result = agent.run("Hello! How can you help me?");
System.out.println(result);
```
<!--- KNIT example-getting-started-java-06.java -->

该示例可能产生以下输出：

``` Hello! I'm a helpful assistant and I can assist you in many ways, including:

Answering questions on a wide range of topics (science, history, technology, etc.)
Writing help - drafting emails, essays, creative content, or editing text
Problem-solving - working through math problems, logic puzzles, or troubleshooting issues
Learning support - explaining concepts, providing study notes, or tutoring
Planning & organizing - helping with projects, schedules, or breaking down tasks
Coding assistance - explaining programming concepts or helping debug code
Creative brainstorming - generating ideas for projects, stories, or solutions
General conversation - discussing topics or just chatting

What would you like help with today? ```

以下示例使用 Mistral Medium 3.1 模型，通过 Mistral AI API 创建并运行一个简单的 Koog 智能体。

KotlinJava

```kotlin fun main() = runBlocking { // Get the Mistral AI API key from the MISTRAL_API_KEY environment variable val apiKey = System.getenv("MISTRAL_API_KEY") ?: error("The API key is not set.")

// Create an agent
val agent = AIAgent(
    promptExecutor = simpleMistralAIExecutor(apiKey),
    llmModel = MistralAIModels.Chat.MistralMedium31
)

// Run the agent
val result = agent.run("Hello! How can you help me?")
println(result)

} ```

```java // Get the Mistral AI API key from the MISTRAL_API_KEY environment variable String apiKey = System.getenv("MISTRAL_API_KEY"); if (apiKey == null) { throw new RuntimeException("The API key is not set."); } // 创建智能体 AIAgent agent = AIAgent.builder() .promptExecutor(simpleMistralAIExecutor(apiKey)) .llmModel(MistralAIModels.Chat.MistralMedium31) .build();

// 运行智能体 String result = agent.run("你好！你能如何帮助我？"); System.out.println(result); ```

示例可能产生以下输出：

``` 我可以协助您处理广泛的主题和任务。以下是一些示例：

回答问题：我可以提供关于历史、科学、技术、文学等各种主题的信息。
提供定义：如果您不确定某个单词或短语的含义，我可以帮助您定义它。
生成文本：无论是撰写电子邮件、创建社交媒体内容还是编写故事，我都可以协助文本生成。
翻译：我可以将文本从一种语言翻译成另一种语言。
对话：我们可以就任何您感兴趣的话题进行聊天，我会相应回应。
语言练习：如果您正在学习一门新语言，我可以帮助发音、语法和词汇练习。
头脑风暴：如果您在某个问题上遇到困难或需要项目创意，我可以帮助构思解决方案。
摘要：如果您有一篇长文本并希望获得摘要，我可以为您浓缩内容。

您在想什么？有什么具体需要帮助的吗？ ```

以下示例使用通过 Ollama 本地运行的 llama3.2 模型创建并运行一个简单的 Koog 智能体。

KotlinJava

```kotlin fun main() = runBlocking { // 创建智能体 val agent = AIAgent( promptExecutor = simpleOllamaAIExecutor(), llmModel = OllamaModels.Meta.LLAMA_3_2 )

// 运行智能体
val result = agent.run("你好！你能如何帮助我？")
println(result)

} ```

```java // 创建智能体 AIAgent agent = AIAgent.builder() .promptExecutor(simpleOllamaAIExecutor("http://localhost:11434")) .llmModel(OllamaModels.Meta.LLAMA_3_2) .build();

// 运行智能体 String result = agent.run("你好！你能如何帮助我？"); System.out.println(result); ```

示例可能产生以下输出：

我可以协助处理各种任务，例如回答问题、提供信息，甚至帮助语言相关任务，如校对或写作建议。您今天有什么想法？

后续步骤

了解更多关于智能体类型的信息