Migrating to AIAgent ctor, simpleSingleRunAgent deprecation (#222)

Author: Rizzen

README.md

@@ -51,7 +51,7 @@ fun main() = runBlocking {
     // Before you run the example, assign a corresponding API key as an environment variable.
    val apiKey = System.getenv("OPENAI_API_KEY") // or Anthropic, Google, OpenRouter, etc.
 
-   val agent = simpleSingleRunAgent(
+   val agent = AIAgent(
       executor = simpleOpenAIExecutor(apiKey), // or Anthropic, Google, OpenRouter, etc.
       systemPrompt = "You are a helpful assistant. Answer user questions concisely.",
       llmModel = OpenAIModels.Chat.GPT4o

agents/agents-core/QuickstartGuide.md

@@ -29,7 +29,7 @@ A single-run agent processes a single input and provides a response:
 fun main() = runBlocking {
     val apiToken = "YOUR_API_TOKEN"
 
-    val agent = simpleSingleRunAgent(
+    val agent = AIAgent(
         executor = simpleOpenAIExecutor("API_TOKEN"),
         systemPrompt = "You are a code assistant. Provide concise code examples."
     )
@@ -42,7 +42,7 @@ Please note that the single-run agent doesn't have any tools by default.
 
 ## Configuration Options
 
-`simpleSingleRunAgent` accept the following parameters:
+`AIAgent` accept the following parameters:
 
 - `executor` (required): Your LLM prompt executor
 - `systemPrompt`: Initial system prompt for the agent (default: empty string)
@@ -116,7 +116,7 @@ val toolRegistry = ToolRegistry {
     // Add more tools as needed
 }
 
-val agent = simpleSingleRunAgent(
+val agent = AIAgent(
     executor = simpleOpenAIExecutor("API_TOKEN"),
     systemPrompt = "You are a helpful assistant with calculator capabilities.",
     toolRegistry = toolRegistry
@@ -175,7 +175,7 @@ fun main() = runBlocking {
         tool(GenerateCodeTool)
     }
 
-    val agent = simpleSingleRunAgent(
+    val agent = AIAgent(
         executor = simpleOpenAIExecutor("API_TOKEN"),
         systemPrompt = "You are a code assistant. Use the generate_code tool to create code examples.",
         toolRegistry = toolRegistry

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

@@ -1,5 +1,6 @@
 package ai.koog.agents.core.agent
 
+import ai.koog.agents.core.agent.config.AIAgentConfig
 import ai.koog.agents.core.agent.config.AIAgentConfigBase
 import ai.koog.agents.core.agent.entity.*
 import ai.koog.agents.core.agent.context.AIAgentContext
@@ -19,8 +20,18 @@ import ai.koog.agents.core.tools.annotations.InternalAgentToolsApi
 import ai.koog.agents.features.common.config.FeatureConfig
 import ai.koog.agents.utils.Closeable
 import ai.koog.agents.core.agent.context.AIAgentLLMContext
+import ai.koog.agents.core.dsl.builder.forwardTo
+import ai.koog.agents.core.dsl.builder.strategy
+import ai.koog.agents.core.dsl.extension.nodeExecuteTool
+import ai.koog.agents.core.dsl.extension.nodeLLMRequest
+import ai.koog.agents.core.dsl.extension.nodeLLMSendToolResult
+import ai.koog.agents.core.dsl.extension.onAssistantMessage
+import ai.koog.agents.core.dsl.extension.onToolCall
+import ai.koog.prompt.dsl.prompt
 import ai.koog.prompt.executor.model.PromptExecutor
+import ai.koog.prompt.llm.LLModel
 import ai.koog.prompt.message.Message
+import ai.koog.prompt.params.LLMParams
 import ai.koog.prompt.text.TextContentBuilder
 import io.github.oshai.kotlinlogging.KotlinLogging
 import kotlinx.coroutines.CompletableDeferred
@@ -80,6 +91,41 @@ public open class AIAgent(
         private const val NO_RESULT = "Required tool argument value not found: \"${TerminationTool.ARG}\"!"
     }
 
+    /**
+     * Creates an instance of [AIAgent] with the specified parameters.
+     *
+     * @param executor The [PromptExecutor] responsible for executing prompts.
+     * @param strategy The [AIAgentStrategy] defining the agent's behavior. Default is a single-run strategy.
+     * @param systemPrompt The system-level prompt context for the agent. Default is an empty string.
+     * @param llmModel The language model to be used by the agent.
+     * @param temperature The sampling temperature for the language model, controlling randomness. Default is 1.0.
+     * @param toolRegistry The [ToolRegistry] containing tools available to the agent. Default is an empty registry.
+     * @param maxIterations Maximum number of iterations for the agent's execution. Default is 50.
+     * @param installFeatures A suspending lambda to install additional features for the agent's functionality. Default is an empty lambda.
+     */
+    public constructor(
+        executor: PromptExecutor,
+        llmModel: LLModel,
+        strategy: AIAgentStrategy = singleRunStrategy(),
+        systemPrompt: String = "",
+        temperature: Double = 1.0,
+        toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
+        maxIterations: Int = 50,
+        installFeatures: FeatureContext.() -> Unit = {}
+    ) : this(
+        promptExecutor = executor,
+        strategy = strategy,
+        agentConfig = AIAgentConfig(
+            prompt = prompt("chat", params = LLMParams(temperature = temperature)) {
+                system(systemPrompt)
+            },
+            model = llmModel,
+            maxAgentIterations = maxIterations,
+        ),
+        toolRegistry = toolRegistry,
+        installFeatures = installFeatures
+    )
+
     /**
      * The context for adding and configuring features in a Kotlin AI Agent instance.
      *
@@ -110,8 +156,8 @@ public open class AIAgent(
         FeatureContext(this).installFeatures()
     }
 
-    override suspend fun run(agentInput: String) {
 
+    override suspend fun run(agentInput: String) {
         runningMutex.withLock {
             if (isRunning) {
                 throw IllegalStateException("Agent is already running")
@@ -164,8 +210,7 @@ public open class AIAgent(
     }
 
     public suspend fun run(builder: suspend TextContentBuilder.() -> Unit) {
-        val agentInput = TextContentBuilder().apply { this.builder() }.build()
-        run(agentInput = agentInput)
+        run(agentInput = TextContentBuilder().apply { this.builder() }.build())
     }
 
     override suspend fun runAndGetResult(agentInput: String): String? {
@@ -368,3 +413,27 @@ public open class AIAgent(
 
     //endregion Private Methods
 }
+
+/**
+* Creates a single-run strategy for an AI agent.
+* This strategy defines a simple execution flow where the agent processes input,
+* calls tools, and sends results back to the agent.
+* The flow consists of the following steps:
+* 1. Start the agent.
+* 2. Call the LLM with the input.
+* 3. Execute a tool based on the LLM's response.
+* 4. Send the tool result back to the LLM.
+* 5. Repeat until LLM indicates no further tool calls are needed or the agent finishes.
+*/
+public fun singleRunStrategy(): AIAgentStrategy = strategy("single_run") {
+    val nodeCallLLM by nodeLLMRequest("sendInput")
+    val nodeExecuteTool by nodeExecuteTool("nodeExecuteTool")
+    val nodeSendToolResult by nodeLLMSendToolResult("nodeSendToolResult")
+
+    edge(nodeStart forwardTo nodeCallLLM)
+    edge(nodeCallLLM forwardTo nodeExecuteTool onToolCall { true })
+    edge(nodeCallLLM forwardTo nodeFinish onAssistantMessage { true })
+    edge(nodeExecuteTool forwardTo nodeSendToolResult)
+    edge(nodeSendToolResult forwardTo nodeFinish onAssistantMessage { true })
+    edge(nodeSendToolResult forwardTo nodeExecuteTool onToolCall { true })
+}

agents/agents-ext/src/commonMain/kotlin/ai/koog/agents/ext/agent/AIAgentExt.kt

@@ -3,8 +3,6 @@ package ai.koog.agents.ext.agent
 import ai.koog.agents.core.agent.AIAgent
 import ai.koog.agents.core.agent.config.AIAgentConfig
 import ai.koog.agents.core.tools.ToolRegistry
-import ai.koog.agents.ext.tool.AskUser
-import ai.koog.agents.ext.tool.ExitTool
 import ai.koog.prompt.dsl.prompt
 import ai.koog.prompt.executor.model.PromptExecutor
 import ai.koog.prompt.llm.LLModel
@@ -22,6 +20,7 @@ import ai.koog.prompt.params.LLMParams
  * @param installFeatures A suspending lambda to install additional features for the agent's functionality. Default is an empty lambda.
  * @return A configured instance of `AIAgent` with a single-run execution strategy.
  */
+@Deprecated("Use AIAgent constructor instead", ReplaceWith("AIAgent(...)"))
 public fun simpleSingleRunAgent(
     executor: PromptExecutor,
     systemPrompt: String = "",
@@ -30,21 +29,13 @@ public fun simpleSingleRunAgent(
     toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
     maxIterations: Int = 50,
     installFeatures: AIAgent.FeatureContext.() -> Unit = {}
-): AIAgent {
-
-    val agentConfig = AIAgentConfig(
-        prompt = prompt("chat", params = LLMParams(temperature = temperature)) {
-            system(systemPrompt)
-        },
-        model = llmModel,
-        maxAgentIterations = maxIterations,
-    )
-
-    return AIAgent(
-        promptExecutor = executor,
-        strategy = singleRunStrategy(),
-        agentConfig = agentConfig,
-        toolRegistry = toolRegistry,
-        installFeatures = installFeatures
-    )
-}
+): AIAgent = AIAgent(
+    systemPrompt = systemPrompt,
+    llmModel = llmModel,
+    temperature = temperature,
+    toolRegistry = toolRegistry,
+    maxIterations = maxIterations,
+    installFeatures = installFeatures,
+    strategy = singleRunStrategy(),
+    executor = executor
+)

agents/agents-test/src/jvmTest/kotlin/ai/koog/agents/test/SimpleAgentMockedTest.kt

@@ -2,14 +2,14 @@
 
 package ai.koog.agents.test
 
+import ai.koog.agents.core.agent.AIAgent
 import ai.koog.agents.core.tools.SimpleTool
 import ai.koog.agents.core.tools.Tool
 import ai.koog.agents.core.tools.ToolDescriptor
 import ai.koog.agents.core.tools.ToolException
 import ai.koog.agents.core.tools.ToolParameterDescriptor
 import ai.koog.agents.core.tools.ToolParameterType
 import ai.koog.agents.core.tools.ToolRegistry
-import ai.koog.agents.ext.agent.simpleSingleRunAgent
 import ai.koog.agents.ext.tool.ExitTool
 import ai.koog.agents.ext.tool.SayToUser
 import ai.koog.agents.features.eventHandler.feature.EventHandler
@@ -161,8 +161,8 @@ class SimpleAgentMockedTest {
     }
 
     @Test
-    fun ` test simpleSingleRunAgent doesn't call tools by default`() = runBlocking {
-        val agent = simpleSingleRunAgent(
+    fun ` test AIAgent doesn't call tools by default`() = runBlocking {
+        val agent = AIAgent(
             systemPrompt = systemPrompt,
             llmModel = OpenAIModels.Reasoning.GPT4oMini,
             temperature = 1.0,
@@ -173,7 +173,7 @@ class SimpleAgentMockedTest {
 
         agent.run("Repeat after me: Hello, I'm good.")
 
-        // by default, a simpleSingleRunAgent has no tools underneath
+        // by default, a AI Agent has no tools underneath
         assertTrue(actualToolCalls.isEmpty(), "No tools should be called")
         assertTrue(results.isNotEmpty(), "No agent run results were received")
         assertTrue(
@@ -183,12 +183,12 @@ class SimpleAgentMockedTest {
     }
 
     @Test
-    fun `test simpleSingleRunAgent calls a custom tool`() = runBlocking {
+    fun `test AIAgent calls a custom tool`() = runBlocking {
         val toolRegistry = ToolRegistry {
             tool(SayToUser)
         }
 
-        val agent = simpleSingleRunAgent(
+        val agent = AIAgent(
             systemPrompt = systemPrompt,
             llmModel = OpenAIModels.Reasoning.GPT4oMini,
             temperature = 1.0,
@@ -212,7 +212,7 @@ class SimpleAgentMockedTest {
     @ParameterizedTest
     @MethodSource("getToolRegistry")
     fun `test simpleSingleRunAgent handles non-registered tools`(toolRegistry: ToolRegistry) = runBlocking {
-        val agent = simpleSingleRunAgent(
+        val agent = AIAgent(
             systemPrompt = systemPrompt,
             llmModel = OpenAIModels.Reasoning.GPT4oMini,
             temperature = 1.0,
@@ -238,7 +238,7 @@ class SimpleAgentMockedTest {
             tool(ErrorTool)
         }
 
-        val agent = simpleSingleRunAgent(
+        val agent = AIAgent(
             systemPrompt = systemPrompt,
             llmModel = OpenAIModels.Reasoning.GPT4oMini,
             temperature = 1.0,
@@ -268,7 +268,7 @@ class SimpleAgentMockedTest {
             tool(ConditionalTool)
         }
 
-        val successAgent = simpleSingleRunAgent(
+        val successAgent = AIAgent(
             systemPrompt = systemPrompt,
             llmModel = OpenAIModels.Reasoning.GPT4oMini,
             temperature = 1.0,
@@ -296,7 +296,7 @@ class SimpleAgentMockedTest {
 
         iterationCount = 0
 
-        val agent = simpleSingleRunAgent(
+        val agent = AIAgent(
             systemPrompt = systemPrompt,
             llmModel = OpenAIModels.Reasoning.GPT4oMini,
             temperature = 1.0,

examples/src/main/kotlin/ai/koog/agents/example/banking/routing/RoutingViaAgentsAsTools.kt

@@ -1,5 +1,6 @@
 package ai.koog.agents.example.banking.routing
 
+import ai.koog.agents.core.agent.AIAgent
 import ai.koog.agents.core.agent.asTool
 import ai.koog.agents.core.tools.ToolRegistry
 import ai.koog.agents.core.tools.reflect.asTools
@@ -8,7 +9,6 @@ import ai.koog.agents.example.banking.tools.MoneyTransferTools
 import ai.koog.agents.example.banking.tools.TransactionAnalysisTools
 import ai.koog.agents.example.banking.tools.bankingAssistantSystemPrompt
 import ai.koog.agents.example.banking.tools.transactionAnalysisPrompt
-import ai.koog.agents.ext.agent.simpleSingleRunAgent
 import ai.koog.agents.ext.tool.AskUser
 import ai.koog.prompt.executor.clients.openai.OpenAIModels
 import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor
@@ -18,23 +18,23 @@ fun main() = runBlocking {
     val apiKey = ApiKeyService.openAIApiKey // Your OpenAI API key
     val openAIExecutor = simpleOpenAIExecutor(apiKey)
 
-    val transferAgent = simpleSingleRunAgent(
+    val transferAgent = AIAgent(
         executor = openAIExecutor,
         llmModel = OpenAIModels.Reasoning.GPT4oMini,
         systemPrompt = bankingAssistantSystemPrompt,
         temperature = 0.0,
         toolRegistry = ToolRegistry { tools(MoneyTransferTools().asTools()) }
     )
 
-    val analysisAgent = simpleSingleRunAgent(
+    val analysisAgent = AIAgent(
         executor = openAIExecutor,
         llmModel = OpenAIModels.Reasoning.GPT4oMini,
         systemPrompt = bankingAssistantSystemPrompt + transactionAnalysisPrompt,
         temperature = 0.0,
         toolRegistry = ToolRegistry { tools(TransactionAnalysisTools().asTools()) }
     )
 
-    val classifierAgent = simpleSingleRunAgent(
+    val classifierAgent = AIAgent(
         executor = openAIExecutor,
         llmModel = OpenAIModels.Reasoning.GPT4oMini,
         toolRegistry = ToolRegistry {

examples/src/main/kotlin/ai/koog/agents/example/banking/routing/RoutingViaGraph.kt

@@ -114,10 +114,10 @@ fun main() = runBlocking {
     )
 
     val agent = AIAgent(
-        toolRegistry = toolRegistry,
+        promptExecutor = simpleOpenAIExecutor(apiKey),
         strategy = strategy,
         agentConfig = agentConfig,
-        promptExecutor = simpleOpenAIExecutor(apiKey),
+        toolRegistry = toolRegistry,
     )
 
     println("Banking Assistant started")

examples/src/main/kotlin/ai/koog/agents/example/banking/tools/MoneyTransferTools.kt

@@ -1,12 +1,12 @@
 package ai.koog.agents.example.banking.tools
 
+import ai.koog.agents.core.agent.AIAgent
 import ai.koog.agents.core.tools.ToolRegistry
 import ai.koog.agents.core.tools.annotations.LLMDescription
 import ai.koog.agents.core.tools.annotations.Tool
 import ai.koog.agents.core.tools.reflect.ToolSet
 import ai.koog.agents.core.tools.reflect.asTools
 import ai.koog.agents.example.ApiKeyService
-import ai.koog.agents.ext.agent.simpleSingleRunAgent
 import ai.koog.prompt.executor.clients.openai.OpenAIModels
 import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor
 import kotlinx.coroutines.runBlocking
@@ -169,7 +169,7 @@ fun main() = runBlocking {
         tools(MoneyTransferTools().asTools())
     }
 
-    val agent = simpleSingleRunAgent(
+    val agent = AIAgent(
         executor = simpleOpenAIExecutor(apiKey),
         llmModel = OpenAIModels.Reasoning.GPT4oMini,
         systemPrompt = bankingAssistantSystemPrompt,

examples/src/main/kotlin/ai/koog/agents/example/banking/tools/TransactionAnalysisTools.kt

@@ -1,12 +1,12 @@
 package ai.koog.agents.example.banking.tools
 
+import ai.koog.agents.core.agent.AIAgent
 import ai.koog.agents.core.tools.reflect.ToolSet
 import ai.koog.agents.core.tools.annotations.Tool
 import ai.koog.agents.core.tools.annotations.LLMDescription
 import ai.koog.agents.core.tools.ToolRegistry
 import ai.koog.agents.core.tools.reflect.asTools
 import ai.koog.agents.example.ApiKeyService
-import ai.koog.agents.ext.agent.simpleSingleRunAgent
 import ai.koog.prompt.executor.clients.openai.OpenAIModels
 import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor
 import kotlinx.coroutines.runBlocking
@@ -141,7 +141,7 @@ fun main() = runBlocking {
         tools(TransactionAnalysisTools().asTools())
     }
 
-    val agent = simpleSingleRunAgent(
+    val agent = AIAgent(
         executor = simpleOpenAIExecutor(apiKey),
         llmModel = OpenAIModels.Reasoning.GPT4oMini,
         systemPrompt = bankingAssistantSystemPrompt + transactionAnalysisPrompt,