Quickstart

This guide will help you start using Koog in your project.

Prerequisites

Ensure your environment and project meet the following requirements:

• JDK 17+
• Kotlin 2.2.0+
• Gradle 8.0+ or Maven 3.8+

Install Koog

Add the Koog package as a dependency:

Gradle (Kotlin)Gradle (Groovy)Maven

build.gradle.kts

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

build.gradle

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

pom.xml

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

Nightly builds

Nightly builds from the develop branch are published to the JetBrains Grazie Maven repository.

To use a nightly build, add the following repository to your build configuration: https://packages.jetbrains.team/maven/p/grazi/grazie-platform-public.

Then update your Koog dependency to the desired nightly version. Nightly versions follow the pattern [next-major-version]-develop-[date]-[time].

You can browse the available nightly builds here.

Set up an API key

Koog requires either an API key from a supported LLM provider or a locally running LLM.

Warning

Avoid hardcoding API keys in the source code. Use environment variables to store API keys.

OpenAIAnthropicGoogleDeepSeekOpenRouterBedrockMistralOllama

Get your OpenAI API key and assign it to the OPENAI_API_KEY environment variable.

Linux/macOSWindows

export OPENAI_API_KEY=your-api-key

setx OPENAI_API_KEY "your-api-key"

Get your Anthropic API key and assign it to the ANTHROPIC_API_KEY environment variable.

Linux/macOSWindows

export ANTHROPIC_API_KEY=your-api-key

setx ANTHROPIC_API_KEY "your-api-key"

Get your Gemini API key and assign it to the GOOGLE_API_KEY environment variable.

Linux/macOSWindows

export GOOGLE_API_KEY=your-api-key

setx GOOGLE_API_KEY "your-api-key"

Get your DeepSeek API key and assign it to the DEEPSEEK_API_KEY environment variable.

Linux/macOSWindows

export DEEPSEEK_API_KEY=your-api-key

setx DEEPSEEK_API_KEY "your-api-key"

Get your OpenRouter API key and assign it to the OPENROUTER_API_KEY environment variable.

Linux/macOSWindows

export OPENROUTER_API_KEY=your-api-key

setx OPENROUTER_API_KEY "your-api-key"

Generate an Amazon Bedrock API key and assign it to the BEDROCK_API_KEY environment variable.

Linux/macOSWindows

export BEDROCK_API_KEY=your-api-key

setx BEDROCK_API_KEY "your-api-key"

Get your Mistral API key and assign it to the MISTRAL_API_KEY environment variable.

Linux/macOSWindows

export MISTRAL_API_KEY=your-api-key

setx MISTRAL_API_KEY "your-api-key"

Run a local LLM in Ollama as described in the Ollama documentation.

Create your first Koog agent

OpenAIAnthropicGoogleDeepSeekOpenRouterBedrockMistralOllama

The following example creates and runs a simple Koog agent using the GPT-4o model via the OpenAI API.

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

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

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

The example can produce the following output:

Hello! I'm here to help you with whatever you need. Here are just a few things I can do:

- Answer questions.
- Explain concepts or topics you're curious about.
- Provide step-by-step instructions for tasks.
- Offer advice, notes, or ideas.
- Help with research or summarize complex material.
- Write or edit text, emails, or other documents.
- Brainstorm creative projects or solutions.
- Solve problems or calculations.

Let me know what you need help with—I’m here for you!

The following example creates and runs a simple Koog agent using the Claude Opus 4.1 model via the Anthropic API.

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

    // Create an agent
    val agent = AIAgent(
        promptExecutor = simpleAnthropicExecutor(apiKey),
        llmModel = AnthropicModels.Opus_4_1
    )

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

The example can produce the following output:

Hello! I can help you with:

- **Answering questions** and explaining topics
- **Writing** - drafting, editing, proofreading
- **Learning** - homework, math, study help
- **Problem-solving** and brainstorming
- **Research** and information finding
- **General tasks** - instructions, planning, recommendations

What do you need help with today?

The following example creates and runs a simple Koog agent using the Gemini 2.5 Pro model via the Gemini API.

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

    // Create an agent
    val agent = AIAgent(
        promptExecutor = simpleGoogleAIExecutor(apiKey),
        llmModel = GoogleModels.Gemini2_5Pro
    )

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

The example can produce the following output:

I'm an AI that can help you with tasks involving language and information. You can ask me to:

*   **Answer questions**
*   **Write or edit text** (emails, stories, code, etc.)
*   **Brainstorm ideas**
*   **Summarize long documents**
*   **Plan things** (like trips or projects)
*   **Be a creative partner**

Just tell me what you need

The following example creates and runs a simple Koog agent using the deepseek-chat model via the DeepSeek API.

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

    // Create an LLM client
    val deepSeekClient = DeepSeekLLMClient(apiKey)

    // Create an agent
    val agent = AIAgent(
        // Create a prompt executor using the LLM client
        promptExecutor = SingleLLMPromptExecutor(deepSeekClient),
        // Provide a model
        llmModel = DeepSeekModels.DeepSeekChat
    )

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

The example can produce the following output:

Hello! I'm here to assist you with a wide range of tasks, including answering questions, providing information, helping with problem-solving, offering creative ideas, and even just chatting. Whether you need help with research, writing, learning something new, or simply want to discuss a topic, feel free to ask—I’m happy to help! 😊

The following example creates and runs a simple Koog agent using the GPT-4o model via the OpenRouter API.

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

    // Create an agent
    val agent = AIAgent(
        promptExecutor = simpleOpenRouterExecutor(apiKey),
        llmModel = OpenRouterModels.GPT4o
    )

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

The example can produce the following output:

I can answer questions, help with writing, solve problems, organize tasks, and more—just let me know what you need!

The following example creates and runs a simple Koog agent using the Claude Sonnet 4.5 model via the Bedrock API.

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

    // Create an agent
    val agent = AIAgent(
        promptExecutor = simpleBedrockExecutorWithBearerToken(apiKey),
        llmModel = BedrockModels.AnthropicClaude4_5Sonnet
    )

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

The example can produce the following output:

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?

The following example creates and runs a simple Koog agent using the Mistral Medium 3.1 model via the Mistral AI API.

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)
}

The example can produce the following output:

I can assist you with a wide range of topics and tasks. Here are some examples:

1. **Answering questions**: I can provide information on various subjects, including history, science, technology, literature, and more.
2. **Providing definitions**: If you're unsure about the meaning of a word or phrase, I can help define it for you.
3. **Generating text**: Whether it's writing an email, creating content for social media, or composing a story, I can help with text generation.
4. **Translation**: I can translate text from one language to another.
5. **Conversation**: We can have a chat about any topic that interests you, and I'll respond accordingly.
6. **Language practice**: If you're learning a new language, I can help with pronunciation, grammar, and vocabulary practice.
7. **Brainstorming**: If you're stuck on a problem or need ideas for a project, I can help brainstorm solutions.
8. **Summarization**: If you have a long piece of text and want a summary, I can condense it for you.

What's on your mind? Is there something specific you'd like help with?

The following example creates and runs a simple Koog agent using the llama3.2 model running locally via Ollama.

fun main() = runBlocking {
    // Create an agent
    val agent = AIAgent(
        promptExecutor = simpleOllamaAIExecutor(),
        llmModel = OllamaModels.Meta.LLAMA_3_2
    )

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

The example can produce the following output:

I can assist with various tasks such as answering questions, providing information, and even helping with language-related tasks like proofreading or writing suggestions. What's on your mind today?

Next steps

• Learn more about building agents