概要

Koogは、AIAgentStorageを使用してデータを保存および渡す方法を提供します。これは、異なるノード間やサブグラフ間でもデータを渡せるように設計された、型安全なキーバリュー型ストレージシステムです。

このストレージは、エージェントノードで利用できるstorageプロパティ（storage: AIAgentStorage）を通じてアクセスでき、AIエージェントシステムの様々なコンポーネント間でシームレスなデータ共有を可能にします。

キーと値の構造

キーバリューデータストレージの構造は、AIAgentStorageKeyデータクラスに基づいています。AIAgentStorageKeyの詳細については、以下のセクションを参照してください。

AIAgentStorageKey

このストレージは、データの保存と取得の際に型安全性を保証するために、型付けされたキーシステムを使用しています。

• AIAgentStorageKey<T>: データの識別とアクセスに使用されるストレージキーを表すデータクラスです。AIAgentStorageKeyクラスの主要な特徴は以下の通りです。
  • 総称型パラメーターTは、このキーに関連付けられたデータの型を指定し、型安全性を保証します。
  • 各キーには、ストレージキーを一意に表現する文字列識別子であるnameプロパティがあります。

使用例

以下のセクションでは、ストレージキーを作成し、それを使用してデータを保存および取得する実際の例を提供します。

データを表すクラスの定義

渡したいデータを保存する際の最初のステップは、そのデータを表すクラスを作成することです。以下は、基本的なユーザーデータを持つシンプルなクラスの例です。

class UserData(
   val name: String,
   val age: Int
)

一度定義したら、以下に説明するように、そのクラスを使用してストレージキーを作成します。

ストレージキーの作成

定義されたデータ構造に対して、型付けされたストレージキーを作成します。

val userDataKey = createStorageKey<UserData>("user-data")

createStorageKey関数は、キーを一意に識別する単一の文字列パラメーターを受け取ります。

データの保存

作成されたストレージキーを使用してデータを保存するには、ノード内でstorage.set(key: AIAgentStorageKey<T>, value: T)メソッドを使用します。

val nodeSaveData by node<Unit, Unit> {
    storage.set(userDataKey, UserData("John", 26))
}

データの取得

データを取得するには、ノード内でstorage.getメソッドを使用します。

val nodeRetrieveData by node<String, Unit> { message ->
    storage.get(userDataKey)?.let { userFromStorage ->
        println("Hello dear $userFromStorage, here's a message for you: $message")
    }
}

APIドキュメント

AIAgentStorageクラスに関する完全なリファレンスについては、AIAgentStorageを参照してください。

AIAgentStorageクラスで利用可能な個々の関数については、以下のAPIリファレンスを参照してください。

• clear
• get
• getValue
• putAll
• remove
• set
• toMap

追加情報

• AIAgentStorageはスレッドセーフであり、ミューテックス（Mutex）を使用して同時アクセスが適切に処理されることを保証します。
• このストレージは、Anyを拡張する任意の型と連携するように設計されています。
• 値を取得する際、型キャストは自動的に処理され、アプリケーション全体で型安全性が保証されます。
• 非null値へのアクセスには、キーが存在しない場合に例外をスローするgetValueメソッドを使用します。
• clearメソッドを使用すると、ストレージに保存されているすべてのキーバリューペアが削除され、ストレージ全体をクリアできます。