KG-505. Add system features to agents core

- Add a list of system features (Debugger) that can be installed through agent configuration parameters;
- Add agent logic to read a system property and set up Debugger feature with a provided config;
- Add tests to check updates in an agent pipeline logic.

Author: sdubov

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

@@ -158,8 +158,8 @@ public interface AIAgent<Input, Output> : Closeable {
          * @param Output The type of the output the AI agent will produce.
          * @param promptExecutor The executor responsible for processing prompts and interacting with the language model.
          * @param agentConfig The configuration for the AI agent, including the prompt, model, and other parameters.
-         * @param toolRegistry The registry of tools available for use by the agent. Defaults to an empty registry.
          * @param strategy The strategy for executing the AI agent's graph logic, including workflows and decision-making.
+         * @param toolRegistry The registry of tools available for use by the agent. Defaults to an empty registry.
          * @param id Unique identifier for the agent. Random UUID will be generated if set to null.
          * @param clock The clock to be used for time-related operations. Defaults to the system clock.
          * @param installFeatures A lambda expression to install additional features in the agent's feature context. Defaults to an empty implementation.
@@ -174,7 +174,7 @@ public interface AIAgent<Input, Output> : Closeable {
             id: String? = null,
             clock: Clock = Clock.System,
             noinline installFeatures: FeatureContext.() -> Unit = {},
-        ): AIAgent<Input, Output> {
+        ): GraphAIAgent<Input, Output> {
             return GraphAIAgent(
                 inputType = typeOf<Input>(),
                 outputType = typeOf<Output>(),
@@ -192,7 +192,6 @@ public interface AIAgent<Input, Output> : Closeable {
          * Operator function to create and invoke an AI agent with the given parameters.
          *
          * @param promptExecutor The executor responsible for running the prompt and generating outputs.
-         * @param prompt The prompt to be processed by the AI agent.
          * @param agentConfig Configuration settings for the AI agent.
          * @param strategy The strategy to be used for the AI agent's execution graph. Defaults to a single-run strategy.
          * @param toolRegistry Registry of tools available for the AI agent to use. Defaults to an empty registry.
@@ -208,7 +207,7 @@ public interface AIAgent<Input, Output> : Closeable {
             toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
             id: String? = null,
             installFeatures: FeatureContext.() -> Unit = {},
-        ): AIAgent<String, String> = GraphAIAgent(
+        ): GraphAIAgent<String, String> = GraphAIAgent(
             inputType = typeOf<String>(),
             outputType = typeOf<String>(),
             promptExecutor = promptExecutor,
@@ -227,9 +226,11 @@ public interface AIAgent<Input, Output> : Closeable {
          * @param Output The type of the output the AI agent will produce.
          * @param promptExecutor The executor responsible for running prompts against the language model.
          * @param agentConfig The configuration for the AI agent, including prompt setup, language model, and iteration limits.
-         * @param toolRegistry The registry containing available tools for the AI agent. Defaults to an empty registry.
          * @param strategy The strategy for executing the agent's logic, including workflows and decision-making.
+         * @param toolRegistry The registry containing available tools for the AI agent. Defaults to an empty registry.
          * @param id Unique identifier for the agent. Random UUID will be generated if set to null.
+         * @param clock The clock instance used for time-related operations. Defaults to the system clock.
+         * @param installFeatures A lambda expression to install additional features in the agent's feature context. Defaults to an empty implementation.
          * @return A `FunctionalAIAgent` instance configured with the provided parameters and execution strategy.
          */
         @OptIn(ExperimentalUuidApi::class)
@@ -332,9 +333,11 @@ public interface AIAgent<Input, Output> : Closeable {
             numberOfChoices: Int = 1,
             maxIterations: Int = 50,
             noinline installFeatures: FeatureContext.() -> Unit = {},
-        ): AIAgent<Input, Output> {
-            return AIAgent(
+        ): GraphAIAgent<Input, Output> {
+            return GraphAIAgent(
                 id = id,
+                inputType = typeOf<Input>(),
+                outputType = typeOf<Output>(),
                 promptExecutor = promptExecutor,
                 strategy = strategy,
                 agentConfig = AIAgentConfig(
@@ -351,6 +354,7 @@ public interface AIAgent<Input, Output> : Closeable {
                     maxAgentIterations = maxIterations,
                 ),
                 toolRegistry = toolRegistry,
+                clock = clock,
                 installFeatures = installFeatures
             )
         }
@@ -359,10 +363,12 @@ public interface AIAgent<Input, Output> : Closeable {
          * Creates an [FunctionalAIAgent] with the specified parameters to execute a strategy with the assistance of a tool registry,
          * configured language model, and associated features.
          *
+         * @param Input The type of input accepted by the agent.
+         * @param Output The type of output produced by the agent.
          * @param promptExecutor The executor used to process prompts for the language model.
          * @param llmModel The language model configuration defining the underlying LLM instance and its behavior.
-         * @param func The operational strategy for the AI agent, which determines how to handle the provided input.
          * @param toolRegistry Registry containing tools available to the agent for use during execution. Default is an empty registry.
+         * @param strategy The strategy to be executed by the agent. Default is a single-run strategy.
          * @param id Unique identifier for the agent. Random UUID will be generated if set to null.
          * @param systemPrompt The system prompt that sets the initial context or instructions for the AI agent.
          * @param temperature The temperature setting for the language model, which adjusts the diversity of output. Default is 1.0.
@@ -382,7 +388,7 @@ public interface AIAgent<Input, Output> : Closeable {
             numberOfChoices: Int = 1,
             maxIterations: Int = 50,
             installFeatures: FunctionalAIAgent.FeatureContext.() -> Unit = {},
-        ): AIAgent<Input, Output> = FunctionalAIAgent(
+        ): FunctionalAIAgent<Input, Output> = FunctionalAIAgent(
             promptExecutor = promptExecutor,
             agentConfig = AIAgentConfig(
                 prompt = prompt(

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

@@ -35,7 +35,7 @@ import kotlin.reflect.KType
  * @property inputType [KType] representing [Input] - agent input.
  * @property outputType [KType] representing [Output] - agent output.
  * @property promptExecutor Executor used to manage and execute prompt strings.
- * @property strategy The execution strategy defining how the agent processes input and produces output..
+ * @property strategy The execution strategy defining how the agent processes input and produces output.
  * @property agentConfig Configuration details for the local agent that define its operational parameters.
  * @property toolRegistry Registry of tools the agent can interact with, defaulting to an empty registry.
  * @property installFeatures Lambda for installing additional features within the agent environment.

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

@@ -0,0 +1,21 @@
+package ai.koog.agents.core.feature.config
+
+/**
+ * A utility object that provides constants representing system variables
+ * related to the configuration of features in the system.
+ *
+ * These system variables enable external configuration of features via
+ * environment variables or JVM options.
+ */
+public object FeatureSystemVariables {
+
+    /**
+     * The name of the environment variable used to configure features in the system.
+     */
+    public const val KOOG_FEATURES_ENV_VAR_NAME: String = "KOOG_FEATURES"
+
+    /**
+     * The name of the JVM option used to configure features in the system.
+     */
+    public const val KOOG_FEATURES_VM_OPTION_NAME: String = "koog.features"
+}

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

@@ -1,13 +1,14 @@
-package ai.koog.agents.features.debugger.feature
+package ai.koog.agents.core.feature.debugger
 
+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.InternalAgentsApi
 import ai.koog.agents.core.environment.ReceivedToolResult
+import ai.koog.agents.core.feature.AIAgentFunctionalFeature
 import ai.koog.agents.core.feature.AIAgentGraphFeature
-import ai.koog.agents.core.feature.debugger.DebuggerConfig
-import ai.koog.agents.core.system.readEnvironmentVariable
-import ai.koog.agents.core.system.readVMOption
+import ai.koog.agents.core.feature.debugger.writer.DebuggerFeatureMessageRemoteWriter
 import ai.koog.agents.core.feature.model.events.AgentClosingEvent
 import ai.koog.agents.core.feature.model.events.AgentCompletedEvent
 import ai.koog.agents.core.feature.model.events.AgentExecutionFailedEvent
@@ -29,11 +30,14 @@ import ai.koog.agents.core.feature.model.events.ToolCallStartingEvent
 import ai.koog.agents.core.feature.model.events.ToolValidationFailedEvent
 import ai.koog.agents.core.feature.model.events.startNodeToGraph
 import ai.koog.agents.core.feature.model.toAgentError
+import ai.koog.agents.core.feature.pipeline.AIAgentFunctionalPipeline
 import ai.koog.agents.core.feature.pipeline.AIAgentGraphPipeline
+import ai.koog.agents.core.feature.pipeline.AIAgentPipeline
 import ai.koog.agents.core.feature.remote.server.config.DefaultServerConnectionConfig
+import ai.koog.agents.core.system.getEnvironmentVariableOrNull
+import ai.koog.agents.core.system.getVMOptionOrNull
 import ai.koog.agents.core.tools.Tool
 import ai.koog.agents.core.utils.SerializationUtils
-import ai.koog.agents.core.feature.debugger.writer.DebuggerFeatureMessageRemoteWriter
 import ai.koog.prompt.llm.toModelInfo
 import io.github.oshai.kotlinlogging.KotlinLogging
 import kotlinx.serialization.json.JsonElement
@@ -52,13 +56,18 @@ import kotlin.time.toDuration
  * This feature serves as a debugging tool for analyzing the AI agent's behavior and
  * interactions with its components, providing insights into the execution flow and
  * potential issues.
+ *
+ * @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.
  */
-public class Debugger {
+public class Debugger(public val port: Int, public val awaitInitialConnectionTimeout: Duration? = null) {
 
     /**
      * Companion object implementing agent feature, handling [Debugger] creation and installation.
      */
-    public companion object Feature : AIAgentGraphFeature<DebuggerConfig, Debugger> {
+    public companion object Feature :
+        AIAgentGraphFeature<DebuggerConfig, Debugger>,
+        AIAgentFunctionalFeature<DebuggerConfig, Debugger> {
 
         private val logger = KotlinLogging.logger { }
 
@@ -89,20 +98,45 @@ public class Debugger {
 
         override fun createInitialConfig(): DebuggerConfig = DebuggerConfig()
 
-        override fun install(
-            config: DebuggerConfig,
-            pipeline: AIAgentGraphPipeline,
-        ): Debugger {
+        override fun install(config: DebuggerConfig, pipeline: AIAgentGraphPipeline): Debugger {
             logger.debug { "Debugger Feature. Start installing feature: ${Debugger::class.simpleName}" }
 
+            val writer = configureRemoteWriter(config)
+            installGraphPipeline(pipeline, writer)
+
+            return Debugger(
+                port = writer.server.connectionConfig.port,
+                awaitInitialConnectionTimeout = writer.server.connectionConfig.awaitInitialConnectionTimeout
+            )
+        }
+
+        override fun install(config: DebuggerConfig, pipeline: AIAgentFunctionalPipeline): Debugger {
+            logger.debug { "Debugger Feature. Start installing feature: ${Debugger::class.simpleName}" }
+
+            val writer = configureRemoteWriter(config)
+            installFunctionalPipeline(pipeline, writer)
+
+            return Debugger(
+                port = writer.server.connectionConfig.port,
+                awaitInitialConnectionTimeout = writer.server.connectionConfig.awaitInitialConnectionTimeout
+            )
+        }
+
+        /**
+         * Creates a new [DebuggerFeatureMessageRemoteWriter] instance for the given [AIAgentGraphPipeline]
+         */
+        private fun configureRemoteWriter(config: DebuggerConfig): DebuggerFeatureMessageRemoteWriter {
+            logger.debug { "Debugger Feature. Creating debugger remote writer" }
+
             // Config that will be used to connect to the debugger server where
             // port is taken from environment variables if not set explicitly
 
             val port = config.port ?: readPortValue()
-            logger.debug { "Debugger Feature. Use debugger port: $port" }
-
             val awaitInitialConnectionTimeout = config.awaitInitialConnectionTimeout ?: readWaitConnectionTimeout()
-            logger.debug { "Debugger Feature. Use debugger server wait connection timeout: $awaitInitialConnectionTimeout" }
+            logger.debug {
+                "Debugger Feature. Use debugger with parameters " +
+                    "(port: $port, server wait connection timeout: $awaitInitialConnectionTimeout)"
+            }
 
             val debuggerServerConfig = DefaultServerConnectionConfig(
                 port = port,
@@ -113,8 +147,13 @@ public class Debugger {
             val writer = DebuggerFeatureMessageRemoteWriter(connectionConfig = debuggerServerConfig)
             config.addMessageProcessor(writer)
 
-            val debugger = Debugger()
+            return writer
+        }
 
+        private fun installCommon(
+            pipeline: AIAgentPipeline,
+            writer: DebuggerFeatureMessageRemoteWriter,
+        ) {
             //region Intercept Agent Events
 
             pipeline.interceptAgentStarting(this) intercept@{ eventContext ->
@@ -184,43 +223,6 @@ public class Debugger {
 
             //endregion Intercept Strategy Events
 
-            //region Intercept Node Events
-
-            pipeline.interceptNodeExecutionStarting(this) intercept@{ eventContext ->
-                val event = NodeExecutionStartingEvent(
-                    runId = eventContext.context.runId,
-                    nodeName = eventContext.node.name,
-                    input = getNodeData(eventContext.input, eventContext.inputType),
-                    timestamp = pipeline.clock.now().toEpochMilliseconds()
-                )
-                writer.onMessage(event)
-            }
-
-            pipeline.interceptNodeExecutionCompleted(this) intercept@{ eventContext ->
-
-                val event = NodeExecutionCompletedEvent(
-                    runId = eventContext.context.runId,
-                    nodeName = eventContext.node.name,
-                    input = getNodeData(eventContext.input, eventContext.inputType),
-                    output = getNodeData(eventContext.output, eventContext.outputType),
-                    timestamp = pipeline.clock.now().toEpochMilliseconds()
-                )
-                writer.onMessage(event)
-            }
-
-            pipeline.interceptNodeExecutionFailed(this) intercept@{ eventContext ->
-                val event = NodeExecutionFailedEvent(
-                    runId = eventContext.context.runId,
-                    nodeName = eventContext.node.name,
-                    input = getNodeData(eventContext.input, eventContext.inputType),
-                    error = eventContext.throwable.toAgentError(),
-                    timestamp = pipeline.clock.now().toEpochMilliseconds()
-                )
-                writer.onMessage(event)
-            }
-
-            //endregion Intercept Node Events
-
             //region Intercept LLM Call Events
 
             pipeline.interceptLLMCallStarting(this) intercept@{ eventContext ->
@@ -354,25 +356,74 @@ public class Debugger {
             }
 
             //endregion Intercept Tool Call Events
+        }
+
+        private fun installGraphPipeline(
+            pipeline: AIAgentGraphPipeline,
+            writer: DebuggerFeatureMessageRemoteWriter,
+        ) {
+            installCommon(pipeline, writer)
+
+            //region Intercept Node Events
+
+            pipeline.interceptNodeExecutionStarting(this) intercept@{ eventContext ->
+                val event = NodeExecutionStartingEvent(
+                    runId = eventContext.context.runId,
+                    nodeName = eventContext.node.name,
+                    input = getNodeData(eventContext.input, eventContext.inputType),
+                    timestamp = pipeline.clock.now().toEpochMilliseconds()
+                )
+                writer.onMessage(event)
+            }
+
+            pipeline.interceptNodeExecutionCompleted(this) intercept@{ eventContext ->
 
-            return debugger
+                val event = NodeExecutionCompletedEvent(
+                    runId = eventContext.context.runId,
+                    nodeName = eventContext.node.name,
+                    input = getNodeData(eventContext.input, eventContext.inputType),
+                    output = getNodeData(eventContext.output, eventContext.outputType),
+                    timestamp = pipeline.clock.now().toEpochMilliseconds()
+                )
+                writer.onMessage(event)
+            }
+
+            pipeline.interceptNodeExecutionFailed(this) intercept@{ eventContext ->
+                val event = NodeExecutionFailedEvent(
+                    runId = eventContext.context.runId,
+                    nodeName = eventContext.node.name,
+                    input = getNodeData(eventContext.input, eventContext.inputType),
+                    error = eventContext.throwable.toAgentError(),
+                    timestamp = pipeline.clock.now().toEpochMilliseconds()
+                )
+                writer.onMessage(event)
+            }
+
+            //endregion Intercept Node Events
+        }
+
+        private fun installFunctionalPipeline(
+            pipeline: AIAgentFunctionalPipeline,
+            writer: DebuggerFeatureMessageRemoteWriter,
+        ) {
+            installCommon(pipeline, writer)
         }
 
         //region Private Methods
 
         private fun readPortValue(): Int? {
             val debuggerPortValue =
-                readEnvironmentVariable(name = KOOG_DEBUGGER_PORT_ENV_VAR)
-                    ?: readVMOption(name = KOOG_DEBUGGER_PORT_VM_OPTION)
+                getEnvironmentVariableOrNull(name = KOOG_DEBUGGER_PORT_ENV_VAR)
+                    ?: getVMOptionOrNull(name = KOOG_DEBUGGER_PORT_VM_OPTION)
 
             logger.debug { "Debugger Feature. Reading Koog debugger port value from system variables: $debuggerPortValue" }
             return debuggerPortValue?.toIntOrNull()
         }
 
         private fun readWaitConnectionTimeout(): Duration? {
             val debuggerWaitConnectionTimeoutValue =
-                readEnvironmentVariable(name = KOOG_DEBUGGER_WAIT_CONNECTION_MS_ENV_VAR)
-                    ?: readVMOption(name = KOOG_DEBUGGER_WAIT_CONNECTION_TIMEOUT_MS_VM_OPTION)
+                getEnvironmentVariableOrNull(name = KOOG_DEBUGGER_WAIT_CONNECTION_MS_ENV_VAR)
+                    ?: getVMOptionOrNull(name = KOOG_DEBUGGER_WAIT_CONNECTION_TIMEOUT_MS_VM_OPTION)
 
             logger.debug { "Debugger Feature. Reading Koog debugger wait connection timeout value from system variables: $debuggerWaitConnectionTimeoutValue" }
             return debuggerWaitConnectionTimeoutValue?.toLongOrNull()?.toDuration(DurationUnit.MILLISECONDS)
@@ -399,3 +450,11 @@ public class Debugger {
         //endregion Private Methods
     }
 }
+
+/**
+ * Extension function to access the Debugger feature from an agent context.
+ *
+ * @return The [Debugger] feature instance for this agent
+ * @throws IllegalStateException if the Debugger feature is not installed
+ */
+public fun AIAgentContext.debugger(): Debugger = featureOrThrow(Debugger)