Introduce initial ACP integration (#1253)

ACP feature to create ACP-compatible agents in Koog
- [x] Raw access to the protocol from the feature in order not to complicate it until ACP becomes stable
- [x] Example
- [x] README (Model.md)
- [x] Documentation

Co-authored-by: Andrey Bragin <[email protected]>

Author: tiginamaria

README.md

@@ -36,6 +36,7 @@ Key features of Koog include:
 - **LLM switching and seamless history adaptation**: Switch to a different LLM at any point without losing the existing conversation history, or reroute between multiple LLM providers.
 - **Integration with JVM and Kotlin applications**: Build AI agents with an idiomatic, type-safe Kotlin DSL designed specifically for JVM and Kotlin developers.
 - **Model Context Protocol integration**: Use Model Context Protocol (MCP) tools in AI agents.
+- **Agent Client Protocol integration**: Build ACP-compliant agents that can communicate with standardized client applications using the Agent Client Protocol (ACP).
 - **Knowledge retrieval and memory**: Retain and retrieve knowledge across conversations using vector embeddings, ranked document storage, and shared agent memory.
 - **Powerful Streaming API**: Process responses in real-time with streaming support and parallel tool calls.
 - **Modular feature system**: Customize agent capabilities through a composable architecture.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/exception/AIAgentException.kt

@@ -44,7 +44,7 @@ internal class AIAgentStuckInTheNodeException(node: AIAgentNodeBase<*, *>, outpu
  * @constructor Creates an instance of this exception with the specified maximum number of iterations.
  * @param maxNumberOfIterations The maximum number of iterations allowed for the agent before the exception is triggered.
  */
-internal class AIAgentMaxNumberOfIterationsReachedException(maxNumberOfIterations: Int) :
+public class AIAgentMaxNumberOfIterationsReachedException(maxNumberOfIterations: Int) :
     AIAgentException(
         "Agent couldn't finish in given number of steps ($maxNumberOfIterations). " +
             "Please, consider increasing `maxAgentIterations` value in agent's configuration"

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/environment/ContextualAgentEnvironment.kt

@@ -28,6 +28,7 @@ internal class ContextualAgentEnvironment(
             runId = context.runId,
             toolCallId = toolCall.id,
             toolName = toolCall.tool,
+            toolDescription = context.llm.toolRegistry.getToolOrNull(toolCall.tool)?.descriptor?.description,
             toolArgs = toolCall.contentJson
         )
 
@@ -39,6 +40,7 @@ internal class ContextualAgentEnvironment(
                 "run id: ${context.runId}, " +
                 "tool call id: ${toolCall.id}, " +
                 "tool: ${toolCall.tool}, " +
+                "tool description: ${toolResult.toolDescription}, " +
                 "args: ${toolCall.contentJson}) " +
                 "with result: $toolResult"
         }
@@ -63,8 +65,8 @@ internal class ContextualAgentEnvironment(
                     runId = context.runId,
                     toolCallId = toolResult.id,
                     toolName = toolResult.tool,
-                    toolArgs = toolResult.toolArgs,
                     toolDescription = toolResult.toolDescription,
+                    toolArgs = toolResult.toolArgs,
                     toolResult = toolResult.result
                 )
             }
@@ -75,8 +77,8 @@ internal class ContextualAgentEnvironment(
                     runId = context.runId,
                     toolCallId = toolResult.id,
                     toolName = toolResult.tool,
-                    toolArgs = toolResult.toolArgs,
                     toolDescription = toolResult.toolDescription,
+                    toolArgs = toolResult.toolArgs,
                     message = toolResult.content,
                     error = toolResultKind.error
                 )
@@ -88,8 +90,8 @@ internal class ContextualAgentEnvironment(
                     runId = context.runId,
                     toolCallId = toolResult.id,
                     toolName = toolResult.tool,
-                    toolArgs = toolResult.toolArgs,
                     toolDescription = toolResult.toolDescription,
+                    toolArgs = toolResult.toolArgs,
                     message = toolResult.content,
                     error = toolResultKind.error
                 )

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/llm/LLMCallEventContext.kt

@@ -39,6 +39,7 @@ public data class LLMCallStartingContext(
  *
  * @property executionInfo The execution information containing parentId and current execution path;
  * @property runId The unique identifier for this LLM call session.
+ * @property callId Identifier for the current LLM call.
  * @property prompt The prompt that was sent to the language model.
  * @property model The language model instance that was used.
  * @property tools The list of tool descriptors that were available for the LLM call.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/tool/ToolCallEventContext.kt

@@ -26,6 +26,7 @@ public data class ToolCallStartingContext(
     val runId: String,
     val toolCallId: String?,
     val toolName: String,
+    val toolDescription: String?,
     val toolArgs: JsonObject,
 ) : ToolCallEventContext {
     override val eventType: AgentLifecycleEventType = AgentLifecycleEventType.ToolCallStarting
@@ -38,8 +39,8 @@ public data class ToolCallStartingContext(
  * @property runId The unique identifier for this tool call session;
  * @property toolCallId The unique identifier for this tool call;
  * @property toolName The name of the tool associated with the validation error;
- * @property toolArgs The arguments passed to the tool when the error occurred;
  * @property toolDescription A description of the tool being executed;
+ * @property toolArgs The arguments passed to the tool when the error occurred;
  * @property message A message describing the validation error.
  * @property error The [AIAgentError] error describing the validation issue.
  */
@@ -48,8 +49,8 @@ public data class ToolValidationFailedContext(
     val runId: String,
     val toolCallId: String?,
     val toolName: String,
-    val toolArgs: JsonObject,
     val toolDescription: String?,
+    val toolArgs: JsonObject,
     val message: String,
     val error: AIAgentError
 ) : ToolCallEventContext {
@@ -63,8 +64,8 @@ public data class ToolValidationFailedContext(
  * @property runId The unique identifier for this tool call session;
  * @property toolCallId The unique identifier for this tool call;
  * @property toolName The name of the tool being executed when the failure occurred;
- * @property toolArgs The arguments that were passed to the tool during execution;
  * @property toolDescription A description of the tool being executed;
+ * @property toolArgs The arguments that were passed to the tool during execution;
  * @property message A message describing the failure that occurred.
  * @property error The [AIAgentError] instance describing the tool call failure.
  */
@@ -73,8 +74,8 @@ public data class ToolCallFailedContext(
     val runId: String,
     val toolCallId: String?,
     val toolName: String,
-    val toolArgs: JsonObject,
     val toolDescription: String?,
+    val toolArgs: JsonObject,
     val message: String,
     val error: AIAgentError?
 ) : ToolCallEventContext {
@@ -88,17 +89,17 @@ public data class ToolCallFailedContext(
  * @property runId The unique identifier for this tool call session;
  * @property toolCallId The unique identifier for this tool call;
  * @property toolName The name of the tool being executed;
- * @property toolArgs The arguments required by the tool for execution;
  * @property toolDescription A description of the tool being executed;
+ * @property toolArgs The arguments required by the tool for execution;
  * @property toolResult An optional result produced by the tool after execution can be null if not applicable.
  */
 public data class ToolCallCompletedContext(
     override val executionInfo: AgentExecutionInfo,
     val runId: String,
     val toolCallId: String?,
     val toolName: String,
-    val toolArgs: JsonObject,
     val toolDescription: String?,
+    val toolArgs: JsonObject,
     val toolResult: JsonElement?
 ) : ToolCallEventContext {
     override val eventType: AgentLifecycleEventType = AgentLifecycleEventType.ToolCallCompleted

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/pipeline/AIAgentPipeline.kt

@@ -451,16 +451,19 @@ public abstract class AIAgentPipeline(public val clock: Clock) {
      * @param runId The unique identifier for the current run.
      * @param toolCallId The unique identifier for the current tool call.
      * @param toolName The tool name that is being called
+     * @param toolDescription The description of the tool that is being called.
      * @param toolArgs The arguments provided to the tool
      */
     public suspend fun onToolCallStarting(
         executionInfo: AgentExecutionInfo,
         runId: String,
         toolCallId: String?,
         toolName: String,
+        toolDescription: String?,
         toolArgs: JsonObject,
     ) {
-        val eventContext = ToolCallStartingContext(executionInfo, runId, toolCallId, toolName, toolArgs)
+        val eventContext =
+            ToolCallStartingContext(executionInfo, runId, toolCallId, toolName, toolDescription, toolArgs)
         toolCallEventHandlers.values.forEach { handler -> handler.toolCallHandler.handle(eventContext) }
     }
 
@@ -471,8 +474,8 @@ public abstract class AIAgentPipeline(public val clock: Clock) {
      * @param runId The unique identifier for the current run;
      * @param toolCallId The unique identifier for the current tool call;
      * @param toolName The name of the tool for which validation failed;
-     * @param toolArgs The arguments that failed validation;
      * @param toolDescription The description of the tool that was called;
+     * @param toolArgs The arguments that failed validation;
      * @param message The validation error message;
      * @param error The [AIAgentError] validation error.
      */
@@ -481,12 +484,12 @@ public abstract class AIAgentPipeline(public val clock: Clock) {
         runId: String,
         toolCallId: String?,
         toolName: String,
-        toolArgs: JsonObject,
         toolDescription: String?,
+        toolArgs: JsonObject,
         message: String,
         error: AIAgentError,
     ) {
-        val eventContext = ToolValidationFailedContext(executionInfo, runId, toolCallId, toolName, toolArgs, toolDescription, message, error)
+        val eventContext = ToolValidationFailedContext(executionInfo, runId, toolCallId, toolName, toolDescription, toolArgs, message, error)
         toolCallEventHandlers.values.forEach { handler -> handler.toolValidationErrorHandler.handle(eventContext) }
     }
 
@@ -497,8 +500,8 @@ public abstract class AIAgentPipeline(public val clock: Clock) {
      * @param runId The unique identifier for the current run;
      * @param toolCallId The unique identifier for the current tool call;
      * @param toolName The tool name that was called;
-     * @param toolArgs The arguments provided to the tool;
      * @param toolDescription The description of the tool that was called;
+     * @param toolArgs The arguments provided to the tool;
      * @param message A message describing the failure.
      * @param error The [AIAgentError] that caused the failure.
      */
@@ -507,12 +510,12 @@ public abstract class AIAgentPipeline(public val clock: Clock) {
         runId: String,
         toolCallId: String?,
         toolName: String,
-        toolArgs: JsonObject,
         toolDescription: String?,
+        toolArgs: JsonObject,
         message: String,
         error: AIAgentError?
     ) {
-        val eventContext = ToolCallFailedContext(executionInfo, runId, toolCallId, toolName, toolArgs, toolDescription, message, error)
+        val eventContext = ToolCallFailedContext(executionInfo, runId, toolCallId, toolName, toolDescription, toolArgs, message, error)
         toolCallEventHandlers.values.forEach { handler -> handler.toolCallFailureHandler.handle(eventContext) }
     }
 
@@ -523,20 +526,20 @@ public abstract class AIAgentPipeline(public val clock: Clock) {
      * @param runId The unique identifier for the current run;
      * @param toolCallId The unique identifier for the current tool call;
      * @param toolName The tool name that was called;
-     * @param toolArgs The arguments that were provided to the tool;
      * @param toolDescription The description of the tool that was called;
+     * @param toolArgs The arguments that were provided to the tool;
      * @param toolResult The result produced by the tool, or null if no result was produced.
      */
     public suspend fun onToolCallCompleted(
         executionInfo: AgentExecutionInfo,
         runId: String,
         toolCallId: String?,
         toolName: String,
-        toolArgs: JsonObject,
         toolDescription: String?,
+        toolArgs: JsonObject,
         toolResult: JsonElement?
     ) {
-        val eventContext = ToolCallCompletedContext(executionInfo, runId, toolCallId, toolName, toolArgs, toolDescription, toolResult)
+        val eventContext = ToolCallCompletedContext(executionInfo, runId, toolCallId, toolName, toolDescription, toolArgs, toolResult)
         toolCallEventHandlers.values.forEach { handler -> handler.toolCallResultHandler.handle(eventContext) }
     }
 
@@ -1375,13 +1378,15 @@ public abstract class AIAgentPipeline(public val clock: Clock) {
                             // Use default configuration
                         }
                     }
+
                     is AIAgentFunctionalPipeline -> {
                         this.install(Debugger) {
                             // Use default configuration
                         }
                     }
                 }
             }
+
             else -> {
                 error(
                     "Unsupported system feature key: ${featureKey.name}. " +

agents/agents-ext/src/commonMain/kotlin/ai/koog/agents/ext/agent/AIAgentSubgraphExt.kt

@@ -140,8 +140,8 @@ internal inline fun <reified Output> identityTool(): Tool<Output, Output> = obje
 @OptIn(InternalAgentToolsApi::class, InternalAgentsApi::class)
 @AIAgentBuilderDslMarker
 public inline fun <reified Input, reified Output> AIAgentSubgraphBuilderBase<*, *>.subgraphWithTask(
-    toolSelectionStrategy: ToolSelectionStrategy,
     name: String? = null,
+    toolSelectionStrategy: ToolSelectionStrategy = ToolSelectionStrategy.ALL,
     llmModel: LLModel? = null,
     llmParams: LLMParams? = null,
     runMode: ToolCalls = ToolCalls.SEQUENTIAL,