JBRes-7677: opentelementry support for MCP

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

@@ -0,0 +1,60 @@
+package ai.koog.agents.core.feature.handler.tool
+
+import ai.koog.agents.core.annotation.InternalAgentsApi
+
+/**
+ * Metadata keys for tools provided by MCP servers.
+ */
+@InternalAgentsApi
+public object McpMetaDataKeys {
+    public const val ToolId: String = "koog.mcp.tool.id"
+    // The URL where the server is accessible, if applicable (e.g., "http://localhost").
+    public const val ServerUrl: String = "koog.mcp.server.url"
+    // The port number on which the server listens, if applicable.
+    public const val ServerPort: String = "koog.mcp.server.port"
+    // Optional server-provided instructions or documentation for using its tools.
+    public const val Instructions: String = "koog.mcp.server.instructions"
+    // The MCP protocol version supported by this server connection.
+    public const val McpProtocolVersion: String = "koog.mcp.protocol.version"
+    // The transport protocol type used for this connection (e.g., pipe for stdio, tcp for HTTP).
+    public const val McpTransportType: String = "koog.mcp.transport.type"
+    // TODO: support [mcpSessionId] when it would be available in the sdk client
+    // Unique identifier for the current MCP session, if session management is enabled.
+    public const val McpSessionId: String = "koog.mcp.session.id"
+}
+
+/**
+ * Information about an MCP server instance.
+ */
+public class McpServerInfo(
+    public val url: String? = null,
+    public val command: String? = null,
+)
+
+/**
+ * Enumeration of supported MCP server transport protocol types.
+ *
+ * This enum defines the different communication mechanisms that can be used
+ * to establish connections with MCP servers. Each transport type has distinct
+ * characteristics and is suitable for different deployment scenarios.
+ *
+ * @property value The canonical name of the transport protocol.
+ */
+public enum class McpTransportType(public val value: String) {
+    /**
+     * Pipe-based transport using standard input/output streams.
+     *
+     * This transport is typically used for local MCP servers running as separate
+     * processes that communicate via stdio. Suitable for development and local tools.
+     */
+    Stdio("pipe"),
+
+    /**
+     * TCP-based transport using HTTP or other network protocols.
+     *
+     * This transport enables communication with remote MCP servers over network
+     * connections, including HTTP, SSE (Server-Sent Events), or custom TCP protocols.
+     * Suitable for distributed architectures and cloud-based MCP servers.
+     */
+    Tcp("tcp"),
+}

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

@@ -9,28 +9,54 @@ import kotlinx.serialization.json.JsonElement
 import kotlinx.serialization.json.JsonObject
 
 /**
- * Represents the context for handling tool-specific events within the framework.
+ * Represents the context for handling tool call events.
  */
-public interface ToolCallEventContext : AgentLifecycleEventContext
+public interface ToolCallEventContext : AgentLifecycleEventContext {
+    /**
+     * [runId] The unique identifier for this tool call session;
+     */
+    public val runId: String
+
+    /**
+     * [toolCallId] The unique identifier for this tool call;
+     */
+    public val toolCallId: String?
+
+    /**
+     * [toolName] The tool name that is being executed;
+     */
+    public val toolName: String
+
+    /**
+     * [toolDescription] A description of the tool being executed;
+     */
+    public val toolDescription: String?
+
+    /**
+     * [toolArgs] The arguments provided for the tool execution, adhering to the tool's expected input structure.
+     */
+    public val toolArgs: JsonObject
+
+    /**
+     * [context] The agent context associated with the tool call;
+     */
+    public val context: AIAgentContext
+}
 
 /**
  * Represents the context for handling a tool call event.
  *
  * @property executionInfo The execution information containing parentId and current execution path;
- * @property runId The unique identifier for this tool call session;
- * @property toolCallId The unique identifier for this tool call;
- * @property toolName The tool name that is being executed;
- * @property toolArgs The arguments provided for the tool execution, adhering to the tool's expected input structure.
  */
 public data class ToolCallStartingContext(
     override val eventId: String,
     override val executionInfo: AgentExecutionInfo,
-    val runId: String,
-    val toolCallId: String?,
-    val toolName: String,
-    val toolDescription: String?,
-    val toolArgs: JsonObject,
-    val context: AIAgentContext
+    override val runId: String,
+    override val toolCallId: String?,
+    override val toolName: String,
+    override val toolDescription: String?,
+    override val toolArgs: JsonObject,
+    override val context: AIAgentContext
 ) : ToolCallEventContext {
     override val eventType: AgentLifecycleEventType = AgentLifecycleEventType.ToolCallStarting
 }
@@ -39,25 +65,20 @@ public data class ToolCallStartingContext(
  * Represents the context for handling validation errors that occur during the execution of a tool.
  *
  * @property executionInfo The execution information containing parentId and current execution path;
- * @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 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.
  */
 public data class ToolValidationFailedContext(
     override val eventId: String,
     override val executionInfo: AgentExecutionInfo,
-    val runId: String,
-    val toolCallId: String?,
-    val toolName: String,
-    val toolDescription: String?,
-    val toolArgs: JsonObject,
+    override val runId: String,
+    override val toolCallId: String?,
+    override val toolName: String,
+    override val toolDescription: String?,
+    override val toolArgs: JsonObject,
     val message: String,
     val error: AIAgentError,
-    val context: AIAgentContext
+    override val context: AIAgentContext
 ) : ToolCallEventContext {
     override val eventType: AgentLifecycleEventType = AgentLifecycleEventType.ToolValidationFailed
 }
@@ -66,25 +87,20 @@ public data class ToolValidationFailedContext(
  * Represents the context provided to handle a failure during the execution of a tool.
  *
  * @property executionInfo The execution information containing parentId and current execution path;
- * @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 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.
  */
 public data class ToolCallFailedContext(
     override val eventId: String,
     override val executionInfo: AgentExecutionInfo,
-    val runId: String,
-    val toolCallId: String?,
-    val toolName: String,
-    val toolDescription: String?,
-    val toolArgs: JsonObject,
+    override val runId: String,
+    override val toolCallId: String?,
+    override val toolName: String,
+    override val toolDescription: String?,
+    override val toolArgs: JsonObject,
     val message: String,
     val error: AIAgentError?,
-    val context: AIAgentContext
+    override val context: AIAgentContext
 ) : ToolCallEventContext {
     override val eventType: AgentLifecycleEventType = AgentLifecycleEventType.ToolCallFailed
 }
@@ -93,23 +109,18 @@ public data class ToolCallFailedContext(
  * Represents the context used when handling the result of a tool call.
  *
  * @property executionInfo The execution information containing parentId and current execution path;
- * @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 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 eventId: String,
     override val executionInfo: AgentExecutionInfo,
-    val runId: String,
-    val toolCallId: String?,
-    val toolName: String,
-    val toolDescription: String?,
-    val toolArgs: JsonObject,
+    override val runId: String,
+    override val toolCallId: String?,
+    override val toolName: String,
+    override val toolDescription: String?,
+    override val toolArgs: JsonObject,
     val toolResult: JsonElement?,
-    val context: AIAgentContext
+    override val context: AIAgentContext
 ) : ToolCallEventContext {
     override val eventType: AgentLifecycleEventType = AgentLifecycleEventType.ToolCallCompleted
 }

agents/agents-features/agents-features-opentelemetry/build.gradle.kts

@@ -43,6 +43,7 @@ kotlin {
             dependencies {
                 implementation(kotlin("test-junit5"))
                 implementation(project(":agents:agents-test"))
+                implementation(libs.opentelemetry.sdk.testing)
             }
         }
     }