クラスベースのツール

このセクションでは、柔軟性の強化と動作のカスタマイズが必要なシナリオ向けに設計されたAPIについて説明します。 このアプローチを使用すると、ツールのパラメータ、メタデータ、実行ロジック、および登録と呼び出し方法に至るまで、ツールを完全に制御できます。

このレベルの制御は、基本的なユースケースを拡張し、エージェントセッションやワークフローへのシームレスな統合を可能にする、高度なツールを作成するのに理想的です。

このページでは、ツールの実装方法、レジストリを介したツールの管理、ツールの呼び出し、およびノードベースのエージェントアーキテクチャ内での使用方法について説明します。

NOTE

このAPIはマルチプラットフォームです。これにより、異なるプラットフォーム間で同じツールを使用できます。

ツールの実装

Koogフレームワークは、ツールの実装に関して次のアプローチを提供します。

• すべてのツールの基底クラスである Tool を使用する。テキスト以外の結果を返す必要がある場合や、ツールの動作を完全に制御する必要がある場合にこのクラスを使用します。
• 基底の Tool クラスを拡張し、テキスト結果を返すツールの作成を簡素化する SimpleTool クラスを使用する。ツールがテキストのみを返す必要があるシナリオでこのアプローチを使用します。

どちらのアプローチも同じコアコンポーネントを使用しますが、実装と返される結果が異なります。

Tool クラス

Tool<Args, Result> 抽象クラスは、Koogでツールを作成するための基底クラスです。 特定の引数型 (Args) を受け入れ、さまざまな型の結果 (Result) を返すツールを作成できます。

各ツールは次のコンポーネントで構成されます。

コンポーネント	説明
Args	ツールに必要な引数を定義するシリアライズ可能なデータクラス。このクラスは ToolArgs インターフェースを実装する必要があります。引数を必要としないツールの場合、組み込みの ToolArgs.Empty 実装を使用できます。
Result	ツールが返す結果の型。これは ToolResult インターフェースを実装する必要があり、ToolResult.Text、ToolResult.Boolean、ToolResult.Number、または ToolResult.JSONSerializable のカスタム実装のいずれかになります。
argsSerializer	ツールの引数をどのようにデシリアライズするかを定義するオーバーライドされた変数。argsSerializer も参照してください。
descriptor	ツールメタデータを指定するオーバーライドされた変数: - name - description - requiredParameters (デフォルトは空) - optionalParameters (デフォルトは空) descriptor も参照してください。
execute()	ツールのロジックを実装する関数。Args 型の引数を受け取り、Result 型の結果を返します。execute() も参照してください。

TIP

LLMがツールを適切に理解して使用できるように、ツールの明確な説明と適切に定義されたパラメータ名があることを確認してください。

使用例

以下は、Tool クラスを使用して数値の結果を返すカスタムツール実装の例です。

// Implement a simple calculator tool that adds two digits
object CalculatorTool : Tool<CalculatorTool.Args, ToolResult.Number>() {
    
    // Arguments for the calculator tool
    @Serializable
    data class Args(
        val digit1: Int,
        val digit2: Int
    ) : ToolArgs {
        init {
            require(digit1 in 0..9) { "digit1 must be a single digit (0-9)" }
            require(digit2 in 0..9) { "digit2 must be a single digit (0-9)" }
        }
    }

    // Serializer for the Args class
    override val argsSerializer = Args.serializer()

    // Tool descriptor
    override val descriptor: ToolDescriptor = ToolDescriptor(
        name = "calculator",
        description = "A simple calculator that can add two digits (0-9).",
        requiredParameters = listOf(
            ToolParameterDescriptor(
                name = "digit1",
                description = "The first digit to add (0-9)",
                type = ToolParameterType.Integer
            ),
            ToolParameterDescriptor(
                name = "digit2",
                description = "The second digit to add (0-9)",
                type = ToolParameterType.Integer
            )
        )
    )

    // Function to add two digits
    override suspend fun execute(args: Args): ToolResult.Number {
        val sum = args.digit1 + args.digit2
        return ToolResult.Number(sum)
    }
}

ツールを実装したら、それをツールレジストリに追加し、エージェントで使用する必要があります。詳細については、「ツールレジストリ」を参照してください。

詳細については、「API リファレンス」を参照してください。

SimpleTool クラス

SimpleTool<Args> 抽象クラスは Tool<Args, ToolResult.Text> を拡張し、テキスト結果を返すツールの作成を簡素化します。

各シンプルツールは次のコンポーネントで構成されます。

コンポーネント	説明
Args	カスタムツールに必要な引数を定義するシリアライズ可能なデータクラス。
argsSerializer	ツールの引数をどのようにシリアライズするかを定義するオーバーライドされた変数。argsSerializer も参照してください。
descriptor	ツールメタデータを指定するオーバーライドされた変数: - name - description - requiredParameters (デフォルトは空) - optionalParameters (デフォルトは空) descriptor も参照してください。
doExecute()	ツールによって実行される主要なアクションを記述するオーバーライドされた関数。Args 型の引数を受け取り、String を返します。doExecute() も参照してください。

TIP

LLMがツールを適切に理解して使用できるように、ツールの明確な説明と適切に定義されたパラメータ名があることを確認してください。

使用例

以下は、SimpleTool を使用したカスタムツール実装の例です。

// Create a tool that casts a string expression to a double value
object CastToDoubleTool : SimpleTool<CastToDoubleTool.Args>() {
    // Define tool arguments
    @Serializable
    data class Args(val expression: String, val comment: String) : ToolArgs

    // Serializer for the Args class
    override val argsSerializer = Args.serializer()

    // Tool descriptor
    override val descriptor = ToolDescriptor(
        name = "cast_to_double",
        description = "casts the passed expression to double or returns 0.0 if the expression is not castable",
        requiredParameters = listOf(
            ToolParameterDescriptor(
                name = "expression", description = "An expression to case to double", type = ToolParameterType.String
            )
        ),
        optionalParameters = listOf(
            ToolParameterDescriptor(
                name = "comment",
                description = "A comment on how to process the expression",
                type = ToolParameterType.String
            )
        )
    )
    
    // Function that executes the tool with the provided arguments
    override suspend fun doExecute(args: Args): String {
        return "Result: ${castToDouble(args.expression)}, " + "the comment was: ${args.comment}"
    }
    
    // Function to cast a string expression to a double value
    private fun castToDouble(expression: String): Double {
        return expression.toDoubleOrNull() ?: 0.0
    }
}

ツールを実装したら、それをツールレジストリに追加し、エージェントで使用する必要があります。 詳細については、「ツールレジストリ」を参照してください。