Quickstart

Quickstart Guide

Get up and running with Koog 0.8.0 in minutes. This guide covers installation, API key configuration, and creating your first AI agent.

Requirements

Installation

Gradle (Kotlin DSL)

Add the Koog agents dependency to your build.gradle.kts:

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

Gradle (Groovy DSL)

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

Maven

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

API Key Configuration

Koog supports 8 LLM providers. Set the appropriate environment variable for your chosen provider:

Set your key as an environment variable:

# macOS/Linux
export OPENAI_API_KEY="sk-..."

# Windows (PowerShell)
$env:OPENAI_API_KEY = "sk-..."

Or load from a .env file using a library like dotenv-kotlin.

Creating Your First Agent

Kotlin Pattern

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.feature.model.featureConfig
import ai.koog.agents.ext.simple.simpleOpenAIExecutor
import ai.koog.agents.ext.llm.OpenAIModels

suspend fun main() {
    val apiKey = System.getenv("OPENAI_API_KEY")

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

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

Java Pattern

import ai.koog.agents.core.agent.AIAgent;
import ai.koog.agents.ext.simple.SimpleOpenAIExecutorKt;
import ai.koog.agents.ext.llm.OpenAIModels;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("OPENAI_API_KEY");

        var agent = AIAgent.builder(
                SimpleOpenAIExecutorKt.simpleOpenAIExecutor(apiKey),
                OpenAIModels.Chat.GPT4o
            )
            .build();

        String result = agent.run("Hello! What can you help me with?");
        System.out.println(result);
    }
}

Running the Agent

# Kotlin
./gradlew run

# Or compile and run directly
kotlinc -cp "koog-agents-0.8.0.jar:..." Main.kt -include-runtime -d app.jar
java -jar app.jar

Next Steps

• LLM Providers — Configure different LLM providers
• Basic Agents — Add system prompts, tools, and event handling
• Key Features — Explore Koog's full capabilities

Troubleshooting