概要

エージェントは、特定のタスクを実行したり、外部システムにアクセスしたりするためにツールを使用します。

ツールワークフロー

Koogフレームワークは、ツールを扱うための以下のワークフローを提供します。

1. カスタムツールを作成するか、組み込みツールのいずれかを使用します。
2. ツールをツールレジストリに追加します。
3. ツールレジストリをエージェントに渡します。
4. エージェントでツールを使用します。

利用可能なツールタイプ

Koogフレームワークには、3種類のツールがあります。

• エージェントとユーザーの対話、および会話管理の機能を提供する組み込みツール。詳細は、組み込みツールを参照してください。
• 関数をLLMにツールとして公開できるアノテーションベースのカスタムツール。詳細は、アノテーションベースのツールを参照してください。
• ツールパラメーター、メタデータ、実行ロジック、および登録・呼び出し方法を制御できるカスタムツール（クラスベースのツール）。詳細は、クラスベースのツールを参照してください。

ツールレジストリ

エージェントでツールを使用する前に、ツールレジストリに追加する必要があります。 ツールレジストリは、エージェントが利用できるすべてのツールを管理します。

ツールレジストリの主な機能：

• ツールを整理します。
• 複数のツールレジストリのマージをサポートします。
• 名前またはタイプでツールを取得するメソッドを提供します。

詳細については、ToolRegistryを参照してください。

以下に、ツールレジストリを作成し、ツールを追加する例を示します。

val toolRegistry = ToolRegistry {
    tool(SayToUser)
}

複数のツールレジストリをマージするには、次のようにします。

val firstToolRegistry = ToolRegistry {
    tool(FirstSampleTool)
}

val secondToolRegistry = ToolRegistry {
    tool(SecondSampleTool)
}

val newRegistry = firstToolRegistry + secondToolRegistry

エージェントへのツールの受け渡し

エージェントがツールを使用できるようにするには、エージェントを作成する際に、このツールを含むツールレジストリを引数として提供する必要があります。

// Agent initialization
val agent = AIAgent(
    executor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
    systemPrompt = "You are a helpful assistant with strong mathematical skills.",
    llmModel = OpenAIModels.Chat.GPT4o,
    // Pass your tool registry to the agent
    toolRegistry = toolRegistry
)

ツールの呼び出し

エージェントコード内でツールを呼び出す方法はいくつかあります。推奨されるアプローチは、ツールを直接呼び出すのではなく、エージェントコンテキストで提供されるメソッドを使用することです。これにより、エージェント環境内でのツール操作が適切に処理されます。

TIP

エージェントの失敗を防ぐため、ツールに適切なエラー処理を実装していることを確認してください。

ツールは、AIAgentLLMWriteSessionで表される特定のセッションコンテキスト内で呼び出されます。 これには、ツールを呼び出すためのいくつかのメソッドが用意されており、次のことができます。

• 指定された引数でツールを呼び出します。
• その名前と指定された引数でツールを呼び出します。
• 提供されたツールクラスと引数でツールを呼び出します。
• 指定されたタイプのツールを、指定された引数で呼び出します。
• 生の文字列結果を返すツールを呼び出します。

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

並列ツール呼び出し

toParallelToolCallsRaw拡張機能を使用して、ツールを並列で呼び出すこともできます。例：

@Serializable
data class Book(
    val title: String,
    val author: String,
    val description: String
) : ToolArgs

class BookTool() : SimpleTool<Book>() {
    companion object {
        const val NAME = "book"
    }

    override suspend fun doExecute(args: Book): String {
        println("${args.title} by ${args.author}:
 ${args.description}")
        return "Done"
    }

    override val argsSerializer: KSerializer<Book>
        get() = Book.serializer()

    override val descriptor: ToolDescriptor
        get() = ToolDescriptor(
            name = NAME,
            description = "A tool to parse book information from Markdown",
            requiredParameters = listOf(),
            optionalParameters = listOf()
        )
}

val strategy = strategy<Unit, Unit>("strategy-name") {

    /*...*/

    val myNode by node<Unit, Unit> { _ ->
        llm.writeSession {
            flow {
                emit(Book("Book 1", "Author 1", "Description 1"))
            }.toParallelToolCallsRaw(BookTool::class).collect()
        }
    }
}

ノードからのツール呼び出し

ノードを使用してエージェントワークフローを構築する場合、特殊なノードを使用してツールを呼び出すことができます。

• nodeExecuteTool: 単一のツール呼び出しを実行し、その結果を返します。詳細は、APIリファレンスを参照してください。

• nodeExecuteSingleTool: 指定された引数で特定のツールを呼び出します。詳細は、APIリファレンスを参照してください。

• nodeExecuteMultipleTools: 複数のツール呼び出しを実行し、それらの結果を返します。詳細は、APIリファレンスを参照してください。

• nodeLLMSendToolResult: ツール結果をLLMに送信し、応答を取得します。詳細は、APIリファレンスを参照してください。

• nodeLLMSendMultipleToolResults: 複数のツール結果をLLMに送信します。詳細は、APIリファレンスを参照してください。