Rewrite all tools and examples with the new API

Author: Ololoshechkin

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

@@ -4,7 +4,8 @@ import ai.koog.agents.core.agent.AIAgentTool.AgentToolArgs
 import ai.koog.agents.core.agent.AIAgentTool.AgentToolResult
 import ai.koog.agents.core.tools.Tool
 import ai.koog.agents.core.tools.ToolDescriptor
-import ai.koog.agents.core.tools.ToolParameterDescriptor
+import ai.koog.agents.core.tools.annotations.InternalAgentToolsApi
+import ai.koog.agents.core.tools.asToolDescriptor
 import kotlinx.serialization.KSerializer
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.descriptors.SerialDescriptor
@@ -20,7 +21,9 @@ import kotlinx.serialization.serializer
  *
  * @param agentName Agent name that would be a tool name for this agent tool.
  * @param agentDescription Agent description that would be a tool description for this agent tool.
- * @param inputDescriptor Descriptor for the agent input.
+ * @param inputDescription An optional description of the agent's input. Required for primitive types only!
+ *  * If not specified for a primitive input type (ex: String, Int, ...), an empty input description will be sent to LLM.
+ *  * Does not have any effect for non-primitive [Input] type with @LLMDescription annotations.
  * @param inputSerializer Serializer to deserialize tool arguments to agent input.
  * @param outputSerializer Serializer to serialize agent output to tool result.
  * @param json Optional [Json] instance to customize de/serialization behavior.
@@ -29,38 +32,43 @@ import kotlinx.serialization.serializer
 public inline fun <reified Input, reified Output> AIAgent<Input, Output>.asTool(
     agentName: String,
     agentDescription: String,
-    inputDescriptor: ToolParameterDescriptor,
+    inputDescription: String? = null,
     inputSerializer: KSerializer<Input> = serializer(),
     outputSerializer: KSerializer<Output> = serializer(),
     json: Json = Json.Default,
 ): Tool<AgentToolArgs, AgentToolResult> = AIAgentTool(
     agent = this,
     agentName = agentName,
     agentDescription = agentDescription,
-    inputDescriptor = inputDescriptor,
+    inputDescription = inputDescription,
     inputSerializer = inputSerializer,
     outputSerializer = outputSerializer,
     json = json,
 )
 
+
 /**
- * AIAgentTool is a specialized tool that integrates an AI agent for processing tasks
- * by leveraging input arguments and producing corresponding results.
- *
- * This class extends the generic Tool interface with custom argument and result types.
- *
- * @constructor Creates an instance of AIAgentTool with the specified AI agent, its name,
- * description, and an optional description for the request parameter.
+ * AIAgentTool is a generic tool that wraps an AI agent to facilitate integration
+ * with the context of a tool execution framework. It enables the serialization,
+ * deserialization, and execution of an AI agent's operations.
  *
- * @param agent The AI agent that implements the AIAgentBase interface and handles task execution.
- * @param agentName A name assigned to the tool that helps identify it.
- * @param agentDescription A brief description of what the tool does.
+ * @param Input The type of input expected by the AI agent.
+ * @param Output The type of output produced by the AI agent.
+ * @property agent The AI agent to be executed.
+ * @property agentName A unique name for the agent.
+ * @property agentDescription A brief description of the agent's functionality.
+ * @property inputDescription An optional description of the agent's input. Required for primitive types only!
+ * If not specified for a primitive input type (ex: String, Int, ...), an empty input description will be sent to LLM.
+ * Does not have any effect for non-primitive [Input] type with @LLMDescription annotations.
+ * @property inputSerializer A serializer for converting the input type to/from JSON.
+ * @property outputSerializer A serializer for converting the output type to/from JSON.
+ * @property json The JSON configuration used for serialization and deserialization.
  */
 public class AIAgentTool<Input, Output>(
     private val agent: AIAgent<Input, Output>,
     private val agentName: String,
     private val agentDescription: String,
-    private val inputDescriptor: ToolParameterDescriptor,
+    private val inputDescription: String? = null,
     private val inputSerializer: KSerializer<Input>,
     private val outputSerializer: KSerializer<Output>,
     private val json: Json = Json.Default,
@@ -104,15 +112,19 @@ public class AIAgentTool<Input, Output>(
         }
     }
 
-    override val descriptor: ToolDescriptor = ToolDescriptor(
-        name = agentName,
-        description = agentDescription,
-        requiredParameters = listOf(inputDescriptor)
-    )
+    override val name: String = agentName
+    override val toolDescription: String = agentDescription
+
+    @OptIn(InternalAgentToolsApi::class)
+    override val descriptor: ToolDescriptor =
+        inputSerializer.descriptor.asToolDescriptor(name, toolDescription, inputDescription)
 
     override suspend fun execute(args: AgentToolArgs): AgentToolResult {
         return try {
-            val input = json.decodeFromJsonElement(inputSerializer, args.args.getValue(inputDescriptor.name))
+            val input = json.decodeFromJsonElement(
+                inputSerializer,
+                args.args.getValue(descriptor.requiredParameters.first().name)
+            )
             val result = agent.run(input)
 
             AgentToolResult(
@@ -122,9 +134,11 @@ public class AIAgentTool<Input, Output>(
         } catch (e: Throwable) {
             AgentToolResult(
                 successful = false,
-                errorMessage = "Error happened: ${e::class.simpleName}(${e.message})\n${e.stackTraceToString().take(
-                    100
-                )}"
+                errorMessage = "Error happened: ${e::class.simpleName}(${e.message})\n${
+                    e.stackTraceToString().take(
+                        100
+                    )
+                }"
             )
         }
     }

agents/agents-core/src/commonTest/kotlin/ai/koog/agents/core/CalculatorTools.kt

@@ -1,51 +1,36 @@
 package ai.koog.agents.core
 
 import ai.koog.agents.core.tools.Tool
-import ai.koog.agents.core.tools.ToolDescriptor
-import ai.koog.agents.core.tools.ToolParameterDescriptor
-import ai.koog.agents.core.tools.ToolParameterType
+import ai.koog.agents.core.tools.annotations.LLMDescription
 import kotlinx.serialization.KSerializer
 import kotlinx.serialization.Serializable
-import kotlinx.serialization.builtins.serializer
 import kotlin.jvm.JvmInline
 
 object CalculatorTools {
 
     abstract class CalculatorTool(
-        name: String,
-        description: String,
+        override val name: String,
+        override val toolDescription: String,
     ) : Tool<CalculatorTool.Args, CalculatorTool.Result>() {
         @Serializable
-        data class Args(val a: Float, val b: Float)
+        data class Args(
+            @property:LLMDescription("First number")
+            val a: Float,
+            @property:LLMDescription("Second number")
+            val b: Float
+        )
 
         @Serializable
         @JvmInline
         value class Result(val result: Float)
 
         final override val argsSerializer = Args.serializer()
         override val resultSerializer: KSerializer<Result> = Result.serializer()
-
-        final override val descriptor = ToolDescriptor(
-            name = name,
-            description = description,
-            requiredParameters = listOf(
-                ToolParameterDescriptor(
-                    name = "a",
-                    description = "First number",
-                    type = ToolParameterType.Float,
-                ),
-                ToolParameterDescriptor(
-                    name = "b",
-                    description = "Second number",
-                    type = ToolParameterType.Float,
-                ),
-            )
-        )
     }
 
     object PlusTool : CalculatorTool(
         name = "plus",
-        description = "Adds a and b",
+        toolDescription = "Adds a and b",
     ) {
         override suspend fun execute(args: Args): Result {
             return Result(args.a + args.b)

agents/agents-core/src/commonTest/kotlin/ai/koog/agents/core/agent/AIAgentToolTest.kt

@@ -3,7 +3,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.tools.DirectToolCallsEnabler
-import ai.koog.agents.core.tools.ToolParameterDescriptor
 import ai.koog.agents.core.tools.ToolParameterType
 import ai.koog.agents.core.tools.annotations.InternalAgentToolsApi
 import ai.koog.prompt.dsl.prompt
@@ -54,11 +53,7 @@ class AIAgentToolTest {
         val tool = agent.asTool(
             agentName = "testAgent",
             agentDescription = "Test agent description",
-            inputDescriptor = ToolParameterDescriptor(
-                name = "request",
-                description = "Test request description",
-                type = ToolParameterType.String
-            )
+            inputDescription = "Test request description"
         )
 
         val argsJson = buildJsonObject {
@@ -71,11 +66,7 @@ class AIAgentToolTest {
         val tool = agent.asTool(
             agentName = "testAgent",
             agentDescription = "Test agent description",
-            inputDescriptor = ToolParameterDescriptor(
-                name = "request",
-                description = "Test request description",
-                type = ToolParameterType.String
-            )
+            inputDescription = "Test request description"
         )
 
         assertEquals("testAgent", tool.descriptor.name)
@@ -91,11 +82,7 @@ class AIAgentToolTest {
         val tool = agent.asTool(
             agentName = "testAgent",
             agentDescription = "Test agent description",
-            inputDescriptor = ToolParameterDescriptor(
-                name = "request",
-                description = "Test request description",
-                type = ToolParameterType.String
-            )
+            inputDescription = "Test request description"
         )
         assertEquals("testAgent", tool.descriptor.name)
     }
@@ -139,11 +126,7 @@ class AIAgentToolTest {
         val tool = agent.asTool(
             agentName = "testAgent",
             agentDescription = "Test agent description",
-            inputDescriptor = ToolParameterDescriptor(
-                name = "request",
-                description = "Test request description",
-                type = ToolParameterType.String
-            )
+            inputDescription = "Test request description"
         )
 
         val args = tool.decodeArgs(argsJson)
@@ -164,11 +147,7 @@ class AIAgentToolTest {
         val tool = agent.asTool(
             agentName = "testAgent",
             agentDescription = "Test agent description",
-            inputDescriptor = ToolParameterDescriptor(
-                name = "request",
-                description = "Test request description",
-                type = ToolParameterType.String
-            )
+            inputDescription = "Test request description"
         )
 
         val args = tool.decodeArgs(argsJson)

agents/agents-core/src/commonTest/kotlin/ai/koog/agents/core/agent/DummyTools.kt

@@ -4,38 +4,29 @@ import ai.koog.agents.core.tools.SimpleTool
 import ai.koog.agents.core.tools.ToolDescriptor
 import ai.koog.agents.core.tools.ToolParameterDescriptor
 import ai.koog.agents.core.tools.ToolParameterType
+import ai.koog.agents.core.tools.annotations.LLMDescription
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.builtins.serializer
 
 object DummyTool : SimpleTool<Unit>() {
     override val argsSerializer = Unit.serializer()
 
-    override val descriptor = ToolDescriptor(
-        name = "dummy",
-        description = "Dummy tool for testing",
-        requiredParameters = emptyList()
-    )
+    override val name: String = "dummy"
+    override val toolDescription: String = "Dummy tool for testing"
 
     override suspend fun doExecute(args: Unit): String = "Dummy result"
 }
 
 object CreateTool : SimpleTool<CreateTool.Args>() {
     @Serializable
-    data class Args(val name: String)
+    data class Args(
+        @property:LLMDescription("Name of the entity to create") val name: String
+    )
 
     override val argsSerializer = Args.serializer()
 
-    override val descriptor = ToolDescriptor(
-        name = "create",
-        description = "Create something",
-        requiredParameters = listOf(
-            ToolParameterDescriptor(
-                name = "name",
-                description = "Name of the entity to create",
-                type = ToolParameterType.String
-            )
-        )
-    )
+    override val name: String = "create"
+    override val toolDescription: String = "Create something"
 
     override suspend fun doExecute(args: Args): String = "created"
 }

agents/agents-core/src/commonTest/kotlin/ai/koog/agents/core/agent/context/AIAgentLLMContextTest.kt

@@ -6,6 +6,7 @@ import ai.koog.agents.core.tools.ToolDescriptor
 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.core.tools.annotations.LLMDescription
 import ai.koog.agents.testing.tools.getMockExecutor
 import ai.koog.agents.testing.tools.mockLLMAnswer
 import ai.koog.prompt.dsl.prompt
@@ -171,22 +172,16 @@ class AIAgentLLMContextTest : AgentTestBase() {
     }
 
     @Serializable
-    private data class TestToolArgs(val input: String)
+    private data class TestToolArgs(
+        @property:LLMDescription("The input to process")
+        val input: String
+    )
 
     private class TestTool : SimpleTool<TestToolArgs>() {
         override val argsSerializer = TestToolArgs.serializer()
 
-        override val descriptor = ToolDescriptor(
-            name = "test-tool",
-            description = "A test tool for testing",
-            requiredParameters = listOf(
-                ToolParameterDescriptor(
-                    name = "input",
-                    description = "The input to process",
-                    type = ToolParameterType.String
-                )
-            )
-        )
+        override val name: String = "test-tool"
+        override val toolDescription: String = "A test tool for testing"
 
         override suspend fun doExecute(args: TestToolArgs): String {
             return "Processed: ${args.input}"

agents/agents-core/src/commonTest/kotlin/ai/koog/agents/core/agent/session/AIAgentLLMWriteSessionTest.kt

@@ -13,6 +13,7 @@ import ai.koog.agents.core.tools.ToolParameterType
 import ai.koog.agents.core.tools.ToolRegistry
 import ai.koog.agents.core.tools.ToolResult
 import ai.koog.agents.core.tools.annotations.InternalAgentToolsApi
+import ai.koog.agents.core.tools.annotations.LLMDescription
 import ai.koog.agents.testing.tools.getMockExecutor
 import ai.koog.agents.testing.tools.mockLLMAnswer
 import ai.koog.prompt.dsl.Prompt
@@ -64,21 +65,15 @@ class AIAgentLLMWriteSessionTest {
 
     class TestTool : SimpleTool<TestTool.Args>() {
         @Serializable
-        data class Args(val input: String)
+        data class Args(
+            @property:LLMDescription("Input parameter")
+            val input: String
+        )
 
         override val argsSerializer: KSerializer<Args> = Args.serializer()
 
-        override val descriptor: ToolDescriptor = ToolDescriptor(
-            name = "test-tool",
-            description = "A test tool",
-            requiredParameters = listOf(
-                ToolParameterDescriptor(
-                    name = "input",
-                    description = "Input parameter",
-                    type = ToolParameterType.String
-                )
-            )
-        )
+        override val name: String = "test-tool"
+        override val toolDescription: String = "A test tool"
 
         override suspend fun doExecute(args: Args): String {
             return "Processed: ${args.input}"
@@ -90,11 +85,17 @@ class AIAgentLLMWriteSessionTest {
         data class Args(val input: String)
 
         @Serializable
-        data class Result(val output: String)
+        data class Result(
+            @property:LLMDescription("Input parameter")
+            val output: String
+        )
 
         override val argsSerializer: KSerializer<Args> = Args.serializer()
         override val resultSerializer: KSerializer<Result> = Result.serializer()
 
+        override val name: String = "custom-tool"
+        override val toolDescription: String = "A custom tool"
+
         override val descriptor: ToolDescriptor = ToolDescriptor(
             name = "custom-tool",
             description = "A custom tool",