refactor(agents): KG-815. Tool agent event context carries the original exception (#1918)

- Tool agent event context contains a serializable AIAgentError
instance. This type hides important details about an exception, e.g.,
the exact type of the exception. Replaced this serializable type with a
Throwable instead and transform to AIAgentError when needed;
- Renamed `throwable` to `error` on Agent/Node/Subgraph failed contexts
and pipeline parameters for consistency across lifecycle events;
- Switched `onToolValidationFailed` and `onToolCallFailed` pipeline
signatures to accept Throwable;
- Added a custom serializer for ToolResultKind.Failure / ValidationError
that encodes a Throwable through AIAgentError, preserving the existing
JSON wire format;
- Updated OpenTelemetry span and metric helpers to take Throwable
directly, fixing a latent `error.type` attribute that always reported
AIAgentError as the exception class;

closes: [KG-815](https://youtrack.jetbrains.com/issue/KG-815)

Author: sdubov

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

@@ -3,7 +3,6 @@ package ai.koog.agents.core.environment
 import ai.koog.agents.core.agent.context.AIAgentContext
 import ai.koog.agents.core.agent.execution.AgentExecutionInfo
 import ai.koog.agents.core.annotation.InternalAgentsApi
-import ai.koog.agents.core.feature.model.toAgentError
 import ai.koog.prompt.message.Message
 import ai.koog.serialization.JSONObject
 import ai.koog.serialization.kotlinx.toKoogJSONObject
@@ -58,7 +57,7 @@ public class ContextualAgentEnvironment(
                 toolDescription = toolDescription,
                 toolArgs = toolArgs,
                 message = message,
-                error = e.toAgentError(),
+                error = e,
                 context = context
             )
             return ReceivedToolResult(
@@ -67,7 +66,7 @@ public class ContextualAgentEnvironment(
                 toolArgs = toolArgs,
                 toolDescription = null,
                 content = message,
-                resultKind = ToolResultKind.ValidationError(e.toAgentError()),
+                resultKind = ToolResultKind.ValidationError(e),
                 result = null
             )
         }

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

@@ -1,6 +1,5 @@
 package ai.koog.agents.core.environment
 
-import ai.koog.agents.core.feature.model.toAgentError
 import ai.koog.agents.core.tools.Tool
 import ai.koog.agents.core.tools.ToolException
 import ai.koog.agents.core.tools.ToolRegistry
@@ -61,7 +60,7 @@ public class GenericAgentEnvironment(
                 toolArgs = JSONObject(emptyMap()),
                 toolDescription = null,
                 content = "Tool with name '$toolName' failed to parse arguments due to the error: ${e.message}",
-                resultKind = ToolResultKind.Failure(e.toAgentError()),
+                resultKind = ToolResultKind.Failure(e),
                 result = null,
             )
         }
@@ -95,7 +94,7 @@ public class GenericAgentEnvironment(
                 toolArgs = toolArgsJson,
                 toolDescription = toolDescription,
                 content = "Tool with name '$toolName' failed to parse arguments due to the error: ${e.message}",
-                resultKind = ToolResultKind.Failure(e.toAgentError()),
+                resultKind = ToolResultKind.Failure(e),
                 result = null,
             )
         }
@@ -112,7 +111,7 @@ public class GenericAgentEnvironment(
                 toolArgs = toolArgsJson,
                 toolDescription = toolDescription,
                 content = e.message,
-                resultKind = ToolResultKind.ValidationError(e.toAgentError()),
+                resultKind = ToolResultKind.ValidationError(e),
                 result = null,
             )
         } catch (e: Exception) {
@@ -124,7 +123,7 @@ public class GenericAgentEnvironment(
                 toolArgs = toolArgsJson,
                 toolDescription = toolDescription,
                 content = "Tool with name '$toolName' failed to execute due to the error: ${e.message}!",
-                resultKind = ToolResultKind.Failure(e.toAgentError()),
+                resultKind = ToolResultKind.Failure(e),
                 result = null
             )
         }
@@ -144,7 +143,7 @@ public class GenericAgentEnvironment(
                 toolArgs = toolArgsJson,
                 toolDescription = toolDescription,
                 content = "Tool with name '$toolName' failed to serialize result due to the error: ${e.message}!",
-                resultKind = ToolResultKind.Failure(e.toAgentError()),
+                resultKind = ToolResultKind.Failure(e),
                 result = null
             )
         }

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

@@ -1,7 +1,12 @@
 package ai.koog.agents.core.environment
 
 import ai.koog.agents.core.feature.model.AIAgentError
+import ai.koog.agents.core.feature.model.toAgentError
+import kotlinx.serialization.KSerializer
 import kotlinx.serialization.Serializable
+import kotlinx.serialization.descriptors.SerialDescriptor
+import kotlinx.serialization.encoding.Decoder
+import kotlinx.serialization.encoding.Encoder
 
 /**
  * Represents the possible result types for a tool operation.
@@ -18,16 +23,46 @@ public sealed class ToolResultKind {
     /**
      * Represents a failure result in the context of a tool operation.
      *
-     * @property error The [Throwable] that caused the failure. It can be null if no specific throwable information is available.
+     * @property error The exception that caused the failure, or `null` if no exception is available.
+     *                 Encoded as an [AIAgentError] over the wire.
      */
     @Serializable
-    public data class Failure(public val error: AIAgentError?) : ToolResultKind()
+    public data class Failure(
+        @Serializable(with = ThrowableAsAgentErrorSerializer::class)
+        public val error: Throwable?,
+    ) : ToolResultKind()
 
     /**
      * Represents a validation error result in the context of a tool operation.
      *
-     * @property error The specific tool exception that describes the details of the validation failure.
+     * @property error The exception describing the validation failure.
+     *                 Encoded as an [AIAgentError] over the wire.
      */
     @Serializable
-    public data class ValidationError(public val error: AIAgentError) : ToolResultKind()
+    public data class ValidationError(
+        @Serializable(with = ThrowableAsAgentErrorSerializer::class)
+        public val error: Throwable,
+    ) : ToolResultKind()
+}
+
+/**
+ * Serializes a [Throwable] field by encoding it through [AIAgentError]
+ *
+ * The original [AIAgentError] is used to preserve the original [Throwable] to use it in agent event context.
+ *
+ * Note: Decoding is intentionally lossy.
+ *      [ReceivedToolResult] is not deserialized anywhere in the codebase today,
+ *      and full round-trip fidelity can be added (via a wrapper) if a real decoded use case appears.
+ *      It returns a plain [Throwable] with the original message but no stack/cause/type.
+ */
+internal object ThrowableAsAgentErrorSerializer : KSerializer<Throwable> {
+    private val delegate = AIAgentError.serializer()
+    override val descriptor: SerialDescriptor = delegate.descriptor
+
+    override fun serialize(encoder: Encoder, value: Throwable) {
+        delegate.serialize(encoder, value.toAgentError())
+    }
+
+    override fun deserialize(decoder: Decoder): Throwable =
+        Throwable(delegate.deserialize(decoder).message)
 }

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

@@ -117,7 +117,7 @@ public class ContextualPromptExecutor(
             }
             .catch { error ->
                 logger.debug(error) { "Error in LLM streaming call (event id: $eventId): $error" }
-                context.pipeline.onLLMStreamingFailed(eventId, context.executionInfo, context.runId, prompt = effectivePrompt, model, throwable = error, context)
+                context.pipeline.onLLMStreamingFailed(eventId, context.executionInfo, context.runId, prompt = effectivePrompt, model, error = error, context)
 
                 throw error
             }

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

@@ -209,7 +209,7 @@ public class Debugger(public val port: Int, public val awaitInitialConnectionTim
                     executionInfo = eventContext.executionInfo,
                     agentId = eventContext.agentId,
                     runId = eventContext.runId,
-                    error = eventContext.throwable.toAgentError(),
+                    error = eventContext.error.toAgentError(),
                     timestamp = pipeline.clock.now().toEpochMilliseconds()
                 )
                 writer.onMessage(event)
@@ -378,7 +378,7 @@ public class Debugger(public val port: Int, public val awaitInitialConnectionTim
                     toolArgs = eventContext.toolArgs,
                     toolDescription = eventContext.toolDescription,
                     message = eventContext.message,
-                    error = eventContext.error,
+                    error = eventContext.error.toAgentError(),
                     timestamp = pipeline.clock.now().toEpochMilliseconds()
                 )
                 writer.onMessage(event)
@@ -393,7 +393,7 @@ public class Debugger(public val port: Int, public val awaitInitialConnectionTim
                     toolName = eventContext.toolName,
                     toolArgs = eventContext.toolArgs,
                     toolDescription = eventContext.toolDescription,
-                    error = eventContext.error,
+                    error = eventContext.error?.toAgentError(),
                     timestamp = pipeline.clock.now().toEpochMilliseconds()
                 )
                 writer.onMessage(event)
@@ -474,7 +474,7 @@ public class Debugger(public val port: Int, public val awaitInitialConnectionTim
                         eventContext.inputType,
                         pipeline.config.serializer
                     ),
-                    error = eventContext.throwable.toAgentError(),
+                    error = eventContext.error.toAgentError(),
                     timestamp = pipeline.clock.now().toEpochMilliseconds()
                 )
                 writer.onMessage(event)
@@ -532,7 +532,7 @@ public class Debugger(public val port: Int, public val awaitInitialConnectionTim
                         eventContext.inputType,
                         pipeline.config.serializer
                     ),
-                    error = eventContext.throwable.toAgentError(),
+                    error = eventContext.error.toAgentError(),
                     timestamp = pipeline.clock.now().toEpochMilliseconds()
                 )
                 writer.onMessage(event)

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

@@ -62,14 +62,14 @@ public data class AgentCompletedContext(
  * @property executionInfo The execution information containing parentId and current execution path;
  * @property agentId The unique identifier of the agent associated with the error.
  * @property runId The identifier for the session during which the error occurred.
- * @property throwable The exception or error thrown during the execution.
+ * @property error The exception or error thrown during the execution.
  */
 public data class AgentExecutionFailedContext(
     override val eventId: String,
     override val executionInfo: AgentExecutionInfo,
     val agentId: String,
     val runId: String,
-    val throwable: Throwable,
+    val error: Throwable,
     public val context: AIAgentContext,
 ) : AgentEventContext {
     override val eventType: AgentLifecycleEventType = AgentLifecycleEventType.AgentExecutionFailed

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

@@ -64,7 +64,7 @@ public data class NodeExecutionCompletedContext(
  * @property context The stage context in which the node experienced the error.
  * @property input The input data for the node execution.
  * @property inputType [TypeToken] representing the type of the [input].
- * @property throwable The exception or error that occurred during node execution.
+ * @property error The exception or error that occurred during node execution.
  */
 public data class NodeExecutionFailedContext(
     override val eventId: String,
@@ -73,7 +73,7 @@ public data class NodeExecutionFailedContext(
     val context: AIAgentGraphContextBase,
     val input: Any?,
     val inputType: TypeToken,
-    val throwable: Throwable
+    val error: Throwable
 ) : NodeExecutionEventContext {
     override val eventType: AgentLifecycleEventType = AgentLifecycleEventType.NodeExecutionFailed
 }

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

@@ -64,7 +64,7 @@ public data class SubgraphExecutionCompletedContext(
  * @property context The context in which the subgraph failed to execute.
  * @property input The input data for the subgraph execution.
  * @property inputType The type of the input data for the subgraph execution.
- * @property throwable The exception that caused the subgraph execution to fail.
+ * @property error The exception that caused the subgraph execution to fail.
  */
 public data class SubgraphExecutionFailedContext(
     override val eventId: String,
@@ -73,7 +73,7 @@ public data class SubgraphExecutionFailedContext(
     val context: AIAgentGraphContextBase,
     val input: Any?,
     val inputType: TypeToken,
-    val throwable: Throwable
+    val error: Throwable
 ) : SubgraphExecutionEventContext {
     override val eventType: AgentLifecycleEventType = AgentLifecycleEventType.SubgraphExecutionFailed
 }

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

@@ -4,7 +4,6 @@ import ai.koog.agents.core.agent.context.AIAgentContext
 import ai.koog.agents.core.agent.execution.AgentExecutionInfo
 import ai.koog.agents.core.feature.handler.AgentLifecycleEventContext
 import ai.koog.agents.core.feature.handler.AgentLifecycleEventType
-import ai.koog.agents.core.feature.model.AIAgentError
 import ai.koog.serialization.JSONElement
 import ai.koog.serialization.JSONObject
 
@@ -66,7 +65,7 @@ public data class ToolCallStartingContext(
  *
  * @property executionInfo The execution information containing parentId and current execution path;
  * @property message A message describing the validation error.
- * @property error The [AIAgentError] error describing the validation issue.
+ * @property error The exception describing the validation issue.
  */
 public data class ToolValidationFailedContext(
     override val eventId: String,
@@ -77,7 +76,7 @@ public data class ToolValidationFailedContext(
     override val toolDescription: String?,
     override val toolArgs: JSONObject,
     val message: String,
-    val error: AIAgentError,
+    val error: Throwable,
     override val context: AIAgentContext
 ) : ToolCallEventContext {
     override val eventType: AgentLifecycleEventType = AgentLifecycleEventType.ToolValidationFailed
@@ -88,7 +87,7 @@ public data class ToolValidationFailedContext(
  *
  * @property executionInfo The execution information containing parentId and current execution path;
  * @property message A message describing the failure that occurred.
- * @property error The [AIAgentError] instance describing the tool call failure.
+ * @property error The exception describing the tool call failure, or `null` if no exception is available.
  */
 public data class ToolCallFailedContext(
     override val eventId: String,
@@ -99,7 +98,7 @@ public data class ToolCallFailedContext(
     override val toolDescription: String?,
     override val toolArgs: JSONObject,
     val message: String,
-    val error: AIAgentError?,
+    val error: Throwable?,
     override val context: AIAgentContext
 ) : ToolCallEventContext {
     override val eventType: AgentLifecycleEventType = AgentLifecycleEventType.ToolCallFailed

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

@@ -103,7 +103,7 @@ public expect open class AIAgentGraphPipeline(
      * @param context The context associated with the AI agent executing the node.
      * @param input The input data provided to the node.
      * @param inputType The type of the input data provided to the node.
-     * @param throwable The exception or error that occurred during node execution.
+     * @param error The exception or error that occurred during node execution.
      */
     @InternalAgentsApi
     public open override suspend fun onNodeExecutionFailed(
@@ -113,7 +113,7 @@ public expect open class AIAgentGraphPipeline(
         context: AIAgentGraphContextBase,
         input: Any?,
         inputType: TypeToken,
-        throwable: Throwable
+        error: Throwable
     )
 
     //endregion Trigger Node Handlers
@@ -173,7 +173,7 @@ public expect open class AIAgentGraphPipeline(
      * @param context The agent context in which the subgraph execution occurred.
      * @param input The input data that was provided to the subgraph when it failed.
      * @param inputType The type of the input data provided to the subgraph.
-     * @param throwable The exception or error that caused the subgraph execution to fail.
+     * @param error The exception or error that caused the subgraph execution to fail.
      */
     @InternalAgentsApi
     public open override suspend fun onSubgraphExecutionFailed(
@@ -183,7 +183,7 @@ public expect open class AIAgentGraphPipeline(
         context: AIAgentGraphContextBase,
         input: Any?,
         inputType: TypeToken,
-        throwable: Throwable
+        error: Throwable
     )
 
     //endregion Trigger Subgraph Handlers
@@ -235,7 +235,7 @@ public expect open class AIAgentGraphPipeline(
      * Example:
      * ```
      * pipeline.interceptNodeExecutionFailed(feature) { eventContext ->
-     *     logger.error("Node ${eventContext.node.name} execution failed with error: ${eventContext.throwable}")
+     *     logger.error("Node ${eventContext.node.name} execution failed with error: ${eventContext.error}")
      * }
      * ```
      */
@@ -290,7 +290,7 @@ public expect open class AIAgentGraphPipeline(
      * Example:
      * ```
      * pipeline.interceptSubgraphExecutionFailed(feature) { eventContext ->
-     *     logger.error("Subgraph ${eventContext.subgraph.name} execution failed with error: ${eventContext.throwable}")
+     *     logger.error("Subgraph ${eventContext.subgraph.name} execution failed with error: ${eventContext.error}")
      * }
      * ```
      */