機能エージェント

機能エージェントは、複雑な戦略グラフを構築することなく動作する軽量なAIエージェントです。代わりに、エージェントロジックは、ユーザー入力を処理し、LLMと対話し、必要に応じてツールを呼び出し、最終的な出力を生成するラムダ関数として実装されます。単一のLLM呼び出しを実行したり、複数のLLM呼び出しを連続して処理したり、ユーザー入力、LLM、およびツール出力に基づいてループしたりすることができます。

TIP

既に基本的なエージェントを最初のMVPとして持っているが、タスク固有の制限に直面している場合は、機能エージェントを使用してカスタムロジックをプロトタイプ作成してください。履歴圧縮や自動状態管理を含むKoogのほとんどの機能を使用しながら、純粋なKotlinでカスタム制御フローを実装できます。
実運用レベルのニーズに対しては、戦略グラフを持つ複雑なワークフローエージェントに機能エージェントをリファクタリングしてください。これは、フォールトトレランスのための制御可能なロールバックによる永続性と、ネストされたグラフイベントによる高度なOpenTelemetryトレースを提供します。

このページでは、最小限の機能エージェントを作成し、それをツールで拡張するために必要な手順を説明します。

前提条件

開始する前に、以下が揃っていることを確認してください。

動作可能なKotlin/JVMプロジェクト。
Java 17以降がインストールされていること。
AIエージェントを実装するために使用するLLMプロバイダーからの有効なAPIキー。利用可能なすべてのプロバイダーのリストについては、LLMプロバイダーを参照してください。
(任意) Ollamaを使用する場合、Ollamaがローカルにインストールされ、実行されていること。

TIP

APIキーは環境変数または安全な構成管理システムを使用して保存してください。ソースコードにAPIキーを直接ハードコーディングすることは避けてください。

依存関係を追加する

AIAgentクラスは、Koogでエージェントを作成するためのメインクラスです。クラスの機能を使用するには、ビルド構成に以下の依存関係を含めてください。

dependencies {
    implementation("ai.koog:koog-agents:VERSION")
}

利用可能なすべてのインストール方法については、Koogのインストールを参照してください。

最小限の機能エージェントを作成する

最小限の機能エージェントを作成するには、以下を実行します。

エージェントが処理する入力および出力タイプを選択し、対応するAIAgent<Input, Output>インスタンスを作成します。このガイドではAIAgent<String, String>を使用します。これは、エージェントがStringを受け取り、Stringを返すことを意味します。
システムプロンプト、プロンプトエグゼキューター、LLMを含む必要なパラメーターを指定します。
functionalStrategy {...} DSLメソッドにラップされたラムダ関数でエージェントロジックを定義します。

以下は、ユーザーテキストを指定されたLLMに送信し、単一のアシスタントメッセージを返す最小限の機能エージェントの例です。

kotlin

// Create an AIAgent instance and provide a system prompt, prompt executor, and LLM
val mathAgent = AIAgent<String, String>(
    systemPrompt = "You are a precise math assistant.",
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
    strategy = functionalStrategy { input -> // Define the agent logic
        // Make one LLM call
        val response = requestLLM(input)
        // Extract and return the assistant message content from the response
        response.asAssistantMessage().content
    }
)

// Run the agent with a user input and print the result
val result = mathAgent.run("What is 12 × 9?")
println(result)

エージェントは以下の出力を生成できます。

The answer to 12 × 9 is 108.

このエージェントは1回のLLM呼び出しを行い、アシスタントメッセージの内容を返します。複数の連続したLLM呼び出しを処理するようにエージェントロジックを拡張できます。例:

kotlin

// Create an AIAgent instance and provide a system prompt, prompt executor, and LLM
val mathAgent = AIAgent<String, String>(
    systemPrompt = "You are a precise math assistant.",
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
    strategy = functionalStrategy { input -> // Define the agent logic
        // ユーザー入力に基づいて最初のドラフトを生成する最初のLLM呼び出し
        val draft = requestLLM("Draft: $input").asAssistantMessage().content
        // ドラフトの内容を再度LLMにプロンプトして、ドラフトを改善する2番目のLLM呼び出し
        val improved = requestLLM("Improve and clarify: $draft").asAssistantMessage().content
        // 改善されたテキストをフォーマットし、最終的なフォーマットされた結果を返す最後のLLM呼び出し
        requestLLM("Format the result as bold: $improved").asAssistantMessage().content
    }
)

// Run the agent with a user input and print the result
val result = mathAgent.run("What is 12 × 9?")
println(result)

エージェントは以下の出力を生成できます。

When multiplying 12 by 9, we can break it down as follows:

**12 (tens) × 9 = 108**

Alternatively, we can also use the distributive property to calculate this:

**(10 + 2) × 9**
= **10 × 9 + 2 × 9**
= **90 + 18**
= **108**

ツールを追加する

多くの場合、機能エージェントは、データの読み書きやAPIの呼び出しなど、特定のタスクを完了する必要があります。 Koogでは、そのような機能をツールとして公開し、LLMがエージェントロジック内でそれらを呼び出せるようにします。

この章では、上記で作成した最小限の機能エージェントを例にとり、ツールを使用してエージェントロジックを拡張する方法を示します。

アノテーションベースのツールを作成します。詳細については、アノテーションベースのツールを参照してください。

kotlin

@LLMDescription("Simple multiplier")
class MathTools : ToolSet {
    @Tool
    @LLMDescription("Multiplies two numbers and returns the result")
    fun multiply(a: Int, b: Int): Int {
        val result = a * b
        return result
    }
}

利用可能なツールについてさらに学ぶには、ツール概要を参照してください。

ツールを登録して、エージェントで利用できるようにします。

kotlin

val toolRegistry = ToolRegistry {
    tools(MathTools())
}

ツールレジストリをエージェントに渡して、LLMが利用可能なツールをリクエストおよび使用できるようにします。
ツール呼び出しを識別し、リクエストされたツールを実行し、その結果をLLMに送り返し、ツール呼び出しがなくなるまでプロセスを繰り返すようにエージェントロジックを拡張します。

NOTE

LLMがツール呼び出しを発行し続ける場合にのみ、ループを使用してください。

kotlin

val mathWithTools = AIAgent<String, String>(
    systemPrompt = "You are a precise math assistant. When multiplication is needed, use the multiplication tool.",
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
    toolRegistry = toolRegistry,
    strategy = functionalStrategy { input -> // ツール呼び出しで拡張されたエージェントロジックを定義
        // ユーザー入力をLLMに送信
        var responses = requestLLMMultiple(input)

        // LLMがツールをリクエストしている間だけループする
        while (responses.containsToolCalls()) {
            // レスポンスからツール呼び出しを抽出
            val pendingCalls = extractToolCalls(responses)
            // ツールを実行し、結果を返す
            val results = executeMultipleTools(pendingCalls)
            // ツール結果をLLMに送り返します。LLMはさらにツールを呼び出すか、最終出力を返す場合があります
            responses = sendMultipleToolResults(results)
        }

        // ツール呼び出しが残っていない場合、レスポンスからアシスタントメッセージの内容を抽出して返す
        responses.single().asAssistantMessage().content
    }
)

// ユーザー入力でエージェントを実行し、結果を出力する
val reply = mathWithTools.run("Please multiply 12.5 and 4, then add 10 to the result.")
println(reply)

エージェントは以下の出力を生成できます。

Here is the step-by-step solution:

1. Multiply 12.5 and 4:
   12.5 × 4 = 50

2. Add 10 to the result:
   50 + 10 = 60

次のステップ

構造化出力APIを使用して構造化データを返す方法を学びます。
エージェントにさらにツールを追加する実験をします。
EventHandler機能で可観測性を向上させます。
履歴圧縮で長期間の会話を処理する方法を学びます。

OpenTelemetry

機能エージェント ​

前提条件 ​

依存関係を追加する ​

最小限の機能エージェントを作成する ​

ツールを追加する ​

次のステップ ​

機能エージェント

前提条件

依存関係を追加する

最小限の機能エージェントを作成する

ツールを追加する

次のステップ