JetBrains Koog Framework: Java ve Kotlin ile Enterprise AI Agent Geliştirme Rehberi (2026)

Koog vs Rakipler Karşılaştırması

Ön Gereksinimler

build.gradle.kts - Kotlin Projesi

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

repositories {
    mavenCentral()
}

dependencies {
    // Koog Agents - Ana framework bağımlılığı
    implementation("ai.koog:koog-agents:0.7.3")
}

build.gradle - Java Projesi

plugins {
    id 'java'
}

repositories {
    mavenCentral()
}

dependencies {
    // Koog Agents - Java API desteği dahil
    implementation 'ai.koog:koog-agents:0.7.3'
}

Basit Kotlin Agent - OpenAI ile

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.tools.annotations.Tool
import ai.koog.agents.core.tools.annotations.LLMDescription
import ai.koog.agents.ext.tool.ToolSet
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.clients.openai.simpleOpenAIExecutor
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    // API anahtarını ortam değişkeninden al
    val apiKey = System.getenv("OPENAI_API_KEY")
        ?: error("OPENAI_API_KEY ortam değişkeni ayarlanmamış!")

    // Basit bir ajan oluştur
    val agent = AIAgent(
        promptExecutor = simpleOpenAIExecutor(apiKey),
        llmModel = OpenAIModels.Chat.GPT4o
    )

    // Ajanı çalıştır ve sonucu al
    val result = agent.run("Merhaba! Bana Kotlin programlama dili hakkında kısa bilgi ver.")
    println("Ajan Yanıtı: $result")
}

Kotlin Agent - Anthropic Claude ile

import ai.koog.prompt.executor.clients.anthropic.AnthropicModels
import ai.koog.prompt.executor.clients.anthropic.simpleAnthropicExecutor
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val apiKey = System.getenv("ANTHROPIC_API_KEY")
        ?: error("ANTHROPIC_API_KEY ortam değişkeni ayarlanmamış!")

    val agent = AIAgent(
        promptExecutor = simpleAnthropicExecutor(apiKey),
        llmModel = AnthropicModels.Sonnet_4
    )

    val result = agent.run("Türkiye'nin başkenti neresidir?")
    println("Claude Yanıtı: $result")
}

Tool Tanımlı Kotlin Agent

import ai.koog.agents.core.tools.annotations.Tool
import ai.koog.agents.core.tools.annotations.LLMDescription
import ai.koog.agents.ext.tool.ToolSet

// Araç seti (ToolSet) sınıfı tanımlayın
class HavaDurumuAraclari : ToolSet {

    @Tool
    @LLMDescription("Belirtilen şehir için güncel hava durumu bilgisini getirir")
    fun havaDurumuGetir(
        @LLMDescription("Hava durumu sorgulanacak şehir adı")
        sehir: String
    ): String {
        // Gerçek uygulamada bir API çağrısı yapılır
        return "$sehir için hava durumu: 22°C, Güneşli"
    }

    @Tool
    @LLMDescription("İki şehir arasındaki sıcaklık farkını hesaplar")
    fun sicaklikFarkiHesapla(
        @LLMDescription("Birinci şehir adı") sehir1: String,
        @LLMDescription("İkinci şehir adı") sehir2: String
    ): String {
        return "$sehir1 ve $sehir2 arasındaki sıcaklık farkı: 5°C"
    }
}

Java ile Tool Tanımlama

import ai.koog.agents.core.tools.annotations.Tool;
import ai.koog.agents.core.tools.annotations.LLMDescription;
import ai.koog.agents.ext.tool.ToolSet;

public class BankaAraclari implements ToolSet {

    @Tool
    @LLMDescription("Belirtilen alıcıya para gönderir")
    public Boolean paraGonder(
        @LLMDescription("Alıcının benzersiz kimliği")
        String aliciId,
        Integer tutar
    ) {
        System.out.println(tutar + " TL " + aliciId + " kişisine gönderildi.");
        return true;
    }

    @Tool
    @LLMDescription("Hesap bakiyesini TL cinsinden döndürür")
    public Integer hesapBakiyesiGetir(String kullaniciId) {
        // Gerçek uygulamada veritabanı sorgusu yapılır
        return 15000;
    }
}

Java ile Agent Oluşturma (Builder Pattern)

import ai.koog.agents.core.agent.AIAgent;
import ai.koog.agents.core.tools.ToolRegistry;
import ai.koog.prompt.executor.MultiLLMPromptExecutor;
import ai.koog.prompt.executor.clients.openai.OpenAILLMClient;
import ai.koog.prompt.executor.clients.openai.OpenAIModels;

public class BankaAjanUygulamasi {

    public static void main(String[] args) {
        // LLM istemcisini (client) oluştur
        String apiKey = System.getenv("OPENAI_API_KEY");
        var promptExecutor = new MultiLLMPromptExecutor(
            new OpenAILLMClient(apiKey)
        );

        // Araç kayıt defterini (tool registry) oluştur
        var toolRegistry = ToolRegistry.builder()
            .tools(new BankaAraclari())
            .build();

        // Ajanı (agent) oluştur
        var bankaAjani = AIAgent.builder()
            .promptExecutor(promptExecutor)
            .llmModel(OpenAIModels.Chat.GPT4o)
            .systemPrompt("Sen bir banka asistanısın. Kullanıcıların hesap " +
                "işlemlerinde yardımcı olursun.")
            .toolRegistry(toolRegistry)
            .build();

        // Ajanı çalıştır
        String sonuc = bankaAjani.run(
            "Yeterli bakiyem varsa ali_123 kullanıcısına 500 TL gönder"
        );
        System.out.println("Ajan Sonucu: " + sonuc);
    }
}

Spring Boot Starter Bağımlılığı

// build.gradle.kts
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("ai.koog:koog-spring-boot-starter:0.7.3")

    // Kotlin kullanıyorsanız coroutine desteği için:
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor:1.10.1")
}

application.properties Yapılandırması

# OpenAI Yapılandırması
ai.koog.openai.enabled=true
ai.koog.openai.api-key=${OPENAI_API_KEY}

# Anthropic Yapılandırması (opsiyonel)
ai.koog.anthropic.enabled=true
ai.koog.anthropic.api-key=${ANTHROPIC_API_KEY}

# Google Gemini Yapılandırması (opsiyonel)
ai.koog.google.enabled=false

Spring Boot Controller ile Koog Agent

import ai.koog.agents.core.agent.AIAgent;
import ai.koog.agents.core.tools.ToolRegistry;
import ai.koog.prompt.executor.PromptExecutor;
import ai.koog.prompt.executor.clients.openai.OpenAIModels;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/agent")
public class AjanController {

    private final PromptExecutor openaiExecutor;

    // Spring, yapılandırılmış executor'ı otomatik enjekte eder
    public AjanController(
        @Qualifier("openaiExecutor") PromptExecutor openaiExecutor
    ) {
        this.openaiExecutor = openaiExecutor;
    }

    @PostMapping("/chat")
    public String chat(@RequestBody String mesaj) {
        var agent = AIAgent.builder()
            .promptExecutor(openaiExecutor)
            .llmModel(OpenAIModels.Chat.GPT4o)
            .systemPrompt("Sen yardımcı bir asistansın.")
            .toolRegistry(
                ToolRegistry.builder()
                    .tools(new BankaAraclari())
                    .build()
            )
            .build();

        return agent.run(mesaj);
    }
}

MCP Sunucusu ile Koog Agent

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.mcp.MCPToolProvider
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.clients.openai.simpleOpenAIExecutor

suspend fun main() {
    val apiKey = System.getenv("OPENAI_API_KEY")
        ?: error("API key bulunamadı!")

    // MCP sunucusundan araçları al
    val mcpTools = MCPToolProvider.fromStdio(
        command = "npx",
        args = listOf("-y", "@modelcontextprotocol/server-filesystem", "/tmp")
    )

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

    val result = agent.run("Dosya sistemindeki dosyaları listele")
    println(result)
}

OpenTelemetry Bağımlılığı Ekleme

// build.gradle.kts
dependencies {
    implementation("ai.koog:koog-agents:0.7.3")

    // OpenTelemetry desteği
    implementation("ai.koog:koog-agents-otel:0.7.3")

    // OpenTelemetry SDK
    implementation("io.opentelemetry:opentelemetry-sdk:1.45.0")
    implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.45.0")
}

OpenTelemetry Yapılandırması

import ai.koog.agents.otel.KoogOpenTelemetry
import io.opentelemetry.sdk.OpenTelemetrySdk
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter

// OTLP exporter yapılandır (Jaeger, Grafana Tempo vb.)
val spanExporter = OtlpGrpcSpanExporter.builder()
    .setEndpoint("http://localhost:4317")
    .build()

// Koog OpenTelemetry entegrasyonunu etkinleştir
KoogOpenTelemetry.configure(spanExporter)

Desteklenen Observability Platformları