Update documentation for agent feature events

Author: sdubov

agents/agents-features/Module.md

@@ -1,44 +1,76 @@
 # Module agents:agents-features
 
-Provides implementations of useful features of AI agents, such as Tracing, Debugger, EventHandler, Memory, OpenTelemetry, Snapshot, and more.
+A collection of plug-and-play features for Koog AI agents. These features hook into the agent execution pipeline to observe, enrich, and extend behavior.
 
-### Overview
+## What is inside
 
-Features integrate with the agent pipeline via interceptor hooks and consume standardized Feature Events emitted during agent execution. These events are defined in the agents-core module under `ai.koog.agents.core.feature.model.events`. After the 0afb32b refactor, event and interceptor names are unified across the system.
+Each feature lives in its own submodule, you only depend on what you need. Commonly used features include:
+- Tracing: End-to-end spans for agent runs and LLM, or Tool calls. Great for local dev and production observability;
+- Debugger: Step-through style inspection of the agent pipeline;
+- EventHandler: Subscribe to standardized agent events and react (log, metrics, custom side effects);
+- Memory: Pluggable memory interfaces for storing and retrieving agent context;
+- OpenTelemetry: OTel exporters and wiring for spans emitted by the agent pipeline;
+- Snapshot: Persist and restore agent snapshots for reproducibility and time-travel debugging.
 
-### Standard Feature Events
+Check each feature’s own README/Module docs for details and advanced configuration.
 
-The canonical description and definitions of Feature Events now live in the agents-core module. See:
+## How features integrate
 
-- agents-core module docs: ../agents-core/Module.md (section "Standard Feature Events")
-- Kotlin definitions: package `ai.koog.agents.core.feature.model.events`
+Features integrate via interceptor hooks and consume standardized events emitted during an agent execution. These events are defined in the agents-core module under:
+- ai.koog.agents.core.feature.model.events
 
-Features in this module (Tracing, Debugger, EventHandler, etc.) consume these events to provide logging, tracing, monitoring, and remote inspection.
+Typical events include:
+- AgentStarting/Completed
+- LLMCallStarting/Completed
+- ToolCallStarting/Completed
 
-### Using in your project
+Features can listen to these events, mutate context when appropriate, and publish additional events for downstream consumers.
 
-Add the desired feature dependency, for example:
+## Installing features
 
-```kotlin
-dependencies {
-    implementation("ai.koog.agents:agents-features-trace:$version")
-    implementation("ai.koog.agents:agents-features-debugger:$version")
-}
-```
-
-Install a feature in the agent builder:
+Install features when constructing your agent. Multiple features can be installed together; they remain decoupled and communicate via events.
 
 ```kotlin
 val agent = createAgent(/* ... */) {
-    install(Tracing)
-    install(Debugger)
+    install(Tracing) {
+        // Tracing configuration
+    }
+    install(OpenTelemetry) {
+        // OTel configuration
+    }
 }
 ```
 
-### Using in unit tests
+Consult each feature’s README for exact configuration options and defaults.
 
-Most features can be installed in tests; they honor testing configuration and can be pointed to test writers/ports.
+## Using in unit tests
 
-### Example of usage
+Features are test-friendly. They honor testing configurations and can be directed to in-memory writers/ports.
+- Install the same feature in tests to capture events deterministically.
+- Point outputs to test stubs to assert behavior (e.g., assert a specific sequence of Feature Events).
+- Prefer higher sampling in tests so important transitions are recorded.
+
+Example (pseudo):
+```kotlin
+@Test
+fun testAgentEmitsExpectedEvents() {
+    val events = MutableListWriter<FeatureEvent>()
+    createAgent { 
+        install(EventHandler) { 
+            writer = events 
+        } 
+    }.use { agent ->
+        agent.run("Hello")
+        assertTrue(events.any { it is LlmCallRequested })
+    }
+}
+```
 
-See each feature's Module/README in its submodule for concrete examples (Tracing, Debugger, EventHandler, Memory, OpenTelemetry, Snapshot).
+## Where to learn more
+See each feature’s Module/README in its submodule for concrete examples and advanced setup:
+- Tracing
+- Debugger
+- EventHandler
+- Memory
+- OpenTelemetry
+- Snapshot

docs/docs/agent-event-handlers.md

@@ -0,0 +1,93 @@
+# Event handlers
+
+You can monitor and respond to specific events during the agent workflow by using event handlers for logging, testing, debugging, and extending agent behavior.
+
+## Feature overview
+
+The EventHandler feature lets you hook into various agent events. It serves as an event delegation mechanism that:
+
+- Manages the lifecycle of AI agent operations.
+- Provides hooks for monitoring and responding to different stages of the workflow.
+- Enables error handling and recovery.
+- Facilitates tool invocation tracking and result processing.
+
+<!--## Key components
+
+The EventHandler entity consists of five main handler types:
+
+- Initialization handler that executes at the initialization of an agent run
+- Result handler that processes successful results from agent operations
+- Error handler that handles exceptions and errors that occur during execution
+- Tool call listener that notifies when a tool is about to be invoked
+- Tool result listener that processes the results after a tool has been called-->
+
+
+### Installation and configuration
+
+The EventHandler feature integrates with the agent workflow through the `EventHandler` class,
+which provides a way to register callbacks for different agent events, and can be installed as a feature in the agent configuration. For details, see [API reference](https://api.koog.ai/agents/agents-features/agents-features-event-handler/ai.koog.agents.features.eventHandler.feature/-event-handler/index.html).
+
+To install the feature and configure event handlers for the agent, do the following:
+
+<!--- INCLUDE
+import ai.koog.agents.core.agent.AIAgent
+import ai.koog.agents.features.eventHandler.feature.handleEvents
+import ai.koog.prompt.executor.llms.all.simpleOllamaAIExecutor
+import ai.koog.prompt.llm.OllamaModels
+
+val agent = AIAgent(
+    promptExecutor = simpleOllamaAIExecutor(),
+    llmModel = OllamaModels.Meta.LLAMA_3_2,
+) {
+-->
+<!--- SUFFIX 
+} 
+-->
+
+```kotlin
+handleEvents {
+    // Handle tool calls
+    onToolCallStarting { eventContext ->
+        println("Tool called: ${eventContext.tool.name} with args ${eventContext.toolArgs}")
+    }
+    // Handle event triggered when the agent completes its execution
+    onAgentCompleted { eventContext ->
+        println("Agent finished with result: ${eventContext.result}")
+    }
+
+    // Other event handlers
+}
+```
+<!--- KNIT example-events-01.kt -->
+
+For more details about event handler configuration, see [API reference](https://api.koog.ai/agents/agents-features/agents-features-event-handler/ai.koog.agents.features.eventHandler.feature/-event-handler-config/index.html).
+
+You can also set up event handlers using the `handleEvents` extension function when creating an agent.
+This function also installs the event handler feature and configures event handlers for the agent. Here is an example:
+
+<!--- INCLUDE
+import ai.koog.agents.core.agent.AIAgent
+import ai.koog.agents.features.eventHandler.feature.handleEvents
+import ai.koog.prompt.executor.llms.all.simpleOllamaAIExecutor
+import ai.koog.prompt.llm.OllamaModels
+-->
+```kotlin
+val agent = AIAgent(
+    promptExecutor = simpleOllamaAIExecutor(),
+    llmModel = OllamaModels.Meta.LLAMA_3_2,
+){
+    handleEvents {
+        // Handle tool calls
+        onToolCallStarting { eventContext ->
+            println("Tool called: ${eventContext.tool.name} with args ${eventContext.toolArgs}")
+        }
+        // Handle event triggered when the agent completes its execution
+        onAgentCompleted { eventContext ->
+            println("Agent finished with result: ${eventContext.result}")
+        }
+
+        // Other event handlers
+    }
+}
+```
+<!--- KNIT example-events-02.kt -->