Skip to content

CHANGELOG.md

Latest commit

 

History

History
790 lines (626 loc) · 50.7 KB

CHANGELOG.md

File metadata and controls

790 lines (626 loc) · 50.7 KB

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