KG-148. Add events for LLM Streaming to make them available in feature processors

agents/agents-core/Module.md

@@ -78,3 +78,42 @@ val agent = AIAgent(
 // Run the agent
 val result = agent.execute("Calculate the square root of 16")
 ```
+
+
+### Standard Feature Events
+
+Features in the Koog ecosystem consume standardized Feature Events emitted by agents-core during agent execution. These events are defined in this module under the package `ai.koog.agents.core.feature.model.events`.
+
+- Agent events:
+  - AgentStartingEvent
+  - AgentCompletedEvent
+  - AgentExecutionFailedEvent
+  - AgentClosingEvent
+
+- Strategy events:
+  - GraphStrategyStartingEvent
+  - FunctionalStrategyStartingEvent
+  - StrategyCompletedEvent
+
+- Node execution events:
+  - NodeExecutionStartingEvent
+  - NodeExecutionCompletedEvent
+  - NodeExecutionFailedEvent
+
+- LLM call events:
+  - LLMCallStartingEvent
+  - LLMCallCompletedEvent
+
+- LLM streaming events:
+  - LLMStreamingStartingEvent
+  - LLMStreamingFrameReceivedEvent
+  - LLMStreamingFailedEvent
+  - LLMStreamingCompletedEvent
+
+- Tool execution events:
+  - ToolExecutionStartingEvent
+  - ToolValidationFailedEvent
+  - ToolExecutionFailedEvent
+  - ToolExecutionCompletedEvent
+
+These events are emitted by the agents-core runtime and consumed by features such as Tracing, Debugger, and EventHandler to enable logging, tracing, monitoring, and remote inspection.

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/entity/AIAgentNode.kt

@@ -119,7 +119,6 @@ public abstract class AIAgentNodeBase<TInput, TOutput> internal constructor() {
     /**
      * Executes the node operation using the provided execution context and input, bypassing type safety checks.
      * This method internally calls the type-safe `execute` method after casting the input.
-     * The lifecycle hooks `onBeforeNode` and `onAfterNode` are invoked before and after the execution respectively.
      *
      * @param context The execution context that provides runtime information and functionality.
      * @param input The input data to be processed by the node, which may be of any type.

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

@@ -117,7 +117,7 @@ internal class GenericAgentEnvironment(
                 )
             }
 
-            pipeline.onToolExecutionStarting(content.runId, content.toolCallId, tool, toolArgs)
+            pipeline.onToolCallStarting(content.runId, content.toolCallId, tool, toolArgs)
 
             val toolResult = try {
                 @Suppress("UNCHECKED_CAST")
@@ -135,7 +135,7 @@ internal class GenericAgentEnvironment(
             } catch (e: Exception) {
                 logger.error(e) { "Tool \"${tool.name}\" failed to execute with arguments: ${content.toolArgs}" }
 
-                pipeline.onToolExecutionFailed(content.runId, content.toolCallId, tool, toolArgs, e)
+                pipeline.onToolCallFailed(content.runId, content.toolCallId, tool, toolArgs, e)
 
                 return toolResult(
                     message = "Tool \"${tool.name}\" failed to execute because of ${e.message}!",
@@ -146,7 +146,7 @@ internal class GenericAgentEnvironment(
                 )
             }
 
-            pipeline.onToolExecutionCompleted(content.runId, content.toolCallId, tool, toolArgs, toolResult)
+            pipeline.onToolCallCompleted(content.runId, content.toolCallId, tool, toolArgs, toolResult)
 
             logger.trace { "Completed execution of ${content.toolName} with result: $toolResult" }
 

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

@@ -41,13 +41,13 @@
 import ai.koog.agents.core.feature.handler.streaming.LLMStreamingFrameReceivedHandler
 import ai.koog.agents.core.feature.handler.streaming.LLMStreamingStartingContext
 import ai.koog.agents.core.feature.handler.streaming.LLMStreamingStartingHandler
+import ai.koog.agents.core.feature.handler.tool.ToolCallCompletedContext
+import ai.koog.agents.core.feature.handler.tool.ToolCallEventHandler
+import ai.koog.agents.core.feature.handler.tool.ToolCallFailedContext
 import ai.koog.agents.core.feature.handler.tool.ToolCallFailureHandler
 import ai.koog.agents.core.feature.handler.tool.ToolCallHandler
 import ai.koog.agents.core.feature.handler.tool.ToolCallResultHandler
-import ai.koog.agents.core.feature.handler.tool.ToolExecutionCompletedContext
-import ai.koog.agents.core.feature.handler.tool.ToolExecutionEventHandler
-import ai.koog.agents.core.feature.handler.tool.ToolExecutionFailedContext
-import ai.koog.agents.core.feature.handler.tool.ToolExecutionStartingContext
+import ai.koog.agents.core.feature.handler.tool.ToolCallStartingContext
 import ai.koog.agents.core.feature.handler.tool.ToolValidationErrorHandler
 import ai.koog.agents.core.feature.handler.tool.ToolValidationFailedContext
 import ai.koog.agents.core.tools.Tool
@@ -123,7 +123,7 @@
      * Map of tool execution handlers registered for different features.
      * Keys are feature storage keys, values are tool execution handlers.
      */
-    protected val toolExecutionEventHandlers: MutableMap<AIAgentStorageKey<*>, ToolExecutionEventHandler> = mutableMapOf()
+    protected val toolCallEventHandlers: MutableMap<AIAgentStorageKey<*>, ToolCallEventHandler> = mutableMapOf()
 
     /**
      * Map of LLM execution handlers registered for different features.
@@ -367,9 +367,9 @@
      * @param tool The tool that is being called
      * @param toolArgs The arguments provided to the tool
      */
-    public suspend fun onToolExecutionStarting(runId: String, toolCallId: String?, tool: Tool<*, *>, toolArgs: Any?) {
-        val eventContext = ToolExecutionStartingContext(runId, toolCallId, tool, toolArgs)
-        toolExecutionEventHandlers.values.forEach { handler -> handler.toolCallHandler.handle(eventContext) }
+    public suspend fun onToolCallStarting(runId: String, toolCallId: String?, tool: Tool<*, *>, toolArgs: Any?) {
+        val eventContext = ToolCallStartingContext(runId, toolCallId, tool, toolArgs)
+        toolCallEventHandlers.values.forEach { handler -> handler.toolCallHandler.handle(eventContext) }
     }
 
     /**
@@ -389,7 +389,7 @@
     ) {
         val eventContext =
             ToolValidationFailedContext(runId, toolCallId, tool, toolArgs, error)
-        toolExecutionEventHandlers.values.forEach { handler -> handler.toolValidationErrorHandler.handle(eventContext) }
+        toolCallEventHandlers.values.forEach { handler -> handler.toolValidationErrorHandler.handle(eventContext) }
     }
 
     /**
@@ -400,15 +400,15 @@
      * @param toolArgs The arguments provided to the tool
      * @param throwable The exception that caused the failure
      */
-    public suspend fun onToolExecutionFailed(
+    public suspend fun onToolCallFailed(
         runId: String,
         toolCallId: String?,
         tool: Tool<*, *>,
         toolArgs: Any?,
         throwable: Throwable
     ) {
-        val eventContext = ToolExecutionFailedContext(runId, toolCallId, tool, toolArgs, throwable)
-        toolExecutionEventHandlers.values.forEach { handler -> handler.toolCallFailureHandler.handle(eventContext) }
+        val eventContext = ToolCallFailedContext(runId, toolCallId, tool, toolArgs, throwable)
+        toolCallEventHandlers.values.forEach { handler -> handler.toolCallFailureHandler.handle(eventContext) }
     }
 
     /**
@@ -419,15 +419,15 @@
      * @param toolArgs The arguments that were provided to the tool
      * @param result The result produced by the tool, or null if no result was produced
      */
-    public suspend fun onToolExecutionCompleted(
+    public suspend fun onToolCallCompleted(
         runId: String,
         toolCallId: String?,
         tool: Tool<*, *>,
         toolArgs: Any?,
         result: Any?
     ) {
-        val eventContext = ToolExecutionCompletedContext(runId, toolCallId, tool, toolArgs, result)
-        toolExecutionEventHandlers.values.forEach { handler -> handler.toolCallResultHandler.handle(eventContext) }
+        val eventContext = ToolCallCompletedContext(runId, toolCallId, tool, toolArgs, result)
+        toolCallEventHandlers.values.forEach { handler -> handler.toolCallResultHandler.handle(eventContext) }
     }
 
     //endregion Trigger Tool Call Handlers
@@ -867,16 +867,16 @@
      *
      * Example:
      * ```
-     * pipeline.interceptToolExecutionStarting(interceptContext) { eventContext ->
+     * pipeline.interceptToolCallStarting(interceptContext) { eventContext ->
      *    // Process or log the tool call
      * }
      * ```
      */
-    public fun <TFeature : Any> interceptToolExecutionStarting(
+    public fun <TFeature : Any> interceptToolCallStarting(
         interceptContext: InterceptContext<TFeature>,
-        handle: suspend TFeature.(eventContext: ToolExecutionStartingContext) -> Unit
+        handle: suspend TFeature.(eventContext: ToolCallStartingContext) -> Unit
     ) {
-        val handler = toolExecutionEventHandlers.getOrPut(interceptContext.feature.key) { ToolExecutionEventHandler() }
+        val handler = toolCallEventHandlers.getOrPut(interceptContext.feature.key) { ToolCallEventHandler() }
         handler.toolCallHandler = ToolCallHandler(
             function = createConditionalHandler(interceptContext, handle)
         )
@@ -899,7 +899,7 @@
         interceptContext: InterceptContext<TFeature>,
         handle: suspend TFeature.(eventContext: ToolValidationFailedContext) -> Unit
     ) {
-        val handler = toolExecutionEventHandlers.getOrPut(interceptContext.feature.key) { ToolExecutionEventHandler() }
+        val handler = toolCallEventHandlers.getOrPut(interceptContext.feature.key) { ToolCallEventHandler() }
         handler.toolValidationErrorHandler = ToolValidationErrorHandler(
             function = createConditionalHandler(interceptContext, handle)
         )
@@ -913,16 +913,16 @@
      *
      * Example:
      * ```
-     * pipeline.interceptToolExecutionFailed(interceptContext) { eventContext ->
+     * pipeline.interceptToolCallFailed(interceptContext) { eventContext ->
      *     // Handle the tool call failure here
      * }
      * ```
      */
-    public fun <TFeature : Any> interceptToolExecutionFailed(
+    public fun <TFeature : Any> interceptToolCallFailed(
         interceptContext: InterceptContext<TFeature>,
-        handle: suspend TFeature.(eventContext: ToolExecutionFailedContext) -> Unit
+        handle: suspend TFeature.(eventContext: ToolCallFailedContext) -> Unit
     ) {
-        val handler = toolExecutionEventHandlers.getOrPut(interceptContext.feature.key) { ToolExecutionEventHandler() }
+        val handler = toolCallEventHandlers.getOrPut(interceptContext.feature.key) { ToolCallEventHandler() }
         handler.toolCallFailureHandler = ToolCallFailureHandler(
             function = createConditionalHandler(interceptContext, handle)
         )
@@ -942,11 +942,11 @@
      * }
      * ```
      */
-    public fun <TFeature : Any> interceptToolExecutionCompleted(
+    public fun <TFeature : Any> interceptToolCallCompleted(
         interceptContext: InterceptContext<TFeature>,
-        handle: suspend TFeature.(eventContext: ToolExecutionCompletedContext) -> Unit
+        handle: suspend TFeature.(eventContext: ToolCallCompletedContext) -> Unit
     ) {
-        val handler = toolExecutionEventHandlers.getOrPut(interceptContext.feature.key) { ToolExecutionEventHandler() }
+        val handler = toolCallEventHandlers.getOrPut(interceptContext.feature.key) { ToolCallEventHandler() }
         handler.toolCallResultHandler = ToolCallResultHandler(
             function = createConditionalHandler(interceptContext, handle)
         )
@@ -966,7 +966,7 @@
             imports = arrayOf("ai.koog.agents.core.feature.handler.agent.AgentStartingContext")
         )
     )
     public fun <TFeature : Any> interceptBeforeAgentStarted(
         interceptContext: InterceptContext<TFeature>,
         handle: suspend (ai.koog.agents.core.feature.handler.AgentStartContext<TFeature>) -> Unit
     ) {
@@ -985,7 +985,7 @@
             )
         )
     )
     public fun <TFeature : Any> interceptAgentFinished(
         interceptContext: InterceptContext<TFeature>,
         handle: suspend TFeature.(eventContext: ai.koog.agents.core.feature.handler.AgentFinishedContext) -> Unit
     ) {
@@ -1004,7 +1004,7 @@
             )
         )
     )
     public fun <TFeature : Any> interceptAgentRunError(
         interceptContext: InterceptContext<TFeature>,
         handle: suspend TFeature.(ai.koog.agents.core.feature.handler.AgentRunErrorContext) -> Unit
     ) {
@@ -1023,7 +1023,7 @@
             )
         )
     )
     public fun <TFeature : Any> interceptAgentBeforeClose(
         interceptContext: InterceptContext<TFeature>,
         handle: suspend TFeature.(ai.koog.agents.core.feature.handler.AgentBeforeCloseContext) -> Unit
     ) {
@@ -1042,7 +1042,7 @@
             )
         )
     )
     public fun <TFeature : Any> interceptStrategyStart(
         interceptContext: InterceptContext<TFeature>,
         handle: suspend (ai.koog.agents.core.feature.handler.StrategyStartContext<TFeature>) -> Unit
     ) {
@@ -1061,7 +1061,7 @@
             )
         )
     )
     public fun <TFeature : Any> interceptStrategyFinished(
         interceptContext: InterceptContext<TFeature>,
         handle: suspend (ai.koog.agents.core.feature.handler.StrategyFinishedContext<TFeature>) -> Unit
     ) {
@@ -1080,7 +1080,7 @@
             )
         )
     )
     public fun <TFeature : Any> interceptBeforeLLMCall(
         interceptContext: InterceptContext<TFeature>,
         handle: suspend TFeature.(eventContext: ai.koog.agents.core.feature.handler.BeforeLLMCallContext) -> Unit
     ) {
@@ -1099,7 +1099,7 @@
             )
         )
     )
     public fun <TFeature : Any> interceptAfterLLMCall(
         interceptContext: InterceptContext<TFeature>,
         handle: suspend TFeature.(eventContext: ai.koog.agents.core.feature.handler.AfterLLMCallContext) -> Unit
     ) {
@@ -1111,57 +1111,57 @@
      * Updates the tool call handler for the given feature key with a custom handler.
      */
     @Deprecated(
-        message = "Please use interceptToolExecutionStarting instead. This method is deprecated and will be removed in the next release.",
+        message = "Please use interceptToolCallStarting instead. This method is deprecated and will be removed in the next release.",
         replaceWith = ReplaceWith(
-            expression = "interceptToolExecutionStarting(interceptContext, handle)",
+            expression = "interceptToolCallStarting(interceptContext, handle)",
             imports = arrayOf(
-                "ai.koog.agents.core.feature.handler.tool.ToolExecutionStartingContext"
+                "ai.koog.agents.core.feature.handler.tool.ToolCallStartingContext"
             )
         )
     )
     public fun <TFeature : Any> interceptToolCall(
         interceptContext: InterceptContext<TFeature>,
         handle: suspend TFeature.(eventContext: ai.koog.agents.core.feature.handler.ToolCallContext) -> Unit
     ) {
-        interceptToolExecutionStarting(interceptContext, handle)
+        interceptToolCallStarting(interceptContext, handle)
     }
 
     /**
      * Intercepts the result of a tool call with a custom handler for a specific feature.
      */
     @Deprecated(
-        message = "Please use interceptToolExecutionCompleted instead. This method is deprecated and will be removed in the next release.",
+        message = "Please use interceptToolCallCompleted instead. This method is deprecated and will be removed in the next release.",
         replaceWith = ReplaceWith(
-            expression = "interceptToolExecutionCompleted(interceptContext, handle)",
+            expression = "interceptToolCallCompleted(interceptContext, handle)",
             imports = arrayOf(
-                "ai.koog.agents.core.feature.handler.tool.ToolExecutionCompletedContext"
+                "ai.koog.agents.core.feature.handler.tool.ToolCallCompletedContext"
             )
         )
     )
     public fun <TFeature : Any> interceptToolCallResult(
         interceptContext: InterceptContext<TFeature>,
-        handle: suspend TFeature.(eventContext: ToolExecutionCompletedContext) -> Unit
+        handle: suspend TFeature.(eventContext: ToolCallCompletedContext) -> Unit
     ) {
-        interceptToolExecutionCompleted(interceptContext, handle)
+        interceptToolCallCompleted(interceptContext, handle)
     }
 
     /**
      * Sets up an interception mechanism to handle tool call failures for a specific feature.
      */
     @Deprecated(
-        message = "Please use interceptToolExecutionFailed instead. This method is deprecated and will be removed in the next release.",
+        message = "Please use interceptToolCallFailed instead. This method is deprecated and will be removed in the next release.",
         replaceWith = ReplaceWith(
-            expression = "interceptToolExecutionFailed(interceptContext, handle)",
+            expression = "interceptToolCallFailed(interceptContext, handle)",
             imports = arrayOf(
-                "ai.koog.agents.core.feature.handler.tool.ToolExecutionFailedContext"
+                "ai.koog.agents.core.feature.handler.tool.ToolCallFailedContext"
             )
         )
     )
     public fun <TFeature : Any> interceptToolCallFailure(
         interceptContext: InterceptContext<TFeature>,
-        handle: suspend TFeature.(eventContext: ToolExecutionFailedContext) -> Unit
+        handle: suspend TFeature.(eventContext: ToolCallFailedContext) -> Unit
     ) {
-        interceptToolExecutionFailed(interceptContext, handle)
+        interceptToolCallFailed(interceptContext, handle)
     }
 
     /**
@@ -1176,7 +1176,7 @@
             )
         )
     )
     public fun <TFeature : Any> interceptToolValidationError(
         interceptContext: InterceptContext<TFeature>,
         handle: suspend TFeature.(eventContext: ToolValidationFailedContext) -> Unit
     ) {

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

@@ -89,7 +89,7 @@ public sealed interface AgentLifecycleEventType {
     /**
      * Represents an event triggered when a tool is called.
      */
-    public object ToolExecutionStarting : AgentLifecycleEventType
+    public object ToolCallStarting : AgentLifecycleEventType
 
     /**
      * Represents an event triggered when a tool call fails validation.
@@ -99,12 +99,12 @@ public sealed interface AgentLifecycleEventType {
     /**
      * Represents an event triggered when a tool call fails.
      */
-    public object ToolExecutionFailed : AgentLifecycleEventType
+    public object ToolCallFailed : AgentLifecycleEventType
 
     /**
      * Represents an event triggered when a tool call succeeds.
      */
-    public object ToolExecutionCompleted : AgentLifecycleEventType
+    public object ToolCallCompleted : AgentLifecycleEventType
 
     //endregion Tool
 

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

@@ -4,25 +4,25 @@ package ai.koog.agents.core.feature.handler
  * Represents the context for handling tool-specific events within the framework.
  */
 @Deprecated(
-    message = "Use ToolExecutionEventContext instead",
+    message = "Use ToolCallEventContext instead",
     replaceWith = ReplaceWith(
-        expression = "ToolExecutionEventContext",
-        imports = arrayOf("ai.koog.agents.core.feature.handler.tool.ToolExecutionEventContext")
+        expression = "ToolCallEventContext",
+        imports = arrayOf("ai.koog.agents.core.feature.handler.tool.ToolCallEventContext")
     )
 )
-public typealias ToolEventHandlerContext = ai.koog.agents.core.feature.handler.tool.ToolExecutionEventContext
+public typealias ToolEventHandlerContext = ai.koog.agents.core.feature.handler.tool.ToolCallEventContext
 
 /**
  * Represents the context for handling a tool call event.
  */
 @Deprecated(
-    message = "Use ToolExecutionStartingContext instead",
+    message = "Use ToolCallStartingContext instead",
     replaceWith = ReplaceWith(
-        expression = "ToolExecutionStartingContext",
-        imports = arrayOf("ai.koog.agents.core.feature.handler.tool.ToolExecutionStartingContext")
+        expression = "ToolCallStartingContext",
+        imports = arrayOf("ai.koog.agents.core.feature.handler.tool.ToolCallStartingContext")
     )
 )
-public typealias ToolCallContext = ai.koog.agents.core.feature.handler.tool.ToolExecutionStartingContext
+public typealias ToolCallContext = ai.koog.agents.core.feature.handler.tool.ToolCallStartingContext
 
 /**
  * Represents the context for handling validation errors that occur during the execution of a tool.
@@ -40,22 +40,22 @@ public typealias ToolValidationErrorContext = ai.koog.agents.core.feature.handle
  * Represents the context provided to handle a failure during the execution of a tool.
  */
 @Deprecated(
-    message = "Use ToolExecutionFailedContext instead",
+    message = "Use ToolCallFailedContext instead",
     replaceWith = ReplaceWith(
-        expression = "ToolExecutionFailedContext",
-        imports = arrayOf("ai.koog.agents.core.feature.handler.tool.ToolExecutionFailedContext")
+        expression = "ToolCallFailedContext",
+        imports = arrayOf("ai.koog.agents.core.feature.handler.tool.ToolCallFailedContext")
     )
 )
-public typealias ToolCallFailureContext = ai.koog.agents.core.feature.handler.tool.ToolExecutionFailedContext
+public typealias ToolCallFailureContext = ai.koog.agents.core.feature.handler.tool.ToolCallFailedContext
 
 /**
  * Represents the context used when handling the result of a tool call.
  */
 @Deprecated(
-    message = "Use ToolExecutionCompletedContext instead",
+    message = "Use ToolCallCompletedContext instead",
     replaceWith = ReplaceWith(
-        expression = "ToolExecutionCompletedContext",
-        imports = arrayOf("ai.koog.agents.core.feature.handler.tool.ToolExecutionCompletedContext")
+        expression = "ToolCallCompletedContext",
+        imports = arrayOf("ai.koog.agents.core.feature.handler.tool.ToolCallCompletedContext")
     )
 )
-public typealias ToolCallResultContext = ai.koog.agents.core.feature.handler.tool.ToolExecutionCompletedContext
+public typealias ToolCallResultContext = ai.koog.agents.core.feature.handler.tool.ToolCallCompletedContext