DEV Community: Ivan Béthus

Koog : un framework agentique pour ne plus réinventer la boucle

Ivan Béthus — Tue, 15 Sep 2026 09:22:50 +0000

Introduction

Construire un agent LLM "à la main", c'est amusant pendant deux heures. Mais, rapidement, émergent les vraies questions : comment gérer une conversation qui dépasse la fenêtre de contexte ? Comment structurer un workflow qui a plus de trois étapes ? Comment brancher ses propres outils sans réécrire un parseur de function-calling maison ?

Koog est le framework agentique de JetBrains. Il est écrit en Kotlin et cible principalement la JVM, avec ses intégrations Spring Boot, Spring AI et Ktor. La version 1.0 est sortie en mai 2026, annoncée à la keynote de KotlinConf.

Découvrons ensemble si ce framework JVM tout neuf tient ses promesses !

Tous les exemples sont donnés en Kotlin.

Une prise en main étonnamment simple

Le point d'entrée de Koog est un DSL Kotlin (avec, depuis mars 2026, une API Java). Pas de YAML tentaculaire : on déclare son agent, ses outils et sa stratégie directement en code typé. Le "hello world" d'un agent tient en quelques lignes :

fun main() = runBlocking {
    val apiKey = System.getenv("ANTHROPIC_API_KEY")
        ?: error("The API key is not set.")

    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(AnthropicLLMClient(apiKey)),
        llmModel = AnthropicModels.Opus_4_1
    )

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

Déclarer un outil personnalisé est tout aussi direct : une classe qui implémente ToolSet, une méthode annotée @Tool, des @LLMDescription pour guider le modèle, et l'outil devient utilisable dès qu'on l'enregistre dans le ToolRegistry de l'agent :

@LLMDescription("Tools for getting weather information")
class MyFirstToolSet : ToolSet {
    @Tool
    @LLMDescription("Get the current weather for a location")
    fun getWeather(
        @LLMDescription("The city and state/country")
        location: String
    ): String {
        return "The weather in $location is sunny and 72°F"
    }
}

fun main() = runBlocking {
    val agent = AIAgent(
        promptExecutor = simpleOpenAIExecutor(apiToken),
        systemPrompt = "Provide weather information for a given location.",
        llmModel = OpenAIModels.Chat.GPT4o,
        toolRegistry = ToolRegistry {
            tools(MyFirstToolSet())
        }
    )

    agent.run("What's the weather like in New York?")
}

Des graphes d'états sur-mesure

Koog ne se contente pas d'une boucle "prompt → outil → prompt". Il expose une véritable architecture en graphe de stratégie (AIAgentGraphStrategyBuilder), composée de trois briques :

des nœuds, qui encapsulent une étape de traitement (appel LLM, appel d'outil, compression d'historique, transformation de données...) ;
des arêtes, qui relient les nœuds et peuvent porter des conditions : on ne suit une arête que si telle condition est vraie ;
des sous-graphes, des unités de traitement autonomes avec leur propre contexte et leurs propres outils.

Chaque nœud a un type d'entrée et un type de sortie, et la stratégie elle-même en a un aussi, ce qui fait que les erreurs de branchement se voient à la compilation plutôt qu'en production.

Koog livre deux stratégies prêtes à l'emploi : chatAgentStrategy, pour une interaction conversationnelle, et reActStrategy, qui implémente le pattern ReAct en alternant phases de raisonnement et phases d'action, à une fréquence réglable via le paramètre reasoningInterval. Mais ce ne sont que des points de départ. Dès que le cas d'usage sort du cadre (boucles de validation, branchements selon le résultat d'un outil, sous-agents spécialisés qui se relaient sur une tâche complexe), on redescend sur le graphe et on assemble ses propres nœuds. Voici par exemple une simple boucle d'appels d'outils, écrite à la main, qui tourne jusqu'à obtenir une réponse textuelle :

val calculatorAgentStrategy = strategy<String, String>("Simple calculator") {
    val sendInput by nodeLLMRequest()
    val executeTools by nodeExecuteTools()
    val sendToolResults by nodeLLMSendToolResults()

    edge(nodeStart forwardTo sendInput)
    edge(sendInput forwardTo nodeFinish onTextMessage { true })
    edge(sendInput forwardTo executeTools onToolCalls { true })
    edge(executeTools forwardTo sendToolResults)
    edge(sendToolResults forwardTo nodeFinish onTextMessage { true })
    edge(sendToolResults forwardTo executeTools onToolCalls { true })
}

La seule contrainte : chaque strategy { } doit avoir un chemin complet entre nodeStart et nodeFinish. Tout le reste, nœuds intermédiaires, boucles, branches, est à la carte.

La boucle agentique, et la compression automatique de l'historique

Le cœur du sujet reste donc la boucle agentique : l'agent appelle le LLM, reçoit éventuellement des demandes d'appel d'outils, les exécute, réinjecte les résultats, et recommence jusqu'à obtenir une réponse finale. Koog gère cette boucle nativement, avec un mécanisme de retry configurable et de la persistance par checkpoints (qui restaure la machine à états complète de l'agent, pas seulement l'historique de messages).

Reste le problème du contexte long. Une conversation agentique qui s'étale sur des dizaines d'itérations, appels d'outils compris, fait exploser le nombre de tokens envoyés à chaque requête. Koog propose une compression automatique de l'historique, activable comme un nœud à part entière dans le graphe (nodeLLMCompressHistory en Kotlin, AIAgentNode.llmCompressHistory() côté Java), avec plusieurs stratégies prêtes à l'emploi :

HistoryCompressionStrategy.WholeHistory (par défaut) : résume l'intégralité de la conversation en un seul message de synthèse.
HistoryCompressionStrategy.FromLastNMessages(n) : ne compresse que les n derniers messages.
HistoryCompressionStrategy.Chunked(size) : découpe l'historique en segments de taille fixe et résume chaque segment indépendamment, pour garder à la fois le passé lointain et le présent récent.
FactRetrievalHistoryCompressionStrategy : extrait uniquement les faits pertinents par rapport à une liste de concepts que vous fournissez, plutôt qu'un résumé généraliste.

Si aucune ne correspond à votre cas d'usage, rien n'empêche d'étendre HistoryCompressionStrategy pour écrire la vôtre. De quoi faire tourner des agents longtemps sans que la facture de tokens (ni la latence) ne devienne ingérable.

Voici à quoi ça ressemble une fois branché sur un graphe de stratégie, avec une compression déclenchée conditionnellement après l'exécution d'un outil :

// Helper maison, pas une API du framework : à vous de définir le seuil
private suspend fun AIAgentContext.historyIsTooLong(): Boolean =
    llm.readSession { prompt.messages.size > 100 }

val strategy = strategy<String, String>("execute-with-history-compression") {
    val callLLM by nodeLLMRequest()
    val executeTool by nodeExecuteTools()
    val sendToolResult by nodeLLMSendToolResults()

    val compressHistory by nodeLLMCompressHistory<ReceivedToolResults>()

    edge(nodeStart forwardTo callLLM)
    edge(callLLM forwardTo nodeFinish onTextMessage { true })
    edge(callLLM forwardTo executeTool onToolCalls { true })

    edge(executeTool forwardTo compressHistory onCondition { historyIsTooLong() })
    edge(compressHistory forwardTo sendToolResult)
    edge(executeTool forwardTo sendToolResult onCondition { !historyIsTooLong() })

    edge(sendToolResult forwardTo executeTool onToolCalls { true })
    edge(sendToolResult forwardTo nodeFinish onTextMessage { true })
}

Ce qui donne, visuellement :

stateDiagram-v2
    [*] --> AppelLLM
    AppelLLM --> [*] : réponse textuelle
    AppelLLM --> ExecutionOutils : appels d'outils
    ExecutionOutils --> CompressionHistorique : historique trop long
    ExecutionOutils --> EnvoiResultats : historique OK
    CompressionHistorique --> EnvoiResultats
    EnvoiResultats --> ExecutionOutils : nouveaux appels d'outils
    EnvoiResultats --> [*] : réponse textuelle

GOAP : planification algorithmique

Koog sait aussi faire du GOAP (Goal-Oriented Action Planning), une technique popularisée par le jeu vidéo (l'exemple le plus connu étant peut-être l'IA des soldats de F.E.A.R. en 2005) et qui se révèle efficace pour organiser le comportement d'un agent.

Contrairement à un planificateur "LLM-based" qui demande au modèle de générer lui-même la séquence d'actions, un agent GOAP la découvre algorithmiquement. En pratique, on déclare :

un état, sous forme de data class, qui représente les propriétés pertinentes du monde de l'agent ;
des actions, chacune avec une précondition (ce qui doit être vrai pour pouvoir l'exécuter), un coût, et une belief : la prédiction optimiste de l'état résultant, utilisée uniquement pendant la phase de planification ;
des buts, avec leur condition de complétion.

Le planificateur part de l'objectif : la recherche A* remonte la chaîne des préconditions, de l'action qui satisfait le but jusqu'à celle qu'on peut exécuter immédiatement, en minimisant le coût total du chemin obtenu. C'est cette recherche à rebours qui rend l'algorithme efficace. La distinction entre la belief et le résultat réel est importante : le plan est construit sur ces prédictions, mais c'est bien l'exécution effective de chaque action qui met à jour l'état courant, celui depuis lequel le planificateur repart à l'étape suivante. Si une action échoue ou produit un résultat inattendu, l'agent le constate et replanifie. Cette approche est intéressante lorsque plusieurs chemins mènent à l'objectif, ou quand les conditions changent en cours de route.

Un exemple pour un agent de rédaction de contenu, qui doit passer par un plan (rédiger, relire, publier) sans qu'on lui impose l'ordre en dur. Pour que le planificateur ait un vrai choix à faire (et pas une simple chaîne linéaire), on lui donne deux façons d'obtenir un plan : le générer via le LLM, ou réutiliser un plan déjà fourni par l'appelant :

data class ContentState(
    val topic: String,
    val providedOutline: String? = null,
    val hasOutline: Boolean = false,
    val outline: String = "",
    val hasDraft: Boolean = false,
    val draft: String = "",
    val hasReview: Boolean = false,
    val isPublished: Boolean = false
) : GoapAgentState<String, String>() {
    override val agentInput = topic
    override fun provideOutput(): String = draft
}

val planner = goap("content-planner", ::ContentState) {
    action(name = "Use provided outline",
        precondition = { state -> !state.hasOutline && state.providedOutline != null },
        belief = { state -> state.copy(hasOutline = true, outline = state.providedOutline!!) },
        cost = { 0.1 }
    ) { ctx, state -> state.copy(hasOutline = true, outline = state.providedOutline!!) }

    action(name = "Create outline",
        precondition = { state -> !state.hasOutline },
        belief = { state -> state.copy(hasOutline = true, outline = "Outline") },
        cost = { 1.0 }
    ) { ctx, state -> /* appel LLM pour générer le plan */ }

    action(name = "Write draft",
        precondition = { state -> state.hasOutline && !state.hasDraft },
        belief = { state -> state.copy(hasDraft = true, draft = "Draft") },
        cost = { 2.0 }
    ) { ctx, state -> /* appel LLM pour rédiger le brouillon */ }

    action(name = "Review content",
        precondition = { state -> state.hasDraft && !state.hasReview },
        belief = { state -> state.copy(hasReview = true) },
        cost = { 1.0 }
    ) { ctx, state -> /* appel LLM pour relire */ }

    action(name = "Publish",
        precondition = { state -> state.hasReview && !state.isPublished },
        belief = { state -> state.copy(isPublished = true) },
        cost = { 1.0 }
    ) { ctx, state -> state.copy(isPublished = true) }

    goal(name = "Published article",
        description = "Complete and publish the article",
        condition = { state -> state.isPublished }
    )
}

// Le planner n'est pas un agent : on l'emballe dans une stratégie
val agent = AIAgent(
    promptExecutor = executor,
    strategy = AIAgentPlannerStrategy.create("content-agent", planner),
    llmModel = OpenAIModels.Chat.GPT4o
)

Aucune de ces actions ne dit explicitement "fais A puis B puis C" : c'est le planificateur qui, à partir des préconditions et de l'objectif final (isPublished == true), reconstruit lui-même l'ordre d'exécution. Et selon que providedOutline est renseigné ou non, il retient "Use provided outline" (coût 0.1, aucun appel LLM) plutôt que "Create outline" (coût 1.0) : deux chemins différents vers le même objectif, sans une ligne de branchement écrite à la main.

Reste une question cruciale : que se passe-t-il si le planificateur ne converge jamais, par exemple parce que deux actions s'annulent mutuellement en boucle (l'une remet l'état dans la configuration que l'autre vient de défaire) ? Côté Koog, le seul garde-fou documenté est générique à tous les agents : le paramètre maxAgentIterations de l'AIAgentConfig, qui plafonne le nombre total d'itérations, planification comprise. Rien d'aussi ciblé qu'un vrai stuck handler dédié au planificateur pour l'instant.

À comparer avec le fonctionnement du framework Embabel, qui, lui, expose une interface StuckHandler pour traiter explicitement l'état "bloqué", ainsi qu'un Budget (nombre d'actions, coût, tokens) branché sur son EarlyTerminationPolicy pour couper court aux boucles. Un point à surveiller si vous comptez vous appuyer sur GOAP en production.

Deux détails pratiques : les planificateurs vivent dans un module à part (agents:agents-planners, à ajouter explicitement à vos dépendances), et cette partie de Koog est encore estampillée beta. L'API peut bouger.

Tools, MCP et A2A : un agent ne travaille jamais seul

Un agent, même bien conçu, ne vaut que par les outils qu'il peut actionner. Koog embarque nativement un système de tools avec un registre typé (nom, description, schéma d'entrée) et la possibilité de déclarer ses propres outils métier en quelques lignes.

Le support du Model Context Protocol (MCP) est inclus de base, via McpToolRegistryProvider : Koog se connecte à un serveur MCP en stdio (defaultStdioTransport) ou en SSE (defaultSseTransport), y découvre dynamiquement les outils disponibles, les transforme en outils Koog et les enregistre dans le tool registry de l'agent. Que ce serveur expose Google Maps, Playwright ou votre propre outillage interne, le code appelant ne change pas.

Pour les architectures multi-agents, Koog implémente le protocole A2A (Agent-to-Agent) en version 0.3.0, côté client comme côté serveur. On peut donc exposer un agent Koog comme serveur A2A consommable par n'importe quel agent compatible, ou faire dialoguer un agent Koog avec des agents tiers respectant le protocole.

Les intégrations : Spring Boot, Spring AI, Ktor

Koog est pensé pour s'intégrer dans votre écosystème JVM avec le moins de friction possible :

Spring Boot a son starter dédié, koog-spring-boot-starter. Il permet d'auto-configurer des PromptExecutor à partir de vos properties (openAIExecutor, anthropicExecutor, googleExecutor, ollamaExecutor, multiLLMPromptExecutor...).
Spring AI bénéficie d'une intégration plus large, avec quatre starters indépendants : koog-spring-ai-starter-model-chat (adapte un ChatModel Spring AI en LLMClient Koog), -model-embedding (un EmbeddingModel en LLMEmbeddingProvider), -chat-memory (un ChatMemoryRepository en ChatHistoryProvider) et -vector-store (un VectorStore en KoogVectorStore). La répartition des rôles est claire : Spring AI couvre l'accès au modèle, la mémoire de chat et le stockage vectoriel pour le RAG, Koog ajoute par-dessus l'orchestration, les stratégies multi-étapes et la résilience. Un point à connaître : même quand le modèle passe par Spring AI, c'est Koog qui exécute les outils. Spring AI ne reçoit que les définitions et les schémas, avec internalToolExecutionEnabled forcé à false.
Ktor dispose également d'un plugin dédié, pour les backends qui préfèrent rester sur l'écosystème Kotlin natif plutôt que Spring.
Côté fournisseurs LLM, la liste est large : OpenAI, Anthropic, Google, DeepSeek, Mistral, Alibaba, AWS Bedrock, Ollama pour les modèles locaux. Et on peut basculer une conversation vers un autre modèle en cours de route, avec un jeu d'outils différent, sans perdre l'historique.

L'observabilité n'est pas en reste, puisque Koog s'appuie sur OpenTelemetry, avec des intégrations clefs en main pour Langfuse, W&B Weave et Datadog.

NB : Kotlin first, mais Java n'est pas en reste

Deux points de vigilance avant de foncer tête baissée :

Koog reste un framework Kotlin-first. Le support Java est arrivé en mars 2026, avec une API fluide en builder et l'accès aux fonctionnalités cœur. Cependant, les nouveautés continuent d'arriver côté Kotlin en premier. Si vous êtes en pur Java, vérifiez au cas par cas dans la documentation que la fonctionnalité qui vous intéresse est bien portée.
Depuis la 1.0, Koog sépare explicitement ses modules en deux flux : stable, sur lequel les APIs ne cassent pas sans cycle de dépréciation, et beta, où elles peuvent changer. C'est plutôt une bonne nouvelle, mais ça veut aussi dire qu'une partie de ce qui rend Koog intéressant, GOAP en tête, est du côté beta. À arbitrer avant de tout miser dessus en production.

Conclusion

Koog coche une case rare : un framework agentique pensé pour la JVM, qui ne sacrifie ni l'ergonomie (DSL Kotlin, builders Java) ni la puissance (graphes d'états sur-mesure, GOAP, MCP, A2A), tout en s'intégrant proprement dans les stacks Spring Boot et Spring AI déjà en place. Si vous devez faire cohabiter des agents LLM avec un backend Java ou Kotlin existant plutôt que de monter une stack Python en parallèle, ça vaut clairement le détour.

Son concurrent direct pour la JVM est Embabel, que je vous conseille de suivre de près également !

La documentation officielle est disponible sur docs.koog.ai.

BreizhCamp2024 : à l'ouest toute !

Ivan Béthus — Thu, 11 Jul 2024 14:15:27 +0000

Nous sommes de nouveau sur la route avec quelques membres des équipes onepoint pour le rendez-vous breton des développeurs en tout genre : le BreizhCamp.
Créé en 2011 à l’initiative du BreizhJUG, le BreizhCamp propose de faire se rencontrer les communautés du développement et de l’expertise, avec un contenu à la carte sur plus de 100 thèmes présentés.

En plus des nombreux sujets présentés par nos collègues, nous avons préparé avec @dlucas un petit top 3 de nos conférences préférées. À vos lunettes, il y a de la bonne lecture !

Du code source à l'exécutable : plongée dans les entrailles de la compilation en Rust par Édouard Siha

Comment le compilateur Rust fait-il pour assurer le respect de la notion d'emprunt ? Pourquoi est-il capable de générer facilement des binaires spécialisés pour une plateforme d'exécution différente de celle de la plateforme de compilation ? Quel genre d'optimisations surprenantes est-il capable de réaliser ? Quelles caractéristiques le différencie des compilateurs utilisés pour le C ? Pour le Java ?

Si ces questionnements vous intéressent, la conférence d'Édouard Siha est un incontournable. Il rentre en détail dans les étapes de la compilation en Rust, en faisant une analogie assez pédagogique avec les profondeurs marines. Un deep dive très intéressant pour renforcer sa compréhension du Rust et de manière générale des différentes étapes de création d'un binaire exécutable.

MongoDB en scale-up : comment sortir d’un enfer monolithique par Alexis Chotard et Caroline Becker

Ce talk, c'est l'histoire d'une scale-up spécialisée dans la gestion de fiches de paie : PayFit. Le 15 mars 2023, leur cluster MongoDB s'écroule, alors qu'il contient 95% des données utilisateur et il est vital au fonctionnement de l'application.

A travers cette conférence, on découvre comment de mauvais choix d'architecture ou une croissance organique et (trop) rapide ont pu mener à une situation aussi critique. Heureusement, Alexis et Caroline nous expliquent également comment ils ont réussi à réparer leur application, entre stabilisation technique, détricotage du modèle de données, ou encore élimination de single point of failure.

Si on ne doit retenir qu'une chose de ce retour d'expérience, c'est qu'un modèle de donnée doit coller au métier et que la duplication doit être maitrisée. Ici, le principal problème était lié à des données redondantes et stockées en grande quantité, qui ont fini par saturer la base NoSQL...

RetEx : Optimisation du temps de démarrage d'une application Java Spring par Daria Hervieux

Daria Hervieux nous explique comment elle et son équipe ont étudié plusieurs manières de réduire le temps de démarrage d'une application Spring pour atteindre un taux de disponibilité de l'application à 99,9%

Elle nous livre donc les résultats des trois expérimentations effectuées :

Class Data Sharing (CDS) : cette technique permet de réduire le temps de démarrage et l'empreinte mémoire des JVM en mettant en cache les métadonnées de classes dans un fichier d'archive afin qu'elles puissent être rapidement préchargées dans une JVM nouvellement lancée.
Spring Ahead-of-Time (AOT) : sans aller jusqu'à la création d'image native, Daria nous explique qu'ils ont utilisé la technique de compilation AOT qui permet de pré-compiler le bytecode en code natif avant le démarrage de l'application. Le tout, s'exécutant sur une JVM traditionnelle.
CRaC (Coordinated Restore at Checkpoint) : cette technique repose sur le principe d'effectuer un checkpoint de l'état de l'application à un moment donné, puis de le restaurer à partir de ce checkpoint lors du redémarrage de l'application. Cela permettant notamment d'avoir les hotspots de l'application déjà chargés en mémoire.

Daria conclut par un tableau comparatif en termes de gain, inconvénients, taille de livrable... Pas de spoil ! Nous vous laissons découvrir le résultat de son étude dans le replay (quand il sera disponible) !

Git update-refs in a nutshell

Ivan Béthus — Thu, 23 May 2024 17:26:37 +0000

Original article on my blog (🇫🇷)

When working on a versioned project, it is relatively common to end up with a "stack" of branches. What could be more frustrating than having to rebase all the other branches on top of the first one when updating it? This process becomes even more tedious when the number of branches is high or when they are regularly modified.

Git version 2.38¹ introduces a solution to this problem: the update-refs rebase option.

Stack?

Branch stacking is a way to break down important features, allowing for smaller pull requests. In the example below, three branches dependent on each other have been created, allowing "my feature" to be divided into three distinct blocks.

The assumption here is that when each of these branches is individually merged into the main branch, the code will still be functional, as it has been appropriately divided.

Let's say a small typo was made in the commit of the my-feature-v1 branch. A second commit needs to be added to fix the issue, resulting in the following history:

In this situation, the only solution to update my-feature-v2 and my-feature-v3 is to checkout and rebase v2 on v1, then v3 on v2.

This cumbersome process is remedied by the update-refs rebase option.

The solution

update-refs

The goal of this option is to automatically update the n branches on which the branch being rebased depends.

Thus, in our case, we can simply checkout our my-feature-v3 branch and run the command git rebase my-feature-v1 --update-refs. With this option, Git updates not only the v3 branch but also the v2 branch to preserve the history. The result of this operation is as follows:

In practice:

Updating the Remote Repository

Even if the branches being manipulated have already been pushed to the remote repository, it is possible to update all of them in a single command: git push --force-with-lease origin my-feature-v1 my-feature-v2 my-feature-v3

Here, a specific force push is used to preserve the remote history².

Global Activation

Why not always use the update-refs option during a rebase? The Git team asked themselves the same question and decided to include this possibility in the configuration. Thus, git config --global rebase.updateRefs true activates the option globally for each of your rebases.

In Summary

git rebase {my-branch} --update-refs updates a branch and all its dependencies
git push --force-with-lease origin my-branch-1 my-branch-2 my-branch-n pushes the update of these branches to the remote repository

Happy rebasing!

The release note is available here ↩
See the use case ↩