agents-tools

A module that provides a framework for defining, describing, and executing tools that can be used by AI agents to interact with the environment.

Overview

The agents-tools module provides a comprehensive framework for creating and managing tools that AI agents can use to perform actions. It includes:

A core Tool abstract class that represents a tool with arguments and results
Descriptors for tools and their parameters, allowing for rich metadata
Reflection-based utilities for converting Kotlin functions to tools
Support for serialization and deserialization of tool arguments and results
A ToolSet interface for grouping related tools together

Tools are designed to be executed within an environment context, ensuring proper handling of events, feature pipelines, and testing capabilities.

Passing metadata to a tool

Tools can receive caller- and feature-contributed per-call metadata alongside their typed arguments, through a side channel that is not part of the tool's argument schema and is not serialized to the LLM. See Class-based tools on the documentation site for usage and code samples.

Using in your project

To use tools in your project:

Create a class that implements the ToolSet interface
Annotate methods with @Tool and @LLMDescription to define tools
Use the asTools() extension function to convert the methods to a list of tools
Register the tools with your agent or environment

class MyToolSet : ToolSet {
    @Tool
    @LLMDescription("Performs a calculation")
    fun calculate(
        @LLMDescription("First number") a: Int,
        @LLMDescription("Second number") b: Int
    ): Int {
        return a + b
    }
}

// Convert to tools
val myToolSet = MyToolSet()
val tools = myToolSet.asTools()

Using in unit tests

For unit testing tools:

Create instances of your tool classes or tool sets
Use the asTools() or asTool() functions to convert them to tools
Execute the tools directly with test arguments
Verify the results

@Test
fun testCalculateTool() {
    val myToolSet = MyToolSet()
    val tools = myToolSet.asTools()
    val calculateTool = tools.first { it.name == "calculate" }

    // Create a DirectToolCallsEnabler for testing
    val enabler = object : DirectToolCallsEnabler {}

    // Execute the tool
    val args = calculateTool.decodeArgsFromString("""{"a": 5, "b": 3}""")
    val result = runBlocking { calculateTool.execute(args, enabler) }

    assertEquals(8, result.result)
}

Example of usage

Here's a complete example of defining and using tools:

// Define a tool set
class MathTools : ToolSet {
    @Tool
    @LLMDescription("Adds two numbers")
    fun add(
        @LLMDescription("First number") a: Int,
        @LLMDescription("Second number") b: Int
    ): Int = a + b

    @Tool
    @LLMDescription("Multiplies two numbers")
    fun multiply(
        @LLMDescription("First number") a: Int,
        @LLMDescription("Second number") b: Int
    ): Int = a * b
}

// Use the tools
fun main() {
    val mathTools = MathTools()
    val tools = mathTools.asTools()

    // Create a tool registry
    val registry = ToolRegistry.Builder().apply {
        tools
    }.build()

    // Find and use a tool (in a real scenario, this would be done through an agent)
    val enabler = object : DirectToolCallsEnabler {}
    val addTool = registry.findTool("add")
    val args = addTool.decodeArgsFromString("""{"a": 10, "b": 20}""")

    runBlocking {
        val (result, stringResult) = addTool.executeAndSerialize(args, enabler)
        println("Result: $stringResult") // Output: Result: 30
    }
}

A module that provides a framework for defining, describing, and executing tools that can be used by AI agents to interact with the environment.

Overview

The agents-tools module provides a comprehensive framework for creating and managing tools that AI agents can use to perform actions. It includes:

A core Tool abstract class that represents a tool with arguments and results
Descriptors for tools and their parameters, allowing for rich metadata
Reflection-based utilities for converting Kotlin functions to tools
Support for serialization and deserialization of tool arguments and results
A ToolSet interface for grouping related tools together

Tools are designed to be executed within an environment context, ensuring proper handling of events, feature pipelines, and testing capabilities.

Passing metadata to a tool

Using in your project

To use tools in your project:

Create a class that implements the ToolSet interface
Annotate methods with @Tool and @LLMDescription to define tools
Use the asTools() extension function to convert the methods to a list of tools
Register the tools with your agent or environment

class MyToolSet : ToolSet {
    @Tool
    @LLMDescription("Performs a calculation")
    fun calculate(
        @LLMDescription("First number") a: Int,
        @LLMDescription("Second number") b: Int
    ): Int {
        return a + b
    }
}

// Convert to tools
val myToolSet = MyToolSet()
val tools = myToolSet.asTools()

Using in unit tests

For unit testing tools:

Create instances of your tool classes or tool sets
Use the asTools() or asTool() functions to convert them to tools
Execute the tools directly with test arguments
Verify the results

@Test
fun testCalculateTool() {
    val myToolSet = MyToolSet()
    val tools = myToolSet.asTools()
    val calculateTool = tools.first { it.name == "calculate" }

    // Create a DirectToolCallsEnabler for testing
    val enabler = object : DirectToolCallsEnabler {}

    // Execute the tool
    val args = calculateTool.decodeArgsFromString("""{"a": 5, "b": 3}""")
    val result = runBlocking { calculateTool.execute(args, enabler) }

    assertEquals(8, result.result)
}

Example of usage

Here's a complete example of defining and using tools:

// Define a tool set
class MathTools : ToolSet {
    @Tool
    @LLMDescription("Adds two numbers")
    fun add(
        @LLMDescription("First number") a: Int,
        @LLMDescription("Second number") b: Int
    ): Int = a + b

    @Tool
    @LLMDescription("Multiplies two numbers")
    fun multiply(
        @LLMDescription("First number") a: Int,
        @LLMDescription("Second number") b: Int
    ): Int = a * b
}

// Use the tools
fun main() {
    val mathTools = MathTools()
    val tools = mathTools.asTools()

    // Create a tool registry
    val registry = ToolRegistry.Builder().apply {
        tools
    }.build()

    // Find and use a tool (in a real scenario, this would be done through an agent)
    val enabler = object : DirectToolCallsEnabler {}
    val addTool = registry.findTool("add")
    val args = addTool.decodeArgsFromString("""{"a": 10, "b": 20}""")

    runBlocking {
        val (result, stringResult) = addTool.executeAndSerialize(args, enabler)
        println("Result: $stringResult") // Output: Result: 30
    }
}

A module that provides a framework for defining, describing, and executing tools that can be used by AI agents to interact with the environment.

Overview

The agents-tools module provides a comprehensive framework for creating and managing tools that AI agents can use to perform actions. It includes:

A core Tool abstract class that represents a tool with arguments and results
Descriptors for tools and their parameters, allowing for rich metadata
Reflection-based utilities for converting Kotlin functions to tools
Support for serialization and deserialization of tool arguments and results
A ToolSet interface for grouping related tools together

Tools are designed to be executed within an environment context, ensuring proper handling of events, feature pipelines, and testing capabilities.

Passing metadata to a tool

Using in your project

To use tools in your project:

Create a class that implements the ToolSet interface
Annotate methods with @Tool and @LLMDescription to define tools
Use the asTools() extension function to convert the methods to a list of tools
Register the tools with your agent or environment

class MyToolSet : ToolSet {
    @Tool
    @LLMDescription("Performs a calculation")
    fun calculate(
        @LLMDescription("First number") a: Int,
        @LLMDescription("Second number") b: Int
    ): Int {
        return a + b
    }
}

// Convert to tools
val myToolSet = MyToolSet()
val tools = myToolSet.asTools()

Using in unit tests

For unit testing tools:

Create instances of your tool classes or tool sets
Use the asTools() or asTool() functions to convert them to tools
Execute the tools directly with test arguments
Verify the results

@Test
fun testCalculateTool() {
    val myToolSet = MyToolSet()
    val tools = myToolSet.asTools()
    val calculateTool = tools.first { it.name == "calculate" }

    // Create a DirectToolCallsEnabler for testing
    val enabler = object : DirectToolCallsEnabler {}

    // Execute the tool
    val args = calculateTool.decodeArgsFromString("""{"a": 5, "b": 3}""")
    val result = runBlocking { calculateTool.execute(args, enabler) }

    assertEquals(8, result.result)
}

Example of usage

Here's a complete example of defining and using tools:

// Define a tool set
class MathTools : ToolSet {
    @Tool
    @LLMDescription("Adds two numbers")
    fun add(
        @LLMDescription("First number") a: Int,
        @LLMDescription("Second number") b: Int
    ): Int = a + b

    @Tool
    @LLMDescription("Multiplies two numbers")
    fun multiply(
        @LLMDescription("First number") a: Int,
        @LLMDescription("Second number") b: Int
    ): Int = a * b
}

// Use the tools
fun main() {
    val mathTools = MathTools()
    val tools = mathTools.asTools()

    // Create a tool registry
    val registry = ToolRegistry.Builder().apply {
        tools
    }.build()

    // Find and use a tool (in a real scenario, this would be done through an agent)
    val enabler = object : DirectToolCallsEnabler {}
    val addTool = registry.findTool("add")
    val args = addTool.decodeArgsFromString("""{"a": 10, "b": 20}""")

    runBlocking {
        val (result, stringResult) = addTool.executeAndSerialize(args, enabler)
        println("Result: $stringResult") // Output: Result: 30
    }
}

Packages

ai.koog.agents.core.tools

common

jvmCommon

nonJvmCommon

ai.koog.agents.core.tools.annotations

common

ai.koog.agents.core.tools.reflect

jvmCommon

ai.koog.agents.core.tools.reflect.java

jvmCommon

ai.koog.agents.core.tools.schema

common

jvmCommon

nonJvmCommon

ai.koog.agents.core.tools.serialization

common