KG-505. Add ExperimentalAgentsApi annotation to mark Debugger feature

Author: sdubov

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/annotation/ExperimentalAgentsApi.kt

@@ -0,0 +1,13 @@
+package ai.koog.agents.core.annotation
+
+/**
+ * Marks an API as experimental for agent-related implementations.
+ *
+ * APIs annotated with `ExperimentalAgentsApi` are not considered stable and may change, be removed,
+ * or have their behavior modified in future updates. This warning is provided to
+ * indicate that the use of such APIs requires caution and acknowledgment of potential instability.
+ *
+ * Note that no guarantees are made regarding backward compatibility of elements marked with this annotation.
+ */
+@RequiresOptIn("This API is experimental and is likely to change in the future.")
+public annotation class ExperimentalAgentsApi

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

@@ -4,6 +4,7 @@ import ai.koog.agents.core.agent.context.AIAgentContext
 import ai.koog.agents.core.agent.context.featureOrThrow
 import ai.koog.agents.core.agent.entity.AIAgentGraphStrategy
 import ai.koog.agents.core.agent.entity.AIAgentStorageKey
+import ai.koog.agents.core.annotation.ExperimentalAgentsApi
 import ai.koog.agents.core.annotation.InternalAgentsApi
 import ai.koog.agents.core.environment.ReceivedToolResult
 import ai.koog.agents.core.feature.AIAgentFunctionalFeature
@@ -60,6 +61,7 @@ import kotlin.time.toDuration
  * @property port The port number on which the debugger server is listening for connections.
  * @property awaitInitialConnectionTimeout The timeout duration for the debugger server to wait for a connection.
  */
+@ExperimentalAgentsApi
 public class Debugger(public val port: Int, public val awaitInitialConnectionTimeout: Duration? = null) {
 
     /**
@@ -457,4 +459,5 @@ public class Debugger(public val port: Int, public val awaitInitialConnectionTim
  * @return The [Debugger] feature instance for this agent
  * @throws IllegalStateException if the Debugger feature is not installed
  */
+@OptIn(ExperimentalAgentsApi::class)
 public fun AIAgentContext.debugger(): Debugger = featureOrThrow(Debugger)

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

@@ -6,6 +6,7 @@ import ai.koog.agents.core.agent.context.AIAgentContext
 import ai.koog.agents.core.agent.context.AIAgentGraphContextBase
 import ai.koog.agents.core.agent.entity.AIAgentStorageKey
 import ai.koog.agents.core.agent.entity.AIAgentStrategy
+import ai.koog.agents.core.annotation.ExperimentalAgentsApi
 import ai.koog.agents.core.annotation.InternalAgentsApi
 import ai.koog.agents.core.environment.AIAgentEnvironment
 import ai.koog.agents.core.feature.AIAgentFeature
@@ -127,6 +128,7 @@ public abstract class AIAgentPipeline(public val clock: Clock) {
     /**
      * Set of system features that are always defined by the framework.
      */
+    @OptIn(ExperimentalAgentsApi::class)
     private val systemFeatures: Set<AIAgentStorageKey<*>> = setOf(
         Debugger.key
     )
@@ -1242,6 +1244,7 @@ public abstract class AIAgentPipeline(public val clock: Clock) {
         }
     }
 
+    @OptIn(ExperimentalAgentsApi::class)
     private fun installSystemFeature(featureKey: AIAgentStorageKey<*>) {
         logger.debug { "Installing system feature: ${featureKey.name}" }
         when (featureKey) {