JBRes-7677: opentelementry support for MCP

Author: vova-jb

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

@@ -91,7 +91,7 @@ public expect abstract class AIAgent<Input, Output> constructor() : Closeable {
             promptExecutor: PromptExecutor,
             agentConfig: AIAgentConfig,
             strategy: AIAgentGraphStrategy<Input, Output>,
-            toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
+            toolRegistry: ToolRegistry = ToolRegistry.empty(),
             id: String? = null,
             clock: Clock = Clock.System,
             noinline installFeatures: FeatureContext.() -> Unit = {},
@@ -113,7 +113,7 @@ public expect abstract class AIAgent<Input, Output> constructor() : Closeable {
             promptExecutor: PromptExecutor,
             agentConfig: AIAgentConfig,
             strategy: AIAgentGraphStrategy<String, String> = singleRunStrategy(),
-            toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
+            toolRegistry: ToolRegistry = ToolRegistry.empty(),
             id: String? = null,
             installFeatures: FeatureContext.() -> Unit = {},
         ): GraphAIAgent<String, String>
@@ -137,7 +137,7 @@ public expect abstract class AIAgent<Input, Output> constructor() : Closeable {
             promptExecutor: PromptExecutor,
             agentConfig: AIAgentConfig,
             strategy: AIAgentFunctionalStrategy<Input, Output>,
-            toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
+            toolRegistry: ToolRegistry = ToolRegistry.empty(),
             id: String? = null,
             clock: Clock = Clock.System,
             installFeatures: FunctionalAIAgent.FeatureContext.() -> Unit = {},
@@ -165,7 +165,7 @@ public expect abstract class AIAgent<Input, Output> constructor() : Closeable {
             llmModel: LLModel,
             responseProcessor: ResponseProcessor? = null,
             strategy: AIAgentGraphStrategy<String, String> = singleRunStrategy(),
-            toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
+            toolRegistry: ToolRegistry = ToolRegistry.empty(),
             id: String? = null,
             systemPrompt: String? = null,
             temperature: Double? = null,
@@ -199,7 +199,7 @@ public expect abstract class AIAgent<Input, Output> constructor() : Closeable {
             llmModel: LLModel,
             strategy: AIAgentGraphStrategy<Input, Output>,
             responseProcessor: ResponseProcessor? = null,
-            toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
+            toolRegistry: ToolRegistry = ToolRegistry.empty(),
             id: String? = null,
             clock: Clock = Clock.System,
             systemPrompt: String? = null,
@@ -232,7 +232,7 @@ public expect abstract class AIAgent<Input, Output> constructor() : Closeable {
             promptExecutor: PromptExecutor,
             llmModel: LLModel,
             responseProcessor: ResponseProcessor? = null,
-            toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
+            toolRegistry: ToolRegistry = ToolRegistry.empty(),
             strategy: AIAgentFunctionalStrategy<Input, Output>,
             id: String? = null,
             systemPrompt: String? = null,

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

@@ -0,0 +1,67 @@
+package ai.koog.agents.core.feature.handler.tool
+
+import ai.koog.agents.core.annotation.InternalAgentsApi
+
+/**
+ * Comprehensive metadata describing an MCP server connection.
+ *
+ * This class captures both the server's identity and the active connection details,
+ * including protocol version, transport type, and session information. This metadata
+ * is essential for tracking server capabilities, managing connections, and debugging
+ * tool execution issues.
+ *
+ * @property serverUrl The URL where the server is accessible, if applicable (e.g., "http://localhost").
+ * @property serverPort The port number on which the server listens, if applicable.
+ * @property siteUrl The server's public website URL, if provided by the server.
+ * @property instructions Optional server-provided instructions or documentation for using its tools.
+ * @property mcpProtocolVersion The MCP protocol version supported by this server connection.
+ * @property mcpTransportType The transport protocol type used for this connection (e.g., pipe for stdio, tcp for HTTP).
+ * TODO: support [sessionId] when it would be available in the sdk client
+ * @property sessionId Unique identifier for the current MCP session, if session management is enabled.
+ */
+@InternalAgentsApi
+public class McpServerMeta(
+    public val serverUrl: String?,
+    public val serverPort: Int?,
+    public val siteUrl: String?,
+    public val instructions: String?,
+    public val mcpProtocolVersion: String,
+    public val mcpTransportType: McpTransportType,
+    public val sessionId: String?,
+)
+
+/**
+ * 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.
+     */
+    Pipe("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)
             }
         }
     }