Koog

Koog AI Agent Framework

Kotlin Multiplatform framework for AI agents. Published on Maven Central under ai.koog group.

Current version: 0.7.3

Dependencies

koog-agents is the umbrella module — it transitively includes all sub-modules (agents-core, agents-ext, all provider clients, tools, prompt DSL, etc.).

// build.gradle.kts — minimal setup (JVM project)
repositories { mavenCentral() }

val koogVersion = "0.7.3"

dependencies {
    implementation("ai.koog:koog-agents:$koogVersion")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1")
}

No need to add individual sub-modules like prompt-executor-openrouter-client — they come via koog-agents.

For Spring Boot, also add: implementation("ai.koog:koog-ktor:$koogVersion")

Import Paths (verified from 0.7.3 JARs)

// Agent
ai.koog.agents.core.agent.AIAgent
ai.koog.agents.core.agent.config.AIAgentConfig
ai.koog.agents.core.agent.GraphAIAgent         // graph-based agent
ai.koog.agents.core.agent.FunctionalAIAgent    // functional agent
ai.koog.agents.planner.PlannerAIAgent           // GOAP planner agent

// Tools
ai.koog.agents.core.tools.ToolRegistry
ai.koog.agents.core.tools.annotations.Tool
ai.koog.agents.core.tools.annotations.LLMDescription
ai.koog.agents.core.tools.reflect.ToolSet       // interface for annotation-based tools
ai.koog.agents.core.tools.reflect.tools          // extension for ToolRegistry DSL

// Strategies (predefined)
ai.koog.agents.ext.agent.chatAgentStrategy       // chat agent with tool loop
ai.koog.agents.ext.agent.reActStrategy           // ReAct pattern
ai.koog.agents.core.agent.singleRunStrategy      // single LLM call + tools
ai.koog.agents.core.agent.ToolCalls              // enum: SEQUENTIAL, PARALLEL, SINGLE_RUN_SEQUENTIAL
ai.koog.agents.ext.agent.singleRunStrategyWithHistoryCompression  // with auto history compression
ai.koog.agents.ext.agent.HistoryCompressionConfig

// GOAP Planner Strategy
ai.koog.agents.planner.AIAgentPlannerStrategy
ai.koog.agents.planner.AIAgentPlannerStrategyBuilder
ai.koog.agents.planner.GOAPStrategyBuilder
ai.koog.agents.planner.goap.GoapAgentState

// Strategy DSL (custom strategies)
ai.koog.agents.core.dsl.builder.strategy
ai.koog.agents.core.dsl.builder.forwardTo
ai.koog.agents.core.dsl.extension.nodeLLMRequest
ai.koog.agents.core.dsl.extension.nodeLLMRequestMultiple      // multiple responses
ai.koog.agents.core.dsl.extension.nodeLLMRequestStreaming      // streaming
ai.koog.agents.core.dsl.extension.nodeExecuteTool
ai.koog.agents.core.dsl.extension.nodeExecuteMultipleTools     // parallel tool execution
ai.koog.agents.core.dsl.extension.nodeLLMSendToolResult
ai.koog.agents.core.dsl.extension.nodeLLMSendMultipleToolResults
ai.koog.agents.core.dsl.extension.nodeSetStructuredOutput
ai.koog.agents.core.dsl.extension.nodeLLMCompressHistory
ai.koog.agents.core.dsl.extension.onAssistantMessage
ai.koog.agents.core.dsl.extension.onMultipleAssistantMessages
ai.koog.agents.core.dsl.extension.onToolCall
ai.koog.agents.core.dsl.extension.onMultipleToolCalls
ai.koog.agents.core.dsl.extension.HistoryCompressionStrategy   // WholeHistory, FromLastNMessages, Chunked, etc.

// Prompt
ai.koog.prompt.dsl.Prompt
ai.koog.prompt.dsl.prompt

// Executor
ai.koog.prompt.executor.llms.SingleLLMPromptExecutor

// Providers — see references/providers.md for full list
ai.koog.prompt.executor.clients.openrouter.OpenRouterLLMClient
ai.koog.prompt.executor.clients.openrouter.OpenRouterModels
ai.koog.prompt.executor.clients.openrouter.OpenRouterParams
ai.koog.prompt.executor.clients.openai.OpenAILLMClient
ai.koog.prompt.executor.clients.openai.OpenAIModels
ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor

// Structured Output — see references/structured-output.md for full reference
ai.koog.prompt.structure.StructuredRequest          // sealed: Manual, Native
ai.koog.prompt.structure.StructuredRequestConfig     // replaces old StructuredOutputConfig
ai.koog.prompt.structure.StructuredResponse
ai.koog.prompt.structure.Structure                   // base interface (was StructuredData)
ai.koog.prompt.structure.json.JsonStructure          // was JsonStructuredData
ai.koog.prompt.executor.model.StructureFixingParser  // MOVED from prompt.structure package
ai.koog.agents.ext.agent.structuredOutputWithToolsStrategy

// Streaming
ai.koog.prompt.streaming.StreamFrame                 // sealed: TextDelta, TextComplete, ReasoningDelta, ReasoningComplete, ToolCallDelta, ToolCallComplete, End

// LLModel (custom model definitions)
ai.koog.prompt.llm.LLModel
ai.koog.prompt.llm.LLMProvider       // subclasses: OpenRouter, OpenAI, Anthropic, Google, etc.
ai.koog.prompt.llm.LLMCapability     // singletons: Completion, Temperature, Tools, Schema.JSON.Basic, etc.

// Response Processing
ai.koog.prompt.processor.ResponseProcessor           // NEW: post-process LLM responses (extract tool calls from text)

// MCP Integration
ai.koog.agents.mcp.McpToolRegistryProvider           // fromClient, fromTransport, fromSseUrl
ai.koog.agents.mcp.metadata.McpServerInfo

AIAgent Constructor

The simplest String→String overload:

AIAgent(
    promptExecutor: PromptExecutor,
    llmModel: LLModel,
    responseProcessor: ResponseProcessor? = null,     // NEW in 0.7.x: post-process LLM responses
    strategy: AIAgentGraphStrategy<String, String> = singleRunStrategy(),
    toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
    id: String? = null,
    systemPrompt: String? = null,                     // CHANGED: now nullable
    temperature: Double? = null,                      // CHANGED: now nullable
    numberOfChoices: Int = 1,
    maxIterations: Int = 50,
    installFeatures: FeatureContext.() -> Unit = {}
): AIAgent<String, String>

AIAgentConfig-based overload:

AIAgent(
    promptExecutor: PromptExecutor,
    agentConfig: AIAgentConfig,
    strategy: AIAgentGraphStrategy<Input, Output>,
    toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
    id: String? = null,
    clock: Clock = Clock.System,
    installFeatures: FeatureContext.() -> Unit = {},
): AIAgent<Input, Output>

AIAgentConfig constructor:

AIAgentConfig(
    prompt: Prompt,
    model: LLModel,
    maxAgentIterations: Int,
    missingToolsConversionStrategy: MissingToolsConversionStrategy = MissingToolsConversionStrategy.Missing(ToolCallDescriber.JSON),
    responseProcessor: ResponseProcessor? = null,
    serializer: JSONSerializer = KotlinxSerializer(),
)

// Convenience factory:
AIAgentConfig.withSystemPrompt(
    prompt = "You are a helpful assistant",
    llm = OpenAIModels.Chat.GPT4o,
    id = "koog-agents",
    maxAgentIterations = 3
)

Agent Types

Java Builder API

AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(executor)
    .systemPrompt("You are a helpful assistant.")
    .llmModel(OpenAIModels.Chat.GPT4o)
    .toolRegistry(toolRegistry)
    .build();

Annotation-Based Tools

import ai.koog.agents.core.tools.annotations.LLMDescription
import ai.koog.agents.core.tools.annotations.Tool
import ai.koog.agents.core.tools.reflect.ToolSet

@LLMDescription("Tools for file operations")
class FileTools : ToolSet {

    @Tool
    @LLMDescription("Read file contents")
    fun readFile(
        @LLMDescription("Path to file") path: String
    ): String {
        return java.io.File(path).readText()
    }

    @Tool
    @LLMDescription("List files in directory")
    fun listFiles(
        @LLMDescription("Directory path") dir: String
    ): String {
        return java.io.File(dir).listFiles()?.joinToString("\n") { it.name } ?: "empty"
    }
}

Register in ToolRegistry:

import ai.koog.agents.core.tools.ToolRegistry
import ai.koog.agents.core.tools.reflect.tools

val toolRegistry = ToolRegistry {
    tools(FileTools())         // register all @Tool methods from ToolSet
    tools(AnotherToolSet())    // can register multiple
}

Predefined Strategies

singleRunStrategy run modes

import ai.koog.agents.core.agent.ToolCalls

singleRunStrategy(ToolCalls.SEQUENTIAL)          // multiple tools per call, executed sequentially (default)
singleRunStrategy(ToolCalls.PARALLEL)             // multiple tools per call, executed in parallel
singleRunStrategy(ToolCalls.SINGLE_RUN_SEQUENTIAL)  // one tool per LLM call

History Compression Strategy

import ai.koog.agents.ext.agent.singleRunStrategyWithHistoryCompression
import ai.koog.agents.ext.agent.HistoryCompressionConfig
import ai.koog.agents.core.dsl.extension.HistoryCompressionStrategy

val strategy = singleRunStrategyWithHistoryCompression(
    config = HistoryCompressionConfig(
        isHistoryTooBig = { prompt -> prompt.messages.size > 50 },
        compressionStrategy = HistoryCompressionStrategy.WholeHistory,
        retrievalModel = null  // uses agent's model by default
    ),
    runMode = ToolCalls.SEQUENTIAL
)

Available compression strategies:

• HistoryCompressionStrategy.NoCompression — no-op
• HistoryCompressionStrategy.WholeHistory — TL;DR of entire history
• HistoryCompressionStrategy.WholeHistoryMultipleSystemMessages — handles multiple system messages
• HistoryCompressionStrategy.FromLastNMessages(n) — keep last N messages, summarize rest
• HistoryCompressionStrategy.FromTimestamp(instant) — keep messages after timestamp
• HistoryCompressionStrategy.Chunked(chunkSize) — chunk and summarize

Complete Example: Agent with OpenRouter

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.tools.ToolRegistry
import ai.koog.agents.core.tools.annotations.LLMDescription
import ai.koog.agents.core.tools.annotations.Tool
import ai.koog.agents.core.tools.reflect.ToolSet
import ai.koog.agents.core.tools.reflect.tools
import ai.koog.agents.ext.agent.chatAgentStrategy
import ai.koog.prompt.executor.clients.openrouter.OpenRouterLLMClient
import ai.koog.prompt.executor.clients.openrouter.OpenRouterModels
import ai.koog.prompt.executor.llms.SingleLLMPromptExecutor
import kotlinx.coroutines.runBlocking

@LLMDescription("Math tools")
class MathTools : ToolSet {
    @Tool
    @LLMDescription("Add two numbers")
    fun add(@LLMDescription("First number") a: Int, @LLMDescription("Second number") b: Int): String {
        return "Result: ${a + b}"
    }
}

fun main() = runBlocking {
    val client = OpenRouterLLMClient(apiKey = System.getenv("OPENROUTER_API_KEY"))
    val executor = SingleLLMPromptExecutor(client)

    val agent = AIAgent(
        promptExecutor = executor,
        llmModel = OpenRouterModels.DeepSeekV30324,
        strategy = chatAgentStrategy(),
        toolRegistry = ToolRegistry { tools(MathTools()) },
        systemPrompt = "You are a helpful assistant. Use tools when needed.",
        temperature = 0.7,
        maxIterations = 10
    )

    val result = agent.run("What is 42 + 58?")
    println(result)
}

Streaming Example

import ai.koog.agents.core.dsl.extension.nodeLLMRequestStreaming
import ai.koog.prompt.streaming.StreamFrame
import kotlinx.coroutines.flow.Flow

val streamingStrategy = strategy<String, Flow<StreamFrame>>("streaming") {
    val nodeStream by nodeLLMRequestStreaming()
    edge(nodeStart forwardTo nodeStream)
    edge(nodeStream forwardTo nodeFinish)
}

// In event handler — capture streaming frames
val agent = AIAgent(
    promptExecutor = executor,
    llmModel = model,
    strategy = chatAgentStrategy(),
    toolRegistry = ToolRegistry.EMPTY,
    systemPrompt = "You are a helpful assistant."
) {
    handleEvents {
        onLLMStreamingFrameReceived { ctx ->
            when (val frame = ctx.streamFrame) {
                is StreamFrame.TextDelta -> print(frame.text)
                is StreamFrame.ReasoningDelta -> { /* reasoning text */ }
                is StreamFrame.ToolCallComplete -> { /* tool call received */ }
                is StreamFrame.End -> println("\n[Done: ${frame.finishReason}]")
                else -> {}
            }
        }
    }
}

Prompt DSL (without agent)

import ai.koog.prompt.dsl.prompt
import ai.koog.prompt.executor.llms.SingleLLMPromptExecutor

val prompt = prompt("my-prompt") {
    system("You are a helpful assistant")
    user("Explain coroutines")
}

// Direct execution without agent
val response = executor.execute(prompt, model)

Structured Output

For full reference, see references/structured-output.md.

Quick Start: StructureFixingParser (standalone, most compatible)

Parse LLM text into typed data class, with auto-fix via a secondary model:

import ai.koog.prompt.executor.model.StructureFixingParser  // NOTE: moved in 0.7.x
import ai.koog.prompt.structure.json.JsonStructure           // NOTE: renamed from JsonStructuredData

// 1. Define structure from @Serializable class
val structure = JsonStructure.create<MyResponse>()
// or explicit:
val structure = JsonStructure.create(
    id = "MyResponse",
    serializer = MyResponse.serializer()
)

// 2. Create fixing parser with a cheap model
val fixingParser = StructureFixingParser(
    fixingModel = myModel,  // any LLModel
    retries = 3
)

// 3. Parse raw text (tries direct parse first, then fixes with LLM)
val result: MyResponse = fixingParser.parse(executor, structure, rawText)

Custom LLModel (models not in predefined catalogs)

import ai.koog.prompt.llm.LLModel
import ai.koog.prompt.llm.LLMProvider
import ai.koog.prompt.llm.LLMCapability

val customModel = LLModel(
    provider = LLMProvider.OpenRouter,       // singleton objects
    id = "z-ai/glm-4.5-air",                // exact model ID from provider
    capabilities = listOf(
        LLMCapability.Completion,            // ALL are singletons — no ()
        LLMCapability.Temperature,
        LLMCapability.Schema.JSON.Basic
    ),
    contextLength = 128_000L,
    maxOutputTokens = 8_000L                 // nullable
)

structuredOutputWithToolsStrategy (native, model-dependent)

Returns typed output directly from agent. Caveat: not all models support this via OpenRouter (DeepSeek breaks tool calling format).

import ai.koog.agents.ext.agent.structuredOutputWithToolsStrategy
import ai.koog.prompt.structure.StructuredRequestConfig       // NOTE: was StructuredOutputConfig
import ai.koog.prompt.structure.StructuredRequest

val config = StructuredRequestConfig<MyResponse>(
    default = StructuredRequest.Manual(structure),     // prompt-based (most compatible)
    byProvider = mapOf(
        LLMProvider.OpenAI to StructuredRequest.Native(structure)  // use native response_format
    )
)

val agent = AIAgent(
    promptExecutor = executor,
    llmModel = OpenRouterModels.GPT4o,
    strategy = structuredOutputWithToolsStrategy(
        config = config,
        fixingParser = fixingParser,      // optional
        parallelTools = false             // parallel tool execution
    ),
    toolRegistry = toolRegistry,
    systemPrompt = "..."
)

val typed: MyResponse = agent.run("input")

Provider Quick Reference

For detailed provider configuration, see references/providers.md.

Note: AbstractOpenAILLMClient is the base for OpenAI, DeepSeek, OpenRouter, MistralAI, DashScope. Anthropic, Google, Ollama implement LLMClient directly. Bedrock uses AWS Converse API (JVM only).

Custom Strategy DSL

For when predefined strategies aren't enough. Full reference: references/strategies.md.

import ai.koog.agents.core.dsl.builder.forwardTo
import ai.koog.agents.core.dsl.builder.strategy
import ai.koog.agents.core.dsl.extension.*

val myStrategy = strategy<String, String>("my-agent") {
    val nodeLLM by nodeLLMRequest()
    val nodeExec by nodeExecuteTool()
    val nodeSend by nodeLLMSendToolResult()

    edge(nodeStart forwardTo nodeLLM)
    edge(nodeLLM forwardTo nodeFinish onAssistantMessage { true })
    edge(nodeLLM forwardTo nodeExec onToolCall { true })
    edge(nodeExec forwardTo nodeSend)
    edge(nodeSend forwardTo nodeFinish onAssistantMessage { true })
    edge(nodeSend forwardTo nodeExec onToolCall { true })
}

Key concepts (details in strategies.md):

• Nodes: nodeLLMRequest, nodeLLMRequestMultiple, nodeLLMRequestStreaming, nodeExecuteTool, nodeExecuteMultipleTools, nodeLLMSendToolResult, nodeLLMSendMultipleToolResults, nodeSetStructuredOutput, nodeLLMCompressHistory, custom node<In, Out>
• Edges: forwardTo + conditions (onAssistantMessage, onMultipleAssistantMessages, onToolCall, onMultipleToolCalls, onCondition) + transformed
• Subgraphs: isolated sections with own tools/model — subgraph, subgraphWithTask, subgraphWithVerification, subgraphWithRetry
• Parallel: parallel(nodeA, nodeB, nodeC) { selectByMax { it } }
• Sequential: nodeStart then subgraphA then subgraphB then nodeFinish
• Structured output: nodeLLMRequestStructured<MyDataClass>(examples = [...]) or nodeLLMRequestStructured(config = structuredRequestConfig)
• Streaming: nodeLLMRequestStreaming() returns Flow<StreamFrame>

GOAP Planner Strategy

Goal-Oriented Action Planning — agent decomposes tasks into action sequences:

import ai.koog.agents.planner.AIAgentPlannerStrategy
import ai.koog.agents.planner.goap.GoapAgentState

abstract class MyState(input: String, output: String?) : GoapAgentState<String, String>(input, output) {
    // define state properties and goals
}

val strategy = AIAgentPlannerStrategy.goap<String, String, MyState>(
    name = "my-goap",
    initializeState = { input -> MyInitialState(input) }
) {
    // define actions and goals
}

val agent = AIAgent(
    promptExecutor = executor,
    llmModel = model,
    strategy = strategy,
    toolRegistry = toolRegistry,
    systemPrompt = "..."
)

Agent Features & Built-in Tools

Features are installed in the AIAgent constructor's trailing lambda. Each has a dedicated reference:

• Structured Output — typed responses via StructuredRequestConfig, StructureFixingParser, JsonStructure, custom LLModel creation, structuredOutputWithToolsStrategy
• EventHandler — lifecycle callbacks (onAgentStarting, onToolCallCompleted, onLLMCallCompleted, streaming events), custom AIAgentFeature with pipeline interceptors
• Memory — store/retrieve facts across conversations (Concept, Fact, MemoryScope, encrypted storage, memory nodes for strategy DSL)
• Tracing & Persistence — trace events to log/file/remote; checkpoint/restore agent state with rollback strategies
• Built-in Tools — AskUser, SayToUser, ExitTool, ReadFileTool, WriteFileTool, EditFileTool, ListDirectoryTool, ExecuteShellCommandTool, SimpleTool class

val agent = AIAgent(...) {
    handleEvents {
        onAgentStarting { ctx -> println("Starting: ${ctx.agent.id}") }
        onToolCallCompleted { ctx -> println("Tool done") }
    }
    install(Tracing) { addMessageProcessor(TraceFeatureMessageLogWriter(logger)) }
    install(AgentMemory) { memoryProvider = LocalFileMemoryProvider(...) }
}

val registry = ToolRegistry {
    tool(AskUser)                                          // ai.koog.agents.ext.tool
    tool(SayToUser)
    tool(ReadFileTool(JVMFileSystemProvider.ReadOnly))      // ai.koog.agents.ext.tool.file
    tool(ExecuteShellCommandTool(BraveModeConfirmationHandler)) // ai.koog.agents.ext.tool.shell
    tools(MyToolSet())
}

MCP Integration

import ai.koog.agents.mcp.McpToolRegistryProvider
import ai.koog.agents.mcp.metadata.McpServerInfo

// From SSE URL (simplest)
val toolRegistry = McpToolRegistryProvider.fromSseUrl("http://localhost:8931/sse")

// From existing MCP client
val toolRegistry = McpToolRegistryProvider.fromClient(
    mcpClient = existingMcpClient,
    serverInfo = McpServerInfo(url = "http://localhost:8931")
)

// From custom transport (stdio, SSE)
val transport = McpToolRegistryProvider.defaultSseTransport("http://localhost:8931/sse")
val toolRegistry = McpToolRegistryProvider.fromTransport(
    transport = transport,
    serverInfo = McpServerInfo(url = "http://localhost:8931")
)

// Use with agent
val agent = AIAgent(
    promptExecutor = executor,
    llmModel = model,
    strategy = singleRunStrategy(),
    toolRegistry = toolRegistry  // MCP tools work like any other tools
)