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

エージェントメモリ

備考

ベータ版

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

マネージドエージェントメモリDatabricksはメモリをLakebaseに保存し、ストレージ、インデックス作成、検索を管理するため、データベースを操作することなく、エージェントがユーザーの好み、過去の決定、蓄積されたコンテキストを記憶できます。

注記

プレビュー期間中、メモリエントリーを保存する基盤となる Lakebase インスタンスに対して課金されます。エージェントメモリ自体に追加料金は発生しません。価格は、プレビューの進行状況に応じて変更される可能性があります。

エージェントに次のことをさせたい場合、エージェントメモリを使用します。

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

エージェントメモリは、任意のフレームワーク上に構築されたエージェントで動作します。単一のインタラクション内での短期間の会話履歴については、 エージェントセッション を使用してください。

要件​

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

エージェントメモリの仕組み​

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

エージェントのメモリには、次の2つのレベルがあります。

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

入力は、 actor_id、 session_id、 pathの組み合わせによって一意に識別されます。2つの異なるセッション、またはセッションの下とセッションなしの下の同じパスには、2つの別個の入力が保持されます。

エントリがストアに格納される方法は2つあります。エージェントまたはアプリケーションが直接書き込む方法と、メモリパイプラインがセッションストア内の会話から抽出する方法です。

検索​

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

  • アクターのエントリを 一覧表示 します。session_id、pathプレフィックス、またはpathとの完全一致で任意にフィルターできます。エージェントが把握している内容のインデックスを参照または表示するには、これを使用します。
  • 自然言語のクエリーを使用してアクターのエントリを 検索 します。検索は、関連度スコアによってランク付けされた最も関連性の高いエントリを返します。

いずれかの操作に対するsession_idフィルターは、そのセッションで保存されたエントリーのみを返します。セッションなしで保存されたエントリーは返されません。

使い始める​

これらの例では、サポートエージェント用のエージェントメモリを設定します。メモリストアを作成し、ユーザーの好みを保存して、後の会話で呼び出します。プロジェクトに適したクライアントを選択します。メモリ・ストアIDは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",
    )

    add() そのパスにエントリがすでに存在する場合は、ALREADY_EXISTSで失敗します。エントリを作成するか既存のエントリを更新するには、同じ引数でmemory_store.put()を呼び出します。

  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, replacing any memory at the same path."""
        memory_store.put(actor_id=actor_id, path=path, content=content, description=description or None)
        return f"Saved memory at {path}"

    @function_tool
    def list_memories() -> str:
        """List the paths and descriptions of the user's long-term memories."""
        memories = memory_store.list(actor_id=actor_id)
        return "\n".join(f"{m.path}: {m.description}" if m.description else m.path for m in memories) or "No memory found."

    @function_tool
    def forget_memory(path: str) -> str:
        """Delete the long-term memory at a path, such as when the user asks you to forget it."""
        memories = list(memory_store.list(actor_id=actor_id, path=path))
        for memory in memories:
            memory.delete()
        return f"Forgot memory at {path}" if memories else f"No memory at {path}"

    return [search_memory, save_memory, list_memories, forget_memory]

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

put() エントリを作成するか、そのパスに既に存在するエントリの内容を置き換えます。代わりにコンテンツを新しい行として追加するには、append=Trueを渡します。put()はアトミックではないため、同じパスへの並列書き込みが上書きされる可能性があります。list(path=...)は、セッション内のその正確なパスのエントリを返すため、forget_memoryは、セッションでそのパスに保存されたエントリも削除します。

同じパターンが 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 件のエントリが返され、ページ分割はサポートされていません。
  • アクセス制御はストアレベルで強制されます。エントリ単位およびアクター単位のアクセス制御は利用できません。
  • ストアアクセスコントロールは、ストアのエントリを制御します。すべてのワークスペース・ユーザーは、データベース・インスタンスのリストおよび取得（IDおよび説明を含む）が可能です。
  • ストアの作成後にその ID を変更することはできません。descriptionのみ更新可能です。

次のステップ​

このページの見出し