シングルランエージェント

AIAgentクラスは、KotlinアプリケーションでAIエージェントを作成するためのコアコンポーネントです。

最小限の構成でシンプルなエージェントを構築することも、カスタム戦略、ツール、構成、およびカスタム入出力タイプを定義することで、高度な機能を備えた洗練されたエージェントを作成することもできます。

このページでは、カスタマイズ可能なツールと構成を備えたシングルランエージェント（single-run agent）を作成するために必要な手順を説明します。

シングルランエージェントは、単一の入力を処理し、応答を提供します。 そのタスクを完了し、応答を提供するために、ツール呼び出しの単一サイクル内で動作します。 このエージェントは、メッセージまたはツール結果のいずれかを返すことができます。 ツールレジストリがエージェントに提供された場合、ツール結果が返されます。

もし実験するためにシンプルなエージェントを構築することが目的であれば、エージェントを作成する際にプロンプトエクゼキューターとLLMのみを提供すれば十分です。 しかし、より柔軟性とカスタマイズ性を求める場合は、オプションのパラメータを渡してエージェントを構成できます。 構成オプションの詳細については、API referenceを参照してください。

前提条件

• AIエージェントの実装に使用するLLMプロバイダーの有効なAPIキーを持っていること。利用可能なすべてのプロバイダーのリストについては、Overviewを参照してください。

TIP

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

シングルランエージェントの作成

1. 依存関係の追加

AIAgent機能を使用するには、必要なすべての依存関係をビルド構成に含めます。

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

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

2. エージェントの作成

エージェントを作成するには、AIAgentクラスのインスタンスを作成し、executorおよびllmModelパラメータを指定します。

val agent = AIAgent(
    executor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
    llmModel = OpenAIModels.Chat.GPT4o
)

3. システムプロンプトの追加

システムプロンプトは、エージェントの動作を定義するために使用されます。プロンプトを提供するには、systemPromptパラメータを使用します。

val agent = AIAgent(
    executor = simpleOpenAIExecutor(System.getenv("YOUR_API_KEY")),
    systemPrompt = "You are a helpful assistant. Answer user questions concisely.",
    llmModel = OpenAIModels.Chat.GPT4o
)

4. LLM出力の構成

temperatureパラメータを使用して、LLM出力生成の温度を指定します。

val agent = AIAgent(
    executor = simpleOpenAIExecutor(System.getenv("YOUR_API_KEY")),
    systemPrompt = "You are a helpful assistant. Answer user questions concisely.",
    llmModel = OpenAIModels.Chat.GPT4o,
    temperature = 0.7
)

5. ツールの追加

エージェントは特定のタスクを完了するためにツールを使用します。 組み込みツールを使用することも、必要に応じて独自のカスタムツールを実装することもできます。

ツールを構成するには、エージェントが利用できるツールを定義するtoolRegistryパラメータを使用します。

val agent = AIAgent(
    executor = simpleOpenAIExecutor(System.getenv("YOUR_API_KEY")),
    systemPrompt = "You are a helpful assistant. Answer user questions concisely.",
    llmModel = OpenAIModels.Chat.GPT4o,
    temperature = 0.7,
    toolRegistry = ToolRegistry {
        tool(SayToUser)
    }
)

この例では、SayToUserは組み込みツールです。カスタムツールの作成方法については、Toolsを参照してください。

6. エージェントのイテレーションの調整

エージェントが停止を余儀なくされるまでに実行できる最大ステップ数を、maxIterationsパラメータを使用して指定します。

val agent = AIAgent(
    executor = simpleOpenAIExecutor(System.getenv("YOUR_API_KEY")),
    systemPrompt = "You are a helpful assistant. Answer user questions concisely.",
    llmModel = OpenAIModels.Chat.GPT4o,
    temperature = 0.7,
    toolRegistry = ToolRegistry {
        tool(SayToUser)
    },
    maxIterations = 30
)

7. エージェント実行時のイベント処理

シングルランエージェントはカスタムイベントハンドラをサポートしています。 エージェントを作成する上でイベントハンドラは必須ではありませんが、テスト、デバッグ、または連鎖的なエージェントインタラクションのためのフックを作成するのに役立つ場合があります。

エージェントのインタラクションを監視するためのEventHandler機能の使用方法の詳細については、Agent eventsを参照してください。

8. エージェントの実行

エージェントを実行するには、run()関数を使用します。

val agent = AIAgent(
    executor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
    systemPrompt = "You are a helpful assistant. Answer user questions concisely.",
    llmModel = OpenAIModels.Chat.GPT4o,
    temperature = 0.7,
    toolRegistry = ToolRegistry {
        tool(SayToUser)
    },
    maxIterations = 100
)

fun main() = runBlocking {
    val result = agent.run("Hello! How can you help me?")
}

エージェントは次の出力を生成します。

Agent says: Hello! I'm here to assist you with a variety of tasks. Whether you have questions, need information, or require help with specific tasks, feel free to ask. How can I assist you today?