Koog Overview and Setup

What is Koog?

Koog is an open-source JetBrains framework for building AI agents. You write agents in idiomatic Kotlin and run them on the JVM. Koog connects your code to an LLM (Large Language Model) and lets the agent call tools to do real work.

An AI agent is a program that uses an LLM to reason, then calls functions (tools) to act. The LLM decides which tool to call. Your code runs the tool and returns the result.

Diagram: The basic agent loop. A user sends input, the agent asks the LLM, the LLM may request tool calls, the agent runs them, and finally returns a response.

Loading diagram...

Why AI Agents in Kotlin?

• Type safety: tool parameters are checked at compile time
• Coroutines: built-in async for concurrent tool calls and streaming
• Null safety: fewer runtime crashes in tool results
• JVM ecosystem: reuse Java libraries, HTTP clients, and databases

Prerequisites

• JDK 17+
• Kotlin 2.4.x (Koog requires 2.2.0+)
• Gradle 8.0+
• An LLM API key (for example OPENAI_API_KEY)

Add the Dependency

Create a Gradle project and add Koog 1.0.0 to build.gradle.kts:

plugins {
    kotlin("jvm") version "2.4.20"
    kotlin("plugin.serialization") version "2.4.20"
}

dependencies {
    implementation("ai.koog:koog-agents:1.0.0")
    // Optional beta additions (extra providers, features)
    implementation("ai.koog:koog-agents-additions:1.0.0-beta")
}

Re-import the Gradle project in IntelliJ IDEA to download the libraries.

Your First Agent ("Hello Agent")

The simplest agent takes a String and returns a String. It uses AIAgent with a prompt executor and a model. The types come from the ai.koog.* packages.

import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val apiKey = System.getenv("OPENAI_API_KEY")
        ?: error("Set the OPENAI_API_KEY environment variable")

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

    val result = agent.run("Hello! What can you do?")
    println(result)
}

The key types are AIAgent, simpleOpenAIExecutor, and OpenAIModels.Chat.GPT4o from the ai.koog packages. Your IDE (IntelliJ IDEA) will add the correct imports automatically.

Set the key in your shell first:

export OPENAI_API_KEY=sk-your-key-here

Expected output (the exact text varies):

Hello! I can answer questions, write text, explain code, and more. What do you need?

Key Terms

• AIAgent — the agent class. Holds the model, tools, and strategy
• promptExecutor — sends prompts to the LLM provider
• llmModel — which model to use (e.g. gpt-4o, claude-opus-4-1)
• systemPrompt — optional text that sets the agent's role
• toolRegistry — the tools the agent may call (added in the next file)

Practice

1. Run the Hello Agent and print the response.
2. Add a systemPrompt that makes the agent answer like a pirate.
3. Swap the OpenAI client for Anthropic (AnthropicLLMClient and MPModelType.Anthropic("claude-opus-4-1")). Confirm the agent still works.