koog

What this skill does

# 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.).

```kotlin
// 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:

```kotlin
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:

```kotlin
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:

```kotlin
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

| Type | Strategy | Use case |
|------|----------|----------|
| `GraphAIAgent<I, O>` | `AIAgentGraphStrategy` | Custom strategy graphs (most common) |
| `FunctionalAIAgent<I, O>` | `AIAgentFunctionalStrategy` | Simple functional agents |
| `PlannerAIAgent<I, O>` | `AIAgentPlannerStrategy` (GOAP) | Goal-oriented planning |

### Java Builder API

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

## Annotation-Based Tools

```kotlin
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"
    }
}
```

Regi