メインコンテンツまでスキップ
に最終更新

マネージドエージェントメモリ

備考

ベータ版

この機能はベータ版です。

マネージドエージェントメモリを使用すると、エージェントに会話をまたいで保持される永続的な長期メモリを提供できます。DatabricksはメモリをLakebaseに保存し、ストレージ、インデックス作成、セマンティック検索を代わりに管理します。これにより、データベースを運用しなくても、エージェントはユーザーの好み、過去の意思決定、蓄積されたコンテキストを記憶できます。

注記

プレビュー期間中は、メモリエントリーを保存する基盤となる Lakebase インスタンスに対して課金されます。マネージドエージェントメモリ自体には追加料金はかかりません。価格はプレビューの進行に伴い変更される場合があります。

エージェントに次のことを行わせる場合は、マネージドメモリを使用します。

  • 別の会話間でユーザーの好み、事実、および決定事項を記憶します。
  • エージェントが以前のセッションで学習した内容に基づいて応答をパーソナライズします。
  • 蓄積されたナレッジをエージェントやプロジェクト間で共有します。
  • 時間の経過とともに精度と効率が向上します。

マネージドメモリは、任意のフレームワークで構築されたエージェントと連携します。単一のインタラクション内での短期的な会話履歴には、マネージドエージェントセッションを使用します。

マネージドメモリの仕組み​

Managed agent memoryのリソース階層: メモリストアには多数のメモリエントリーが含まれており、それぞれが actor_id、オプションの session_id、パスによって識別され、コンテンツと説明を保持します。

マネージドメモリには 2 つのレベルがあります：

  • メモリストア は、エージェントのメモリのためのワークスペーススコープのコンテナです。ストアを作成すると、バッキングLakebaseストレージが自動的にプロビジョニングされます。ストアにはdisplay_nameでアクセスします。
  • メモリエントリー は、ストア内の個々のコンテンツです。各エントリーには、自由形式のテキスト content、取得に使用される短い description、およびそれを整理してパーティション分割するためのフィールドのセットがあります。
    • actor_id （必須）：エンドユーザーや別のエージェントなど、メモリの所有者。
    • session_id （オプション）：トレーサビリティと出所の確認のために、メモリが取得されたセッションを記録します。特定のセッションに結び付けられていないメモリについては、設定を未設定のままにします。
    • path （必須）：/preferences/response-style.mdなど、アクター内のエントリーを整理するファイルシステムのようなパス。

エントリは、actor_id、session_id、および path の組み合わせによって一意に識別されます。

検索​

メモリを検索する2つの方法：

  • アクターのエントリーを リスト 表示します（session_id または path のプレフィックスによるフィルタリングはオプションです）。エージェントが認識している情報のインデックスを参照またはレンダリングするには、これを使用します。
  • 自然言語のクエリーを使用してアクターのエントリを 検索 します。検索では、全文（BM25）関連性スコアによってランク付けされた、最も関連性の高いエントリが返されます。

要件​

  • AgentKit SDK を使用するには、 Python 3.10以降 をインストールします。AgentKit SDKは、以下の例で使用されているエージェントAPI用のDatabricks Pythonクライアントです。Pythonの要件なしで、任意の言語から直接REST APIを呼び出すこともできます。

使い始める​

これらの例では、サポートエージェント用に管理されたメモリを設定します。メモリストアを作成し、ユーザーの設定を保存して、その後の会話でそれを呼び出します。プロジェクトに適したクライアントを選択します。メモリストアの display_name は3～56文字で、小文字で始まり、文字または数字で終わり、小文字、数字、およびハイフンのみを含める必要があります。

AgentKit SDKは、エージェントAPI用のDatabricks Pythonクライアントであり、databricks-agentbricksパッケージで配布されています。Databricks SDKのWorkspaceClientで認証を行います。

  1. AgentKit SDKをインストールする：

    Bash
    pip install databricks-agentbricks

  2. エージェント用のメモリストアを作成します。AgentKitClientはWorkspaceClientの認証情報で認証を行います：

    Python
    from databricks.sdk import WorkspaceClient
    from databricks_agentkit import AgentKitClient

    client = AgentKitClient(WorkspaceClient())
    memory_store = client.memory_stores.create("support-agent-memory")

  3. エージェントがユーザーに関する永続的な情報を学習した後に、メモリを保存します。actor_id はこのメモリの所有者であり、path はそのアクター内でメモリを整理し、description は検索性を向上させます。

    Python
    memory_store.add(
        actor_id="user-123",
        path="/preferences/communication.md",
        content="Prefers email over phone. Timezone: PST. Enterprise subscription.",
        description="User 123 communication preferences",
    )

  4. 自然言語検索を使用して、その後の会話でユーザーのメモリを呼び出します。

    Python
    results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)

エージェントにメモリツールを提供します​

エージェントがメモリを保存および呼び出すタイミングを自ら判断できるようにするには、クライアント操作をツールとしてラップし、システムプロンプトでツールを使用するタイミングをエージェントに指示します。検証済みのエンドユーザーIDから、信頼できるアプリケーションコード内のactor_idを設定します。どのメモリを読み書きするかをモデルに決して選択させないようにします。

次の例では、はじめにのAgentKit SDK memory_storeをOpenAI Agents SDKのツールとしてラップします。

Python
from agents import Agent, function_tool

def make_memory_tools(memory_store, actor_id: str):
    @function_tool
    def search_memory(query: str) -> str:
        """Search long-term memory for relevant facts about the user."""
        results = memory_store.search(actor_id=actor_id, query=query, limit=10)
        return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."

    @function_tool
    def save_memory(path: str, content: str, description: str = "") -> str:
        """Save a durable, long-term memory about the user."""
        memory_store.add(actor_id=actor_id, path=path, content=content, description=description)
        return f"Saved memory at {path}"

    return [search_memory, save_memory]

agent = Agent(
    name="Support agent",
    instructions="Save durable user preferences and recall them when relevant.",
    tools=make_memory_tools(memory_store, actor_id="user-123"),
)

Claude Agent SDK やその他のフレームワークでも同様のパターンが機能します。ストアの検索と追加の操作を、フレームワークのツールタイプとしてラップします。

メモリのパーティション分割とセキュリティ保護​

ストア内では、誰のメモリが誰のものかを分離する方法として actor_id が使用されます。すべてのリストと検索のスコープは単一の actor_id に限定されるため、エージェントが記憶する必要がある内容に一致する戦略を選択してください。

  • 各ユーザーのプライベートメモリ: actor_idを検証済みのエンドユーザーIDに設定します。各ユーザーに個別のパーティションが割り当てられ、エージェントはそのユーザーのエントリーのみを呼び出します。

    • 例: サポートエージェントは、ユーザーの通信設定と過去のチケットを記憶します。

  • グループの共有メモリ: actor_idに、チーム、プロジェクト、組織 ID などの選択した固定キーを設定します。全員が同じメモリを読み書きします。

    • 例： チームエージェントは、会社の用語や内部の規約に関する共有用語集を記憶します。

  • その他の条件で分割されたメモリ： テナント ID や user:project の複合など、独自の値から actor_id を構築します。

    • 例: マルチテナントアプリは、各顧客のユーザーが互いに分離された状態を維持できるように、actor_idを{tenant}:{user}に設定します。

信頼できる呼び出し元のコンテキストからアプリケーションコードに actor_id を設定します。ユーザーごとのメモリの場合は検証済みのエンドユーザーの識別情報、共有メモリの場合は信頼できるチームまたはプロジェクトのキーを指定します。モデルに選択させないでください。戦略がエンドユーザーの識別情報に依存している場合は、共有の actor_id にフォールバックするのではなく、識別情報を持たないリクエストを拒否してください。

警告

actor_id メモリを分離しますが、アクセス制御ではありません。マネージドメモリストアはワークスペースのスコープ内にあるため、ストアにアクセスできるプリンシパルであれば誰でも、すべてのパフォーマ（アクター）にわたるすべてのエントリーの読み取りと書き込みを行うことができます。セキュリティ境界となるのは、アクターではなくストアです。テナントまたはユーザー間で厳密に分離するには、境界ごとに個別のメモリストアを作成します。

エージェントのService Principalなどの別のプリンシパルにストアの使用を許可するには、ストアの付与権限操作（AgentKit SDKのmemory_store.grant_permission(principal_id)）を使用してアクセス権を付与します。

制限事項​

  • マネージドメモリは、長期メモリのみを提供します。短期的な会話履歴については、マネージドエージェントセッションをご覧ください。
  • 検索は関連性でランク付けされた全文（BM25）操作であり、最大100件のエントリーからなるトップNの結果セットを返します。ページネーションやベクトル類似性検索はサポートされていません。
  • アクセス制御はストアレベルで強制されます。エントリ単位およびアクター単位のアクセス制御は利用できません。
  • ストア display_name は作成後は変更できません。description のみを更新できます。

次のステップ​

このページの見出し