Building AI Agents with Koog: A Software Engineer's Guide

JetBrains/koog

From a software engineer's perspective, Koog is particularly valuable because it solves some of the most common and complex challenges in building AI-powered applications.

Platform Versatility
Koog is built on Kotlin, which means it can run on the JVM, Android, iOS (via Kotlin Multiplatform), and even in the browser (via Kotlin/JS). This allows you to build a single AI agent that can be deployed across multiple platforms without significant code changes. This is a huge win for maintaining a consistent codebase and reducing development time.

Production-Ready Features
The framework is designed for production use, providing built-in solutions for common AI-related problems. This includes managing complex interactions with Large Language Models (LLMs), handling state, and ensuring scalability. You don't have to reinvent the wheel for things like robust error handling or managing API quotas.

Focus on AI Agents
Koog isn't just a generic library; it's specifically tailored for building AI agents. An agent is more than just a model call—it's an entity that can perceive its environment, make decisions, and take actions. Koog provides the scaffolding for this, allowing you to focus on the agent's logic rather than the underlying plumbing.

Intuitive and Robust
The framework leverages Kotlin's strengths, like coroutines for concurrent operations and a rich type system, to create a codebase that is both easy to read and less prone to errors. This makes it a great choice for teams already working with Kotlin.

To begin using Koog, you'll need a Kotlin-friendly development environment, such as IntelliJ IDEA.

The first step is to add the Koog library as a dependency. If you're using Gradle, you would add the following to your build.gradle.kts file

// build.gradle.kts
dependencies {
    implementation("org.jetbrains.kotlinx.koog:koog-core:latest_version")
    // Depending on your project, you might also need platform-specific dependencies,
    // like `koog-jvm` or `koog-android`.
}

You'll need to replace latest_version with the most recent version of the library, which you can find on the official JetBrains/koog GitHub page or on Maven Central.

Koog needs to know which LLM you want to use. It supports various providers. You'll need to configure your API key and other settings. This is typically done in your application's main configuration.

// Example of configuring OpenAI
val provider = OpenAILLMProvider(
    apiKey = "YOUR_OPENAI_API_KEY"
)

An agent in Koog is defined by its ability to interact with the LLM and the tools at its disposal. Here's a simple example of a "Greeter" agent.

import org.jetbrains.koog.agent.Agent

// Define a simple agent that just greets people.
// The tools are what the agent can "do."
class GreeterAgent(
    private val llmProvider: LLMProvider
) : Agent() {

    // You can define functions that the agent can "call."
    // This is a simple example of a tool.
    fun greet(name: String): String {
        return "Hello, $name! Nice to meet you."
    }

    override suspend fun thinkAndAct(input: String): String {
        // Here, the agent uses the LLM to decide what to do.
        // The LLM's response guides the agent's actions.
        val response = llmProvider.generateText(
            prompt = "The user says: '$input'. What should I do? Options are to 'greet' or just respond."
        )

        // A more complex agent would parse the response and call the right tool.
        // For this simple example, we'll just return a direct response.
        return "I received your message: '$input'. I'm still learning!"
    }
}

This is a simplified example, but it shows the basic structure. The thinkAndAct method is where the agent's core logic lives, processing an input and deciding how to respond or what action to take.

Let's put it all together in a complete, runnable example.

import kotlinx.coroutines.runBlocking
import org.jetbrains.koog.agent.Agent
import org.jetbrains.koog.llm.OpenAILLMProvider

// Your main application entry point
fun main() = runBlocking {
    // 1. Configure the LLM provider with your API key
    val llmProvider = OpenAILLMProvider(
        apiKey = System.getenv("OPENAI_API_KEY")
    )

    // 2. Instantiate your agent
    val greeterAgent = GreeterAgent(llmProvider)

    // 3. Interact with the agent
    println("Agent is active. Say something:")
    val userInput = readLine() ?: "Hello" // Read user input from the console

    println("You said: $userInput")

    // The agent processes your input and gives a response
    val agentResponse = greeterAgent.thinkAndAct(userInput)

    println("Agent says: $agentResponse")
}

// GreeterAgent class definition from the previous section would go here.
// For a real-world scenario, you would have much more sophisticated logic and tools.

To run this, you would set your OpenAI API key as an environment variable (OPENAI_API_KEY) and execute the main function. This code provides a basic blueprint for building more complex agents that can perform tasks, use external APIs, or even learn from past interactions.