Koog: Framework Kotlin para Agentes de IA da JetBrains | Kotlin Brasil

Se você acompanha o ecossistema Kotlin, já percebeu que a JetBrains está investindo pesado em inteligência artificial. E a peça central dessa estratégia para devs Kotlin é o Koog — um framework open-source para construir agentes de IA diretamente em Kotlin, com suporte a múltiplas plataformas, tolerância a falhas e integração nativa com Spring Boot e Ktor.

Neste artigo, vamos explorar o que é o Koog, como funciona, e criar exemplos práticos para você sair daqui pronto para montar seu primeiro agente.

O que é o Koog?

O Koog é um framework JVM criado pela JetBrains para construir agentes de IA previsíveis, tolerantes a falhas e prontos para produção. Diferente de SDKs simples que apenas fazem chamadas a APIs de LLMs, o Koog oferece uma arquitetura completa para orquestrar agentes que:

• Executam ferramentas (tools) para interagir com sistemas externos
• Mantêm contexto em conversas longas com compressão inteligente de histórico
• Se recuperam de falhas com retries automáticos e persistência de estado
• Rodam em múltiplas plataformas via Kotlin Multiplatform (JVM, Android, iOS, WasmJS, browser)

A versão mais recente é a 0.7.3, lançada em março de 2026, e já suporta provedores como OpenAI, Anthropic, Google, DeepSeek, Ollama e até Amazon Bedrock.

Se você já leu nosso artigo sobre Kotlin e IA/Machine Learning, o Koog é a evolução natural desse cenário — agora com um framework oficial da JetBrains.

Configurando o projeto

O setup é simples. Adicione a dependência no seu build.gradle.kts:

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.3.20"
}

repositories {
    mavenCentral()
}

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

O Koog exige JDK 17+ e Kotlin 2.3.10+. Se você ainda está em versões anteriores, vale conferir nosso guia de novidades do Kotlin 2.3.20.

Criando seu primeiro agente

O exemplo mais básico é um agente que responde perguntas usando um LLM:

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.tools.simpleOpenAIExecutor
import ai.koog.agents.ext.model.OpenAIModels
import kotlinx.coroutines.runBlocking

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

    val agente = AIAgent(
        promptExecutor = simpleOpenAIExecutor(apiKey),
        systemPrompt = "Você é um assistente especializado em Kotlin. " +
            "Responda em português brasileiro de forma clara e concisa.",
        llmModel = OpenAIModels.Chat.GPT4o
    )

    val resposta = agente.run("Qual a diferença entre val e var em Kotlin?")
    println(resposta)
}

Esse é o “Hello World” do Koog. O AIAgent recebe um executor (que faz a comunicação com o LLM), um system prompt e o modelo a ser usado. Se você quiser usar Anthropic ou outro provedor, basta trocar o executor.

Criando Tools personalizadas

O verdadeiro poder dos agentes está nas tools — funções que o agente pode chamar para interagir com o mundo externo. O Koog oferece duas abordagens para definir tools: baseada em anotações e baseada em classes.

Tool com anotações

A forma mais simples usa a anotação @Tool:

import ai.koog.agents.core.tools.annotations.Tool
import ai.koog.agents.core.tools.annotations.ToolParam

@Tool("buscar_salario", "Busca o salário médio de um cargo em Kotlin no Brasil")
fun buscarSalario(
    @ToolParam("cargo", "O cargo a ser pesquisado, ex: junior, pleno, senior")
    cargo: String
): String {
    val salarios = mapOf(
        "junior" to "R$ 4.500 - R$ 7.000",
        "pleno" to "R$ 8.000 - R$ 14.000",
        "senior" to "R$ 15.000 - R$ 25.000"
    )
    return salarios[cargo.lowercase()]
        ?: "Cargo não encontrado. Tente: junior, pleno ou senior."
}

Quando o agente percebe que precisa buscar informações de salário, ele automaticamente chama essa tool. Se você se interessa por dados de carreira, temos conteúdos detalhados sobre salários de dev Kotlin e mercado de trabalho.

Tool baseada em classe

Para tools mais complexas com estado ou dependências:

import ai.koog.agents.core.tools.Tool
import ai.koog.agents.core.tools.ToolDescriptor
import ai.koog.agents.core.tools.ToolParameter

class BuscaGlossarioTool : Tool {
    override val descriptor = ToolDescriptor(
        name = "buscar_glossario",
        description = "Busca a definição de um termo Kotlin no glossário",
        parameters = listOf(
            ToolParameter(
                name = "termo",
                description = "O termo Kotlin a ser pesquisado",
                type = "string",
                required = true
            )
        )
    )

    private val glossario = mapOf(
        "coroutine" to "Mecanismo de concorrência leve do Kotlin para programação assíncrona",
        "sealed class" to "Classe que restringe hierarquia de herança a um conjunto finito",
        "data class" to "Classe que gera automaticamente equals, hashCode, toString e copy",
        "flow" to "Stream reativo frio do Kotlin para emitir valores assíncronos",
        "suspend" to "Modificador que marca uma função como suspendível para uso com coroutines"
    )

    override suspend fun execute(arguments: Map<String, String>): String {
        val termo = arguments["termo"]?.lowercase() ?: return "Termo não informado"
        return glossario[termo]
            ?: "Termo '$termo' não encontrado. Consulte o glossário completo."
    }
}

Nosso glossário Kotlin tem mais de 50 termos — imagine integrar isso a um agente que responde dúvidas de estudantes!

Agentes com fluxo baseado em grafo

Além do modo funcional, o Koog permite definir fluxos de agente como um grafo de estados. Isso é útil para workflows mais complexos onde o agente precisa tomar decisões em sequência:

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.dsl.builder.forwardTo
import ai.koog.agents.core.dsl.builder.strategy

val estrategia = strategy("analise-codigo") {
    val analisar by node {
        prompt("Analise este código Kotlin e identifique problemas de performance.")
    }
    val sugerir by node {
        prompt("Sugira melhorias com exemplos de código corrigido.")
    }
    val revisar by node {
        prompt("Revise as sugestões e dê uma nota de 1 a 10 para o código.")
    }

    edge(analisar forwardTo sugerir)
    edge(sugerir forwardTo revisar)

    entryNode = analisar
    exitNode = revisar
}

Esse padrão é especialmente poderoso para criar pipelines de code review, análise de dados ou automação de DevOps. Se você trabalha com CI/CD em Kotlin, vale conferir nosso artigo sobre Kotlin e DevOps.

Integração com Spring Boot

O Koog se integra nativamente com Spring Boot, o que facilita expor agentes como endpoints REST:

import ai.koog.agents.spring.AgentService
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/agente")
class AgenteKotlinController(
    private val agentService: AgentService
) {
    @PostMapping("/perguntar")
    suspend fun perguntar(@RequestBody pergunta: PerguntaRequest): RespostaDTO {
        val resposta = agentService.run(pergunta.texto)
        return RespostaDTO(resposta = resposta)
    }
}

data class PerguntaRequest(val texto: String)
data class RespostaDTO(val resposta: String)

Se você já usa Spring Boot com Kotlin, adicionar um agente de IA ao seu backend é questão de configurar o Koog como um bean e injetá-lo nos seus controllers.

Integração com Ktor

Para quem prefere o Ktor, o Koog oferece um plugin dedicado:

import ai.koog.agents.ktor.koogAgent
import io.ktor.server.application.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.routing.*
import io.ktor.server.request.*
import io.ktor.server.response.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(KoogAgent) {
            apiKey = System.getenv("OPENAI_API_KEY")
            systemPrompt = "Assistente Kotlin em português"
        }

        routing {
            post("/chat") {
                val input = call.receiveText()
                val resposta = call.application.koogAgent.run(input)
                call.respondText(resposta)
            }
        }
    }.start(wait = true)
}

Provedores de LLM suportados

O Koog não te prende a um único provedor. Atualmente, ele suporta:

Isso significa que você pode começar testando com Ollama localmente e depois migrar para OpenAI ou Anthropic em produção sem mudar a lógica do agente.

Kotlin Multiplatform: agentes em todo lugar

Uma das maiores vantagens do Koog é o suporte a Kotlin Multiplatform. Você pode executar agentes em:

• Backend (JVM com Spring Boot ou Ktor)
• Android (diretamente no app)
• iOS (via compilação Kotlin/Native)
• Browser (via Kotlin/WasmJS)

Isso abre possibilidades como agentes embarcados em apps mobile que funcionam offline com modelos locais via Ollama.

Quando usar o Koog?

O Koog faz sentido quando você precisa de mais do que uma simples chamada de API para um LLM. Cenários ideais incluem:

• Chatbots empresariais com acesso a bases de dados internas
• Automação de workflows com múltiplas etapas e decisões
• Assistentes de código que executam análise estática e sugerem melhorias
• Pipelines de dados com agentes que coletam, processam e relatam informações
• Apps mobile com IA embarcada via Kotlin Multiplatform

Conclusão

O Koog posiciona o Kotlin como uma linguagem de primeira classe para desenvolvimento de agentes de IA. Com suporte a múltiplos provedores, integração nativa com Spring Boot e Ktor, e a flexibilidade do Kotlin Multiplatform, ele remove as barreiras para quem quer construir aplicações inteligentes sem sair do ecossistema Kotlin.

Se você está começando com Kotlin, confira nosso guia completo da linguagem. Para quem já domina o básico e quer explorar o backend, nossos guias de Ktor e Spring Boot são ótimos pontos de partida antes de mergulhar no Koog.

A documentação oficial está em docs.koog.ai e o código-fonte no GitHub da JetBrains. No mundo de IA, Python ainda domina com LangChain e CrewAI, mas o Koog traz a vantagem de type safety e coroutines nativas — ideal para times que já vivem no ecossistema Kotlin e não querem manter uma stack separada em Python só para IA.

Tem interesse em carreira Kotlin? Confira nossas páginas de vagas remotas e como se tornar dev Kotlin.