Skip to content

CHANGELOG.md

Latest commit

 

History

History
981 lines (779 loc) · 81.5 KB

CHANGELOG.md

File metadata and controls

981 lines (779 loc) · 81.5 KB
Raw

1.0.0

Published 21 May 2026

This is the first stable release of Koog. The 1.0 line establishes a long-term-supported surface across the framework: modules are split into stable and beta streams so production code can pin to APIs that won't break without a deprecation cycle, every previously deprecated API has been removed, and the graph DSL's node names are finalized. Alongside that, 1.0 lands a redesigned Java interop layer, decouples HTTP transport from Ktor, brings OpenTelemetry to Kotlin Multiplatform, and adds Anthropic prompt caching.

Major Features

Stable / Beta module split

  • Modules now ship under two streams — stable and beta — so production code can pin to APIs that won't break without a deprecation cycle (#2011, #2000).
  • All previously @Deprecated APIs have been removed across event handlers, pipeline, agent/strategy/DSL, tools, persistence, executors, MCP, models, Spring autoconfig, and RAG utilities. The 1.0 line carries no deprecated surface (#2001).

Java interop, redesigned

  • Uniform blocking API: All Java-facing entry points follow one pattern — xxxBlocking in Kotlin, plain xxx from Java. Explicit ExecutorService / Executor parameters are gone; the agent's configured dispatcher is used instead (#2005).
  • Deadlock-free reentrant calls: Kotlin → Java → Kotlin call chains on a single-threaded executor no longer deadlock — the reentrant dispatch is detected and skipped (#1945, KG-750).

Graph DSL, finalized

  • The String-input nodes (nodeLLMRequest, nodeLLMRequestOnlyCallingTools, nodeLLMRequestWithoutTools, nodeLLMRequestForceOneTool, nodeLLMRequestMultipleChoices, nodeLLMRequestStreaming, nodeLLMRequestStructured) keep their original names; the Message.User-input variants now use a nodeLLMSendMessage* prefix.
  • nodeExecuteTools returns ReceivedToolResults directly — connect it to nodeLLMSendMessage / nodeLLMSendToolResults* instead of relying on the old auto-writeback behavior.
  • New nodeLLMModerateText(name, moderatingModel, includeCurrentPrompt) accepts plain String input alongside the existing nodeLLMModerateMessage(Message.User) (#2035).

Memory and persistence

  • AIAgentStorage in checkpoints: Custom key-value data is now saved and restored alongside agent checkpoints; a new runFromCheckpoint API restores execution without requiring the Persistence feature (#1998, #1828).
  • Persistence for planner agents: Planner-based agents now support checkpoint/restore (#1786, KG-673).
  • Amazon Bedrock AgentCore as LongTermMemory: Managed vector-memory backend on Bedrock (#1855, KG-603).
  • LongTermMemory reliability: Storage errors no longer silently swallowed — new FailurePolicy plus a fix for double-ingestion during active sessions. Feature promoted from experimental (#1963).

HTTP transport, decoupled from Ktor

  • Pluggable HTTP factory: LLM clients now take a KoogHttpClient.Factory instead of a Ktor HttpClient. A Ktor-backed default is auto-discovered on JVM/Android; users can plug in Java's HTTP client, OkHttp, or Spring's RestClient without touching Koog internals (#2006, #1948, KG-821, KG-818).
  • Ollama on KoogHttpClient: Ollama now routes streaming, headers, and endpoint config through the same abstraction as every other provider (#1993, KG-833).

OpenTelemetry on every target

  • Multiplatform OpenTelemetry: Langfuse, Weave, and DataDog now run on every Koog target via a Ktor-based OTLP/JSON exporter, not just JVM (#1942, KG-785). Please note: the WasmJS target is not included for now (please see KG-846 for more details).
  • Built-in metrics: Agents emit standard gen_ai.client.token.usage, gen_ai.client.operation.duration, and a custom gen_ai.client.tool.count metric — plug straight into existing Prometheus/Grafana stacks (#1381, KG-136).

Anthropic prompt caching

  • Automatic and explicit cache control: End-to-end caching support — automatic on requests, explicit breakpoints on messages, cache tokens in usage metrics. Cuts cost and latency for agents that re-send long system prompts (#1812, KG-707).

New providers

  • LiteRT LLM client: New client for running Google's LiteRT models locally (#1980).
  • Oracle Database ChatHistoryProvider for Oracle-standardized deployments (#1851, KG-772).

Improvements

  • New models: Anthropic Opus 4.7 (#1861), OpenAI GPT-5.5 and GPT-5.5 Pro (#1913), DeepSeek V4 Flash and Pro (#1914), additional Bedrock models — Kimi K 2.5, MiniMax 2.5, Gemma 3, GPT OSS (#1902), and Ollama gpt-oss / qwen3.5 (#1292).
  • ToolCallMetadata side channel: Tools can now receive per-call context (trace IDs, correlation IDs, feature flags, the live AIAgentContext) without polluting their LLM-visible argument schema. Features can contribute metadata via AIAgentPipeline.provideToolCallMetadata, with caller-supplied values winning on key collision (#1886, #1777).
  • Planners moved to a dedicated module: GOAPPlanner and SimpleLLMPlanner now live in a separate agents:agents-planners module, and a simpler AIAgentPlannerStrategy.create(name, planner) factory replaces the old builder. Agents that don't use planning no longer pay the dependency cost (#1997).
  • MCP SDK upgrade with Streamable HTTP: MCP kotlin-sdk upgraded from 0.8.1 to 0.11.1; Streamable HTTP is now the primary transport for both MCP client and server (#1870, KG-792, KG-756, KG-755, KG-49).
  • RetrieveFactsFromHistory extracted from AgentMemory: This HistoryCompressionStrategy now lives outside the AgentMemory feature so it can be used independently. The old AgentMemory feature is removed in favor of the more capable LongTermMemory (#1927).
  • OpenTelemetry GenAI semantic conventions update: Aligned with the latest spec — content is carried via gen_ai.input.messages / gen_ai.output.messages attributes instead of deprecated per-message events; moderation results moved to a Koog custom attribute koog.moderation.result (#1967, KG-826).
  • KoogClock migration: Internal time APIs now use a KoogClock abstraction instead of kotlin.time.Clock, enabling virtual-time testing and consistent clock behavior across platforms (#1925).
  • Minimum Java version raised to 17: Aligns the runtime requirement with documentation and modern toolchain expectations (#1931).
  • Factory functions replace invoke constructors: AIAgent, AIAgentService, ToolRegistry, RollbackToolRegistry, and AIAgentPlannerStrategy now use top-level factory functions. Usage syntax (A(...)) is unchanged for normal callers (#1882).
  • Agent pipeline cleanup: Pipeline event contexts now expose the AIAgent instance directly instead of separate agentId / config fields; parameter order is harmonized across pipeline interfaces (#1991, KG-807).

Bug Fixes

Highlights below — see the 1.0.0-preview entry for the full per-PR list.

  • Streaming hardening across providers (#1844, #1775, #1887, #1237, #1888, KG-811, #1884, #1878, #2012, #1978, #1868, #1865, #1866, #1369, KG-626): Ollama (Flow invariant is violated from cross-dispatcher emission, text/plain JSON responses, tool-call-before-text ordering), OpenAI (additional_properties leak under JsonNamingStrategy.SnakeCase, decode failures wrapped in LLMClientException, keepalive frames honored), Google (reasoning vs. plain text in streaming), and OpenRouter (tool calls during streaming) all now behave consistently end-to-end.
  • Error propagation through the pipeline (#1918, KG-815, #1548, KG-704, #2037, KG-845, #2024, KG-844): Pipeline failure hooks now receive the original Throwable instead of a stringified AIAgentError — fixes a latent error.type mislabel in OpenTelemetry spans, and reflective tool failures surface the real exception message instead of "Unknown error". LLMCallFailedContext.eventType now reports LLMCallFailed (was LLMCallStarting); LLMCallFailedEvent / LLMStreaming / SubgraphExecution are registered for remote event serialization.
  • OpenTelemetry stability (#1435, KG-675, #1969, KG-808, #1547, KG-703, #1856, #1850): Failed LLM requests no longer crash the feature — failures are signaled via span ERROR status and error.type. SpanAdapter.onBeforeSpanFinished now runs on fully populated spans, so Langfuse and Weave adapters see the same data the SDK exports. Langfuse trace-level attributes (langfuse.environment, etc.) are set on every span, not just invoke_agent. The hardcoded JVM shutdown hook is gone — opt in via setShutdownOnAgentClose (default false).
  • Persistence & subgraph correctness (#2044, #1971, #2039): Persistence.runFromCheckpoint skips tools that are no longer registered instead of throwing. subgraphWithTask / subtask no longer drop tool results when the finish tool is called alongside other tools. PromptAugmenter implementations (SystemPromptAugmenter, UserPromptAugmenter, AgentcorePromptAugmenter) append a new MessagePart to the existing Message after the Message / MessagePart refactor.
  • Tool / concurrency / security (#1883, #1881, #1871, #1965): @Tool(customName = ...) is honored in ToolSet.asTools(). withPrompt uses a write lock (was read lock — could race with concurrent prompt mutations). Anthropic API key is masked in Spring Boot autoconfiguration logs (security fix).

Breaking Changes

The 1.0 release is the stable baseline. Highlights below — for the full per-API list (constructor signatures, parameter renames, removed members), see the 1.0.0-preview entry.

  • All @Deprecated APIs removed (#2001): no deprecated members survive into 1.0. Includes a typo-spelling fix Persistency* → Persistence* across the storage providers (update imports). Old AIAgentPipeline / AIAgentPipelineImpl are gone — use AIAgentPipelineAPI / AIAgentGraphPipeline / AIAgentPlannerPipeline. Retired models: AnthropicModels.Haiku_3, BedrockModels.AnthropicClaude3Haiku, and deprecated Google / DeepSeek entries. Companion invoke constructors for AIAgent, AIAgentService, ToolRegistry, RollbackToolRegistry, AIAgentPlannerStrategy are also gone (#1882) — normal A(...) syntax is unchanged.
  • Graph DSL node renames (#2035): String-input nodes are nodeLLMRequest* / nodeLLMModerate*; Message.User-input variants are nodeLLMSendMessage* / nodeLLMSendToolResults*. nodeExecuteTools now returns ReceivedToolResults directly (previously nodeExecuteToolsAndGetResults); the old auto-writeback nodeExecuteTools is removed.
  • Java blocking API redesign (#2005): uniform xxxBlocking in Kotlin, plain xxx from Java via @JvmName, so most Java source code requires no changes. ExecutorService / Executor parameters are removed from blocking wrappers — the agent's own dispatcher is used instead (also drops SubtaskBuilder.withExecutorService() and the executorService property). Renames cover AIAgent.javaNonSuspendRun → runBlocking, FeatureMessageProcessor.javaNonSuspend* → *Blocking, AIAgentService / PromptExecutor / LLMClient Java overloads → *Blocking, NonSuspendAIAgentStrategy → AIAgentStrategyBlocking, NonSuspendAIAgentFunctionalStrategy → AIAgentFunctionalStrategyBlocking.
  • HTTP transport decoupled from Ktor (#2006): LLM client constructors and PromptExecutor.builder().{openAI, anthropic, google, deepseek, mistral, ollama, openRouter, dashscope}(...) no longer accept a Ktor HttpClient — pass a KoogHttpClient.Factory instead, or omit for the auto-discovered default. prompt-executor-llms-all no longer leaks Ktor types transitively (depend on http-client-ktor directly if you used KtorKoogHttpClient). Java synthetic class SimplePromptExecutorsKt is renamed to SimplePromptExecutors. KoogHttpClient implementations must implement the new lines() method for non-SSE line streaming and accept per-request headers parameters (#1993, KG-833); OllamaClient.baseUrl property removed — endpoint configuration is delegated to the supplied KoogHttpClient.
  • OpenTelemetry Multiplatform migration (#1942, KG-785, #1967, KG-826): addSpanExporter, addMetricExporter, addMetricFilter are now JVM-only extensions on OpenTelemetryConfigJvm (JVM users must update imports). addResourceAttributes signature changes from io.opentelemetry.api.common.Attributes to Map<String, Any>. The SpanEndStatus wrapper is removed — use StatusData directly. The ai.koog.agents.features.opentelemetry.event package and all event APIs on GenAIAgentSpan (events, addEvent, addEvents, removeEvent) are removed; the gen_ai.system attribute and moderation.result span event are no longer emitted.
  • Planners moved to a new module (#1997): GOAP and LLM-based planner usage requires an explicit agents:agents-planners dependency. AIAgentPlanner and JavaAIAgentPlanner gain two abstract methods (initializeState, provideOutput); AIAgentPlannerStrategy.builder() / .goap() are removed in favor of AIAgentPlannerStrategy(name, planner) / .create(name, planner).
  • Memory & persistence API changes: AgentMemory feature removed — use LongTermMemory instead; RetrieveFactsFromHistory moved out of agents-features-memory (#1927). LongTermMemory renames: QueryExtractor → SearchQueryProvider, ExtractionStrategy → DocumentExtractor, IngestionTiming removed (#1963). AIAgentStorage: AIAgentStorageKey equality is now name-based; no-arg constructor replaced by AIAgentStorage(serializer); toMap() removed (use toSerializedMap() / putAll(other)); runFromCheckpoint's agentInput renamed to input (#1998). AgentCheckpointData fields nodePath, lastInput, lastOutput removed — they now live inside properties: JSONObject (#1786).
  • Prompt class moved out of dsl (#2022): ai.koog.prompt.dsl.Prompt → ai.koog.prompt.Prompt. The prompt { ... } DSL builder stays in ai.koog.prompt.dsl — only the type import changes.
  • KoogClock replaces kotlin.time.Clock (#1925) in all APIs that previously took a Clock parameter.
  • Anthropic prompt caching: deprecated user message builders removed to make room for the cacheControl variant (#1812).
  • Minimum Java version: 17 (#1931).
  • Dependency ABI cleanup (#2007): oshai.kotlin.logging no longer in :prompt-executor-clients public API (consumers must add their own implementation(libs.oshai.kotlin.logging)); oshai-logging upgraded 7.0.7 → 8.0.01; ktor.server.sse no longer transitively exposed by :agents-features-tokenizer / :agents-features-trace; android.useAndroidX=true is now required.

1.0.0-preview

Published 15 May 2026

This release marks Koog's transition toward a stable 1.0 API. The library is now split into "stable" and "beta" modules, so production code can pin to APIs that won't break unexpectedly while experimental features continue to evolve. Alongside that, this release lands a redesigned Java interop layer, decouples HTTP transport from Ktor, brings OpenTelemetry to Kotlin Multiplatform, and adds Anthropic prompt caching.

Major Features

Stable / Beta module split

  • Versioning by stability: Modules now ship under two streams — stable (1.0.0-preview) and beta (1.0.0-preview-beta) — so production code can pin to APIs that won't break without a deprecation cycle (#2011, #2000).

Java interop, redesigned

  • Uniform blocking API: All Java-facing entry points now follow one pattern — xxxBlocking in Kotlin, plain xxx from Java. Explicit ExecutorService / Executor parameters are gone; the agent's configured dispatcher is used instead (#2005).
  • Deadlock-free reentrant calls: Kotlin → Java → Kotlin call chains on a single-threaded executor no longer deadlock — the reentrant dispatch is detected and skipped (#1945, KG-750).

HTTP transport, decoupled from Ktor

  • Pluggable HTTP factory: LLM clients now take a KoogHttpClient.Factory instead of a Ktor HttpClient. A Ktor-backed default is auto-discovered on JVM/Android; users can plug in Java's HTTP client, OkHttp, or Spring's RestClient without touching Koog internals (#2006, #1948, KG-821, KG-818).
  • Ollama on KoogHttpClient: Ollama now routes streaming, headers, and endpoint config through the same abstraction as every other provider (#1993, KG-833).

OpenTelemetry on every target

  • Multiplatform OpenTelemetry: Langfuse, Weave, and DataDog now run on every Koog target via a Ktor-based OTLP/JSON exporter, not just JVM (#1942, KG-785).
  • Built-in metrics: Agents emit standard gen_ai.client.token.usage, gen_ai.client.operation.duration, and a custom gen_ai.client.tool.count metric — plug straight into existing Prometheus/Grafana stacks (#1381, KG-136).

Anthropic prompt caching

  • Automatic and explicit cache control: End-to-end caching support — automatic on requests, explicit breakpoints on messages, cache tokens in usage metrics. Cuts cost and latency for agents that re-send long system prompts (#1812, KG-707).

Memory and persistence

  • AIAgentStorage in checkpoints: Custom key-value data is now saved and restored alongside agent checkpoints; a new runFromCheckpoint API restores execution without requiring the Persistence feature (#1998, #1828).
  • Persistence for planner agents: Planner-based agents now support checkpoint/restore (#1786, KG-673).
  • Amazon Bedrock AgentCore as LongTermMemory: Managed vector-memory backend on Bedrock (#1855, KG-603).
  • LongTermMemory reliability: Storage errors no longer silently swallowed — new FailurePolicy plus a fix for double-ingestion during active sessions. Feature promoted from experimental (#1963).

New providers

  • LiteRT LLM client: New client for running Google's LiteRT models locally (#1980).
  • Oracle Database ChatHistoryProvider for Oracle-standardized deployments (#1851, KG-772).

Improvements

  • New models: Anthropic Opus 4.7 (#1861), OpenAI GPT-5.5 and GPT-5.5 Pro (#1913), DeepSeek V4 Flash and Pro (#1914), additional Bedrock models — Kimi K 2.5, MiniMax 2.5, Gemma 3, GPT OSS (#1902), and Ollama gpt-oss / qwen3.5 (#1292).
  • ToolCallMetadata side channel: Tools can now receive per-call context (trace IDs, correlation IDs, feature flags, the live AIAgentContext) without polluting their LLM-visible argument schema. Features can contribute metadata via AIAgentPipeline.provideToolCallMetadata, with caller-supplied values winning on key collision (#1886, #1777).
  • Planners moved to a dedicated module: GOAPPlanner and SimpleLLMPlanner now live in a separate agents:agents-planners module, and a simpler AIAgentPlannerStrategy.create(name, planner) factory replaces the old builder. Agents that don't use planning no longer pay the dependency cost (#1997).
  • MCP SDK upgrade with Streamable HTTP: MCP kotlin-sdk upgraded from 0.8.1 to 0.11.1; Streamable HTTP is now the primary transport for both MCP client and server (#1870, KG-792, KG-756, KG-755, KG-49).
  • RetrieveFactsFromHistory extracted from AgentMemory: This HistoryCompressionStrategy now lives outside the AgentMemory feature so it can be used independently. The old AgentMemory feature is removed in favor of the more capable LongTermMemory (#1927).
  • OpenTelemetry GenAI semantic conventions update: Aligned with the latest spec — content is carried via gen_ai.input.messages / gen_ai.output.messages attributes instead of deprecated per-message events; moderation results moved to a Koog custom attribute koog.moderation.result (#1967, KG-826).
  • KoogClock migration: Internal time APIs now use a KoogClock abstraction instead of kotlin.time.Clock, enabling virtual-time testing and consistent clock behavior across platforms (#1925).
  • Ollama think parameter from prompt params: The think flag is now sourced from prompt.params instead of being hard-coded, so callers can control reasoning behavior per prompt (#1615, #1877, KG-736).
  • SearchRequest interface in LongTermMemory: Replaces the concrete SimilaritySearchRequest so storages can implement keyword, hybrid, or other search types (#1864).
  • Minimum Java version raised to 17: Aligns the runtime requirement with documentation and modern toolchain expectations (#1931).
  • Factory functions replace invoke constructors: AIAgent, AIAgentService, ToolRegistry, RollbackToolRegistry, and AIAgentPlannerStrategy now use top-level factory functions instead of companion-object invoke operators. Usage syntax (A(...)) is unchanged for normal callers; only unusual forms like A.Companion.invoke() are affected (#1882).
  • Agent pipeline cleanup: Pipeline event contexts now expose the AIAgent instance directly instead of separate agentId / config fields, parameter order is harmonized, and KDoc style is unified across pipeline interfaces (#1991, KG-807).
  • Locks and exception utilities consolidated: Duplicate RWLock code moved into a dedicated agents-utils module (#1893, KG-812).

Bug Fixes

  • Spring Boot: Anthropic API key masked in autoconfiguration logs: Previously the key was emitted in plaintext during application startup. Security fix (#1965).
  • Ollama streaming Flow invariant is violated: buildStreamFrameFlow now uses channelFlow so emission works across the dispatched contexts Ktor's streaming HTTP introduces. Most visibly fixes Ollama streaming (#1844, #1775).
  • Ollama: text/plain responses parsed as JSON: Ollama sometimes returns valid JSON with Content-Type: text/plain. The client now registers JSON decoding for that content type too (#1887, #1237).
  • Ollama: tool calls returned before assistant text: When the model emits both a tool call and a text message, the tool call now comes first — matching OpenAI behavior — so built-in strategies don't terminate prematurely (#1888, KG-811).
  • Ollama batch embeddings: Implementation now handles both current and legacy Ollama API response formats (#1885, #1874).
  • Ollama embeddings implementation: Aligned with the official Ollama embeddings API (#1854).
  • OpenAI: additional_properties no longer leaks into requests: AdditionalPropertiesFlatteningSerializer now recognizes both camelCase and snake_case forms, so the additionalProperties map is correctly stripped under JsonNamingStrategy.SnakeCase and no longer trips OpenAI's 400 unknown_parameter error (#1884, #1878).
  • OpenAI: response decoding exceptions wrapped: AbstractOpenAILLMClient now wraps decode failures in LLMClientException instead of letting arbitrary exception types escape (#2012, #1978).
  • OpenAI / Google: keepalive and reasoning handling in streaming responses: OpenAI streaming now honors keepalive events; Google streaming now correctly distinguishes reasoning content from plain text (#1868, #1865, #1866).
  • OpenRouter: streaming with tool calls no longer errors (#1369, KG-626).
  • Streaming: blank tool call IDs processed correctly (#1915, #1900).
  • Streaming: empty text complete frames filtered out (#1924).
  • Reflective tool failures preserve the original exception message: Previously the InvocationTargetException wrapper hid the real error so agents received "Unknown error" — now the underlying cause is surfaced (#1548, KG-704).
  • @Tool(customName = ...) honored in ToolSet.asTools(): Custom tool names declared via the @Tool annotation are now respected when registering via tools(ToolSet) (#1883, #1881).
  • AIAgentError carries a type parameter: Adds the exception type to the error data class so downstream consumers can branch on it (#1917, KG-814).
  • Tool/agent event contexts carry the original Throwable: Pipeline failure hooks (onToolValidationFailed, onToolCallFailed, etc.) now receive a real Throwable instead of a stringified AIAgentError, preserving full exception details and fixing a latent error.type mislabel in OpenTelemetry spans (#1918, KG-815).
  • OpenTelemetry: failed LLM requests no longer crash the feature: Failures are signalled via span ERROR status and error.type attribute instead of the non-spec finish_reasons=[error] (#1435, KG-675).
  • OpenTelemetry: span adapter hooks run on fully populated spans: SpanAdapter.onBeforeSpanFinished now fires after all attributes are set, so Langfuse and Weave adapters see the same data the SDK exports (#1969, KG-808).
  • OpenTelemetry: Langfuse trace attributes set on every span: Previously only invoke_agent carried trace-level attributes, so settings like langfuse.environment were ignored on most spans (#1547, KG-703).
  • OpenTelemetry: Java API for the feature works correctly (#1992, KG-835).
  • OpenTelemetry: configurable shutdown hook: Removed the hardcoded JVM shutdown hook that caused IllegalStateException during graceful drain windows. A new setShutdownOnAgentClose opt-in (default false) replaces the previous always-on behavior (#1856, #1850).
  • subgraphWithTask / subtask: missing tool results when finish tool is called alongside other tools: When the model requests other tools together with the finish tool, results from those tools are now appended to the prompt so the model doesn't see orphan tool calls (#1971).
  • RetryingLLMClient JSON schema generators: The wrapper no longer drops the underlying client's JsonSchemaGenerator implementation on retry (#1781).
  • Tool raw result preserved: Added resultObject to ReceivedToolResult so tools producing structured intermediate results expose them to downstream code (#2004).
  • withPrompt uses a write lock: Previously used a read lock and could race with concurrent prompt mutations (#1871).
  • LiteRT iOS stub + FactRetrieval varargs constructor restored (#2008).
  • Gemini 2.0 Flash and Flash-Lite advertise fullCapabilities: These models support structured output and now declare it (#1191).
  • Llama 3 model IDs on OpenRouter: Corrected the provider prefix from meta to meta-llama so the models actually resolve (#1346).
  • LLAMA4_SCOUT model definition: Fixed LLAMA4_SCOUT which was incorrectly pointing to base LLAMA4 (#1155).

Breaking Changes

This is the 1.0 preview — breaking changes are intentional and grouped here so migration is straightforward.

  • LLM client constructors: The (apiKey, settings, baseClient: HttpClient, ...) constructor is removed from all 8 HTTP-based LLM clients. Use the factory-based constructor or, on JVM, the convenience top-level function. The baseClient: HttpClient parameter is also removed from PromptExecutor.builder().{openAI, anthropic, google, deepseek, mistral, ollama, openRouter, dashscope}(...); pass an optional httpClientFactory: KoogHttpClient.Factory instead, or omit it for the default. The deprecated KoogHttpClient.Companion.fromKtorClient(... baseUrl ...) overload is also removed (#2006).
  • prompt-executor-llms-all consumers: Ktor types no longer leak onto the compile classpath transitively — add an explicit http-client-ktor dependency if you need KtorKoogHttpClient / KtorKoogHttpClient.Factory directly. The Java synthetic class SimplePromptExecutorsKt is renamed to SimplePromptExecutors (update import static lines) (#2006).
  • Java blocking API rename: javaNonSuspendRun → runBlocking on AIAgent; javaNonSuspendInitialize / javaNonSuspendOnMessage → initializeBlocking / onMessageBlocking on FeatureMessageProcessor; all createAgent*, removeAgent*, agentById Java overloads on AIAgentService and all blocking overloads on PromptExecutor / LLMClient renamed to *Blocking; NonSuspendAIAgentStrategy → AIAgentStrategyBlocking (abstract executeStrategy → executeBlocking); NonSuspendAIAgentFunctionalStrategy → AIAgentFunctionalStrategyBlocking. Java callers see the original names via @JvmName, so most Java source code requires no changes (#2005).
  • ExecutorService / Executor parameters removed from blocking wrappers: Each agent's own configured dispatcher is used instead. Also removed: SubtaskBuilder.withExecutorService() and executorService property (#2005).
  • Planners moved to a new module: GOAP and LLM-based planner usage now requires an explicit agents:agents-planners dependency. AIAgentPlanner and JavaAIAgentPlanner gain two abstract methods (initializeState, provideOutput); AIAgentPlannerStrategy.builder() and AIAgentPlannerStrategy.goap() are removed in favor of AIAgentPlannerStrategy(name, planner) / AIAgentPlannerStrategy.create(name, planner) (#1997).
  • AgentMemory feature removed: Use LongTermMemory instead. RetrieveFactsFromHistory moved out of agents-features-memory (#1927).
  • LongTermMemory API renames: IngestionTiming removed; QueryExtractor → SearchQueryProvider; ExtractionStrategy → DocumentExtractor (#1963).
  • AIAgentStorage API changes: AIAgentStorageKey equality is now name-based rather than referential; the no-arg AIAgentStorage() constructor is replaced by AIAgentStorage(serializer); AIAgentStorageAPI.toMap() removed (use toSerializedMap() or putAll(other)); runFromCheckpoint's agentInput parameter renamed to input (#1998).
  • OpenTelemetry Multiplatform migration: addSpanExporter, addMetricExporter, addMetricFilter are now JVM-only extensions on OpenTelemetryConfigJvm — JVM users must update imports. addResourceAttributes signature changes from io.opentelemetry.api.common.Attributes to Map<String, Any>. The SpanEndStatus wrapper is removed — use StatusData directly (#1942, KG-785).
  • OpenTelemetry deprecated events removed: The ai.koog.agents.features.opentelemetry.event package and all event APIs on GenAIAgentSpan (events, addEvent, addEvents, removeEvent) are removed. The gen_ai.system attribute and moderation.result span event are no longer emitted (#1967, KG-826).
  • KoogClock replaces kotlin.time.Clock: All APIs that previously took a Clock parameter are affected (#1925).
  • KoogHttpClient implementations: Must now implement the new lines() method for non-SSE line streaming, and methods accept per-request headers parameters (#1993, KG-833).
  • OllamaClient.baseUrl property removed — endpoint configuration is delegated to the supplied KoogHttpClient (#1993).
  • Anthropic prompt caching: Removed deprecated user message builders to make room for the cacheControl variant (#1812).
  • Companion invoke constructors removed: For AIAgent, AIAgentService, ToolRegistry, RollbackToolRegistry, AIAgentPlannerStrategy. Normal A(...) syntax is unchanged; only unusual forms like A.Companion.invoke() or A.invoke() no longer compile (#1882).
  • Minimum Java version: 17 (#1931).
  • AgentCheckpointData shape: Fields nodePath, lastInput, and lastOutput are removed — they now live in the existing properties: JSONObject (#1786).

Deprecations

  • AIAgentConfig JVM constructors / methods taking ExecutorService — use the more general Executor variants instead (#1945).
  • startSseMcpServer(factory, port, host, tools) and startSseMcpServer(factory, host, tools) — use startMcpServer(factory, tools, port, host) / startMcpServer(factory, tools, host) (#1870).

0.8.0

Published 10 April 2026

Major Features

  • Spring AI Integration: Added comprehensive Spring AI support with ChatMemoryRepository and VectorStore integration for seamless persistence and retrieval (#1719, #1763)
  • Amazon Bedrock AgentCore Memory: Introduced ChatHistoryProvider backed by Amazon Bedrock AgentCore Memory for managed conversation state (#1758)
  • DataDog LLM Observability: Added DataDog LLM Observability exporter with response metadata forwarding to inference spans (#1591)

Improvements

  • Native structured output for Claude 4.5+: Added JSON Schema support for Claude 4.5+ series models across Anthropic, Bedrock, and Vertex AI providers (#1593)
  • Mermaid diagram support for nested subgraphs: Enhanced Mermaid diagram generator to visualize subgraphs and nested subgraphs (#1745)
  • RAG-based abstractions:LongTermMemory feature now uses cleaner abstractions from rag-base for better modularity (#1785)
  • LLMClient constructor decoupling: Decoupled LLMClient constructors from Ktor for improved flexibility (#1742)
  • Customizable field names: Added support for customized field names in AdditionalPropertiesFlatteningSerializer (#1626)
  • GPT-5.4 models: Added support for GPT-5.4Mini and GPT-5.4Nano models (#1837)
  • Google models update: Updated Google models capabilities and deprecated older model versions (#1827)
  • Environment creation abstraction: Extracted environment creation into prepareEnvironment method in agent implementations for better extensibility (#1790)
  • Reasoning prompt refactoring: Moved reasoning prompt configuration to strategy parameters for better encapsulation (#1789)
  • JSON schema capabilities: Added JSON schema capabilities to OpenAI models (#1822)
  • Add missing JavaAPI for history compression inside write session: Added replaceHistoryWithTLDR as non-suspend method of AIAgentWriteSession (#1839)

Bug Fixes

  • Agent message handling: Corrected description of Koog agent message handling (#1010)
  • History compression with chat memory: Fixed missed prompt messages when chat memory feature is enabled (#1835)
  • Reasoning messages: Added IDs for reasoning messages and improved reasoning process to fix status 400 errors from OpenAI (#1779)
  • Ollama embedding: Check HTTP status before deserializing Ollama embedding response to prevent parsing errors (#1702)
  • Ktor parameter shadowing: Renamed registerTools parameter in koog-ktor to avoid Builder.build() shadowing (#1705, #1721)
  • Opus 4.6 token limit: Corrected maxOutputTokens from 1M to 128K for Claude Opus 4.6 (#1825)
  • Java AIAgentLLMWriteSession: Added Java support for AIAgentLLMWriteSession compress history functionality

Breaking Changes

  • LLMProvider singletons restored: Restored LLMProvider singletons and fixed reified type inference (potentially breaking for custom provider implementations) (#1800)

Examples

  • Spring AI Examples Add comprehensive examples of Koog + Spring AI integration

Documentation

  • Java API documentation: Add Java code snippets for Agent Events documentation (#1833)
  • DataDog documentation: add DataDog exporter documentation (#1801)
  • Java API documentation: Add Java code snippets for tracing feature (#1821)
  • Java API documentation: Add missing Java snippets for Persistence (#1818)
  • Java API documentation: Add java snippets for model capabilities docs (#1815)
  • Java API documentation: Add java snippets for content moderation docs (#1814)
  • Java API documentation: Add missing Java snippets for read/write LLM sessions (#1808)
  • Java API documentation: Predefined strategies Java snippets (#1796)
  • Java API documentation: Update streaming docs with Java snippets (#1792)
  • Fixed broken formatting: fix code snippets to remove leaking includes (#1759)
  • Improve wording: Update wording in History compression and Predefined nodes and components (#1699)

0.7.3

Published 26 March 2026

New Features

  • Bedrock prompt caching: Added CacheControl property on Assistant, User, and System messages within the Prompt and integrated explicit cache blocks in the Bedrock Converse API (#1583)

Bug Fixes

  • Agent deadlock fix: Fixed deadlock when agent.run() is called from within executor.submit — when the agent was invoked from a worker thread of the configured ExecutorService, runBlocking(context) would dispatch the coroutine back onto that executor and park the calling thread (KG-750, #1716)
  • AIAgentTool for simple agents: Fixed AIAgentTool to support simple agents that accept primitives as input by introducing AIAgentToolInput wrapper (#1729)
  • MCP custom transport: Fixed runtime crash when using non-default custom MCP transports in MCPToolRegistryProvider (#1740)
  • Anthropic tool error reporting: Added is_error flag for failed tool calls in the Anthropic client so the model is properly informed of tool execution failures (#1700)
  • DeepSeek reasoning with tool calls: Ensured reasoningContent is preserved and merged with tool calls to satisfy DeepSeek API requirements (#1614)

Breaking Changes

  • ToolRegistry.Builder removed: Unified everything under expect/actual ToolRegistryBuilder. Removed tools(Any) overload that was interfering with tools(List) and causing unexpected bugs (#1746)

Build

  • Removed stale coreLibrariesVersion override: The convention plugins were setting coreLibrariesVersion = "2.1.21" which made published POMs declare kotlin-stdlib 2.1.21, mismatching the actual 2.3.x compiler version. Removed the override so the POM picks up the real compiler version (#1697, #1722)

Documentation

  • Updated serialization documentation with Java snippets (#1732)
  • Added Java implementation for custom subgraphs documentation (KG-770, #1730)
  • Added Java implementation for OpenTelemetry, Langfuse, and Weave integration documentation (KG-760, #1696)
  • Moved "Chat agent with memory" tutorial under "Chat memory" feature section (#1686)

0.7.2

Published 19 March 2026

Bug Fixes

  • Java API for OpenTelemetry extensions: Fixed Java API inside OpenTelemetryConfig class annotated with @JavaOverride that relied on Kotlin Duration class, causing all further attributes to be skipped by the compiler in Langfuse and Weave extensions (KG-754, #1682)
  • System prompt preservation in agent builder: Fixed systemPrompt method in agent builders to preserve previously configured messages, id, and params in the prompt (KG-747, #1671)
  • LLMParams copy overloads: Added correct override fun copy() to all LLMParams subclasses (GoogleParams, AnthropicParams, OpenAIChatParams, etc.) so that Prompt.withUpdatedParams preserves provider-specific fields instead of silently dropping them. Also fixed BedrockConverseParams.copy() missing parameters and DashscopeParams incorrect super.copy() call (KG-742, #1668)

Breaking Changes

  • Removed input parameter from AIAgentFunctionalContext.subtask: The input parameter was not actually used; taskDescription is the right way to specify the task. Related methods and builders updated accordingly (#1667)

Documentation

  • Started porting rest of the documentation to Java (#1669)

0.7.1

Published 17 March 2026

Major Features

  • Java API: Introduced comprehensive Java interoperability across the framework:
    • Java API for creating and running agents from pure Java projects (#1185)
    • Builder-based Java API for graph strategies (#1581, #1617, #1366)
    • Java-friendly API for AIAgentStorage with JVM-specific methods (#1600)
    • Blocking API builders for PromptExecutor and LLMClient for Java (#1555, #1604)
    • Jackson as the default serializer for Java API (#1630)
    • Weave and Langfuse integrations now available from Java (#1616)
    • Centralized Java/Kotlin time conversion utilities (TimeUtils, toKotlinDuration, etc.) (#1620)
  • Spring AI Integration: Added two new Spring Boot starters (koog-spring-ai-starter-model-chat and koog-spring-ai-starter-model-embedding) to integrate Spring AI ChatModel and EmbeddingModel implementations as Koog LLM backends, enabling support for the wide range of providers available in Spring AI (KG-109, #1587)
  • Chat Memory: Introduced persistent chat memory with multiple storage backend options:
    • Core ChatMemory feature and ChatHistoryProvider abstraction (#1511)
    • Exposed-ORM based providers for PostgreSQL, MySQL, and H2 (#1584)
    • Pure JDBC ChatHistoryProvider for PostgreSQL, MySQL, and H2 with no ORM dependency (#1597)
    • JDBC-based PersistenceStorageProvider (#1612)
  • Long-term Memory: Added LongTermMemory feature that augments prompts with relevant memory records from storage and extracts/ingests new memories from agent conversations (#1490)
  • Library-Agnostic Serialization API: Introduced a JSONSerializer abstraction to support pluggable serialization libraries. Two implementations provided: KotlinxSerializer (default) and the new JacksonSerializer in a separate serialization-jackson module. Tools API migrated to this new abstraction (#1588)

Improvements

  • OpenTelemetry:
    • Added OpenTelemetry support for functional agent pipelines (KG-677, #1447)
    • Added OpenTelemetry spans for MCP tool calls (#1421)
  • Planner improvements:
    • Added AIAgentPlannerContext and AIAgentFunctionalContextBase for better context hierarchy and planner-specific APIs (#1480)
    • Added planner-specific pipeline interceptors: onPlanCreationStarting/Completed, onStepExecutionStarting/Completed, onPlanCompletionEvaluationStarting/Completed (KG-672, #1550)
    • GOAP strategies now have typed input/output and a dedicated GoapAgentState (#1498)
  • OpenRouter embedding support: Implemented LLMEmbeddingProvider for OpenRouter, enabling access to 21+ embedding models (KG-659, #1398)
  • Swift Package Manager support: Added XCFramework build and distribution infrastructure for iOS/macOS development via SPM (KG-682, #1485)

New LLM Models

  • Anthropic Claude Opus 4.6: Added support via Anthropic and Bedrock executors (#1513)
  • Google Gemini 3 Flash Preview: New model with extended capabilities and high-speed processing (#1621)
  • OpenAI GPT-5.x series: Added GPT-5.1-Codex-Max, GPT-5.2-Codex, GPT-5.3-Codex, GPT-5.4, and GPT-5.4-Pro (#1595)
  • Moonshot Kimi K2 Thinking: Added support via the Bedrock Converse API (#1436)
  • Ollama thinking support: Added think=true request parameter and streaming reasoning delta support for Ollama models (#1532)

Bug Fixes

  • Persistence checkpoints: Fixed last successful node being re-executed when restoring from a checkpoint; changed lastInput to lastOutput in checkpoint structure (#1308)
  • Ollama streaming: Fixed Ollama client to use preparePost(...).execute for proper streaming instead of buffering the full response (#1497)
  • OpenRouter streaming: Fixed missing reasoning and reasoningDetails fields in OpenRouterStreamDelta causing deserialization errors (#1504)
  • Dashscope streaming: Fixed tool call argument merging for streaming responses in DashscopeLLMClient (KG-658, #1590)
  • agents-ext dependency leak: Moved agents-ext from commonMain api to jvmTest implementation in agents-test to prevent transitive compile-time dependency leakage (#1506)
  • Streaming exception handling: executeStreaming now properly propagates exceptions from LLM clients and requires StreamFrame.End to signal stream completion (KG-550, #1580)
  • Debugger feature: Extended to support functional agents in addition to graph-based agents by dispatching appropriate strategy starting events (KG-741, #1637)

Breaking Changes

  • Serialization API: All encode/decode methods in Tool now accept a second JSONSerializer parameter. Automatic ToolDescriptor generation for primitive argument types (Tool<String, String>) is no longer supported without a custom descriptor. AIAgentFeature.createInitialConfig now takes an agentConfig: AIAgentConfig parameter. JSON types in pipeline events changed from kotlinx.serialization to ai.koog.serialization (#1588)
  • TypeToken replaces KType: Nodes and agent features now work with ai.koog.serialization.TypeToken instead of kotlin.reflect.KType. All typeOf<Foo>() usages should be replaced with typeToken<Foo>() (#1581)
  • Global JSON schema registries removed: RegisteredStandardJsonSchemaGenerators and RegisteredBasicJsonSchemaGenerators removed. getStructuredRequest and StructureFixingParser moved to ai.koog.prompt.executor.model package (KG-698, #1517)
  • LLMDescription.description renamed to value: The description field of LLMDescription has been renamed to value for Java compatibility (#1607)
  • Deprecated kotlinx.datetime imports replaced with kotlin.time equivalents (Clock, Instant) (#1533)
  • Retired Anthropic/Bedrock models: Removed Sonnet_3_7, Haiku_3_5, Sonnet_3_5, and Opus_3 from Anthropic models; removed several AI21, Bedrock, and legacy Anthropic models. Haiku_3 marked as deprecated (#1526)

Documentation

  • Added documentation for Java API and Java examples (#1610)
  • Added documentation for Spring AI integration (KG-109, #1627)
  • Added documentation for custom feature creation (#1295)
  • Reworked Getting Started, agent types, and Chat Memory tutorials (#1349, #1552)
  • Improved Prompts and Planner agent documentation (#1302, #1301)
  • Added nightly builds documentation (#1433)

Documentation

  • Added Java code snippets for Agent Events documentation (#1833)
  • Added Java code snippets for tracing feature (#1821)
  • Added Java snippets for Persistence (#1818)
  • Added Java snippets for model capabilities documentation (#1815)
  • Added Java snippets for content moderation documentation (#1814)
  • Added Java snippets for sessions (#1808)
  • Added Java snippets for predefined strategies (#1796)
  • Updated streaming documentation with Java snippets (#1792)
  • Added DataDog exporter documentation (#1801)
  • Restored Koog on Slack page (#1823)
  • Fixed link to Slack channel in documentation (#1816)
  • Updated wording in History compression and Predefined nodes and components documentation (#1699)
  • Added hook to remove blank lines from HTML comments to avoid breaking tab groups (#1760)
  • Fixed code snippets to remove leaking includes (#1759)

Examples

  • Added Spring AI examples (#1799)

Examples

  • Added Java example for JavaOne 2026 (#1641)
  • Added full Spring Boot Java API example (#1350)
  • Added example for calling a Koog agent from JavaScript code, including browser (TypeScript webapp) and Node.js usage with AbortSignal support (#1500)

0.6.4

Published 4 March 2026

Major Features

  • LLM Client Router: Added support for routing requests across multiple LLM clients with pluggable load balancing strategies. Includes a built-in round-robin router and fallback handling when a provider is unavailable (#1503)

Improvements

  • Anthropic models list: Implemented models() for the Anthropic LLM client, consistent with other supported providers (KG-527, #1460)
  • Dependency updates: Updated io.lettuce:lettuce-core from 6.5.5.RELEASE to 7.2.1.RELEASE (#1304)

Breaking Changes

  • OllamaModels relocation: OllamaModels and OllamaEmbeddingModels moved from prompt-llm to prompt-executor-ollama-client module (KG-121, #1470)

0.6.3

Published 24 February 2026

Improvements

  • Streaming reasoning support: Models with reasoning capabilities (like Claude Sonnet 4.5 or GPT-o1) now stream their reasoning process in real-time, allowing you to see how the model thinks through problems as it generates responses (KG-592, #1264)
  • LLModel API enhancement: LLM clients now return List<LLModel> instead of List<String> for improved type safety and direct access to model metadata (#1452)
  • Multiple event handlers per feature: Features can register multiple handlers for the same event type, enabling more flexible event processing (KG-678, #1446)
  • Dependency updates: Updated Kotlin libraries (KG-544, #1475):
    • Kotlin from 2.2.21 to 2.3.10
    • kotlinx-serialization from 1.8.1 to 1.10.0
    • kotlinx-datetime from 0.6.2 to 0.7.1

Bug Fixes

  • OpenRouter streaming: Fixed parsing errors when receiving reasoning content from models with reasoning capabilities by adding missing reasoning and reasoningDetails fields to the streaming response (#854)
  • ReadFileTool: Fixed incorrect binary file detection for empty files (KG-533, #1340)
  • DevstralMedium model: Added missing LLMCapability.Document capability (#1482)
  • Ktor integration: Fixed custom timeout values being ignored when configuring LLM providers in application.yaml (KTOR-8881, #807)

Breaking Changes

  • Streaming API redesign: Restructured StreamFrame types to distinguish between delta frames (incremental content like TextDelta, ReasoningDelta) and complete frames (full content like TextComplete, ReasoningComplete). Added End frame type to signal stream completion (#1264)
  • Kotlin version update: Migrated from Kotlin 2.2.21 to 2.3.10; replaced kotlinx.datetime.Clock/Instant with kotlin.time.Clock/Instant (#1475)
  • LLModel API changes: LLMClient.models() now returns List<LLModel> instead of List<String>; LLModel.capabilities and LLModel.contextLength are now nullable (#1452)

Documentation

  • Updated documentation for the singleRunStrategy API and AIAgentService class.

Refactoring

  • Module restructuring: Moved file-system abstractions (GlobPattern, FileSize, FileSystemEntry, FileSystemEntryBuilders) from agents-ext to rag-base module to reduce transitive dependencies (#1278)

Examples

  • Added the ACP (Agent Communication Protocol) agent example project (#1438)

0.6.2

Published 10 February 2026

Improvements

  • Structured output with examples: Include examples in the prompt with StructuredRequest.Native to help LLMs better understand desired data format (#1328, #1396)

Bug fixes

  • Kotlin/Wasm support: Applied workaround for Kotlin/Wasm compiler bug which produced invalid Wasm files (KT-83728, #1365)

0.6.1

Published 28 January 2026

Major Features

Block of changes:

  • Converse API support in Bedrock LLM client: Added support for the Converse API in the Bedrock LLM client, enabling richer prompt-based interactions (KG-543, #1384)
  • Tool choice heuristics: Introduced heuristic-based required tool selection via LLMBasedToolCallFixProcessor for models that do not support explicit tool choice (KG-200, #1389)

Improvements

  • Prompt parameter preservation: Ensured that LLMParams fields are preserved after calling Prompt.withUpdatedParams (#1194)
  • Error handling for tools: Improved error handling for tool argument parsing, result serialization, and subgraph tool execution failures (KG-597, #1329)
  • OpenTelemetry:
    • Updated span attributes and names to better align with semantic conventions (KG-646, #1351; KG-647, #1359)
    • Replaced agent data propagation through the coroutine context with the AIAgentContext instance for agent events (KG-178, #1336)
  • ACP SDK update: Updated the ACP SDK to version 0.13.1 to enable connections from IntelliJ-based IDE clients (KG-671, #1363)

Bug fixes

  • OpenAI client:
    • Restored the minimal option in ReasonEffort within OpenAIDataModels (#1412)
    • Fixed missing token usage information in streaming mode (#1072, #1404)
  • Bedrock client:
    • Fixed JSON schema generation for Bedrock tools to correctly handle nested objects (#1259, #1361)
    • Fixed parsing of tool usage in Bedrock Anthropic streaming responses (KG-627, #1310)
  • DeepSeek structured output: Fixed structured output handling for DeepSeek (KG-537, #1385)
  • Gemini 3.0 tool calls: Fixed thought signature handling for tool calls (KG-596, #1317)
  • Subtask completion flow: Ensured that subtasks return after a tool call finishes, before issuing a new LLM request (#1322, #1362)

Examples

  • Updated the ACP example to use the latest ACP SDK version (#1363)
  • Updated the Compose Demo App to use the latest Koog version (#1227)

0.6.0

Published 22 December 2025

Major Features

  • ACP Integration: Introduce initial ACP (Agent Communication Protocol) integration to create ACP-compatible agents in Koog (#1253)
  • Planner Agent Type: Introduce new "planner" agent type with iterative planning capabilities. Provide two out-of-the box strategies: simple LLM planner and GOAP (Goal-Oriented Action Planning) (#1232)
  • Response Processor: Introduce ResponseProcessor to fix tool call messages from weak models that fail to properly generate tool calls (KG-212, #871)

Improvements

  • Event ID Propagation: Integrate event ID and execution info propagation across all pipeline events, agent execution flow, and features including Debugger and Tracing (KG-178)
  • Bedrock Enhancements:
    • Add fallback model support and warning mechanism for unsupported Bedrock models with custom families (KG-595, #1224)
    • Add global inference profile prefix support to Bedrock models for improved availability and latency (#1139)
    • Add Bedrock support in Ktor integration for configuring and initializing Bedrock LLM clients (#1141)
    • Improve Bedrock moderation implementation with conditional guardrails API calls (#1105)
  • Ollama: Add support for file attachments in Ollama client (#1221)
  • Tool Schema: Add extension point for custom tool schemas to allow clients to provide custom schemas or modify existing ones (#1158)
  • Google Client:
    • Add support for /models request in Google LLM Client (#1181)
    • Add text embedding support for Google's Gemini models via gemini-embedding-001 (KG-314, #1235)
  • HTTP Client: Make KoogHttpClient auto-closable and add clientName parameter (#1184)
  • Update MCP SDK version to 0.7.7 (#1154)
  • Use SEQUENTIAL mode as default for singleRunStrategy (#1195)

Bug Fixes

  • Streaming: Fix streaming + tool call issues for Google and OpenRouter clients - Google client now passes tools parameter, OpenRouter uses CIO engine for SSE, improved SSE error handling (KG-616, #1262)
  • Tool Calling: Fix requestLLMOnlyCallingTools ignoring tool calls after reasoning messages from models with Chain of Thought (KG-545, #1198)
  • File Tools:
    • Handle empty filters in ListDirectoryTool (KG-628, #1285)
    • Fix directory collapse in ListDirectoryUtil (KG-583, #1260)
    • Clamp endLine to file length and add warnings for overflow in ReadFileTool (KG-534, #1182)
  • Model-Specific Fixes:
    • Pass jsonObject as responseFormat for DeepSeek to fix JSON mode (KG-537, #1258)
    • Remove LLMCapability.Temperature from GPT-5 model capabilities (#1277)
    • Fix OpenAI streaming with tools in Responses API (KG-584, #1255)
    • Fix Bedrock timeout setting propagation to BedrockRuntimeClient.HttpClient (#1190)
    • Add handler for GooglePart.InlineData to support binary content responses (KG-487, #1094)
  • Other Fixes:
    • Fix reasoning message handling in provided simple strategies (#1166)
    • Fix empty list condition check in onMultipleToolResults and onMultipleAssistantMessages (#1192)
    • Fix timeout not respected in executor because join() was called before timeout check (#1005)
    • Fix ContentPartsBuilder to flush whenever textBuilder is not empty (KG-504, #1123)
    • Fix and simplify McpTool to properly support updated Tool serialization (#1128)
    • Fix OpenAIConfig.moderationsPath to be mutable (var instead of val) (#1097)
    • Finalize pipeline feature processors after agent run for StatefulSingleUseAIAgent (KG-576)

Breaking Changes

  • Persistence: Remove requirement for unique graph node names in Persistence feature, migrate to node path usage (#1288)
  • Tool API: Update Tool API to fix name and descriptor discrepancy - moved configurable tool properties to constructors, removed doExecute in favor of execute (KG-508, #1226)
  • OpenAI Models: GPT-5-Codex and GPT-5.1 reasoning models moved from Chat section to Reasoning section (KG-562, #1146)
  • Structured Output: Rename structured output classes - StructuredOutput → StructuredRequest, StructuredData → Structure, JsonStructuredData → JsonStructure (#1107)
  • Module Organization: Move LLMChoice from prompt-llm to prompt-executor-model module (#1109)

0.5.4

Published 03 December 2025

Improvements

  • LLM clients: better error reporting (#1149). Potential breaking change: LLM clients now throw LLMClientException instead of IllegalStateException (KG-552)
  • Add support for OpenAI GPT-5.1 and GPT-5 pro (#1121) and (#1113) and Anthropic Claude Opus 4.5 (#1199)
  • Add Bedrock support in Ktor for configuring and initializing Bedrock LLM clients. (#1141)
  • Improve Bedrock moderation implementation (#1105)
  • Add handler for GooglePart.InlineData in GoogleLLMClient (#1094) (KG-487)
  • Improvements in ReadFileTool (#1182) and (#1213)

Bug Fixes

  • Fix and simplify McpTool to properly support updated Tool serialization (#1128)
  • Fix file tools to properly use newer API to provide textual tool result representation (#1201)
  • Fix empty list condition check in onMultipleToolResults and onMultipleAssistantMessages (#1192)
  • Fix reasoning message handling in strategy (#1166)
  • Fix timeout in JvmShellCommandExecutor (#1005)

0.5.3

Published 12 November 2025

New Features

  • Reasoning messages support (#943)
  • Add get models list request to OpenAI-based LLMClients (#1074)

Improvements

  • Support subgraph execution events in an agent pipeline and features, including OpenTelemetry (#1052)
  • Make systemPrompt and temperature optional, set default temperature to null in AIAgent factory functions (#1078)
  • Improve compatibility with kotlinx-coroutines 1.8 in runtime by removing featurePrepareDispatcher from AIAgentPipeline (#1083)

Bug Fixes

  • Fix persistence feature by making ReceivedToolResult serializable (#1049)
  • Make clients properly rethrow cancellations and remove exception wrapping (#1057)
  • Fix StructureFixingParser to do the right number of retires (#1084)

0.5.2

Published 29 Oct 2025

New Features

  • Add subtask extension for non-graph agents similar to subgraphWithTask (#982)
  • Add MistralAI LLM Client (#622)

Improvements

  • Replace string content and attachments list in messages with a unified content parts list to make the API more flexible and preserve text/attachment parts order (#1004)
  • Add input and output attributes to the NodeExecuteSpan span in OpenTelemetry to improve observability (KG-501)
  • Set the JVM target to 11 to support older JVM versions and explicitly specify the JVM target. (#1015)
  • Support multi-responses from LLM in the subgraphWithTask API (KG-507)
  • Add error handling for missing tools in GenericAgentEnvironment by passing the error message to the agent instead of failing with exception (KG-509)

0.5.1

Published 15 Oct 2025

Improvements

  • Add error handling in LocalFileMemoryProvider (#905)
  • Add GPT-5 Codex model support (#888)
  • Added support for filters in PersistenceProvider (#936)
  • Added DashScope (Qwen) LLM client support (#687)
  • Excluded Ktor engine dependencies (KG-315)
  • Support additional Bedrock auth options (#923)
  • requestLLMStreaming now respect AgentConfig.missingToolsConversionStrategy (#944)

Bug Fixes

  • Make subgraphWithTask work with models without ToolChoice support (KG-440)
  • Fix for KTOR-8881 - Ktor/Koog configuration in application.yaml gives error
  • Fixed the ordering issue for Persistence checkpoints (#964)
  • Fixed issue with the tool name in @Tool annotation - now we take it into account (#930)

Examples

  • Supported Multi-LLM Prompt Executor Spring Bean by adding llmProvider method to LLM clients (#842)

0.5.0

Published 2 Oct 2025

Major Features

  • Full Agent-to-Agent (A2A) Protocol Support:
    • Multiplatform Kotlin A2A SDK: Including server and client with JSON-RPC HTTP support.
    • A2A Agent Feature: seamlessly integrate A2A in your Koog agents
  • Non-Graph API for Strategies: Introduced non-graph API for creating AI Agent strategies as Kotlin extension functions with most of Koog's features supported (#560)
  • Agent Persistence and Checkpointing:
    • Roll back Tool Side-Effects: Add RollbackToolRegistry in the Persistence feature in order to roll back tool calls with side effects when checkpointing.
    • State-Machine Persistence / Message History Switch: Support switching between full state-machine persistence and message history persistence (#856)
  • Tool API Improvements:
    • Make ToolDescriptor auto-generated for class-based tools (#791)
    • Get rid of ToolArgs and ToolResult limitations for Tool<*, *> class (#791)
  • subgraphWithTask Simplification: Get rid of required finishTool and support tools as functions in subgraphWithTask, deduce final step automatically by data class (#791)
  • AIAgentService Introduced: Make AIAgent state-manageable and single-run explicitly, introduce AIAgentService to manage multiple uniform running agents.
  • New components:
    • Add LLM as a Judge component (#866)
    • Tool Calling loop with Structured Output strategy (#829)

Improvements

  • Make Koog-based tools exportable via MCP server (KG-388)
  • Add additionalProperties to LLM clients in order to support custom LLM configurations (#836)
  • Allow adjusting context window sizes for Ollama dynamically (#883)
  • Refactor streaming api to support tool calls (#747)
  • Provide an ability to collect and send a list of nodes and edges out of AIAgentStrategy to the client when running an agent (KG-160)
  • Add excludedProperties to inline createJsonStructure too, update KDocs (#826)
  • Refactor binary attachment handling and introduce Base64 serializer (#838)
  • In JsonStructuredData.defaultJson instance rename class discriminator from #type to kind to align with common practices (#772, KG-384)
  • Make standard json generator default when creating JsonStructuredData (it was basic before) (#772, KG-384)
  • Add default audio configuration and modalities (#817)
  • Add GptAudio model in OpenAI client (#818)
  • Allow re-running of finished agents that have Persistence feature installed (#828, KG-193)
  • Allow ideomatic node transformations with .transform { ...} lambda function (#684)
  • Add ability to filter messages for every agent feature (KG-376)
  • Add support for trace-level attributes in Langfuse integration (#860, KG-427)
  • Keep all system messages when compressing message history of the agent(#857)
  • Add support for Anthropic's Sonnet 4.5 model in Anthropic/Bedrock providers (#885)
  • Refactored LLM client auto-configuration in Spring Boot integration, to modular provider-specific classes with improved validation and security (#886)
  • Add LLM Streaming agent events (KG-148)

Bug Fixes

  • Fix broken Anthropic models support via Amazon Bedrock (#789)
  • Make AIAgentStorageKey in agent storage actually unique by removing data modifier (#825)
  • Fix rerun for agents with Persistence (#828, KG-193)
  • Update mcp version to 0.7.2 with fix for Android target (#835)
  • Do not include an empty system message in Anthropic request (#887, KG-317)
  • Use maxTokens from params in Google models (#734)
  • Fix finishReason nullability (#771)

Deprecations

  • Rename agent interceptors in EventHandler and related feature events (KG-376)
  • Deprecate concurrent unsafe AIAgent.asTool in favor of AIAgentService.createAgentTool (#873)
  • Rename Persistency to Persistence everywhere (#896)
  • Add agentId argument to all Persistence methods instead of persistencyId class field (#904)

Examples

  • Add a basic code-agent example (#808, KG-227)
  • Add iOS and Web targets for demo-compose-app (#779, #780)

0.4.2

Published 15 Sep 2025

Improvements

  • Make agents‑mcp support KMP targets to run across more platforms (#756).
  • Add LLM client retry support to Spring Boot auto‑configuration to improve resilience on transient failures (#748).
  • Add Claude Opus 4.1 model support to Anthropic client to unlock latest reasoning capabilities (#730).
  • Add Gemini 2.5 Flash Lite model support to Google client to enable lower‑latency, cost‑efficient generations (#769).
  • Add Java‑compatible non‑streaming Prompt Executor so Java apps can call Koog without coroutines (KG-312, #715).
  • Support excluding properties in JSON Schema generation to fine‑tune structured outputs (#638).
  • Update AWS SDK to latest compatible version for Bedrock integrations.
  • Introduce Postgres persistence provider to store agent state and artifacts (#705).
  • Update Kotlin to 2.2.10 in dependency configuration for improved performance and language features (#764).
  • Refactor executeStreaming to remove suspend for simpler interop and better call sites (#720).
  • Add Java‑compatible prompt executor (non‑streaming) wiring and polish across modules (KG-312, #715).
  • Decouple FileSystemEntry from FileSystemProvider to simplify testing and enable alternative providers (#664).

Bug Fixes

  • Add missing tool calling support for Bedrock Nova models so agents can invoke functions when using Nova (KG-239).
  • Add Android target support and migrate Android app to Kotlin Multiplatform to widen KMP coverage (KG-315, #728, #767).
  • Add Spring Boot Java example to jump‑start integration (#739).
  • Add Java Spring auto‑config fixes: correct property binding and make Koog starter work out of the box (#698).
  • Fix split package issues in OpenAI LLM clients to avoid classpath/load errors (KG-305, #694).
  • Ensure Anthropic tool schemas include the required "type" field in serialized request bodies to prevent validation errors during tool calling (#582).
  • Fix AbstractOpenAILLMClient to correctly handle plain‑text responses in capabilities flow; add integration tests to prevent regressions (#564).
  • Fix GraalVM native image build failure so projects can compile native binaries again (#774).
  • Fix usages in OpenAI‑based data model to align with recent API changes (#688).
  • Fix SpringBootStarters initialization and improve RetryingClient (#894)

CI and Build

  • Nightly build configuration and dependency submission workflow added (#695, #737).

0.4.1

Published 28 Aug 2025

Bug Fixes

Fixed iOS target publication

0.4.0

Published 27 Aug 2025

Major Features

  • Integration with Observability Tools:
    • Langfuse Integration: Span adapters for Langfuse client, including open telemetry and graph visualisation (KG-217, KG-223)
    • W&B Weave Integration: Span adapters for W&B Weave open telemetry and observability (KG-217, KG-218)
  • Ktor Integration: First-class Ktor support via the "Koog" Ktor plugin to register and run agents in Ktor applications (#422).
  • iOS Target Support: Multiplatform expanded with native iOS targets, enabling agents to run on Apple platforms ( #512).
  • Upgraded Structured Output: Refactored structured output API to be more flexible and add built-in/native provider support for OpenAI and Google, reducing prompt boilerplate and improving validation (#443).
  • GPT5 and Custom LLM Parameters Support: Now GPT5 is available together with custom additional LLM parameters for OpenAI-compatible clients (#631, #517)
  • Resilience and Retries:
    • Retryable LLM Clients: Introduce retry logic for LLM clients with sensible defaults to reduce transient failures (#592)
    • Retry Anything with LLM Feedback: Add a feedback mechanism to the retry component (subgraphWithRetry) to observe and tune behavior (#459).

Improvements

  • OpenTelemetry and Observability:
    • Finish reason and unified attributes for inference/tool/message spans and events; extract event body fields to attributes for better querying (KG-218).
    • Mask sensitive data in events/attributes and introduce a “hidden-by-default” string type to keep secrets safe in logs (KG-259).
    • Include all messages into the inference span and add an index for ChoiceEvent to simplify analysis (KG-172).
    • Add tool arguments to gen_ai.choice and gen_ai.assistant.message events (#462).
    • Allow setting a custom OpenTelemetry SDK instance in Koog (KG-169).
  • LLM and Providers:
    • Support Google’s “thinking” mode in generation config to improve reasoning quality (#414).
    • Add responses API support for OpenAI (#645)
    • AWS Bedrock: support Inference Profiles for simpler, consistent configuration (#506) and accept AWS_SESSION_TOKEN (#456).
    • Add maxTokens as prompt parameters for finer control over generation length (#579).
    • Add contextLength and maxOutputTokens to LLModel ( #438, KG-134)
  • Agent Engine:
    • Add AIAgentPipeline interceptors to uniformly handle node errors; propagate NodeExecutionError across features (KG-170).
    • Include finish node processing in the pipeline to ensure finalizers run reliably (#598).
  • File Tools and RAG:
    • Reworked FileSystemProvider with API cleanups and better ergonomics; moved blocking/suspendable operations to Dispatchers.IO for improved performance and responsiveness (#557, “Move suspendable operations to Dispatchers.IO”).
    • Introduce filterByRoot helpers and allow custom path filters in FilteredFileSystemProvider for safer agent sandboxes (#494, #508).
    • Rename PathFilter to TraversalFilter and make its methods suspendable to support async checks.
    • Rename fromAbsoluteString to fromAbsolutePathString for clarity (#567).
    • Add ReadFileTool for reading local file contents where appropriate (#628).
  • Update kotlin-mcp dependency to v0.6.0 (#523)

Bug Fixes

  • Make parts field nullable in Google responses to handle missing content from Gemini models (#652).
  • Fix enum parsing in MCP when type is not mentioned (#601, KG-49)
  • Fix function calling for gemini-2.5-flash models to correctly route tool invocations (#586).
  • Restore OpenAI responseFormat option support in requests (#643).
  • Correct o4-mini vs gpt-4o-mini model mix-up in configuration (#573).
  • Ensure event body for function calls is valid JSON for telemetry ingestion (KG-268).
  • Fix duplicated tool names resolution in AIAgentSubgraphExt to prevent conflicts (#493).
  • Fix Azure OpenAI client settings to generate valid endpoint URLs (#478).
  • Restore llama3.2:latest as the default for LLAMA_3_2 to match the provider expectations (#522).
  • Update missing Document capabilities for LLModel (#543)
  • Fix Anthropic json schema validation error (#457)

Removals / Breaking Changes

  • Remove Google Gemini 1.5 Flash/Pro variants from the catalog (KG-216, #574).
  • Drop execute extensions for PromptExecutor in favor of the unified API (#591).
  • File system API cleanup: removed deprecated FSProvider interfaces and methods; PathFilter renamed to TraversalFilter with suspendable operations; fromAbsoluteString renamed to fromAbsolutePathString.

Examples

  • Add a web search agent (from Koog live stream 1) showcasing retrieval + summarization (#575).
  • Add a trip planning agent example (from Koog live stream 2) demonstrating tools + planning + composite strategy ( #595).
  • Improve BestJokeAgent sample and fix NumberGuessingAgent example (#503, #445).

0.3.0

Published 15 Jul 2025

Major Features

  • Agent Persistence and Checkpoints: Save and restore agent state to local disk, memory, or easily integrate with any cloud storages or databases. Agents can now roll back to any prior state on demand or automatically restore from the latest checkpoint (#305)
  • Vector Document Storage: Store embeddings and documents in persistent storage for retrieval-augmented generation ( RAG), with in-memory and local file implementations (#272)
  • OpenTelemetry Support: Native integration with OpenTelemetry for unified tracing logs across AI agents (#369, #401, #423, #426)
  • Content Moderation: Built-in support for moderating models, enabling AI agents to automatically review and filter outputs for safety and compliance (#395)
  • Parallel Node Execution: Parallelize different branches of your agent graph with a MapReduce-style API to speed up agent execution or to choose the best of the parallel attempts (#220, #404)
  • Spring Integration: Ready-to-use Spring Boot starter with auto-configured LLM clients and beans (#334)
  • AWS Bedrock Support: Native support for Amazon Bedrock provider covering several crucial models and services ( #285, #419)
  • WebAssembly Support: Full support for compiling AI agents to WebAssembly (WASM) for browser deployment (#349)

Improvements

  • Multimodal Data Support: Seamlessly integrate and reason over diverse data types such as text, images, and audio ( #277)
  • Arbitrary Input/Output Types: More flexibility over how agents receive data and produce responses (#326)
  • Improved History Compression: Enhanced fact-retrieval history compression for better context management (#394, #261)
  • ReAct Strategy: Built-in support for ReAct (Reasoning and Acting) agent strategy, enabling step-by-step reasoning and dynamic action taking (#370)
  • Retry Component: Robust retry mechanism to enhance agent resilience (#371)
  • Multiple Choice LLM Requests: Generate or evaluate responses using structured multiple-choice formats (#260)
  • Azure OpenAI Integration: Support for Azure OpenAI services (#352)
  • Ollama Enhancements: Native image input support for agents running with Ollama-backed models (#250)
  • Customizable LLM in fact search: Support providing custom LLM for fact retrieval in the history (#289)
  • Tool Execution Improvements: Better support for complex parameters in tool execution (#299, #310)
  • Agent Pipeline enhancements: More handlers and context available in AIAgentPipeline (#263)
  • Default support of tools and messages mixture: Simple single run strategies variants for multiple message and parallel tool calls (#344)
  • ResponseMetaInfo Enhancement: Add additionalInfo field to ResponseMetaInfo (#367)
  • Subgraph Customization: Support custom LLModel and LLMParams in subgraphs, make nodeUpdatePrompt a pass-through node (#354)
  • Attachments API simplification: Remove additional content builder from MessageContentBuilder, introduce TextContentBuilderBase (#331)
  • Nullable MCP parameters: Added support for nullable MCP tool parameters (#252)
  • ToolSet API enhancement: Add missing tools(ToolSet) convenience method for ToolRegistry builder (#294)
  • Thinking support in Ollama: Add THINKING capability and it's serialization for Ollama API 0.9 (#248)
  • kotlinx.serialization version update: Update kotlinx-serialization version to 1.8.1
  • Host settings in FeatureMessageRemoteServer: Allow configuring custom host in FeatureMessageRemoteServer (#256)

Bug Fixes

  • Make CachedPromptExecutor and PromptCache timestamp-insensitive to enable correct caching (#402)
  • Fix requestLLMWithoutTools generating tool calls (#325)
  • Fix Ollama function schema generation from ToolDescriptor (#313)
  • Fix OpenAI and OpenRouter clients to produce simple text user message when no attachments are present (#392)
  • Fix intput/output token counts for OpenAILLMClient (#370)
  • Using correct Ollama LLM provider for ollama llama4 model (#314)
  • Fixed an issue where structured data examples were prompted incorrectly (#325)
  • Correct mistaken model IDs in DEFAULT_ANTHROPIC_MODEL_VERSIONS_MAP (#327)
  • Remove possibility of calling tools in structured LLM request (#304)
  • Fix prompt update in subgraphWithTask (#304)
  • Removed suspend modifier from LLMClient.executeStreaming (#240)
  • Fix requestLLMWithoutTools to work properly across all providers (#268)

Examples

  • W&B Weave Tracing example
  • Langfuse Tracing example
  • Moderation example: Moderating iterative joke-generation conversation
  • Parallel Nodes Execution example: Generating jokes using 3 different LLMs in parallel, and choosing the funniest one
  • Snapshot and Persistence example: Taking agent snapshots and restoring its state example

0.2.1

Published 6 Jun 2025

Bug Fixes

  • Support MCP enum arg types and object additionalParameters (#214)
  • Allow appending handlers for the EventHandler feature (#234)
  • Migrating of simple agents to AIAgent constructor, simpleSingleRunAgent deprecation (#222)
  • Fix LLM clients after #195, make LLM request construction again more explicit in LLM clients (#229)

0.2.0

Published 5 Jun 2025

Features

  • Add media types (image/audio/document) support to prompt API and models (#195)
  • Add token count and timestamp support to Message.Response, add Tokenizer and MessageTokenizer feature (#184)
  • Add LLM capability for caching, supported in anthropic mode (#208)
  • Add new LLM configurations for Groq, Meta, and Alibaba (#155)
  • Extend OpenAIClientSettings with chat completions API path and embeddings API path to make it configurable (#182)

Improvements

  • Mark prompt builders with PromptDSL (#200)
  • Make LLM provider not sealed to allow it's extension (#204)
  • Ollama reworked model management API (#161)
  • Unify PromptExecutor and AIAgentPipeline API for LLMCall events (#186)
  • Update Gemini 2.5 Pro capabilities for tool support
  • Add dynamic model discovery and fix tool call IDs for Ollama client (#144)
  • Enhance the Ollama model definitions (#149)
  • Enhance event handlers with more available information (#212)

Bug Fixes

  • Fix LLM requests with disabled tools, fix prompt messages update (#192)
  • Fix structured output JSON descriptions missing after serialization (#191)
  • Fix Ollama not calling tools (#151)
  • Pass format and options parameters in Ollama request DTO (#153)
  • Support for Long, Double, List, and data classes as tool arguments for tools from callable functions (#210)

Examples

  • Add demo Android app to examples (#132)
  • Add example with media types - generating Instagram post description by images (#195)

Removals

  • Remove simpleChatAgent (#127)

0.1.0 (Initial Release)

Published 21 May 2025

The first public release of Koog, a Kotlin-based framework designed to build and run AI agents entirely in idiomatic Kotlin.

Key Features

  • Pure Kotlin implementation: Build AI agents entirely in natural and idiomatic Kotlin
  • MCP integration: Connect to Model Context Protocol for enhanced model management
  • Embedding capabilities: Use vector embeddings for semantic search and knowledge retrieval
  • Custom tool creation: Extend your agents with tools that access external systems and APIs
  • Ready-to-use components: Speed up development with pre-built solutions for common AI engineering challenges
  • Intelligent history compression: Optimize token usage while maintaining conversation context
  • Powerful Streaming API: Process responses in real-time with streaming support and parallel tool calls
  • Persistent agent memory: Enable knowledge retention across sessions and different agents
  • Comprehensive tracing: Debug and monitor agent execution with detailed tracing
  • Flexible graph workflows: Design complex agent behaviors using intuitive graph-based workflows
  • Modular feature system: Customize agent capabilities through a composable architecture
  • Scalable architecture: Handle workloads from simple chatbots to enterprise applications
  • Multiplatform: Run agents on both JVM and JS targets with Kotlin Multiplatform

Supported LLM Providers

  • Google
  • OpenAI
  • Anthropic
  • OpenRouter
  • Ollama

Supported Targets

  • JVM (requires JDK 17 or higher)
  • JavaScript