Skip to content
CAI
Software that uses CAICheck a score

JetBrains/koog

68.4

Adequate · 13 November 2026

131.2k

lines of production code

Kotlin

primary language

6

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Features

A2A module documentation and test infrastructure added

The A2A module now includes comprehensive development guidelines in CLAUDE.md and per-module documentation (Module.md) for the client, server, core, transport, and test submodules. Additionally, a new test infrastructure has been introduced: a Python-based A2A test server (test-python-a2a-server) using the a2a-sdk 0.3.22, and a Technology Compatibility Kit (TCK) integration (test-tck) that pins the A2A protocol to version 0.3.x and provides shell scripts to set up, run, and validate the Kotlin SDK against the official A2A specification.

a2a · high confidence

AWS Bedrock client expands model support and adds cache control

The Bedrock client now supports a wider range of model families including Anthropic Claude, Amazon Nova, Meta Llama, and others, with specific data models and request structures for each. It introduces cache control options for Anthropic models with 5-minute and 1-hour TTLs, and adds support for inference profile prefixes to prepend region-specific prefixes to model IDs. New model definitions include Claude Opus 4.6, Opus 4.7, and various Nova and Llama models with their respective capabilities.

prompt-executor-bedrock-client · high confidence

Add ACP agent example project

Introduces a new example project in \examples/acp-agent\ that demonstrates an AI coding agent implementing the Agent Client Protocol (ACP). The example includes a Koog-based agent implementation (\KoogAgentSupport\, \KoogAgentSession\) with file system and terminal tools, a terminal client (\TerminalClientOperations\) for interactive chat, and two runner modes: a standalone agent (\AcpAgent\) and a client-server setup using pipes (\PipeApp\) or external processes (\ProcessApp\).

examples/acp-agent · high confidence

Add AWS Bedrock AgentCore as a Long-Term Memory backend

Introduces a new long-term memory implementation backed by AWS Bedrock AgentCore, enabling agents to store and retrieve semantic, episodic, preference, and summary memory. The change includes \AgentcoreSearchStorage\ for executing similarity and listing searches, an \AgentcorePromptAugmenter\ that injects retrieved context into system or user messages based on strategy type, and an auto-discovery mechanism (\AgentcoreStrategyDiscovery\) that automatically maps configured AgentCore memory strategies to retrieval subrequests, eliminating the need for manual namespace configuration.

agents/agents-features/agents-features-longterm-memory-aws/src/jvmMain/kotlin/ai/koog/agents/features/longtermmemory · high confidence

Add AWS Bedrock AgentCore long-term memory support

This change introduces a new long-term memory backend for AWS Bedrock AgentCore. It adds a search storage implementation that supports semantic similarity, listing, and composite (concurrent multi-strategy) searches, along with a namespace resolver that handles actor- and session-scoped memory paths. An auto-discovery feature allows the system to detect available AgentCore memory strategies and automatically configure retrieval subrequests, with DSL support for per-strategy overrides and exclusions.

agents-features-longterm-memory-aws · high confidence

Add ChatMemory feature for conversation history persistence

A new ChatMemory feature has been added to the agents library, enabling agents to store and load conversation history across multiple sessions. This feature integrates with the agent pipeline to automatically load previous messages before a strategy starts and store the updated conversation history after completion. Users can configure the feature by providing a custom chat history provider and optionally setting a window size to limit the number of stored messages.

agents-features-memory · high confidence

Add Dashscope (Qwen) LLM client support

Users can now interact with Alibaba's Dashscope models (such as Qwen-Flash, Qwen-Plus, and Qwen3 series) through a new client implementation. This update introduces a dedicated parameter class (\DashscopeParams\) supporting provider-specific features like web search, parallel tool calls, and thinking mode, alongside a model enumeration for easy selection. The client uses an OpenAI-compatible API format and includes a JVM-specific factory that automatically resolves the HTTP client, simplifying integration for Java-based projects.

prompt-executor-dashscope-client, prompt/prompt-executor/prompt-executor-clients/prompt-executor-dashscope-client · high confidence

Add DeepSeek LLM client with model listing and reasoning support

Introduces a new DeepSeekLLMClient implementation that enables users to interact with the DeepSeek API. This client supports listing available models via the /models endpoint, handles streaming responses, and specifically preserves reasoning\_content in delta streams when tool calls are present. It also ensures structured output works correctly by appending an explicit JSON response hint when a schema is provided.

prompt-executor-deepseek-client · high confidence

Add JSON-RPC 2.0 message model classes

The \a2a-transport-core-jsonrpc\ module now includes the core data models for the JSON-RPC 2.0 protocol, enabling structured serialization of requests, notifications, success responses, and error responses. This provides the foundational message types required for the A2A transport layer to communicate over JSON-RPC.

a2a-transport-core-jsonrpc · high confidence

Add JVM shell command execution with timeout support

Introduces JvmShellCommandExecutor to enable agents to run shell commands on JVM platforms, supporting both Windows and Unix-like systems. The implementation respects a configurable timeout, forcibly terminating the process and its descendants if execution exceeds the limit, and returns partial output in such cases. It also handles standard output and error streams, combining them into a single result string for easier consumption by the agent.

agents/agents-ext/src/jvmMain · high confidence

Add Jackson-based JSON serialization implementation

The serialization-jackson module now provides a complete Jackson-based implementation of the library's serialization API. This includes the JacksonSerializer class for encoding and decoding objects to and from JSON strings and JSON elements, along with a JacksonModule that handles serialization of the library's core JSON types (JSONElement, JSONObject, JSONArray, JSONPrimitive, etc.). The implementation supports generic type preservation through JavaType resolution and includes comprehensive test coverage for both Kotlin and Java usage scenarios.

serialization/serialization-jackson · high confidence

Add Java and OkHttp implementations for the Koog HTTP client

Users can now choose between Java's standard HttpClient and OkHttp as the underlying transport for the Koog HTTP client, in addition to existing options. This change introduces \JavaKoogHttpClient\ and \OkHttpKoogHttpClient\ modules, both implementing the \KoogHttpClient\ interface to support GET, POST, and Server-Sent Events (SSE) streaming. These implementations provide configurable base URLs, headers, query parameters, and request timeouts, allowing users to select the HTTP engine that best fits their runtime environment or performance requirements.

http-client-java, http-client-okhttp · high confidence

Add Java banking agent example for Spring I/O 2026

A new Java-based example application has been added to the Spring I/O 2026 examples directory, demonstrating an AI banking agent built with Spring Boot. The example includes a REST API endpoint for launching support agents, a service layer that configures an AI agent with tools for reading and writing account data, and data models for transactions and account issues. It integrates with PostgreSQL for persistence and vector storage, and supports multiple LLM providers including OpenAI, Anthropic, and Ollama.

examples/spring-io-2026/java · high confidence

Add JavaScript example demonstrating Koog agent integration in a React web app

This change introduces a new example application located in \examples/koog-js-example/webApp\ that demonstrates how to invoke a Koog agent from JavaScript/TypeScript code. The example includes a React-based web interface featuring a \Greeting\ component that allows users to request jokes, utilizing the \koogelis\ library for agent configuration and execution. It also provides the necessary styling and a logo component to render the user interface.

examples/koog-js-example/webApp, koogelis · high confidence

Add MessageTokenizer feature for configurable message tokenization

The agents-features-tokenizer module now includes a new MessageTokenizer feature that allows users to configure how messages are tokenized within the agent pipeline. This feature supports switching between caching and on-demand tokenization strategies via the MessageTokenizerConfig, enabling optimization of token counting and processing performance. Users can access the configured PromptTokenizer instance through the AIAgentContext.tokenizer() extension function.

agents-features-tokenizer · high confidence

Add Mistral AI LLM client

Users can now interact with Mistral AI models through a new MistralAILLMClient. This client supports chat completions (including streaming), embeddings, and content moderation, and includes a predefined set of Mistral models (such as Mistral Medium 3, Mistral Large, and Codestral) with their specific capabilities and context lengths.

prompt-executor-mistralai-client · high confidence

Add MistralAI LLM client

Introduces a new MistralAI client for the prompt executor, enabling users to interact with Mistral AI models. This includes Mistral-specific parameters (such as topP, stop sequences, penalties, and reasoning mode), request/response models for chat completions and streaming, and a JVM convenience factory that automatically resolves the HTTP client. Comprehensive tests cover parameter validation, serialization, and model listing.

prompt/prompt-executor/prompt-executor-clients/prompt-executor-mistralai-client · high confidence

Add SQL-based chat history persistence with TTL support

This change introduces a new pure JDBC implementation for storing chat conversation history in SQL databases, utilizing the JetBrains Exposed ORM. It provides a generic base provider alongside database-specific implementations for H2, MySQL, and PostgreSQL, each handling their own schema migration (e.g., using native JSON columns in MySQL). The feature supports configurable Time-To-Live (TTL) for automatic expiration of conversation records and exposes a blocking migration helper for Java interoperability.

agents/agents-features/agents-features-chat-memory-sql/src/jvmMain/kotlin/ai/koog/agents/features/chatmemory · high confidence

Add Spring AI VectorStore integration starter

This release introduces a new Spring Boot starter that adapts Spring AI VectorStore implementations to Koog's storage abstractions. Users can now inject a unified KoogVectorStore interface to perform document ingestion, similarity search, and deletion against any Spring AI-compatible backend (such as Pinecone, Qdrant, or PostgreSQL). The integration includes auto-configuration that supports selecting a specific VectorStore bean via the koog.spring.ai.vectorstore.vector-store-bean-name property, restricts document metadata to primitive types (String, Number, Boolean) to match Spring AI constraints, and provides configurable coroutine dispatchers for handling blocking vector-store operations.

koog-spring-ai/koog-spring-ai-starter-vector-store · high confidence

Add Spring AI integration for chat models and chat memory

This release introduces two new Spring Boot starters that bridge Koog agents with Spring AI. The chat model starter (\koog-spring-ai-starter-model-chat\) auto-configures an \LLMClient\ backed by a Spring AI \ChatModel\, supporting multi-model setups via property-based bean selection, auto-detecting LLM providers (e.g., OpenAI, Anthropic), and allowing optional moderation via a \ModerationModel\. It also provides a \ChatOptionsCustomizer\ extension point for provider-specific tuning. The chat memory starter (\koog-spring-ai-starter-chat-memory\) bridges Koog's \ChatHistoryProvider\ with Spring AI's \ChatMemoryRepository\, enabling persistent conversation history. This adapter is text-only: it persists System, User, and Assistant text messages while silently dropping tool calls, reasoning steps, and attachments on store, and skipping Spring AI TOOL messages on load. Both starters are enabled by default and respect \koog.spring.ai.\*.enabled\ configuration properties.

koog-spring-ai/koog-spring-ai-starter-model-chat · high confidence

Add Spring Boot Java example for AI chat integration

Introduces a new Spring Boot Java example that demonstrates integrating the Koog prompt library to send chat messages to OpenAI. The example includes a REST controller at /api/chat, an AI service layer using JavaPromptExecutor with GPT-4o-mini, and configuration for the OpenAI API key via environment variables. It also provides an integration test to verify the chat endpoint functionality.

examples/spring-boot-java · high confidence

Add Spring Boot Kotlin example with YAML-configured Koog agent

A new example project demonstrates how to build a Spring Boot application in Kotlin that integrates with the Koog agent framework. The example uses YAML configuration to define agent properties (model, system prompt, tools) and supports optional S3-based persistence for agent checkpoints. It includes a REST controller for chat interactions, a service layer that constructs and runs the AI agent, and providers for MCP-based tools (via SSE or Docker) and S3 storage.

examples/spring-boot-kotlin · high confidence

Add Spring WebClient HTTP client implementation

The http-client module now includes a new Spring WebClient-based implementation of the KoogHttpClient interface for JVM platforms. This addition allows users to integrate the Koog framework with Spring WebFlux applications by providing a factory and adapter that wraps a configured Spring WebClient, supporting standard HTTP operations (GET, POST) as well as streaming responses (SSE and lines). The implementation includes a ServiceLoader registration for automatic discovery and tests verifying UTF-8 stream decoding and SPI integration.

http-client · high confidence

Add Spring WebClient-based HTTP client implementation

Users can now use Spring WebFlux's WebClient as the underlying transport for the Koog HTTP client. This change introduces the SpringWebClientKoogHttpClient, which implements the standard KoogHttpClient interface to support GET, POST, Server-Sent Events (SSE), and line-based streaming responses. It includes a custom UTF-8 stream decoder to correctly handle multi-byte characters split across network buffers and registers itself via Java ServiceLoader for automatic discovery.

http-client-spring-webclient, http-client/http-client-spring-webclient · high confidence

The step-04 code-agent example now demonstrates a multi-agent workflow where a main programming agent delegates code-search tasks to a specialized 'FindAgent' subagent. The main agent uses tools to read, edit, and execute shell commands, while the new FindAgent tool leverages an internal LLM to intelligently locate code elements (classes, functions, variables) based on semantic queries and file paths, rather than simple text matching. The example also includes updated observability setup using OpenTelemetry and Langfuse for tracing agent interactions.

examples/code-agent/step-04-add-subagent · high confidence

Add code-agent example with shell execution tool

A new example agent in the code-agent step-02 directory now includes a shell execution tool, allowing the AI agent to run commands and verify changes via tests. The agent is configured with file tools (read, write, list) and a shell executor, with optional confirmation handling based on environment variables.

examples/code-agent/step-02-add-execution-tool · high confidence

Add coroutine-safe result handling utility

A new utility function, runCatchingCancellable, has been added to the A2A core module to handle coroutine execution results safely. This function wraps code execution in a Result, ensuring that CancellationException is propagated immediately rather than being caught and wrapped, which prevents unintended suppression of cancellation signals in asynchronous flows.

a2a/a2a-core/src/commonMain/kotlin/ai/koog/a2a/utils · high confidence

Add customer support agent example using Koog AI framework

The spring-ai-kotlin example now includes a new CustomerSupportGraphService that demonstrates building an e-commerce support agent using the Koog AI library. This service implements a graph-based workflow to classify user intents (such as order status, address changes, or refunds) and leverages features like chat memory, long-term vector-based knowledge retrieval, and persistent state recovery with rollback capabilities for tool side effects.

spring-ai-kotlin · high confidence

Add low-level utility classes for byte-array key handling in tokenizer

The prompt-tokenizer module now includes a new \ByteArrayKey\ utility class and associated helper functions (\MutablePair\, \toM\, \toByteArrayKey\) in the \tiktoken/utils.kt\ file. This class provides content-based equality and hashing for byte arrays, enabling their safe use as keys in collections, and supports extracting sub-ranges of bytes. These utilities serve as foundational building blocks for the tokenizer's internal encoding logic.

prompt-tokenizer · high confidence

Add minimal code agent example with GPT-5 Codex and file tools

A new example project has been added at \examples/code-agent/step-01-minimal-agent\ that demonstrates a minimal code agent setup. The example configures an \AIAgent\ using the \GPT5Codex\ model and registers file-based tools (\ListDirectoryTool\, \ReadFileTool\, \EditFileTool\) to allow the agent to interact with the local filesystem. It includes a \main\ entry point that accepts a project path and task description as arguments, runs the agent, and prints the result, while also setting up basic logging via \logback.xml\.

examples/code-agent/step-01-minimal-agent · high confidence

Add structured data models for problem descriptions and solutions

The simple-examples-java module now includes two new Java record classes, ProblemDescription and ProblemSolution, to provide typed context for agent subtasks. ProblemDescription structures the output of the initial problem identification step with title, details, and severity fields, while ProblemSolution defines the structure for the output of the solving subtask with a description field.

simple-examples-java · high confidence

Add trip planning agent example

Introduces a new example application in examples/trip-planning-example that demonstrates an AI agent capable of planning multi-day trips. The example includes a main entry point that configures a multi-LLM executor (OpenAI, Anthropic, Google) and integrates Google Maps via an MCP server, alongside tools for querying weather forecasts from the Open Meteo API and interacting with the user. It showcases agent strategies for clarifying user requirements and suggesting detailed itineraries based on location and weather data.

examples/trip-planning-example · high confidence

Add trip planning agent example with weather integration

Introduces a new trip-planning example agent that allows users to generate and refine travel itineraries. The example includes data structures for defining trip steps (location, dates, description) and handling user feedback on plan suggestions. It integrates a weather tool that fetches daily or hourly forecasts from the Open-Meteo API, enabling the agent to consider weather conditions when planning trips.

trip-planning-example · high confidence

Added A2A message conversion utilities

The agents-features-a2a-core module now provides type converters that bridge between A2A's message format and Koog's internal message representation, enabling seamless communication between A2A-enabled agents and Koog's agent system. This includes bidirectional conversion functions (toKoogMessage and toA2AMessage) that handle text, data, and file attachments, while preserving A2A-specific metadata such as message IDs, context IDs, and task references.

agents/agents-features/agents-features-a2a-core · high confidence

Added Java and OkHttp HTTP client implementations with SPI discovery

This change introduces two new implementations of the Koog HTTP client: one based on the standard Java \java.net.http.HttpClient\ and another using OkHttp. Both modules register their respective factories (\JavaKoogHttpClient.Factory\ and \OkHttpKoogHttpClient.Factory\) via Java Service Provider Interface (SPI) files, allowing them to be automatically discovered by the \ServiceLoader\. The entry includes the SPI configuration files and the corresponding test suites that verify factory instantiation, SPI discovery, and core HTTP operations (GET, POST, SSE) for both client types.

http-client/http-client-java, http-client/http-client-okhttp · high confidence

Added desktop and web entry points for the Koog demo app

The demo application now includes specific entry points for desktop and web platforms. A new desktop main function initializes a Compose window titled "Koog Demo App" with defined dimensions and minimum size constraints, launching the shared KoinApp. For the web platform, a new main function renders the KoinApp within a browser viewport, supported by an HTML template featuring a loading animation and a PWA manifest for standalone display.

examples/demo-compose-app/desktopApp, examples/demo-compose-app/webApp · high confidence

Added internal trace and event string helpers for debugging and logging

A new \messageFormat.kt\ file introduces internal extension properties (\traceString\ for \Prompt\, \Message\, and \MessagePart\, and \eventString\ for \LLModel\) that generate human-readable string representations of agent state. These helpers are designed for debugging and logging, allowing users to easily inspect prompt structures, message contents, and LLM model identifiers in a standardized format.

agents/agents-features/agents-features-event-handler/src/commonMain/kotlin/ai/koog/agents/features/eventHandler · high confidence

Added trace string formatting for Prompt and Message objects

A new \messageFormat.kt\ file has been added to the tracing module, introducing internal \traceString\ extension properties for \Prompt\, \Message\, and \MessagePart\. This change enables the generation of human-readable string representations of these objects, which are primarily intended for debugging and logging purposes within the agent's tracing infrastructure.

agents/agents-features/agents-features-trace/src/commonMain/kotlin/ai/koog/agents/features/tracing · high confidence

Agent checkpointing now supports state rollback and backward-compatible serialization

The snapshot feature now includes a RollbackToolRegistry, allowing agents to undo tool calls with side effects when restoring from checkpoints. The AgentCheckpointData model has been expanded to store LLM model, parameters, tools, and agent iterations, and a custom serializer ensures backward compatibility with older checkpoint formats by migrating legacy fields into the new structure.

agents-features-snapshot · high confidence

Amazon Bedrock AgentCore Memory as Chat History Provider

The AWS chat history module now includes a new \AgentcoreChatHistoryProvider\ that stores and retrieves conversational history (User and Assistant messages) using Amazon Bedrock AgentCore Memory. This implementation persists only plain-text conversational messages, filtering out system, tool, reasoning, and attachment types based on the \ignoreUnsupportedValues\ setting. It uses delta tracking via event IDs to avoid re-saving loaded messages and supports configurable pagination and total event limits when loading history.

agents/agents-features/agents-features-chat-history-aws/src/jvmMain/kotlin/ai/koog/agents/features/chathistory · high confidence

Amazon Bedrock AgentCore Memory as ChatHistoryProvider

Users can now persist conversational history to Amazon Bedrock AgentCore Memory via the new \AgentcoreChatHistoryProvider\. This implementation stores and retrieves only user and assistant messages (filtering out system, tool, or reasoning messages) using the AgentCore \createEvent\ and \listEvents\ APIs. It supports delta tracking to avoid re-saving loaded messages, paginated loading with configurable limits, and handles conversation IDs in the format \actorId\ or \actorId:sessionId\.

agents-features-chat-history-aws · high confidence

Anthropic client adds prompt caching, structured output, and extended parameter support

The Anthropic client now supports automatic prompt caching via the \cacheControl\ parameter (with 5-minute and 1-hour TTL options), enabling lower latency and cost for multi-turn conversations. It also introduces native structured output support for Claude 4.5+ models using JSON Schema, with custom schema generators handling Anthropic-specific requirements like mandatory \required\ lists and \anyOf\ substitution. Additionally, the client exposes extended generation parameters including \topK\, \topP\, \stopSequences\, \container\, \serviceTier\, and MCP server integration, while providing a JVM-specific convenience constructor that auto-resolves the HTTP client factory.

prompt/prompt-executor/prompt-executor-clients/prompt-executor-anthropic-client · high confidence

Anthropic client adds prompt caching, structured output, and model listing support

The Anthropic client now supports prompt caching via \AnthropicCacheControl\ (default 5-minute or 1-hour TTL) on messages and system prompts, enabling lower latency and cost for repeated prefixes. It also introduces native structured output support through \AnthropicOutputConfig\ with JSON Schema constraints, and exposes a \models list\ method via new response models to discover available Claude models. These changes are implemented in the client's request models and serialization definitions.

prompt-executor-anthropic-client · high confidence

Configurable coroutine dispatcher for blocking Spring AI calls

Users can now control how blocking Spring AI operations are executed via a new \DispatcherProperties\ configuration. The system supports an \Auto\ mode that automatically uses Spring's \AsyncTaskExecutor\ (enabling virtual thread support when enabled) or falls back to \Dispatchers.IO\, and an \IO\ mode that allows limiting thread parallelism. This prevents potential thread starvation in environments where the default Spring task executor is bounded, giving users explicit control over concurrency for AI-related blocking calls.

koog-spring-ai-common · high confidence

Demo Compose App now supports Ollama as an LLM provider

The Demo Compose App's Settings screen now includes Ollama as a selectable LLM client alongside OpenAI, Anthropic, and Gemini. Users can choose Ollama in the provider configuration and enter a base URL to connect to a local or remote Ollama instance. The app's dependency injection is updated to instantiate an OllamaClient with the qwen3.5:0.8b model when Ollama is selected, enabling agent demos to run against this local model.

examples/demo-compose-app/commonApp · high confidence

Demo app adds calculator and weather agent tools with unified settings

The demo Compose app now includes a Calculator agent with arithmetic tools (add, subtract, multiply, divide) and a Weather agent that fetches forecasts via the Open Meteo API, along with a new Exit tool to end sessions. The app's settings screen has been updated to support selecting between OpenAI, Anthropic, Gemini, and Ollama providers, with a unified DataStore-based implementation for storing credentials and provider selection across platforms.

commonApp · high confidence

Dynamic context window control and new Ollama model definitions

The Ollama client now supports dynamic adjustment of context window sizes via a new \ContextWindowStrategy\ interface, offering strategies to let the server decide, use a fixed length, or fit the prompt dynamically based on token counts. Additionally, the \OllamaModels\ registry has been expanded with new model definitions, including Meta's Llama 4 (latest and scout variants with 10M context length), Llama 3.2, and Groq-hosted Llama 3 tool-use models.

prompt-executor-ollama-client · high confidence

Enhanced Google client model support for embeddings, reasoning, and structured output

The Google client now supports embedding generation via new request and response data classes, enabling users to create vector embeddings. It also introduces handling for model reasoning interactions by adding a \thoughtSignature\ field to content parts, allowing thoughts to be reused in subsequent requests. Additionally, the client improves structured output handling with a new \GoogleResponseFormat\ utility to manage Google's flat schema types and adds support for file-based data (\FileData\) alongside inline media, expanding the types of content that can be processed.

prompt-executor-google-client · high confidence

Expanded LLM capability model and enhanced LLModel metadata

The LLM capability system has been significantly expanded to include new features such as multiple response choices, audio and document processing, prompt caching, content moderation, and reasoning (thinking) capabilities. Vision support is now granular, distinguishing between image and video processing, while JSON schema support has been restructured into Basic and Standard levels. Additionally, OpenAI-specific endpoints for chat completions and the experimental Responses API are now explicitly defined. The LLModel class has been updated to expose context length and maximum output token limits, and its capabilities list is now optional with a convenience method to check for specific support.

prompt-llm · high confidence

Google client adds thinking mode support and Google-specific schema generation

The Google LLM client now supports Google's "thinking" mode via a new \thinkingConfig\ parameter in \GoogleParams\, allowing users to control whether the model exposes its chain-of-thought reasoning and how many tokens to spend on it. Additionally, the client introduces \GoogleBasicJsonSchemaGenerator\ and \GoogleStandardJsonSchemaGenerator\ to handle Google's specific JSON Schema requirements, such as removing unsupported \additionalProperties\ in simple schemas and wrapping \$ref\ fields in \oneOf\ to work around limitations with co-located description fields. The client also now handles embedding requests and responses via new model classes, and provides a JVM-specific convenience factory that automatically resolves the HTTP client factory.

prompt/prompt-executor/prompt-executor-clients/prompt-executor-google-client · high confidence

Initial ACP integration with message conversion utilities

This change introduces the initial integration with the Agent Client Protocol (ACP) by adding the \MessageConverters.kt\ file. This component provides the specific mapping logic required to translate between Koog's internal message structures (such as \Message.User\, \MessagePart\, and various \AttachmentSource\ types like Audio, Image, File, and Video) and ACP's protocol models (such as \ContentBlock\, \SessionUpdate\, and \EmbeddedResourceResource\). It enables the system to convert incoming ACP prompts into Koog messages and vice versa, handling details like base64 encoding, MIME type parsing, and resource linking, while explicitly noting that video content is not yet supported in ACP content blocks.

agents/agents-features/agents-features-acp/src/jvmMain/kotlin/ai/koog/agents/features/acp · high confidence

Initial public API definitions for OpenTelemetry and Embeddings modules

This change introduces the initial public API contracts for the \agents-features-opentelemetry\ and \embeddings-base\ libraries. For OpenTelemetry, it exposes the \OpenTelemetry\ feature and \OpenTelemetryConfig\ for configuring tracing, including span adapters, exporters, and service metadata, alongside \SpanType\ enums and attribute classes for GenAI telemetry. For Embeddings, it defines the \Embedder\ interface for generating vector embeddings and the \Vector\ class with utility methods for similarity calculations (cosine, dot product, Euclidean distance) and serialization support. These API dumps establish the stable surface area for these modules across JVM, Android, and Kotlin Multiplatform targets.

agents/agents-features/agents-features-opentelemetry/api, embeddings · high confidence

Introduce A2A client agent feature for inter-agent communication

Adds the A2AAgentClient feature, enabling agents to communicate with other A2A-enabled agents. This feature provides a registry of A2A clients accessible within agent strategies, allowing nodes to send messages, retrieve agent cards and capabilities, manage tasks, and subscribe to streaming responses. It includes convenience nodes for common operations like sending messages (with streaming support), getting/caching agent cards, and task management (get, cancel).

agents-features-a2a-client · high confidence

Introduce A2A client foundation with agent card resolution and protocol methods

The A2A client library now provides the core \A2AClient\ class, enabling applications to connect to A2A servers, resolve and cache agent cards (via explicit or URL-based resolvers), and execute protocol operations such as sending messages (including streaming), managing tasks (get, cancel, resubscribe), and configuring push notifications. This change establishes the foundational client-side API for interacting with A2A-compliant agents.

a2a/a2a-client/src/commonMain · high confidence

Introduce A2A server core with session, task, and push notification management

The A2A server module now provides a complete server-side implementation of the A2A protocol, centered on the new \A2AServer\ class which orchestrates request handling, agent execution, and session lifecycle. This release adds a robust session management system via \SessionManager\ and \SessionEventProcessor\ to handle concurrent agent jobs, task persistence through \TaskStorage\ (with an \InMemoryTaskStorage\ implementation), and message history via \MessageStorage\. It also introduces push notification support, allowing clients to receive task updates via \PushNotificationSender\ (including a \SimplePushNotificationSender\ using Ktor). The \AgentExecutor\ interface defines the contract for agent logic, and the server includes built-in concurrency safety using read-write locks and keyed mutexes to prevent race conditions during task and session operations.

a2a/a2a-server/src/commonMain · high confidence

Introduce ACP integration feature

Added the \AcpAgent\ feature to the agents-features-acp module, enabling agents to interact with the Agent Client Protocol (ACP). This new component allows developers to install ACP support into their agents, configure session IDs and protocol instances, and automatically send events and notifications to connected ACP clients, including default handling for agent completion events.

agents-features-acp · high confidence

Introduce AWS Bedrock LLM client with Converse API, model families, and embedding support

The Bedrock LLM client now supports the AWS Bedrock Converse API alongside the legacy InvokeModel method, providing a consistent interface for models that support messages. This update adds serialization and request handling for Amazon Nova, Anthropic Claude, Cohere, and Meta Llama model families, including tool calling and structured output. It also introduces support for Amazon Titan Embedding models (G1 and V2) and Cohere Embed models. Authentication is expanded to support both AWS Credentials and Bearer Token providers, and the client now handles guardrails, caching, and streaming responses for these new capabilities.

prompt/prompt-executor/prompt-executor-clients/prompt-executor-bedrock-client · high confidence

Introduce Agent-to-Agent (A2A) protocol support with client, server, and transport modules

This release adds a complete implementation of the Agent-to-Agent (A2A) protocol, enabling agents to discover, communicate, and exchange tasks with other agents over HTTP. The change introduces a new module structure including \a2a-core\ for data models, \a2a-client\ and \a2a-server\ for the respective endpoints, and \a2a-transport\ for JSON-RPC over HTTP. It also adds \agents-features-a2a-client\ and \agents-features-a2a-server\ to integrate these capabilities into the Koog agent framework, along with a Python test server for integration testing.

(dependencies) · high confidence

Introduce AgentCardResolver for flexible agent card retrieval

The a2a-client module now includes an AgentCardResolver interface and two concrete implementations to handle agent card discovery. Users can choose between ExplicitAgentCardResolver to provide a pre-defined card locally, or UrlAgentCardResolver to automatically fetch the card from a specified base URL and path via HTTP. This change provides a standardized way to resolve agent metadata before initiating interactions.

a2a-client · high confidence

Introduce DeepSeek LLM client with V4 model support

Adds a new DeepSeek LLM client to the prompt executor, enabling integration with DeepSeek's V4 family of models (V4 Flash, V4 Pro, and V4 Flash Vision Exp). The client supports standard chat completion features including tool calling, JSON schema output, and streaming, along with DeepSeek-specific parameters like frequency and presence penalties, logprobs, and topP. It also handles reasoning content in responses, allowing users to access the model's internal thought process alongside tool calls or text output.

prompt/prompt-executor/prompt-executor-clients/prompt-executor-deepseek-client · high confidence

Introduce DocumentWithMetadata model for vector store interactions

The vector store starter now includes a new DocumentWithMetadata class that implements the TextDocument interface, serving as the primary document model for vector store operations. This model restricts metadata values to primitive types (String, Number, Boolean) to align with Spring AI's Document metadata constraints, and provides a Java-friendly Builder pattern for constructing documents with content, metadata, and optional IDs.

koog-spring-ai-starter-vector-store · high confidence

Introduce EventHandler feature for agent lifecycle callbacks

The new EventHandler feature allows users to register callbacks for various events during an agent's execution, including agent lifecycle events (starting, completed, closing), node execution events (starting, completed, failed), subgraph execution events, LLM call events (starting, completed, streaming), and tool call events (starting, validation failed, failed, completed). This enables monitoring and interception of agent behavior at key points in the pipeline.

agents-features-event-handler · high confidence

Introduce HTTP-based JSON-RPC server transport with SSE and CORS support

Added a new \HttpJSONRPCServerTransport\ class that enables A2A agents to communicate over HTTP using JSON-RPC. This transport leverages Ktor to provide a standalone server mode or allows mounting routes into an existing Ktor application. Key features include Server-Sent Events (SSE) for streaming responses, automatic CORS configuration to allow cross-origin requests, and optional serving of the Agent Card at a well-known path. This change provides the underlying network transport layer for A2A server interactions.

a2a/a2a-transport/a2a-transport-server-jsonrpc-http/src/commonMain · high confidence

Introduce JSON-RPC transport layer for A2A client and server communication

This change adds the core implementation for the A2A protocol's JSON-RPC transport mechanism, introducing \JSONRPCClientTransport\ and \JSONRPCServerTransport\ alongside the \A2AMethod\ enum. For users, this enables connecting to and hosting A2A agents using the standard JSON-RPC protocol, supporting both synchronous requests (such as sending messages, retrieving tasks, and managing push notification configurations) and streaming operations (like streaming message responses and task resubscriptions). The implementation handles the serialization of A2A model objects into JSON-RPC requests and responses, including error mapping and version compliance.

a2a/a2a-transport/a2a-transport-core-jsonrpc/src/commonMain/kotlin/ai/koog/a2a/transport/jsonrpc · high confidence

Introduce Ktor integration for Koog AI agents

The new \koog-ktor\ module provides a Ktor server plugin that enables seamless integration of the Koog AI agents framework into Ktor applications. Users can now install the \Koog\ plugin to configure multiple LLM providers (OpenAI, Anthropic, Google, MistralAI, OpenRouter, DeepSeek, Ollama, and AWS Bedrock) via code or YAML/CONF configuration files. The module exposes extension functions like \llm()\ for direct LLM interaction and \aiAgent()\ for creating and running AI agents within Ktor routes, supporting features such as content moderation, custom agent strategies, and JVM-specific Model Context Protocol (MCP) tool integration.

koog-ktor · high confidence

Introduce Ktor-based HTTP client implementation

Added a new \KtorKoogHttpClient\ implementation that wraps the Ktor \HttpClient\ to provide HTTP operations (GET, POST, and SSE streaming) for the \KoogHttpClient\ interface. This allows users to leverage Ktor's underlying engine and plugins for network requests within the Koog framework.

http-client-ktor · high confidence

Introduce Ktor-based MCP server with Streamable HTTP and SSE transports

Users can now start an MCP server using Ktor with support for both Streamable HTTP and SSE transports via the new \startMcpServer\ function, in addition to the existing \startStdioMcpServer\ for stdin/stdout communication. The server automatically registers tools from a \ToolRegistry\ and handles argument decoding and result serialization using a configurable \JSONSerializer\ (defaulting to \KotlinxSerializer\), with built-in error handling for argument parsing failures.

agents/agents-mcp-server/src/commonMain · high confidence

Introduce LLM-based tool call fix processor

The prompt-processor module now includes an LLM-based response processor that iteratively asks the model to correct malformed or incorrectly formatted tool calls. It detects when a tool call is intended but improperly structured, then loops (up to a configurable retry limit) to fix issues such as invalid JSON, wrong tool names, or missing arguments, falling back to a manual regex-based fixer or the original message if corrections fail.

prompt/prompt-processor · high confidence

Introduce LiteRT LLM client for on-device Android inference

Adds a new LiteRT-based LLM client for Android, enabling on-device inference with models like FunctionGemma and Gemma4. The implementation manages long-lived inference sessions to avoid native crashes, supports tool calling with synthetic ID correlation, and handles message conversion between Koog and LiteRT formats.

prompt-executor-litert-client · high confidence

Introduce LiteRT LLMClient for on-device Android inference

Adds a new LiteRT LLMClient for Android that enables on-device inference using the LiteRT runtime. This client supports the FunctionGemma, Gemma4E2B, and Gemma4E4B models, allows configuration of model paths, cache directories, and compute backends (CPU/GPU), and handles tool calling by forwarding tool descriptors to the LiteRT session while executing tool logic within the Koog agent framework. It also includes message conversion utilities to map Koog messages to LiteRT formats and manages session lifecycle with conversation reuse to optimize performance.

prompt/prompt-executor/prompt-executor-clients/prompt-executor-litert-client · high confidence

Introduce LongTermMemory feature for agent context persistence and retrieval

Agents can now maintain persistent memory by ingesting conversation messages into a vector database and retrieving relevant context to augment prompts. This feature allows configuring independent ingestion and retrieval pipelines: ingestion filters specific message roles (defaulting to User and Assistant) and converts them into searchable text documents, while retrieval uses a similarity search strategy to find relevant records and injects them into the system prompt before LLM calls. Users can customize the storage backend, search parameters (such as top-K results and similarity thresholds), and failure handling policies to ensure robust context augmentation.

agents-features-longterm-memory · high confidence

Introduce LongTermMemory feature with configurable retrieval, ingestion, and failure handling

The LongTermMemory feature is now available, enabling agents to persist conversation history to a vector database and retrieve it for retrieval-augmented generation (RAG). Users can configure independent retrieval and ingestion pipelines, including search strategies (defaulting to vector similarity), query providers, and prompt augmenters (injecting context into system or user messages). The feature introduces a FailurePolicy to control error handling: retrieval failures default to failing fast to prevent ungrounded answers, while ingestion failures default to logging and continuing to avoid blocking agent runs. An InMemoryRecordStorage is included for local testing and development.

agents/agents-features/agents-features-longterm-memory/src/commonMain · high confidence

Introduce OpenAI data models for reasoning content and developer messages

Added the \OpenAIDataModels.kt\ file defining the data structures for the OpenAI client base, including support for \reasoningContent\ in assistant messages and the new \developer\ message role (replacing \system\ for o1 models and newer). This establishes the serialization models required to handle these specific API features.

prompt-executor-openai-client-base · high confidence

Introduce OpenAI-compatible client base with provider-specific schema generation

This change introduces the \AbstractOpenAILLMClient\ base class and associated data models for the OpenAI-compatible prompt executor, establishing a unified foundation for OpenAI-like LLM integrations. It includes \OpenAICompatibleToolDescriptorSchemaGenerator\ to convert tool descriptors into OpenAI-specific JSON schemas, alongside \OpenAIBasicJsonSchemaGenerator\ and \OpenAIStandardJsonSchemaGenerator\ to handle parameter serialization with OpenAI-specific constraints (such as handling nullable lists via \anyOf\ and enforcing required property lists). The entry also adds the core data models (\OpenAIMessage\, \OpenAIContentPart\, etc.) and tests to validate the schema generation and tool descriptor conversion logic.

prompt/prompt-executor/prompt-executor-clients/prompt-executor-openai-client-base · high confidence

Introduce Spring AI v2 chat adapter with auto-configuration and provider detection

The \koog-spring-ai-v2-starter-model-chat\ module now provides a complete adapter for Spring AI v2, enabling Koog agents to use any Spring AI chat model (OpenAI, Anthropic, Google, Ollama, etc.) as their LLM backend. The \SpringAiChatAutoConfiguration\ automatically wires a \SpringAiLLMClient\ when a \ChatModel\ is present, supporting both single-candidate auto-detection and explicit bean-name selection via \koog.spring.ai.chat.chat-model-bean-name\. Provider identity is resolved automatically from the model class name or explicitly via \koog.spring.ai.chat.provider\, falling back to a generic \spring-ai\ provider. The adapter includes robust message conversion between Koog and Spring AI types, handles provider-specific streaming differences for tool calls (immediate emission for Anthropic/Google, buffering for OpenAI), and allows runtime customization of Spring AI \ChatOptions\ via the new \ChatOptionsCustomizer\ extension point.

koog-spring-ai-v2/koog-spring-ai-v2-starter-model-chat · high confidence

Introduce Spring Boot auto-configuration for Koog AI agents

The new koog-spring-boot-starter module provides seamless integration between the Koog AI agents framework and Spring Boot applications. It includes auto-configuration for LLM clients (Anthropic, Google, MistralAI, OpenAI, OpenRouter, DeepSeek, Ollama), configuration properties for easy setup through application.properties/yml, conditional bean creation based on configuration presence, and ready-to-use SingleLLMPromptExecutor beans for dependency injection.

koog-spring-boot-starter · high confidence

Introduce Tracing feature for comprehensive agent execution monitoring

The \agents-features-trace\ module now provides a new \Tracing\ feature that captures detailed execution data for debugging, auditing, and performance analysis. This feature intercepts agent lifecycle events (start, complete, fail, close), strategy execution, node visits, LLM calls (including streaming frames), and tool invocations, sending structured events to configurable message processors such as log writers or file writers. Users can install this feature to gain visibility into prompts, responses, tool arguments/results, and graph flow, with optional filtering capabilities to reduce noise.

agents-features-trace · high confidence

Introduce agent state persistence and checkpointing feature

The Snapshot feature now includes a new Persistence capability that allows AI agents to save and restore their execution state. Users can configure automatic checkpointing after each node execution via \PersistenceFeatureConfig.enableAutomaticPersistence\ and provide a custom \PersistenceStorageProvider\ to define where snapshots are stored. The feature supports rolling back to previous checkpoints using a \RollbackToolRegistry\ to handle tools with side-effects, and includes a \RollbackStrategy\ to control whether the full context or just message history is restored. This enables resuming agent execution from specific points, persisting state across sessions, and recovering from failures.

agents/agents-features/agents-features-snapshot/src/commonMain/kotlin/ai/koog/agents/snapshot/feature · high confidence

Introduce explicit model resolution and multi-LLM routing for prompt execution

The PromptExecutor model layer now supports explicit model resolution and load-balanced routing across multiple LLM clients. A new \DynamicPromptExecutor\ base class enforces a single \resolveModel\ step before every operation, allowing custom executors to implement fallback strategies or model substitution. Two concrete executors are provided: \MultiLLMPromptExecutor\ for direct provider-to-client mapping with fallback, and \RoutingLLMPromptExecutor\ which delegates client selection to pluggable routers like the new \RoundRobinRouter\ for even load distribution. The underlying \PromptExecutorAPI\ interface introduces \ResolvedModel\ and \PromptExecutorOperation\ types to distinguish between requested and effective models, and platform-specific \PromptExecutor\ stubs are added for Android and Apple targets.

prompt/prompt-executor/prompt-executor-model · high confidence

Introduce extensible persistence storage providers with filtering support

The snapshot feature now supports pluggable storage backends for agent checkpoints, including an in-memory provider for testing, a file-system provider for persistent storage, and a no-op provider for disabling snapshots. A new \PersistenceStorageProvider\ interface allows implementations to define their own filtering capabilities, enabling users to retrieve or remove checkpoints based on custom predicates (e.g., by node or time). Utility functions for JSON serialization and tombstone handling are also included to support these storage operations.

agents/agents-features/agents-features-snapshot/src/commonMain/kotlin/ai/koog/agents/snapshot/providers · high confidence

Introduce library-agnostic JSON element model and serialization API

The serialization module now provides a library-agnostic representation of JSON data through the new \JSONElement\ sealed interface hierarchy (\JSONObject\, \JSONArray\, \JSONPrimitive\, \JSONLiteral\, \JSONNull\). This allows consumers to manipulate JSON structures without being tied to a specific serialization library. To support this, a new \JSONSerializer\ interface and a concrete \KotlinxSerializer\ implementation have been added, enabling encoding and decoding of both raw JSON elements and typed objects using Kotlinx Serialization under the hood.

serialization-core, serialization/serialization-test · high confidence

Introduce library-agnostic serialization API with Jackson and kotlinx-serialization implementations

The serialization module now exposes a unified, library-agnostic \JSONSerializer\ interface that decouples JSON encoding/decoding from specific underlying libraries. This change introduces \serialization-core\ with core abstractions (e.g., \JSONElement\, \TypeToken\) and provides two concrete implementations: \serialization-jackson\ for JVM-based serialization using Jackson, and built-in support for \kotlinx-serialization\. A new \serialization-test\ module offers a shared test base (\JSONElementSerializationTestBase\) to validate serialization round-trips across these implementations, ensuring consistent behavior regardless of the chosen backend.

serialization · high confidence

Introduce prompt caching and LLM client retry capabilities

This release adds a new prompt caching system and robust retry logic for LLM clients. Users can now cache prompt responses using \InMemoryPromptCache\ or \FilePromptCache\ (via \prompt-cache-model\ and \prompt-cache-files\) and wrap executors with \CachedPromptExecutor\ to avoid redundant API calls. Additionally, the \prompt-executor-clients\ module introduces \RetryingLLMClient\ and configurable \RetryConfig\ (including backoff, jitter, and retryable patterns) to automatically handle transient LLM failures, along with \ConnectionTimeoutConfig\ for fine-grained network control.

prompt · high confidence

Introduce session management with event validation and concurrency control

The A2A server now includes core session management components that enforce strict event sequencing and concurrency safety. The new Session class provides lifecycle methods (start, join, cancel) for managing agent execution, while the SessionEventProcessor validates incoming events against context and task IDs, ensures mutual exclusivity between message and task events, and uses mutex locking to prevent race conditions during event processing and storage updates.

a2a-server · high confidence

Introduce skills module for discovering and formatting agent capabilities

Added a new skills module that enables automatic discovery of agent skills from directory structures and generates structured prompts for them. The module includes a discovery engine that scans directories for skill definition files (SKILL.md), parses YAML frontmatter to extract metadata (name, description, license, compatibility, allowed tools), and resolves name collisions using configurable precedence rules. It also provides a prompt generation utility that formats discovered skills into XML, JSON, or YAML representations, allowing users to include optional fields like location, license, and metadata in the output.

skills · high confidence

Introduce strategy-specific event contexts for agent lifecycle tracking

The agent framework now provides dedicated context objects for strategy-related events, allowing users to access specific details when strategies start or complete. A new \StrategyEventContext\ interface extends the base lifecycle context to include the current \AIAgentContext\ and the \AIAgentStrategy\ instance. Two concrete implementations are introduced: \StrategyStartingContext\, which carries the strategy input and execution info, and \StrategyCompletedContext\, which provides the strategy result and its type token. This enables more granular handling and inspection of strategy execution phases within the agent pipeline.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/strategy · high confidence

Introduce structured output API with native and manual modes

The prompt-structure module now provides a new structured output API that allows you to define data schemas and examples for LLM responses. You can choose between Native mode, which leverages the model's built-in structured output capabilities via JSON schemas, or Manual mode, which guides the model through explicit prompting. The API includes a JsonStructure for JSON-based schemas with support for description overrides and property exclusion, a MarkdownStructureDefinition for text-based structures, and a new LLMStructuredParsingError exception to handle parsing failures.

prompt/prompt-structure · high confidence

Introduce structured output support with JSON and Markdown schemas

The prompt-structure module now provides a new \Structure\ abstraction and concrete implementations (\JsonStructure\, \MarkdownStructureDefinition\) to define and enforce structured data formats in LLM prompts. Users can create JSON structures with auto-generated schemas, support for polymorphic types, property exclusion, and description overrides, while Markdown structures allow custom schema definitions via builders. Both types support including examples in prompts to improve LLM understanding of the desired output format.

prompt-structure · high confidence

Introduce unified KoogHttpClient interface with automatic factory discovery

The http-client-core module now provides a new, unified \KoogHttpClient\ interface that standardizes HTTP operations (GET, POST, SSE streaming, and line-based streaming) across different underlying libraries. This change decouples the core HTTP client contract from specific implementations like Ktor, allowing LLM clients to use any compliant HTTP engine. On the JVM, the system automatically discovers the default HTTP client implementation at runtime using \ServiceLoader\, simplifying setup by removing the need to manually configure the HTTP client for most use cases, while still allowing explicit factory injection for custom configurations.

http-client/http-client-core · high confidence

Introduces A2A protocol core data models and transport abstractions

The a2a-core module now provides the foundational data structures and transport interfaces for the A2A protocol. This includes model classes for AgentCard, Task, Message, Artifact, and various event types (such as TaskStatusUpdateEvent and TaskArtifactUpdateEvent), along with supporting types for push notifications and file parts. Additionally, it defines the ClientTransport and ServerTransport interfaces, which expose the standard A2A protocol RPC methods (e.g., sendMessage, getTask, cancelTask) and handle request/response serialization, enabling clients and servers to communicate using the A2A specification.

a2a-core · high confidence

Introduces A2A protocol data models and serialization logic

This change adds the core data models for the A2A protocol, including \MessageSendParams\ and \MessageSendConfiguration\ for defining message requests, and a well-known path constant for agent card discovery. It also implements custom Kotlinx serialization serializers to handle polymorphic JSON structures for security schemes, message parts, file representations, and various event types (such as task status updates and artifacts), ensuring correct deserialization of the protocol's complex object hierarchies.

a2a/a2a-core/src/commonMain/kotlin/ai/koog/a2a/model · high confidence

Introduces A2A-specific exception hierarchy and error codes

The A2A core library now provides a dedicated set of exception classes and error codes compliant with the JSON-RPC specification and A2A protocol requirements. Users can now catch specific errors such as \A2AParseException\, \A2AMethodNotFoundException\, \A2ATaskNotFoundException\, and \A2APushNotificationNotSupportedException\ instead of handling generic exceptions. The \createA2AException\ factory function allows for automatic instantiation of the correct exception type based on the error code returned by the server, simplifying error handling in client and server implementations.

a2a/a2a-core/src/commonMain/kotlin/ai/koog/a2a/exceptions · high confidence

Introduces Debugger feature and core agent lifecycle abstractions

The agents-core module now includes a Debugger feature that intercepts and records agent lifecycle events (such as starting, completing, and failing) for monitoring and debugging purposes. This release also introduces foundational abstractions for agent execution, including the AIAgentState sealed interface to track agent status (NotStarted, Starting, Running, Finished, Failed), the AIAgentRunSession interface to manage execution contexts and pipelines, and the AgentExecutionInfo data class to provide hierarchical execution path information. Additionally, it adds the AgentLifecycleEventType sealed interface to categorize various agent events and the DefinedFeatureEvent base class for structured event handling.

agents-core · high confidence

Introduces JSON-RPC message serialization and polymorphic deserialization

The JSON-RPC transport module now includes a dedicated serialization configuration (JSONRPCJson) and polymorphic serializers for JSON-RPC messages. This enables the library to automatically distinguish between requests, notifications, and responses based on the presence of specific JSON keys (such as 'method', 'id', and 'error'), allowing for seamless encoding and decoding of A2A protocol messages without manual type handling.

a2a/a2a-transport/a2a-transport-core-jsonrpc/src/commonMain/kotlin/ai/koog/a2a/transport/jsonrpc/model · high confidence

Introduces SQL-based chat history persistence with schema migration support

The chat memory module now includes a new SQL-based implementation for storing conversation history. This change adds an abstract \SQLChatHistoryProvider\ base class that handles core persistence logic, including JSON-serialized message storage, time-to-live (TTL) expiration management, and conversation deletion. It also introduces a \SQLChatHistorySchemaMigrator\ interface to allow concrete implementations to manage database table creation and updates, along with a \NoOpSQLChatHistorySchemaMigrator\ for cases where schema management is handled externally.

agents/agents-features/agents-features-chat-memory-sql/src/commonMain/kotlin/ai/koog/agents/features/chatmemory · high confidence

Introduces a library-agnostic serialization API with a dynamic JSON model

The serialization-core module now provides a new, library-agnostic serialization API that decouples JSON handling from specific underlying libraries. This change introduces a dynamic \JSONElement\ model (including \JSONObject\, \JSONArray\, and \JSONPrimitive\) that can be manipulated independently of the serialization engine. It defines a \JSONSerializer\ interface and \TypeToken\ abstractions to support runtime type representation across platforms, with a default \KotlinxSerializer\ implementation that bridges the new API to \kotlinx-serialization\. This allows the system to mix internal data structures with external user inputs and supports Java interop via \TypeCapture\.

serialization/serialization-core · high confidence

Introduces configurable retry logic for LLM client operations

Adds a new \RetryConfig\ class and associated pattern matching logic to the prompt executor clients, enabling automatic retries for transient LLM errors. Users can now configure retry behavior—including maximum attempts, delays, backoff multipliers, and jitter—via predefined profiles (Default, Conservative, Aggressive, Production, Disabled) or custom settings. The system identifies retryable errors using HTTP status codes (e.g., 429, 5xx) and specific error keywords, and supports extracting 'retry-after' hints from error messages to optimize wait times.

prompt-executor-clients · high confidence

Introduces feature configuration and system variable utilities in agents-core

The agents-core module now includes a new \FeatureConfig\ abstract base class that allows features to register message processors and define event filters to control which lifecycle events are processed or traced. Additionally, a \FeatureSystemVariables\ utility object has been added to expose the environment variable (\KOOG\_FEATURES\) and JVM option (\koog.features\) names used for external feature configuration, with the utility marked as experimental.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/config · high confidence

Introduction of FeatureMessageProcessor for event filtering

A new \FeatureMessageProcessor\ class has been added to the agents core library to handle feature-related messages and events. This component allows users to configure a filter function that determines which incoming messages are processed, providing a foundational mechanism for managing system events and updates within the agent framework.

agents/agents-core/src/nonJvmCommonMain/kotlin/ai/koog/agents/core/feature/message · high confidence

Introduction of InternalA2AApi annotation for internal API marking

The A2A module now includes an \InternalA2AApi\ annotation to mark APIs as internal. This allows the library to explicitly signal that certain interfaces or functions are not part of the public contract and may change or be removed without notice, helping developers avoid relying on unstable internal details.

a2a/a2a-core/src/commonMain/kotlin/ai/koog/a2a/annotations · high confidence

JDBC-based persistence storage for agent checkpoints

Agents can now persist checkpoints to relational databases using a new JDBC implementation. This location provides the core JDBC storage provider and database-specific schema migrators for H2, MySQL, and PostgreSQL, enabling automatic table creation and checkpoint upserts. The implementation supports optional time-to-live (TTL) expiration for checkpoints and allows in-memory filtering of results via a custom filter interface.

agents/agents-features/agents-features-persistence-jdbc/src/main/kotlin/ai/koog/agents/features/persistence · high confidence

JVM-specific checkpoint persistence and rollback tool support

This update introduces JVM-specific implementations for the agent snapshotting feature, enabling robust state management on the JVM platform. Users can now persist agent checkpoints to the local file system using the new \JVMFilePersistenceStorageProvider\, which wraps standard Java NIO paths. Additionally, the \RollbackToolRegistry\ and \RollbackToolSet\ are now available on JVM, allowing developers to define rollback mechanisms for tools with side effects using the new \@Reverts\ annotation and builder APIs, ensuring that agent state can be safely reverted during checkpointing operations.

agents/agents-features/agents-features-snapshot/src/jvmMain · high confidence

Java examples for OpenTelemetry tracing with Jaeger, Langfuse, and Weave

Added Java example implementations for the OpenTelemetry feature, demonstrating how to integrate tracing into Koog agents. The examples show configuration for standard log and OTLP exporters (viewable in Jaeger), a Langfuse exporter with custom session and trace attributes, and a Weave exporter using environment variables. A docker-compose file is also included to spin up a local Jaeger instance for local debugging.

examples/simple-examples-java/src/main/java/ai/koog/agents/example/features/opentelemetry · high confidence

Java-compatible AIAgentPlanner base class added

A new abstract base class, JavaAIAgentPlanner, has been introduced in the agents-core module to simplify integration for Java users. This class provides a Java-friendly API by exposing standard synchronous methods for building plans, executing steps, and checking completion status, while internally handling the necessary Kotlin coroutine continuations required by the underlying planner interface.

agents/agents-core/src/jvmMain/java · high confidence

Java-compatible tracing writers for file and log output

The tracing feature now exposes Java-friendly factory methods for writing trace events. In the JVM-specific tracing module, \TraceFeatureMessageFileWriter\ and \TraceFeatureMessageLogWriter\ gain \@JavaAPI\-annotated \create\ methods that accept \java.nio.file.Path\ and SLF4J \Logger\ respectively, allowing Java callers to configure trace output without dealing with Kotlin-specific types. The non-JVM tracing module provides the corresponding platform-specific implementations of these writers to ensure the tracing capability is available across all supported targets.

agents/agents-features/agents-features-trace/src/jvmCommonMain/kotlin/ai/koog/agents/features/tracing, agents/agents-features/agents-features-trace/src/nonJvmCommonMain/kotlin/ai/koog/agents/features/tracing · high confidence

Java-friendly API for AI agents and services

The agents-core module now provides a dedicated Java API for building and running AI agents. Users can construct agents using \AIAgentBuilder\ with \functionalStrategy\ or \graphStrategy\ methods, and execute them synchronously via \runBlocking\. The \AIAgentService\ class offers a blocking interface for managing agent lifecycles, including \createAgentBlocking\, \createAgentAndRunBlocking\, and \removeAgentBlocking\. Configuration is handled through \AIAgentConfig\ and its builder, which supports setting executors for strategy and LLM dispatchers. Additionally, graph-based agent workflows can be visualized as Mermaid diagrams using the new \MermaidDiagramGenerator\.

agents/agents-core/src/jvmCommonMain · high confidence

Java-friendly blocking event handlers for agent lifecycle events

The \EventHandlerConfig\ class now exposes a set of \\*Blocking\ methods (e.g., \onAgentStartingBlocking\, \onSubgraphExecutionCompletedBlocking\) that allow Java callers to register synchronous interceptors for agent, strategy, node, and subgraph lifecycle events. These methods internally wrap the provided handlers using \withContextReentrant\ to ensure proper coroutine context propagation, simplifying integration for Java users who previously had to deal with asynchronous or complex coroutine-based event registration.

agents/agents-features/agents-features-event-handler/src/jvmCommonMain/kotlin/ai/koog/agents/features/eventHandler · high confidence

Java-friendly blocking interceptors for agent pipelines

The agent pipeline now exposes JVM-friendly blocking interceptor methods (e.g., interceptNodeExecutionStartingBlocking, interceptAgentStartingBlocking, interceptPlanCreationStartingBlocking) across AIAgentPipeline, AIAgentGraphPipeline, and AIAgentPlannerPipeline. These methods accept Java-compatible functional interfaces (Interceptor, TransformInterceptor, AsyncInterceptor) and execute the interception logic on the strategy dispatcher using withContextReentrant, enabling Java callers to hook into node, subgraph, agent, strategy, and planner lifecycle events without dealing with Kotlin coroutines directly.

agents/agents-core/src/jvmCommonMain/kotlin/ai/koog/agents/core/feature/pipeline · high confidence

New A2A and ACP agent examples with centralized API key management

The simple-examples directory now includes new demonstrations for Agent-to-Agent (A2A) communication and the Agent Client Protocol (ACP). The A2A examples feature a simple joke agent for basic message-based interaction and an advanced joke agent that supports task-based workflows, streaming responses, and artifact delivery. Additionally, ACP examples show how to integrate Koog agents as both clients and servers, including a terminal client for interacting with agents and a Koog-based agent supporting file system and terminal operations. To support these examples, a new ApiKeyService utility has been added to centralize access to environment variables for various LLM providers (OpenAI, Anthropic, Google, AWS Bedrock, MistralAI, etc.).

examples/simple-examples · high confidence

New A2A server feature for agent-to-agent communication

This change introduces the \agents-features-a2a-server\ module, providing an agent feature that enables A2A server mode. It exposes the A2A \RequestContext\ and \SessionEventProcessor\ to agent strategies, allowing nodes to send messages, update task status, and manage session lifecycle. The feature includes convenience DSL nodes for responding with messages (\nodeA2ARespondMessage\), sending task events (\nodeA2ARespondTaskEvent\), and performing message and task storage operations (\nodeA2AMessageStorageSave\, \nodeA2AMessageStorageLoad\, \nodeA2AMessageStorageReplace\, \nodeA2ATaskGet\, \nodeA2ATaskGetAll\).

agents-features-a2a-server · high confidence

New ACP agent example project with file system tools

Added a new example project for the ACP agent that demonstrates integration with the Koog framework. This example includes a \KoogTools\ implementation providing three specific tools for file system interaction: \list\_directory\ to recursively list directory contents, \read\_file\ to retrieve file text, and \edit\_file\ to perform string replacements within files. It also includes serialization helpers to convert internal plan structures to the Agent Client Protocol format.

acp-agent · high confidence

New Agent Checkpoint feature for state persistence and rollback

The \agents-features-snapshot\ module introduces a new \Persistence\ feature that allows AI agents to save and restore their state at specific points during execution. Users can now resume agent execution from a checkpoint, roll back to previous states, and persist state across sessions using configurable storage providers (in-memory or file-based). The feature supports automatic checkpoint creation after each node execution and includes a \RollbackToolRegistry\ to undo side effects of tools when rolling back. This enables continuous persistence and fine-grained recovery of agent state, including message history, current node, and input data.

agents/agents-features/agents-features-snapshot · high confidence

New Code Agent and ACP integration examples

The examples directory now includes a new ACP agent example demonstrating how to connect a Koog agent to IntelliJ IDEA via the Agent Communication Protocol, and a multi-step Code Agent series (minimal agent, execution tool, and observability) that guides users through building a coding agent with shell execution and LangFuse tracing capabilities.

examples · high confidence

New Devoxx Belgium 2025 example: Spring + Koog interactive support bot with persistence and rollbacks

Added a new example application in the \devoxx-belgium-2025\ directory demonstrating an interactive e-commerce support bot built with Spring Boot and Koog. The example includes a \KoogAgentService\ that manages AI agents with PostgreSQL-based checkpoint persistence and automatic rollback capabilities (e.g., undoing refunds, order cancellations, and address updates). It also introduces supporting data structures (\Item\, \Order\, \UserAccount\, \OrderUpdateSummary\) and specific tool implementations (\RollbackTools\) to handle state reversals, providing a complete reference for implementing persistent, rollback-enabled AI agents in Java/Kotlin projects.

devoxx-belgium-2025 · high confidence

New Devoxx Belgium 2025 example: Spring-based interactive support agent

Added a new example application in \examples/devoxx-belgium-2025\ demonstrating an interactive e-commerce support bot built with Spring Boot and Koog. The example includes a REST API (\ApiController\) for launching support agents, checking status, and rolling back to specific checkpoints. It features a complex agent strategy (\AgentStrategy\) that uses subgraphs for problem identification, fixing, verification, and history compression, leveraging tools for user order management, communication, and order updates. The example also includes configuration for OpenAI and Anthropic API keys, in-memory data stores for simulation, and PostgreSQL checkpoint storage setup.

examples/devoxx-belgium-2025 · high confidence

New GOAP and LLM-based planner implementations in agents-planner module

The agents-planner module now includes concrete implementations for Goal-Oriented Action Planning (GOAP) and Large Language Model (LLM) based planning strategies. This introduces the GoapAgentState class to manage GOAP agent states, a SimpleLLMPlanner that generates and executes plans via LLM calls with optional history compression, and a SimpleLLMWithCriticPlanner that extends the simple planner by adding an LLM-driven evaluation step to decide whether to continue or replan based on current state and plan validity.

agents-planner · high confidence

New HTTP JSON-RPC client transport for A2A agents

Users can now communicate with A2A agents using an HTTP-based JSON-RPC client transport. This new component, located in the \a2a-transport-client-jsonrpc-http\ module, leverages the Ktor HTTP client to send standard JSON-RPC requests and supports Server-Sent Events (SSE) for streaming responses. It handles JSON serialization via \kotlinx.serialization\ and allows for custom HTTP headers, enabling integration with agents that expose their endpoints over standard HTTP.

a2a/a2a-transport/a2a-transport-client-jsonrpc-http · high confidence

New JDBC-based persistence storage providers for agent checkpoints

This change introduces a new module providing pure JDBC implementations for persisting agent checkpoints, eliminating the need for ORM dependencies like Exposed. It adds specific storage providers for PostgreSQL, MySQL, and H2 databases, each with automatic schema migration support. The implementation includes TTL-based automatic cleanup of expired checkpoints and offers both coroutine-based and blocking Java-compatible methods for saving, retrieving, and managing checkpoint data.

agents/agents-features/agents-features-persistence-jdbc · high confidence

New Java API for agent graph strategies

The library now exposes Java-friendly entry points for defining agent execution flows, including \chatAgentStrategy()\, \reActStrategy()\, and \singleRunStrategyWithHistoryCompression()\. These functions allow Java projects to construct and configure agent graphs with features like tool execution loops, ReAct reasoning cycles, and automatic conversation history compression, bridging the gap between the Kotlin DSL and pure Java usage.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/ext/agent · high confidence

New Java example for JavaOne 2026

Added a new Java-based example application in the examples/javaone-2026 directory that demonstrates how to build and run AI agents using the Koog framework. The example includes a Spring Boot application with a REST API endpoint for launching support agents, along with several agent strategy implementations: a functional agent, a GOAP (Goal-Oriented Action Planning) agent, an LLM-planner agent with history compression, and a simple graph-based agent. It also provides tool implementations for reading and writing account information, communication, and data structures for handling account issues and transactions.

examples/javaone-2026 · high confidence

New Java examples for agent strategies, persistence, and chat memory

The simple-examples-java module now includes a comprehensive set of Java demonstrations for building AI agents. These examples cover graph-based strategies (Calculator, Problem Solver), functional strategies (Chat, Problem Solver), and GOAP planning. They also showcase advanced features like JDBC-backed chat history persistence and agent state persistence using PostgreSQL, as well as custom subgraph implementations for research workflows. A shared ApiKeyService utility is provided to manage environment-based API keys for various providers.

examples/simple-examples-java · high confidence

New Java-blocking API for synchronous feature message processing

The \FeatureMessageProcessor\ now exposes dedicated blocking methods (\initializeBlocking\, \onMessageBlocking\) and non-suspend override hooks (\handleMessage\, \handleClose\) to facilitate synchronous interaction from Java code. This allows Java developers to initialize and process feature messages without managing Kotlin coroutines, while the underlying implementation delegates to the existing coroutine-based logic using \runBlockingReentrant\.

agents/agents-core/src/jvmCommonMain/kotlin/ai/koog/agents/core/feature/message · high confidence

New JavaScript example for running Koog agents

This change introduces a new example project (koogelis) that demonstrates how to invoke a Koog agent from JavaScript code. The example provides a configurable agent setup supporting Google AI models (including Gemini 3 Flash Preview) and local Ollama instances, with features like MCP tool integration, agent persistence, and tracing. It includes the necessary Kotlin/JS source files to bridge the agent logic to the JavaScript environment.

examples/koog-js-example/koogelis · high confidence

New LLM client infrastructure with retry logic and Java blocking APIs

This change introduces the core \LLMClient\ and \LLMEmbeddingProvider\ interfaces and their platform-specific implementations (JVM, Android, Apple, JS) in the \prompt-executor-clients\ module. It adds a \RetryingLLMClient\ decorator that automatically retries transient failures (such as rate limits or timeouts) based on a configurable \RetryConfig\, and provides Java-friendly blocking wrappers (e.g., \executeBlocking\, \embedBlocking\) on the JVM target to allow synchronous usage from Java code. The module also includes serialization helpers for handling additional JSON properties and defines model definition interfaces.

prompt/prompt-executor/prompt-executor-clients · high confidence

New MCP metadata library for transport types and server info

The \agents-mcp-metadata\ module has been introduced to provide common classes for MCP metadata. This includes the \McpTransportType\ enum, which defines supported transport protocols (Stdio, Tcp, StreamableHttp, and Unknown), and the \McpServerInfo\ class for storing server connection details. Additionally, the \McpMetadataKeys\ object exposes standard keys for tool identification, server URLs, ports, instructions, protocol versions, and session IDs, enabling consistent metadata handling across MCP tool integrations.

agents/agents-mcp-metadata · high confidence

New McpTool implementation and registry provider for Model Context Protocol integration

This change introduces the core components for integrating Model Context Protocol (MCP) tools into the agent framework. It adds McpTool, which bridges the agent framework's Tool interface with the MCP SDK by handling argument conversion, tool execution, and result serialization (including improved error handling for LLMs). It also adds McpToolRegistryProvider, which facilitates connecting to MCP servers via Streamable HTTP, SSE, or stdio transports, and McpToolDefinitionParser to convert MCP tool schemas into the framework's ToolDescriptor format, supporting complex types like anyOf and enums.

agents/agents-mcp/src/commonMain · high confidence

New MessageTokenizer feature for token counting and caching

The agents-features-tokenizer module introduces the MessageTokenizer feature, allowing AI Agents to count tokens in individual messages and entire prompts, manage token usage for cost and performance optimization, and support both on-demand and cached tokenization strategies. Users can install the feature via the MessageTokenizer config to specify a tokenizer implementation and enable caching, then access token counts through the agent context's LLM session.

agents/agents-features/agents-features-tokenizer · high confidence

New OpenTelemetry tracing examples for Jaeger, Langfuse, and Weave

Added example code demonstrating how to integrate Koog agents with OpenTelemetry for distributed tracing. The new examples show how to configure the OpenTelemetry feature to export traces to a local Jaeger instance (via OTLP gRPC), Langfuse (via OTLP HTTP), and Weave (via OTLP HTTP), including the necessary setup for environment variables and Docker services.

examples/simple-examples/src/main/kotlin/ai/koog/agents/example/features/opentelemetry · high confidence

New Python-based A2A test server with agent execution and task management

A new test server implementation has been added to the \a2a/test-python-a2a-server\ location, providing a functional Python-based A2A (Agent-to-Agent) server for integration testing. The server, built on Starlette and Uvicorn, exposes an agent card with skills (including a basic 'hello world' and an extended authenticated skill) and handles requests via a \DefaultRequestHandler\. It supports various agent execution scenarios, including simple text responses, task submission with status updates (submitted, working, completed), cancellable tasks, and long-running tasks with streaming progress updates. The server uses in-memory stores for task history and push notification configurations, running on port 9999 by default.

a2a/test-python-a2a-server · high confidence

New SQL persistence provider infrastructure with schema migration and storage abstraction

The SQL persistence feature now includes a new \SQLPersistenceSchemaMigrator\ interface and a \NoOpSQLPersistenceSchemaMigrator\ implementation to handle database schema changes asynchronously, alongside a new \SQLPersistenceStorageProvider\ abstract base class. This provider establishes a generic SQL abstraction for persisting agent checkpoints to relational databases, defining a standard schema (persistence\_id, checkpoint\_id, created\_at, checkpoint\_json, ttl\_timestamp) and providing methods for transaction management, TTL-based cleanup, and checkpoint CRUD operations, enabling concrete implementations to support specific SQL dialects.

agents/agents-features/agents-features-sql/src/commonMain/kotlin/ai/koog/agents/features/sql · high confidence

New Spring AI integration for chat memory, embedding, and streaming tool calls

This release adds a new Spring Boot integration layer for Koog. It introduces a chat memory adapter that bridges Koog's conversation history to Spring AI's ChatMemoryRepository, handling text-only round-trips while silently filtering out tool calls, reasoning, and attachments. It also provides an embedding model adapter that wraps Spring AI's EmbeddingModel, supporting both single-candidate auto-detection and explicit bean-name selection via configuration properties. Additionally, it adds a streaming tool-call assembler that correctly handles provider-specific differences, buffering incremental arguments for OpenAI while emitting immediately for Anthropic and Google. All adapters use a configurable coroutine dispatcher that can leverage Spring's virtual-thread executor when available.

(repo-wide) · high confidence

New Spring Boot example for the Koog Java API

Added a complete Spring Boot application example in the \examples/koog-java-api-example\ directory that demonstrates how to integrate the Koog Java API. The example includes a REST controller for launching and monitoring support agents, a service layer using the new \AIAgent\ builder and \MultiLLMPromptExecutor\, and supporting data structures annotated with \@LLMDescription\. It also provides a \RollbackTools\ implementation to show how tool reversibility works within the agent's execution context.

examples/koog-java-api-example · high confidence

New agent testing API with graph assertions and LLM capture

The agents-test module now exposes a comprehensive testing API for validating AI agent behavior. Users can assert on agent graph structure and execution flow using \GraphAssertions\, \EdgeAssertion\, \NodeOutputAssertion\, and \ReachabilityAssertion\. A \CapturingLLMClient\ is provided to intercept and inspect LLM interactions, exposing details like executed prompts, models, tools, and embeddings. Additionally, \AIAgentContextMockBuilderBase\ allows constructing mock agent contexts for isolated testing.

agents/agents-test · high confidence

New agents-cli module for integrating Claude Code and OpenAI Codex

The new \agents-cli\ module allows you to use Claude Code and OpenAI Codex as agents within Koog workflows. Instead of communicating with LLMs through API calls, it invokes their CLI binaries and parses the output. Agents can run locally via \ProcessCliTransport\ or inside Docker containers via \DockerCliTransport\. CLI agents can also be embedded as nodes in Koog graph-based strategies using \asNode()\, enabling multi-agent orchestration.

agents-cli, agents/agents-cli · high confidence

New agents-planner module with GOAP and LLM-based planning strategies

The new \agents-planner\ module provides planner strategy implementations for \agents-core\, exposing a central \Planners\ entry point for creating built-in planning strategies. Users can now build Goal-Oriented Action Planning (GOAP) strategies using a DSL or Java-style chained builders, defining actions with preconditions, beliefs, costs, and execution logic, and goals with conditions and value functions; the planner uses an A\* search algorithm to find the optimal action sequence. Additionally, LLM-based planning is available via \Planners.llmBased\ and \Planners.llmBasedWithCritic\, where the latter adds a second LLM pass to evaluate and refine the generated plan, with optional history compression. The module includes cross-platform support (JVM and non-JVM) and comprehensive tests for both Kotlin and Java builders.

agents/agents-planner · high confidence

New code-agent example with OpenTelemetry and Langfuse observability

Added a new example agent in the step-03-add-observability directory that demonstrates how to integrate observability into a code-agent application. The example configures OpenTelemetry tracing with a Langfuse exporter to send trace data, allowing users to monitor agent execution and tool calls. It also includes a Logback configuration for console logging at the ERROR level.

examples/code-agent/step-03-add-observability · high confidence

New example demonstrating Koog agent deployment to Amazon Bedrock AgentCore Runtime

This change adds a new example application (\koog-agentcore-runtime\) that illustrates how to deploy a Koog agent to Amazon Bedrock AgentCore Runtime. The example provides a minimal, vision-enabled streaming chat agent using the Anthropic Claude model, serving both streaming (SSE) and non-streaming responses via a single Ktor endpoint. It also includes an E2E harness to verify full plugin regression coverage for various input types (text, binary, stream, multipart) and output formats.

examples/koog-agentcore-runtime, koog-agentcore-runtime · high confidence

New file-system and document abstractions in rag-base

The rag-base module introduces a new set of interfaces and utilities for handling files and documents, including a generic DocumentProvider for retrieving and editing document text, a FileSystemProvider with read-only and read-write capabilities, and a TraversalFilter system (with GlobPattern support) to restrict file-system visibility. It also adds data models such as DocumentWithPayload, TextDocument, FileMetadata, FileSize, and FileSystemEntry to represent document metadata, file sizes, and hierarchical file-system entries, along with utility functions for text range manipulation and path filtering.

rag/rag-base · high confidence

New file-system and search data models for RAG storage

The rag-base module introduces foundational data structures to support embedding-based file storage and search. This includes a generic DocumentWithPayload type to associate documents with metadata, and a comprehensive FileSystemEntry model (with File and Folder variants) that exposes file metadata, content types, and text excerpts. Supporting types such as FileSize, FileMetadata, TextRange, and DocumentProvider (including Position and DocumentRange) provide the necessary utilities for file navigation and text manipulation. Additionally, the SearchResult and Score classes define the output format for storage search operations, including relevance scores and optional metadata.

rag-base · high confidence

New inspection for missing KDoc in public API declarations

A new local inspection named 'Missing KDoc for public API declaration' has been added to the inspections directory. This tool scans Kotlin files for public classes, functions, properties, and object declarations that lack KDoc comments, flagging them as warnings. It specifically excludes overridden members, ensuring that only original public API surface areas are checked for documentation coverage.

inspections · high confidence

New koog-bedrock-agentcore-runtime module for Amazon Bedrock AgentCore integration

This change introduces the \koog-bedrock-agentcore-runtime\ module, providing a Ktor route installer that implements the Amazon Bedrock AgentCore Runtime HTTP contract. It exposes two endpoints: \POST /invocations\ for handling agent invocations (supporting JSON, text, binary, multipart, and streaming payloads via a unified handler) and \GET /ping\ for health checks that report \Healthy\, \HealthyBusy\, or \Unhealthy\ status based on background task tracking. The module includes utilities for mapping Bedrock content blocks to HTTP responses, handling specific AgentCore headers, and integrating with Ktor's rate limiting and content negotiation plugins.

koog-bedrock-agentcore-runtime · high confidence

New node execution event contexts with input/output type information

The framework now exposes specific event context classes for node lifecycle events (starting, completed, failed). These contexts include the node's input and output data along with their corresponding TypeToken metadata, allowing users to inspect the exact data types flowing through the agent graph during execution.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/node · high confidence

New prompt executors with model resolution and load balancing

The prompt-executor-model module now includes MultiLLMPromptExecutor and RoutingLLMPromptExecutor, enabling execution across multiple LLM providers with configurable fallback strategies and load-balanced routing (e.g., round-robin). A new ResolvedModel type decouples model selection from execution, allowing executors to resolve the effective model before dispatching requests. Additionally, StructureFixingParser (renamed from StructureParser) has been refactored to accept an executor and model directly, supporting configurable retries and custom fixing prompts for malformed structured outputs.

prompt-executor-model · high confidence

New pure JDBC ChatHistoryProvider implementations for PostgreSQL, MySQL, H2, and Oracle

This module introduces a set of chat history providers that persist conversation history using plain JDBC without requiring an ORM like Exposed. It includes specific implementations for PostgreSQL, MySQL, H2, and Oracle, each extending the base \JdbcChatHistoryProvider\ and providing their own schema migrators for automatic table creation. The providers support configurable TTL for automatic cleanup of expired conversations and are designed for Java interoperability with \@JvmOverloads\ constructors.

agents/agents-features/agents-features-chat-history-jdbc · high confidence

New shared utils module with platform-specific system config, secrets, and time utilities

The \utils\ module introduces a set of cross-platform helpers for the Koog project. It provides a \SystemConfigReader\ interface with platform-specific implementations: on JVM it reads from environment variables and system properties, and on Apple platforms it reads from \NSUserDefaults\ (Android, JS, and WasmJS currently throw \NotImplementedError\). A \SystemSecretsReader\ interface is also added, with a JVM implementation that reads from environment variables (Apple, Android, JS, and WasmJS currently throw \NotImplementedError\). A \KoogClock\ functional interface abstracts the current time source, defaulting to \kotlin.time.Clock.System\, and a \TimeUtils\ class on JVM bridges Java and Kotlin time types. Additional utilities include a \ByteArrayAsBase64Serializer\ for kotlinx.serialization, a \masked\ extension on strings for hiding sensitive data, a \Closeable\ interface with a \use\ extension for coroutines, and a \Dispatchers.SuitableForIO\ property that delegates to platform-appropriate dispatchers. Reentrant coroutine utilities (\runBlockingReentrant\, \withContextReentrant\) are included for safe interop with blocking Java code, and an \@InternalKoogUtils\ opt-in annotation marks internal APIs.

utils · high confidence

New simple-examples showcase advanced agent patterns and integrations

The simple-examples directory now includes a comprehensive set of new agent implementations demonstrating advanced capabilities: an A2A (Agent-to-Agent) joke writer with task-based conversation flow and structured output, an ACP (Agent Client Protocol) integration with file system tools, a chess game agent with move validation, a GOAP-based grouper agent for marketing copy, a parallel execution agent that generates and critiques jokes across multiple LLM providers, a persistence snapshot strategy for agent state management, advanced structured output examples with complex schemas and polymorphism, a payment status tool, and a web search agent using BrightData. Existing examples have been migrated to the new simple-examples structure with updated imports and formatting.

simple-examples · high confidence

New structured event models for LLM calls, streaming, node execution, and subgraphs

The agent core now exposes a comprehensive set of serializable event classes in the \ai.koog.agents.core.feature.model.events\ package to track agent lifecycle and model interactions. This includes \LLMCallStartingEvent\, \LLMCallCompletedEvent\, and \LLMCallFailedEvent\ for standard model calls, as well as \LLMStreamingStartingEvent\, \LLMStreamingFrameReceivedEvent\, \LLMStreamingCompletedEvent\, and \LLMStreamingFailedEvent\ to support real-time streaming responses. Additionally, \NodeExecutionStartingEvent\, \NodeExecutionCompletedEvent\, and \NodeExecutionFailedEvent\ provide visibility into individual agent node processing, while \SubgraphExecutionStartingEvent\, \SubgraphExecutionCompletedEvent\, and \SubgraphExecutionFailedEvent\ track nested subgraph runs. All events utilize \JSONElement\ for input/output data and \ModelInfo\ for model details, enabling consistent monitoring and debugging of agent behavior.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/model/events · high confidence

New test-utils module with serialization helpers and coroutine-aware Awaitility extensions

A new test-utils module has been introduced to provide shared testing utilities across the Koog codebase. This includes a CapturingKoogHttpClient test double for verifying HTTP request paths and bodies, and SerializationHelpers that allow verifying JSON deserialization and re-serialization consistency with configurable strict/lenient modes. For JVM-based tests, the module adds Awaitility extensions that support Kotlin Coroutines (allowing suspendable assertions within Awaitility's polling loop) and a DockerAvailableCondition to automatically skip tests when Docker is not present.

test-utils · high confidence

New token counting capabilities for prompts and messages

The prompt module now includes a tokenizer library that allows you to estimate token usage for messages and prompts. This includes a \PromptTokenizer\ interface with \OnDemandTokenizer\ and \CachingTokenizer\ implementations, as well as several \Tokenizer\ implementations like \NoTokenizer\, \SimpleRegexBasedTokenizer\, and \TiktokenEncoder\ for different accuracy and performance needs. This enables better management of context windows and cost estimation when interacting with LLMs.

prompt/prompt-tokenizer · high confidence

New trace event formatters and writers for file, log, and remote output

The tracing feature now includes dedicated message processors to write trace events to files, logs, and remote servers, each with customizable formatting. Users can install \TraceFeatureMessageFileWriter\ to persist traces to disk, \TraceFeatureMessageLogWriter\ to stream them to a logger (defaulting to INFO level), or \TraceFeatureMessageRemoteWriter\ (moved to the core tracing package) to send data to a remote server. The system also introduces a comprehensive default formatting strategy that structures event output to include specific context such as agent ID, run ID, node names, prompts, model identifiers, tool details, and error messages for events like LLM calls, streaming, tool usage, and node execution.

agents/agents-features/agents-features-trace/src/commonMain/kotlin/ai/koog/agents/features/tracing/writer · high confidence

New utility classes for locking, model info, and hidden strings in agents-utils

The agents-utils module now exposes several new public utilities: a KeyedMutex for keyed, suspend-friendly mutual exclusion and an RWLock for concurrent read/exclusive write access, both supporting Kotlin Multiplatform; a ModelInfo data class that replaces the previous 'provider:model' string format with structured fields (provider, model, displayName, contextLength, maxOutputTokens) and includes serialization support; and a HiddenString data class that obscures sensitive values in string representations while keeping the original value accessible. Additionally, a public rootCause extension property for CancellationException and a withLockCheck extension for Mutex are now available in this module, and the previous expect/actual declaration for Dispatchers.SuitableForIO has been removed.

agents/agents-utils · high confidence

Ollama client introduces configurable context window strategies and dynamic model metadata

The Ollama client now allows users to control how the \num\_ctx\ parameter is determined for chat requests through a new \ContextWindowStrategy\ interface with three built-in modes: \None\ (delegates to the Ollama server's default logic), \Fixed\ (enforces a specific context length, capped by the model's maximum), and \FitPrompt\ (dynamically calculates the context length based on prompt tokenization or previous usage, rounded to configurable chunk sizes). Additionally, the client now parses detailed model metadata from the Ollama API via \OllamaModelCard\, exposing properties like parameter count, embedding length, and capabilities, which are used to populate \LLModel\ definitions with accurate context lengths and capabilities.

prompt/prompt-executor/prompt-executor-clients/prompt-executor-ollama-client · high confidence

OpenAI client adds model definitions, serialization models, and moderation support

The OpenAI client now includes a comprehensive set of predefined model configurations (LLModel instances) covering chat, reasoning, audio, embedding, and moderation models, implementing the LLModelDefinitions interface to expose these capabilities. New internal serialization models have been added to support the OpenAI Responses API, embeddings, and moderation endpoints, enabling structured request/response handling for these features. The moderation support specifically introduces the Omni moderation model for detecting harmful content in text and images.

prompt-executor-openai-client · high confidence

OpenAI client now supports reasoning content, Azure configuration, and new GPT-5.5 models

The OpenAI client implementation has been updated to support reasoning interactions, including parsing \reasoning\_content\ from both streaming deltas and tool-call responses. It now includes dedicated configuration classes for Azure OpenAI, such as \AzureOpenAIClientSettings\ and \AzureOpenAIServiceVersion\ with predefined stable and preview versions. Additionally, the client exposes new model definitions for GPT-5.5 and GPT-5.5 Pro, which support the Responses API and structured output capabilities, while \OpenAIChatParams\ and \OpenAIResponsesParams\ provide fine-grained control over parameters like \reasoningEffort\, \serviceTier\, and \promptCacheKey\.

prompt/prompt-executor/prompt-executor-clients/prompt-executor-openai-client · high confidence

OpenRouter client now supports embeddings and model listing

The OpenRouter LLM client has been extended to support embedding generation and model discovery. New data models for embeddings (OpenRouterEmbedding) and model listings (OpenRouterModelsResponse) have been added, enabling users to generate vector embeddings and retrieve available model details via the client. The client implementation has also been refactored to decouple from Ktor, now accepting a generic KoogHttpClient and using a clock for metadata tracking.

prompt-executor-openrouter-client · high confidence

OpenRouter client refactored with embedding support and model metadata

The OpenRouter client has been restructured to support embedding generation alongside chat completions, introducing dedicated data models for embedding requests and responses, and adding a comprehensive suite of tests for embedding serialization and client behavior. The client's internal data models have been migrated to reuse OpenAI-compatible base classes, and the model definitions now expose structured metadata including context length and maximum output tokens. On the JVM, the client factory now automatically resolves the default HTTP client factory, simplifying initialization for Java users.

prompt/prompt-executor/prompt-executor-clients/prompt-executor-openrouter-client · high confidence

OpenTelemetry feature migrated to Kotlin Multiplatform

The OpenTelemetry integration has been rewritten to support Kotlin Multiplatform, moving the core tracing logic from JVM-only to commonMain. This enables telemetry collection on non-JVM targets (such as Android and iOS) using the Kotlin OpenTelemetry SDK. The change introduces a new configuration API (OpenTelemetryConfig) for managing service info, span processors, and verbose modes, along with platform-agnostic integrations for Langfuse and Datadog via a new OTLP/JSON exporter. Existing JVM-specific metrics capabilities remain isolated in jvmMain extensions.

agents/agents-features/agents-features-opentelemetry/src/commonMain/kotlin/ai/koog/agents/features/opentelemetry · high confidence

OpenTelemetry feature now supports Java API compatibility and Kotlin Multiplatform

The OpenTelemetry feature has been migrated to Kotlin Multiplatform, introducing platform-specific implementations for JVM and non-JVM targets. For Java users, the feature now provides Java-friendly API overrides in OpenTelemetryConfig, including methods like setServiceInfo and integration exporters (Langfuse, Weave, Datadog) that accept java.time.Duration to work around Kotlin value-class name mangling. The JVM implementation includes a full metric collector with counters and histograms, while non-JVM platforms use a no-op metric collector. The feature also adds tool name cardinality restriction capabilities to manage metric dimensions.

agents/agents-features/agents-features-opentelemetry/src/jvmCommonMain/kotlin/ai/koog/agents/features/opentelemetry, agents/agents-features/agents-features-opentelemetry/src/nonJvmCommonMain/kotlin/ai/koog/agents/features/opentelemetry · high confidence

Planner lifecycle event contexts added

The planner agent pipeline now exposes specific event context classes (such as PlanCreationStartingContext, StepExecutionCompletedContext, and PlanCompletionEvaluationCompletedContext) that extend the base AgentLifecycleEventContext. These contexts provide structured access to the AIAgentContext, current state, plan details, and step index for key planner operations, enabling interceptors and handlers to observe and react to the planner's lifecycle events like plan building and step execution.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/planner · high confidence

Pure JDBC Chat History Provider with multi-database support

The chat history module now includes a pure JDBC implementation that allows storing conversation history in standard SQL databases. This adds a base \JdbcChatHistoryProvider\ and specific implementations for H2, MySQL, PostgreSQL, and Oracle, each handling database-specific schema creation and upsert logic (such as \MERGE\ for H2/Oracle and \ON DUPLICATE KEY\ for MySQL). Users can now persist chat history using their existing JDBC data sources with built-in support for message serialization and optional TTL-based expiration.

agents/agents-features/agents-features-chat-history-jdbc/src/main/kotlin/ai/koog/agents/features/chathistory · high confidence

SQL checkpoint persistence now supports TTL and filtering

The SQL persistence provider for agent checkpoints has been updated to support automatic expiration (TTL) and query filtering. Checkpoints can now be assigned a time-to-live, after which they are automatically cleaned up by the storage provider, helping to manage database size. Additionally, the provider now accepts filters to retrieve specific checkpoints rather than just the latest one, enabling more granular state management and querying capabilities for agents using SQL-backed persistence.

agents/agents-features/agents-features-sql/src/jvmMain/kotlin/ai/koog/agents/features/sql · high confidence

SQL persistence providers for agent checkpoints and chat history

The agents-features-sql module now provides SQL-based persistence for agent checkpoints using the JetBrains Exposed ORM, supporting PostgreSQL, MySQL, H2, and SQLite with HikariCP connection pooling and configurable TTL cleanup. Additionally, the new agents-features-chat-memory-sql module exposes SQL-based providers for persisting chat history, supporting PostgreSQL, MySQL, and H2 with automatic cleanup of expired conversations. Both modules include database-specific schema migrators and allow independent installation.

agents/agents-features/agents-features-sql · high confidence

Subgraph execution lifecycle events now expose input, output, and error details

The framework now provides richer context for subgraph execution events (starting, completed, and failed). Consumers of these events can now access the specific input data and its type, the output data and its type upon completion, and the original exception in case of failure, in addition to the existing execution info and agent context.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/subgraph · high confidence

Support for A2A message metadata storage and retrieval

Users can now attach and access A2A-specific metadata (such as message, context, and task IDs) within message metadata fields. This change introduces the MessageA2AMetadata data class and helper functions to serialize and deserialize this information, enabling better tracking and correlation of messages in A2A agent interactions.

agents-features-a2a-core · high confidence

Support for multi-choice LLM responses with selectable strategies

The agent framework now supports generating multiple response choices from the LLM and selecting one based on a configurable strategy. This is enabled by new DSL nodes (\nodeLLMSendResultsMultipleChoices\ and \nodeSelectLLMChoice\) that allow agents to send tool results and request multiple LLM outputs, then apply a \ChoiceSelectionStrategy\ (defaulting to picking the first choice) to determine the final assistant message. A specialized \PromptExecutorWithChoiceSelection\ wraps the standard executor to handle this multi-choice generation and selection flow transparently.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/ext/llm · high confidence

Tool execution metadata side channel and enhanced parameter schema support

Agents can now pass arbitrary context (such as tracing IDs or feature flags) to tool execution via the new ToolCallMetadata side channel, which is threaded into Tool.execute without affecting the LLM-serialized argument schema. Tool parameter schemas have been expanded to support null types, anyOf unions (with a specific hack to represent type unions like \[string, null\] for providers that require it), and object parameters with required properties and additionalProperties configuration. Additionally, the ToolRegistry API has been refactored to use a builder pattern with a new builder() factory method, replacing the previous Builder inner class, and introduces a getToolOrNull method for safer tool lookup.

agents-tools · high confidence

Tool execution now supports per-call metadata

The agents-tools module now allows tools to receive additional per-call metadata alongside their standard typed arguments. This metadata is passed via a side channel, meaning it is not part of the tool's argument schema and is not serialized to the LLM. This enables caller- and feature-contributed context to be available during tool execution without affecting the prompt sent to the model.

agents/agents-tools · high confidence

Removals

Removal of JVM-specific tool execution extension functions

The JVM-specific file \AIAgentLLMWriteSession.jvm.kt\ has been removed, eliminating extension functions that allowed direct invocation of tools via Kotlin reflection (\KFunction\). This removes the \findTool\, \callTool\, \toParallelToolCalls\, \toParallelToolCallsRaw\, \emitParallelToolCalls\, and \emitParallelToolCallsRaw\ APIs from the \AIAgentLLMWriteSession\ class, meaning users can no longer execute tools by passing function references directly in this session context.

agents/agents-core/src/jvmMain/kotlin/ai/koog/agents/core/agent · high confidence

Removal of MultiLLMPromptExecutor and SingleLLMPromptExecutor classes

The \MultiLLMPromptExecutor\ and \SingleLLMPromptExecutor\ classes, along with their associated test suite (\LLMPromptExecutorMockTest\), have been removed from the \prompt-executor-llms\ module. This change eliminates the previous implementation that routed prompts to specific LLM clients based on provider maps or single-client delegation, indicating a structural shift in how prompt execution is handled within the library.

prompt/prompt-executor/prompt-executor-llms · high confidence

Removal of SafeToolFromCallable wrapper

The \SafeToolFromCallable\ class and its associated \Result\ sealed interface have been removed from the JVM agent environment. This eliminates the previous abstraction layer that wrapped Kotlin callables (\KFunction\) for tool execution, meaning users can no longer utilize this specific wrapper to safely invoke tools within the environment.

agents/agents-core/src/jvmMain/kotlin/ai/koog/agents/core/environment · high confidence

Removal of agents-features-common module

The agents-features-common module has been removed from the codebase. This deletion eliminates the shared infrastructure previously provided for agent features, including the feature configuration framework, message and event system, I/O utilities, and client/server architecture components. Users relying on this module for common agent feature implementation must migrate to the new location where this logic has been moved.

agents/agents-features/agents-features-common · high confidence

Removal of deprecated agent factory functions and strategies

The \simpleChatAgent\, \simpleSingleRunAgent\, \chatAgentStrategy\, and \singleRunStrategy\ functions have been removed from the \agents-ext\ module. This change eliminates the legacy convenience constructors and graph-based strategies that previously handled basic chat and single-run agent configurations, requiring users to migrate to the current agent creation and strategy APIs.

agents/agents-ext/src/commonMain/kotlin/ai/koog/agents/ext/agent · high confidence

Removal of legacy event handling and remote messaging infrastructure

The \EventHandler\ feature, which allowed users to register callbacks for agent lifecycle, strategy, node, LLM, and tool events, has been removed along with its configuration class and associated tests. Additionally, the common feature infrastructure for remote communication has been deleted, including the \FeatureMessage\ types, \FeatureMessageProcessor\, and the \FeatureMessageRemoteServer\ (with its SSE/HTTP endpoints and platform-specific engine implementations) and \FeatureMessageRemoteClient\. The \MemoryBasedHistoryCompression\ strategy for retrieving facts from history has also been removed.

(repo-wide) · high confidence

Removal of legacy feature event type definitions

The file defining the legacy \DefinedFeatureEvent\ sealed class and its specific event data classes (such as \AIAgentStartedEvent\, \LLMCallStartEvent\, and \ToolCallEvent\) has been removed from the \agents-core\ module. This change eliminates the old event model structure, indicating that these specific event types are no longer part of the public API or internal implementation in this location, likely replaced by a newer event schema or moved to a different module.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/model · high confidence

Removal of reflection-based tool implementation

The \ToolFromCallable\ class and its associated reflection utilities in \agents/agents-tools/src/jvmMain\ have been removed. This eliminates the ability to dynamically create tools from arbitrary Kotlin callables (functions/methods) using reflection, requiring users to adopt the library's new serialization API and class-based tool definitions instead.

agents/agents-tools/src/jvmMain · high confidence

API

Publishes agents-core public API surface for multiplatform and JVM

The agents-core module now publishes its stable public API definitions for consumers. This includes the Klib ABI dump for multiplatform targets (iOS, JS, WASM) and the standard API dumps for Android and JVM. These files expose the public interfaces, classes, and functions available in the agents-core library, allowing downstream projects to verify binary compatibility and understand the available agent building blocks, strategies, and service configurations.

agents/agents-core/api · high confidence

Tracing feature API stabilization and event naming updates

The \agents-features-trace\ module now exposes its public API via new ABI dump files for JVM, Android, and multiplatform targets, formally publishing the \Tracing\ feature, \TraceFeatureConfig\, and message writers (\TraceFeatureMessageLogWriter\, \TraceFeatureMessageFileWriter\, \TraceFeatureMessageRemoteWriter\). The module's documentation has been updated to reflect a shift in event naming conventions, changing from \\*StartEvent\/\\*EndEvent\ patterns to \\*StartingEvent\/\\*CompletedEvent\ patterns (e.g., \LLMCallStartingEvent\, \ToolExecutionCompletedEvent\). Additionally, the example configuration demonstrates a refined approach to filtering trace messages, using \setMessageFilter\ on the file writer instance to selectively capture specific execution events.

agents/agents-features/agents-features-trace · high confidence

Behavioural changes

1 commit (0 fixes) modifying examples/spring-io-2026/kotlin, kotlin

A change to existing behaviour in examples/spring-io-2026/kotlin, kotlin — 1 commit, 13 files: “example: Add Kotlin and Java examples for Spring I/O 2026 (\#1846)” (refs \#1846).

examples/spring-io-2026/kotlin, kotlin · medium confidence · unverified

Added iOS build stub for ACP feature module

A stub class has been added to the ACP feature module to satisfy iOS build requirements when the commonMain source set is not explicitly configured, ensuring the module can be published for the iOS target.

agents/agents-features/agents-features-acp/src/commonMain/kotlin/ai/koog/agents/features/acp · high confidence

Added iOS build stub for chat history module

A stub class was added to the chat history AWS module to resolve publishing issues for the iOS target when no commonMain source set is configured.

agents/agents-features/agents-features-chat-history-aws/src/commonMain/kotlin/ai/koog/agents/features/chathistory · medium confidence

Added iOS publishing stub to koog-agents-additions

A new Stub class has been added to the koog-agents-additions module to resolve publishing issues for the iOS target when commonMain is not explicitly set.

koog-agents-additions · high confidence

Added iOS stub and ABI dumps to support iOS publishing

The koog-agents module now includes a stub class in commonMain to satisfy iOS target publishing requirements when no commonMain code is present, alongside new API dump files for JVM, Klib (covering iOS, JS, and WASM targets), and Android. This change ensures the library can be successfully compiled and published for iOS platforms without exposing internal implementation details in the public API.

koog-agents · high confidence

Build infrastructure migrated to convention-plugin-ai with Kotlin 2.3 and JVM 17 defaults

The build configuration for the AI module has been consolidated into the new convention-plugin-ai directory, replacing the previous buildSrc setup. This migration enforces Kotlin 2.3 language and API versions, raises the JVM target and Java compiler compatibility to version 17, and introduces a centralized configuration for source sets, ABI validation, and Dokka documentation links. The multiplatform setup now supports iOS, Android, JVM, JS, and optional WasmJs targets, with Android publishing configured to release variants and a minimum SDK of 23. Additionally, the test infrastructure has been refactored to support parallel execution for JVM tests, and the available test types have been updated to include Ollama-specific tests while removing performance and GPU variants.

convention-plugin-ai · high confidence

CachedPromptExecutor adopts new Message architecture and tool-aware caching

The CachedPromptExecutor now integrates with the updated Message architecture, returning a single Message.Assistant instead of a list of responses, and supports tool-aware caching by including ToolDescriptor lists in cache keys. It also introduces a configurable clock for timestamp-based cache validation, delegates model resolution and JSON schema generation to the nested executor, and implements AutoCloseable to properly clean up resources.

prompt/prompt-executor/prompt-executor-cached · high confidence

Chat memory feature replaces legacy AgentMemory with conversation history management

The agents-features-memory module now provides a new ChatMemory feature that manages conversation history for AI agents, replacing the previous AgentMemory capability. This change introduces a ChatHistoryProvider interface for storing and loading message lists by conversation ID, with an included InMemoryChatHistoryProvider for testing and prototyping. Users can configure message history via ChatMemoryConfig, which supports adding preprocessors to transform messages before storage or retrieval. Two built-in preprocessors are provided: WindowSizePreProcessor to limit history to the most recent N messages, and FilterMessagesPreProcessor to keep only messages matching a predicate. The feature integrates with functional, graph, and planner agent pipelines and includes comprehensive Kotlin and Java tests demonstrating its usage.

agents/agents-features/agents-features-memory · high confidence

Consolidates event handler configuration into a single abstract class

The event handler configuration has been refactored to replace the previous API and implementation split with a single abstract class. This change simplifies the configuration structure for non-JVM platforms, ensuring that the EventHandlerConfig is now defined as a single actual class that extends the common base, reducing complexity in how event handler settings are managed across different environments.

agents/agents-features/agents-features-event-handler/src/nonJvmCommonMain/kotlin/ai/koog/agents/features/eventHandler · medium confidence

Debugger feature moved to agents-core with strict event filtering and connection configuration

The Debugger feature has been relocated to the agents-core module, introducing a new DebuggerConfig class that allows users to configure the remote server port and the timeout for the initial connection. To ensure the integrity of the execution sequence required for debugging, the feature now strictly prohibits event filtering; attempting to apply a filter will throw an UnsupportedOperationException. Additionally, a new DebuggerFeatureMessageRemoteWriter handles the remote transmission of debug messages to the configured server.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/debugger · high confidence

Embedder tests now cover multiple providers and LLMEmbedder gains batch support

The test suite for LLMEmbedder has been consolidated and expanded: the previous Ollama-specific tests have been replaced by a unified LLMEmbedderTest that validates embedding and vector-diff operations across OpenAI, Ollama, and Google Gemini models. Additionally, the underlying LLMEmbedder implementation now supports batch embedding via the LLMEmbeddingProvider interface, allowing multiple inputs to be processed in a single call.

embeddings/embeddings-llm · high confidence

EventHandler API adopts context-based callbacks and unified agent builder

The EventHandler feature now uses a context-based callback model where event handlers (such as onAgentStarting, onAgentCompleted, onLLMCallStarting, and onToolCallCompleted) receive a typed event context object instead of individual arguments, providing structured access to details like agent IDs, tool names, and results. Additionally, the agent construction API has been unified from the AIAgents builder to the AIAgent builder, and the module documentation has been updated to reflect these naming and structural changes.

agents/agents-features/agents-features-event-handler · high confidence

File prompt cache now stores single assistant messages instead of response lists

The file-based prompt cache implementation has been updated to align with the new message architecture. Cache entries now store a single \Message.Assistant\ object rather than a list of \Message.Response\ objects, and the request key is derived from the new \PromptCache.Request\ model. This change simplifies the cached data structure and removes the previous logic for serializing tool descriptors into JSON objects for cache keys.

prompt-cache-files · high confidence

File, search, and shell tools refactored with new serialization and API patterns

The file, search, and shell tool implementations in \agents-ext\ have been rewritten to use the new library-agnostic serialization API and \SimpleTool\ base class. This introduces token-normalized patching for the \EditFileTool\ (allowing fuzzy whitespace/case matching), adds user confirmation and timeout handling to \ExecuteShellCommandTool\, and improves \ReadFileTool\ with line-range clamping and warnings. Additionally, \ListDirectoryTool\ now handles empty filters, \RegexSearchTool\ is restructured for better pagination, and service tools (\AskUser\, \ExitTool\, \SayToUser\) are simplified with auto-generated descriptors and \LLMDescription\ annotations.

agents-ext · high confidence

Improved handling of malformed tool calls from weak models

The prompt processor now includes a new \ToolJsonFixProcessor\ and associated prompt templates to detect and repair tool call messages that are malformed, contain invalid JSON, or use incorrect tool names. This change specifically addresses issues where weak models return intent-based messages (e.g., "I will search for that") instead of structured tool calls, or produce syntactically incorrect JSON. The system now attempts to parse these messages using flexible heuristics and regex patterns to extract tool names and arguments, correcting common formatting errors like unescaped characters or missing quotes, and providing feedback to the model to retry with the correct format.

prompt-processor · high confidence

Improved streaming tool call handling for OpenAI and other providers

The chat starter now correctly handles incremental tool call arguments during streaming, particularly for OpenAI where arguments arrive in fragments. A new assembler buffers these partial JSON fragments and reassembles them before emission, while providers like Anthropic and Google continue to emit complete tool calls immediately. This ensures consistent and accurate tool call data is passed to the application regardless of the underlying LLM provider's streaming behavior.

koog-spring-ai-starter-model-chat · high confidence

Introduce unified AIAgentBuilder and AIAgentService APIs

The agent construction API has been refactored to use a new fluent builder pattern. Users now configure agents via \AIAgentBuilder\ (with \graphStrategy\, \functionalStrategy\, and \plannerStrategy\ entry points) or \AIAgentServiceBuilder\ for managing multiple agent instances. This replaces previous factory methods and direct constructors, providing a consistent way to set up prompts, models, tools, and features across graph, functional, and planner agent types.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core · high confidence

Introduces history compression and multi-LLM support in the code-agent example

The code-agent example now supports multi-LLM execution by using a combined OpenAI and Anthropic prompt executor, allowing the agent to leverage different models for different tasks. It also introduces a single-run strategy with automatic history compression to manage context window limits; when the conversation exceeds 200 messages or 200k characters, the system compresses the history by extracting key facts (such as project structure, dependencies, and current status) using a dedicated retrieval model. This change improves the agent's ability to handle long-running coding tasks without losing context, while maintaining observability through OpenTelemetry and Langfuse integration.

examples/code-agent/step-05-history · high confidence

Ktor HTTP client factory registered via JVM ServiceLoader

The Ktor-based HTTP client implementation is now discoverable through the standard JVM ServiceLoader mechanism. A new service provider configuration file registers the \KtorKoogHttpClient.Factory\, and corresponding tests verify that the factory can be resolved automatically and instantiated reflectively, ensuring seamless integration with the LLM client abstraction layer.

http-client/http-client-ktor · high confidence

LLM provider model definitions and provider hierarchy refactored

The predefined model constants previously located in OllamaModels.kt (such as Meta's LLAMA\_3\_2 and Alibaba's QWQ) have been removed from this module. Concurrently, the LLMProvider class has been changed from a sealed hierarchy to an open class, with specific provider instances (e.g., OpenAI, Anthropic, Google, Meta, Alibaba, OpenRouter, Ollama, Bedrock, DeepSeek, MistralAI) now defined as properties in the companion object. A new extension function, toModelInfo(), has been added to LLModel to convert model instances into a standardized ModelInfo structure containing provider, model ID, display name, context length, and max output tokens.

prompt/prompt-llm · high confidence

Major prompt-model API overhaul: unified message parts, streaming frames, and expanded LLM parameters

The prompt-model module has been significantly refactored to support more flexible and detailed LLM interactions. Messages now use a unified \parts\ list (replacing single content strings) to preserve the order of text, reasoning, tool calls, and attachments, with new \MessagePart\ types and a \textContent()\ helper. Streaming responses are now modeled via a new \StreamFrame\ sealed interface supporting text, reasoning, and tool call deltas/completions, with a \StreamFrameFlowBuilder\ to handle chunking. \LLMParams\ has expanded to include \maxTokens\, \numberOfChoices\, \user\, and \additionalProperties\, with input validation. New \Attachment\ types (Image, Video, Audio, File) and \ModerationCategory\ definitions have been added to the DSL.

prompt-model · high confidence

Markdown and XML builders now accept TextContentBuilderBase

The \markdown\ and \xml\ extension functions in the prompt modules now accept \TextContentBuilderBase\<\*\>\ instead of the concrete \TextContentBuilder\. This change allows these builders to be used in a wider range of contexts where a base text content builder is available, improving composability. The update also includes minor syntax cleanups in the DSL usage (e.g., removing unnecessary parentheses in lambda arguments) and formatting fixes in the associated tests.

prompt/prompt-markdown, prompt/prompt-xml · high confidence

New LLM call event context types with execution info and moderation support

The LLM handler now exposes richer context objects for agent lifecycle events. LLMCallStartingContext, LLMCallFailedContext, and LLMCallCompletedContext all include AgentExecutionInfo and a runId for session tracking, while LLMCallCompletedContext additionally provides the assistant response and any moderation result. This enables users to correlate LLM calls, access execution metadata, and inspect moderation outcomes in event handlers.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/llm · high confidence

New agent lifecycle event contexts with execution info and event IDs

The agent feature handler now exposes a set of specific context objects (AgentStartingContext, AgentCompletedContext, AgentExecutionFailedContext, AgentClosingContext, and AgentEnvironmentTransformingContext) that extend the base AgentEventContext. These contexts provide richer information for event handling, including the associated AIAgent instance, the AIAgentContext, a runId, and crucially, AgentExecutionInfo and a unique eventId. This allows users implementing custom agent event handlers to access detailed execution metadata and traceability for each agent lifecycle stage.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/agent · high confidence

New file and shell tool utilities with safer reading and confirmation workflows

This change introduces new utility implementations for the agent's file and shell tooling. For file operations, a new directory listing utility now builds directory trees with glob pattern support and collapses single-child directory chains to simplify output. The file reading utility now automatically clamps line ranges to the actual file length and invokes a callback when an overflow occurs, preventing errors on out-of-bounds requests. Additionally, a text rendering module standardizes how file entries and content are displayed, including syntax highlighting for code. For shell operations, new confirmation handlers allow agents to either bypass user approval in 'Brave mode' or prompt the user via console input before executing commands, adding a layer of safety and control.

agents/agents-ext/src/commonMain/kotlin/ai/koog/agents/ext/tool · high confidence

New tool call event context types with execution info

The tool handler now exposes a richer event context for tool lifecycle events. A new \ToolCallEventContext\ interface and its implementations (\ToolCallStartingContext\, \ToolValidationFailedContext\, \ToolCallFailedContext\, \ToolCallCompletedContext\) are introduced, each carrying \AgentExecutionInfo\ (providing parent ID and execution path) alongside standard tool details like name, arguments, and results. This allows users observing tool events to access detailed execution tracing and specific error or result data for each tool call stage.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/tool · high confidence

Non-JVM platform implementations for persistence and rollback tool registry

This change introduces platform-specific implementations for the non-JVM common code in the agents snapshot feature. For persistence, a new \PersistenceBlocking.kt\ file ensures that blocking execution strategies throw an \UnsupportedOperationException\ on non-JVM targets, clarifying that this capability is JVM/Android-only. Additionally, the \RollbackToolRegistryBuilder\ is now implemented as an actual open class for non-JVM platforms, inheriting from the common base and providing the necessary \self()\ method to support the rollback tool registry builder abstraction across different targets.

agents/agents-features/agents-features-snapshot/src/nonJvmCommonMain · high confidence

OpenTelemetry feature rewritten for Kotlin Multiplatform with new attribute model

The OpenTelemetry integration has been migrated to Kotlin Multiplatform, introducing a new, structured attribute system that replaces previous implementations. This change adds comprehensive support for OpenTelemetry GenAI semantic conventions (covering agent, provider, conversation, and tool attributes), standard vendor-neutral attributes (error, server), and Koog-specific namespaces (node, subgraph, strategy, moderation, tool). It also introduces Model Context Protocol (MCP) attribute support and a new internal OTLP/JSON data model for exporting traces. For users, this means telemetry data is now emitted with richer, standardized context and is compatible with Kotlin Multiplatform targets.

agents-features-opentelemetry · high confidence

Prompt cache API updated to use Request objects and Assistant messages

The prompt cache interface has been refactored to accept a new \PromptCache.Request\ object instead of separate prompt and tool lists, and now returns a single \Message.Assistant\ instead of a list of \Message.Response\. This change simplifies cache key generation by serializing the request content and ensures that timestamp metadata is correctly handled via the new \KoogClock\ abstraction. Additionally, validation for the in-memory cache size limit now strictly rejects negative numbers, ensuring only positive values or 'unlimited' are accepted.

prompt-cache-model · high confidence

Prompt cache API updated to use new Message architecture and request model

The file-based prompt cache now uses the new Message architecture, changing the stored response type from a list of messages to a single assistant message and updating the request model to use the new PromptCache.Request class. This aligns the cache implementation with the broader message system changes, ensuring consistent handling of prompt responses and request identification.

prompt/prompt-cache/prompt-cache-files · high confidence

RAG storage layer refactored into modular base and vector components

The RAG system's storage architecture has been restructured to separate core abstractions from vector-specific implementations. The new \rag-base\ module introduces a set of specialized interfaces—\LookupStorage\, \WriteStorage\, \DeletionStorage\, and \SearchStorage\—along with supporting types like \DocumentWithPayload\, \TextDocument\, and \DocumentProvider\ to handle document metadata, file system interactions, and search requests. The \rag-vector\ module now builds upon this foundation, providing the \VectorStorage\ interface and \EmbeddingStorage\ implementation to enable semantic search via vector embeddings. This change provides a consistent, implementation-agnostic API for document management, allowing different storage backends to be used interchangeably while maintaining a unified interface for retrieval operations.

rag · high confidence

Redis prompt cache adopts new message architecture and fixes TTL handling

The Redis-based prompt cache has been updated to align with the new Message architecture, changing its interface to accept and return \Message.Assistant\ instead of \List\<Message.Response\>\, and using \PromptCache.Request\ for cache keys. A Java-compatible constructor accepting \java.time.Duration\ for the TTL parameter has been added. Additionally, the cache now correctly handles timestamps for cache entries, resolving issues where TTLs were not applied properly.

prompt-cache-redis · high confidence

Refactor JVM-specific MCP transport and tool execution logic

The JVM-specific implementation for connecting to Model Context Protocol (MCP) servers has been restructured. The previous \McpToolRegistryProvider\ object, which handled both standard I/O and Server-Sent Events (SSE) transports, has been replaced by a new \McpToolRegistryProvider.jvm.kt\ file that provides JVM-specific helpers for creating \StdioClientTransport\ instances from a \Process\. Additionally, the \McpTool\ class and \McpToolDefinitionParser\ have been removed from this location, indicating that the direct tool execution and descriptor parsing logic has been moved or consolidated elsewhere in the codebase.

agents/agents-mcp/src/jvmMain · high confidence

Refactor feature message processing API and introduce event tracking

The feature message processing system has been restructured to support event tracking and filtering. A new \FeatureEvent\ interface extends \FeatureMessage\ to include a unique \eventId\, enabling better correlation of system events. The \FeatureMessageProcessor\ now exposes a configurable \messageFilter\ property, allowing users to selectively process specific message types (e.g., filtering for LLM call events) before they are handled. Additionally, internal utility methods for safe message processing have been renamed (\onMessageSafe\ to \onMessageCatching\) and moved to the core module, standardizing how messages are caught and logged during processing.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/message · high confidence

Refactor remote server connection configuration

The remote server connection configuration has been restructured to support more flexible setup. A new abstract \ServerConnectionConfig\ base class and a \DefaultServerConnectionConfig\ implementation now expose configurable properties for host (defaulting to 127.0.0.1), port (defaulting to 50881), and a new \awaitInitialConnection\ flag with a 300-second timeout, allowing the server to optionally wait for the first client connection before proceeding. The previous \AIAgentFeatureServerConnectionConfig\ class has been removed as part of this consolidation.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/remote/server/config · high confidence

Refactored agent pipeline architecture with new feature installation API

The agent pipeline has been restructured to separate concerns into distinct pipeline types: \AIAgentFunctionalPipeline\ for non-graph workflows, \AIAgentGraphPipeline\ for graph-based execution, and \AIAgentPlannerPipeline\ for planner agents. Each pipeline type now exposes a specific \install\ method that accepts its corresponding feature type (e.g., \AIAgentFunctionalFeature\, \AIAgentGraphFeature\, \AIAgentPlannerFeature\) along with a configuration lambda, replacing the previous generic installation mechanism. This change introduces a more type-safe and explicit way to add features to the appropriate pipeline context, while the underlying \AIAgentPipelineImpl\ handles the core feature registration and lifecycle management.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/pipeline · high confidence

Refactored remote client connection configuration and moved to agents-core

The \ClientConnectionConfig\ class and its related configuration logic have been moved from the \agents-features-common\ module to \agents-core\, centralizing remote client connection settings. The base \ClientConnectionConfig\ class has been refactored to use nullable parameters for protocol, headers, and timeouts, with defaults applied via a companion object (e.g., defaulting to HTTPS) rather than constructor arguments, allowing for more flexible configuration. A new \DefaultClientConnectionConfig\ implementation has been added to provide sensible defaults (localhost:50881, 5s request timeout, 15s connect timeout), replacing the previous \AIAgentFeatureClientConnectionConfig\ which is now removed. This change simplifies client connection initialization by offering a standardized default configuration while maintaining the ability to customize specific connection parameters.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/remote/client/config · high confidence

Refactored tool serialization to use a new schema generator interface

The internal implementation for serializing tool descriptors has been restructured to support a library-agnostic serialization API. The previous custom serialization logic, including the \ToolResultStringSerializer\ and the \ToolSerialization\ module (which handled JSON encoding via \kotlinx.serialization\), has been removed. In its place, a new \ToolDescriptorSchemaGenerator\ interface has been introduced, allowing tool descriptors to be converted into a JSON object representation through a pluggable generator rather than hardcoded serialization rules.

agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools/serialization · high confidence

Remote client connection state is now reactive

The \FeatureMessageClient\ interface and its \FeatureMessageRemoteClient\ implementation have been moved to the \agents-core\ module and updated so that the connection status is exposed as a reactive \StateFlow\<Boolean\>\ instead of a static \Boolean\. This allows consumers to observe connection state changes in real-time rather than polling a single snapshot. The implementation also removes the platform-specific \expect\ engine factory, defaulting to a standard \HttpClient\ instance, and refactors internal header handling to use \appendAll\.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/remote/client · high confidence

Remote feature serialization configuration and module consolidation

The remote feature's JSON serialization logic has been consolidated into the \agents-core\ module, introducing a preconfigured \Json\ instance (\defaultFeatureMessageJsonConfig\) that enables pretty printing, ignores unknown keys, and omits null fields to ensure robust backward and forward compatibility for remote communication. This configuration registers a comprehensive \SerializersModule\ capable of polymorphically serializing and deserializing a wide range of agent lifecycle, strategy, node, tool, and LLM events (including new streaming events like \LLMStreamingFrameReceivedEvent\), and the \ConnectionConfig\ class has been moved to this new location to utilize these shared serialization settings.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/remote · high confidence

Remote server now waits for initial client connection before proceeding

The remote feature message server now supports a configuration flag to pause execution until the first client connects. When the \awaitInitialConnection\ option is enabled in the server configuration, the server will block after starting until a client establishes a connection, ensuring that the server is ready to receive messages before the agent continues. This change is implemented in the \FeatureMessageRemoteServer\ class within the \agents-core\ module, which also includes the server implementation and the \FeatureMessageServer\ interface.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/remote/server · high confidence

Removal of legacy buildSrc Gradle convention plugins

The buildSrc module has removed three Kotlin Gradle plugin scripts: ai.kotlin.configuration (which set JVM toolchains, language versions, and compiler options), ai.kotlin.dokka (which configured documentation generation and source links), and ai.kotlin.jvm (which registered JVM test tasks and applied the above plugins). This change eliminates these specific build conventions from the project's source code, likely as part of a broader migration to a different build configuration strategy.

buildSrc · high confidence

Rename LLMDescription annotation property to 'value' for Java compatibility

The \LLMDescription\ annotation's primary property has been renamed from \description\ to \value\. This change improves compatibility with Java consumers of the library, as Java does not support named arguments for annotations. Additionally, the \@SerialInfo\ annotation from kotlinx.serialization has been added to the class, and redundant \AnnotationTarget.PROPERTY\ targets have been removed from the \@Target\ declaration.

agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools/annotations · high confidence

Simplified multi-provider executors and added AWS Bedrock support

The \prompt-executor-llms-all\ module now provides simplified \simple\*Executor\ convenience functions for OpenAI, Azure OpenAI, Anthropic, OpenRouter, Google AI, Ollama, Mistral AI, and AWS Bedrock, all returning a \MultiLLMPromptExecutor\ instead of the previous \SingleLLMPromptExecutor\. These functions accept an explicit \KoogHttpClient.Factory\ on common platforms, while JVM/Android builds offer additional overloads that automatically resolve the default HTTP client factory. AWS Bedrock is now supported via \simpleBedrockExecutor\ (using static credentials) and \simpleBedrockExecutorWithBearerToken\. The legacy \DefaultMultiLLMPromptExecutor\ class has been removed in favor of the new \MultiLLMPromptExecutor\ constructor, and tests have been updated to reflect the new message and streaming APIs.

prompt/prompt-executor/prompt-executor-llms-all · high confidence

Stub class added for iOS publishing compatibility

A stub class has been added to the long-term memory AWS module to satisfy publishing requirements for the iOS target when no commonMain is set, ensuring the module can be published correctly without build errors.

agents/agents-features/agents-features-longterm-memory-aws/src/commonMain/kotlin/ai/koog/agents/features/longtermmemory · high confidence

Support for complex MCP tool parameter schemas

The agents-mcp module now correctly parses advanced JSON Schema structures in Model Context Protocol (MCP) tool definitions. Users can now utilize tools that define parameters using \anyOf\ (allowing multiple types), \null\ types, \$ref\ references for schema reuse, and nested object properties with \additionalProperties\. This ensures that complex tool schemas are accurately translated into the agent framework's internal tool descriptors, preventing errors when interacting with MCP servers that use these advanced schema features.

agents-mcp · high confidence

Tool execution now supports per-call metadata and serialization is unified

The tool execution contract has been updated to thread per-call context (such as tracing span IDs) into the execution flow via a new \ToolCallMetadata\ side channel, allowing features to inject cross-cutting information without altering the tool's argument schema. Additionally, the tool API has been refactored to use a library-agnostic serialization system, replacing the previous \Tool.Args\ and \ToolResult\ types with generic \TypeToken\-based encoding and decoding, and the \ToolDescriptor\ is now serializable to support consistent tool definition handling.

agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools · high confidence

Unified ToolRegistryBuilder and non-JVM schema generation for agents

The \ToolRegistryBuilder\ is now implemented as an \expect/actual\ class, providing a unified builder API for registering tools across all platforms, which resolves previous issues where \tools(Any)\ interfered with \tools(List)\. Additionally, a new \SchemaGenerator\ implementation for non-JVM platforms enables automatic JSON schema generation for \@Serializable\ classes or explicit \KSerializer\ instances, ensuring consistent tool schema support outside the JVM.

agents/agents-tools/src/nonJvmCommonMain · high confidence

Unified event handler configuration with append-only API

The EventHandler feature now uses a consolidated \EventHandlerConfig\ class that exposes a fluent, append-only API for registering callbacks across the entire agent lifecycle. Users can now attach handlers for agent, strategy, node, subgraph, LLM call, tool, and streaming events using dedicated methods (e.g., \onAgentStarting\, \onToolCallCompleted\, \onLLMStreamingFrameReceived\). This change replaces previous fragmented configuration approaches with a single entry point that supports chaining multiple handlers for the same event type, simplifying the setup of event-driven agent behaviors.

agents/agents-features/agents-features-event-handler/src/commonMain/kotlin/ai/koog/agents/features/eventHandler/feature · high confidence

Unified message parts API with reasoning, caching, and streaming support

The prompt model now uses a unified list of content parts for messages, replacing the previous separate text and attachments fields. This change introduces builders for constructing request and response message parts, supporting text, images, audio, video, and files. It adds native support for reasoning messages (including deltas and summaries) and cache control configurations for prompt caching. The streaming API is updated to handle these new part types, including reasoning and tool calls, and includes robust error handling for incomplete streams.

prompt/prompt-model · high confidence

Updated persistence blocking implementation to use reentrant concurrency model

The JVM/JS common implementation for blocking persistence operations now utilizes the reentrant concurrency model (runBlockingReentrant) instead of the previous standard blocking mechanism. This change improves compatibility with Java interop scenarios by ensuring that blocking calls within the agent's strategy dispatcher do not deadlock when nested or reentrant execution contexts are involved.

agents/agents-features/agents-features-snapshot/src/jvmCommonMain · high confidence

Updated test executor to use new Message architecture and Tool API

The test implementation in CalculatorPromptExecutor and CalculatorTools has been updated to align with the new Message architecture and Tool API. CalculatorPromptExecutor now returns a single Message.Assistant object containing MessagePart.Tool.Call instances instead of a list of Message.Response objects, and utilizes the new KoogClock for timestamping. CalculatorTools has been refactored to use the new Tool base class constructor with explicit type tokens and LLMDescription annotations for argument descriptions, removing the manual ToolDescriptor definition.

agents/agents-core/src/commonTest/kotlin/ai/koog/agents/core · high confidence

Writer state exposure changed from Boolean to StateFlow

The \FeatureMessageFileWriter\ in \agents-core\ now exposes its open/closed status via a reactive \StateFlow\<Boolean\>\ instead of a simple \Boolean\. This allows consumers to observe state changes asynchronously, and internal checks for initialization and locking now access the current value via \.value\.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/writer · high confidence

Fixes

Add platform-specific error type name retrieval for AIAgentError

The AIAgentError model now includes platform-specific logic to retrieve the class name of a Throwable. On JVM platforms, it returns the fully qualified class name, while on non-JVM platforms, it returns the simple class name. This enhancement allows for more precise error identification and debugging across different execution environments.

agents/agents-core/src/jvmCommonMain/kotlin/ai/koog/agents/core/feature/model, agents/agents-core/src/nonJvmCommonMain/kotlin/ai/koog/agents/core/feature/model · high confidence

Fix tool schema generation for nested nullable objects

The schema generator in the agents tools module now correctly handles nested nullable objects when creating tool descriptors. This fix ensures that complex argument types with optional nested structures are accurately represented in the generated JSON schema, preventing errors or incorrect tool definitions when agents interact with tools requiring such parameters.

agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools/schema · high confidence

Unified tool registration and reflection-based tool discovery

The tool registration API has been consolidated into a single \ToolRegistryBuilder\ class, removing the previous \ToolRegistry.Builder\ and the conflicting \tools(Any)\ overload to prevent registration errors. Additionally, reflection-based tool discovery now correctly respects the \customName\ attribute from the \@Tool\ annotation when converting Kotlin functions or Java methods into tools, ensuring that explicitly named tools are registered with their intended identifiers rather than defaulting to the function name.

agents/agents-tools/src/jvmCommonMain · high confidence

Test coverage

Add tests for Streamable HTTP transport and nullable tool parameters; Added A2A protocol compliance test suite and test utilities; Added A2A server integration and stress tests; Added CapturingLLMClient test double for LLM interactions; Added JVM tests for HTTP JSON-RPC server transport; Added JVM tests for Java method tool reflection and schema generation; Added JVM tests for Java-friendly agent APIs and graph strategies; Added JVM tests for LongTermMemory ingestion, retrieval, and storage; Added JVM tests for OpenTelemetry agent span collection; Added JVM tests for OpenTelemetry metrics collection; Added JVM tests for agent feature events, pipeline configuration, and tool call failures; Added JVM tests for file tool utilities and tool implementations; Added JVM tests for shell command execution tool; Added JVM-specific mock OpenTelemetry components for testing; Added JVM-specific tests for OpenTelemetry attribute conversion; Added TCK test server implementation for A2A compliance testing; Added and updated tests for reflective tool execution and serialization; Added comprehensive tests for the Agent Event Handler feature; Added concurrency tests for AIAgentLLMContext; Added in-memory filesystem utility for tests; Added integration tests for A2A client JSON-RPC communication; Added integration tests for OpenTelemetry trace structure; Added integration tests for SQL persistence providers; Added mock test utilities for agent event collection and agent creation; Added mock test utilities for agent feature events; Added mock utilities for tracing feature tests; Added snapshot tests for agent persistence and checkpointing; Added test assertion helpers for filtering and validating pipeline events; Added test coverage for AIAgent generic types, service management, and streaming error handling; Added test infrastructure for KoogHttpClient implementations; Added test infrastructure for OpenTelemetry agent tracing; Added test utilities and data models for JVM tool testing; Added test utilities and refactored mock builder for tool execution; Added tests for AIAgentStorage; Added tests for AWS AgentCore chat history provider and message conversion; Added tests for AgentContextAwareTool metadata handling; Added tests for AgentExecutionInfo path construction; Added tests for Amazon Bedrock AgentCore long-term memory components; Added tests for Debugger feature configuration and event collection; Added tests for EditFileTool and file rendering logic; Added tests for FeatureMessageProcessor lifecycle and filtering; Added tests for InMemoryPromptCache behavior; Added tests for JDBC Chat History Provider implementations; Added tests for JDBC persistence storage provider; Added tests for JSON-RPC message serialization; Added tests for Java API blocking behavior and prompt XML injection safety; Added tests for Java-facing ToolRegistry API; Added tests for Koog tool integration with MCP server; Added tests for Kotlin and Java tool schema generation; Added tests for LLM choice selection strategies; Added tests for LLM description annotation handling and ToolCallMetadata behavior; Added tests for LLMAsJudgeNode; Added tests for MCP tool descriptor parsing; Added tests for MockLLMBuilder capabilities; Added tests for OpenTelemetry feature configuration and span management; Added tests for OpenTelemetry response metadata handling; Added tests for OpenTelemetry span assertions and attribute handling; Added tests for Redis prompt cache expiration behavior; Added tests for RegexSearchTool; Added tests for ResultUtils; Added tests for SQL chat history providers; Added tests for agent configuration and tool call description logic; Added tests for agent environment metadata propagation and tool execution; Added tests for agent execution path construction; Added tests for agent execution strategies and subgraph behaviors; Added tests for agent node transformation and parallel node merging; Added tests for agent storage, Java API, and Mermaid diagram generation; Added tests for history compression and fact retrieval strategies; Added tests for sealed type output handling in subgraph finish tool; Added tests for structured output parsing and LLM write session management; Added tests for the MessageTokenizer feature; Added tests for the remote server feature; Added tests for tool schema generation with new serialization API; Added tests for tracing feature message writers; Added unit tests for A2A model serialization and concurrency utilities; Added unit tests for A2A server storage and session components; Added unit tests for AIAgentContext and LLM context behavior; Expanded test coverage for agent exceptions, token counting, and error handling; Migrate feature message writer tests to agents-core module; New Java integration test infrastructure and agent service coverage; New testing utilities for mocking agent contexts and LLM executors; Removed tests for remote server message handling; Updated agent DSL tests for new message architecture and parallel node execution; Updated agent pipeline tests to align with new event architecture and graph-based strategy API; Updated test utilities to align with new Agent and Tool APIs; Updated tests for new graph API and tool definitions; Updated tests for remote client connection state and new wait-connection flag; Updated tool serialization tests to reflect new descriptor generation and API changes.

Dependencies

Updated Gradle wrapper to version 8.14.3

The Gradle wrapper has been upgraded from version 8.2.1 to 8.14.3. This ensures that all builds use the newer Gradle distribution, which may include performance improvements, bug fixes, and new features available in the 8.14.x release line.

gradle · high confidence

Housekeeping

Added KDoc comments to Vector utility methods; Project documentation and development guidelines overhaul.

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 59 → 68 (+8.9)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.

Lenses

  • Code Health 79 → 78 (-0.9)
  • Architecture 88 → 88 (+0.0)
  • Maturity 72 → 77 (+5.1)
  • Readiness 43 → 63 (+19.1)
  • Security 75 → 67 (-8.1)
  • Performance 71 → 85 (+13.7)

Resolved (164)

  • Ambiguous extension function names in different modules. Both Jackson and Kotlinx serialization modules expose toKoogJSONElement() as an extension function on their respective JSON types. While technically distinct due to receiver types, this creates a confusing API where users must know which module's extension is in scope to convert to the common JSONElement.
  • Change coupling: AIAgentPipeline.kt ↔ Tracing.kt (agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/pipeline/AIAgentPipeline.kt)
  • Dependency hygiene PARTLY measured — Maven/Gradle declarations read, no dependency graph resolved
  • Documentation: no architecture or design documentation (README.md)
  • Duplicate conversion utilities with inconsistent naming and placement. TimeUtils provides static methods for Java/Kotlin Instant conversion, while TimeUtilsKt provides extension functions that do the same thing. The naming toJavaInstant vs toKotlinInstant is also inconsistent with the static method names fromJavaInstant/toJavaInstant.
  • Duplicated block (10 lines × 2) (agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/debugger/Debugger.kt)
  • Duplicated block (10 lines × 2) (agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/debugger/Debugger.kt)
  • Duplicated block (10 lines × 2) (agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/debugger/Debugger.kt)
  • Duplicated block (10 lines × 2) (examples/demo-compose-app/commonApp/src/commonMain/kotlin/com/jetbrains/example/koog/compose/agents/weather/OpenMeteoClient.kt)
  • Duplicated block (10 lines × 2) (http-client/http-client-spring-webclient/src/main/kotlin/ai/koog/http/client/spring/SpringWebClientKoogHttpClient.kt)
  • Duplicated block (10 lines × 2) (koog-spring-ai-v2/koog-spring-ai-v2-starter-chat-memory/src/main/kotlin/ai/koog/spring/ai/memory/SpringAiChatHistoryProvider.kt)
  • Duplicated block (10 lines × 2) (prompt/prompt-executor/prompt-executor-clients/prompt-executor-bedrock-client/src/jvmMain/kotlin/ai/koog/prompt/executor/clients/bedrock/converse/BedrockConverseConverters.kt)
  • Duplicated block (10 lines × 2) (prompt/prompt-executor/prompt-executor-model/src/commonMain/kotlin/ai/koog/prompt/executor/llms/MultiLLMPromptExecutor.kt)
  • Duplicated block (10–11 lines × 2) (prompt/prompt-executor/prompt-executor-clients/prompt-executor-deepseek-client/src/commonMain/kotlin/ai/koog/prompt/executor/clients/deepseek/DeepSeekParams.kt)
  • Duplicated block (11 lines × 2) (agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/debugger/Debugger.kt)
  • Duplicated block (11 lines × 2) (agents/agents-features/agents-features-opentelemetry/src/commonMain/kotlin/ai/koog/agents/features/opentelemetry/metric/events/histogramMetricEvents.kt)
  • Duplicated block (11 lines × 2) (http-client/http-client-java/src/main/kotlin/ai/koog/http/client/java/JavaKoogHttpClient.kt)
  • Duplicated block (11 lines × 2) (koog-spring-ai-v2/koog-spring-ai-v2-starter-model-chat/src/main/kotlin/ai/koog/spring/ai/chat/SpringAiLLMClient.kt)
  • Duplicated block (11 lines × 2) (koog-spring-ai-v2/koog-spring-ai-v2-starter-model-chat/src/main/kotlin/ai/koog/spring/ai/chat/SpringAiToolCallAssembler.kt)
  • Duplicated block (11 lines × 2) (prompt/prompt-executor/prompt-executor-clients/prompt-executor-deepseek-client/src/commonMain/kotlin/ai/koog/prompt/executor/clients/deepseek/DeepSeekLLMClient.kt)
  • …and 144 more

New (748)

  • Banned license: com.mysql:mysql-connector-j
  • Critical CVE: [GHSA redacted] (examples/spring-ai-java/pom.xml)
  • Critical CVE: [GHSA redacted] (examples/spring-io-2026/java/pom.xml)
  • Critical CVE: [GHSA redacted] (examples/spring-ai-java/pom.xml)
  • Critical CVE: [GHSA redacted] (examples/spring-boot-java/pom.xml)
  • Critical CVE: [GHSA redacted] (examples/spring-io-2026/java/pom.xml)
  • Critical CVE: [GHSA redacted] (examples/spring-ai-java/pom.xml)
  • Critical CVE: [GHSA redacted] (examples/spring-boot-java/pom.xml)
  • Critical CVE: [GHSA redacted] (examples/spring-io-2026/java/pom.xml)
  • Critical CVE: [GHSA redacted] (examples/spring-ai-java/pom.xml)
  • Critical CVE: [GHSA redacted] (examples/spring-io-2026/java/pom.xml)
  • Duplicated block (10 lines × 2) (agents/agents-features/agents-features-chat-history-jdbc/src/main/kotlin/ai/koog/agents/features/chathistory/jdbc/JdbcChatHistoryProvider.kt)
  • Duplicated block (10 lines × 2) (examples/demo-compose-app/commonApp/src/commonMain/kotlin/com/jetbrains/example/koog/compose/agents/weather/OpenMeteoClient.kt)
  • Duplicated block (10 lines × 2) (http-client/http-client-spring-webclient/src/main/kotlin/ai/koog/http/client/spring/SpringWebClientKoogHttpClient.kt)
  • Duplicated block (10 lines × 2) (prompt/prompt-executor/prompt-executor-clients/prompt-executor-bedrock-client/src/jvmMain/kotlin/ai/koog/prompt/executor/clients/bedrock/converse/BedrockConverseConverters.kt)
  • Duplicated block (10 lines × 2) (prompt/prompt-executor/prompt-executor-model/src/commonMain/kotlin/ai/koog/prompt/executor/llms/MultiLLMPromptExecutor.kt)
  • Duplicated block (10 lines × 3) (agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/debugger/Debugger.kt)
  • Duplicated block (10–11 lines × 2) (prompt/prompt-executor/prompt-executor-clients/prompt-executor-deepseek-client/src/commonMain/kotlin/ai/koog/prompt/executor/clients/deepseek/DeepSeekParams.kt)
  • Duplicated block (11 lines × 2) (agents/agents-features/agents-features-chat-memory-sql/src/jvmMain/kotlin/ai/koog/agents/features/chatmemory/sql/H2ChatHistoryProvider.kt)
  • Duplicated block (11 lines × 2) (agents/agents-features/agents-features-opentelemetry/src/commonMain/kotlin/ai/koog/agents/features/opentelemetry/metric/events/histogramMetricEvents.kt)
  • …and 728 more

Changes since last survey

  • 2 commits — 2 feature/other, 0 fixes

By area

  • agents/agents-features — 2 commits

Notable commits

  • change: build(agents)!: upgrade Exposed to 1.6.0 (#2321)
  • change: feat(agents): report Gemini cached and thinking tokens to Langfuse (#2303)

Architecture

  • Containers 0 added · 0 removed · contexts 3 added · 3 removed · edges 7 added · 8 removed

Added bounded contexts (3)

  • examples/javaone-2026
  • examples/koog-java-api-example
  • examples/spring-io-2026/java

Removed bounded contexts (3)

  • examples/javaone-2026
  • examples/koog-java-api-example
  • examples/spring-io-2026/java

Added dependency edges (7)

  • examples/koog-java-api-example → examples/javaone-2026
  • koog-spring-ai-starter-model-chat → prompt-llm
  • koog-spring-ai-starter-model-chat → prompt-model
  • koog-spring-ai-starter-vector-store → rag-base
  • koog-spring-ai-v2-starter-model-chat → prompt-llm (coupling)
  • koog-spring-ai-v2-starter-model-chat → prompt-model (coupling)
  • koog-spring-ai-v2-starter-vector-store → rag-base (coupling)

Removed dependency edges (was a dependency, now gone) (8)

  • examples/javaone-2026 → examples/koog-java-api-example
  • examples/koog-java-api-example → examples/javaone-2026
  • koog-spring-ai-starter-model-chat → prompt-llm (coupling)
  • koog-spring-ai-starter-model-chat → prompt-model (coupling)
  • koog-spring-ai-starter-vector-store → rag-base (coupling)
  • koog-spring-ai-v2-starter-model-chat → prompt-llm
  • koog-spring-ai-v2-starter-model-chat → prompt-model
  • koog-spring-ai-v2-starter-vector-store → rag-base

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

JetBrains/koog was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 13 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 709079e4a34d6c9234583352550e6a2b88a0bb85 — the exact code this score is about.
  • Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.64+preprod-569132d3dfbe.