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

Important

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

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

Note

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

エージェントに以下のことをしたいときにマネージドメモリを使います:

  • ユーザーの好み、事実、意思決定を別々の会話で覚えておく。
  • エージェントが以前のセッションで学んだことを基に、個別の回答をカスタマイズしましょう。
  • エージェントやプロジェクト間で蓄積された知識を共有しましょう。
  • 時間の経過に伴う精度と効率の向上。

マネージドメモリは、どんなフレームワークでも構築されたエージェントと連携して動作します。 単一のやり取り内での短期的な会話履歴を記録するには 、マネージドエージェントセッションをご利用ください。

Requirements

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

マネージド メモリのしくみ

マネージドエージェントのメモリリソース階層:メモリストアには多くのメモリエントリが含まれ、それぞれが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)スコアでランク付けされた最も関連性の高いエントリーを返します。

概要

これらの例はサポートエージェントのためにマネージドメモリを設定するもので、メモリストアを作成し、ユーザーの好みを保存し、後の会話で呼び戻します。 自分のプロジェクトに合ったクライアントを選びましょう。 メモリストアの display_name は3文字から56文字で、小文字で始まり、文字または数字で終わり、小文字の文字、数字、ハイフンのみを含む必要があります。

AgentKit SDK

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

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

    pip install databricks-agentbricks

  2. エージェントのためにメモリーストアを作成しましょう。 AgentKitClientお客様のWorkspaceClient認証情報で認証します:

    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 検索を改善します。

    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. 自然言語検索で後の会話でユーザーの記憶を思い出す:

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

REST API

クライアントはREST APIを /api/2.0/agents/memory-storesで呼び出します。 Python以外の言語では直接呼び出せばいいです。

  1. Databricks CLIを使ってOAuthトークンを生成します:

    databricks auth login --host ${DATABRICKS_HOST}
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

  2. エージェントのためのメモリストアを作成する:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"display_name": "support-agent-memory", "description": "Support agent memory"}'

  3. ユーザー用のメモリエントリを保存します。 actor_id はこのメモリの所有者であり、 path はそれを整理し、 description は検索を改善します。

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "path": "/preferences/communication.md", "content": "Prefers email over phone.", "description": "Communication preferences"}'

  4. 自然言語検索でユーザーの記憶を呼び起こす:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "query": "communication preferences"}'

エージェントに記憶ツールを与えましょう

エージェントがいつメモリを保存・リコールするかを決められるようにし、クライアント操作をツールとしてラップし、システムプロンプトでいつ使用するか指示します。 認証済みのエンドユーザーIDから信頼されたアプリケーションコードで actor_id を設定します。 どちらのメモリを読み書きするかをモデルに決めさせてはいけません。

以下の例は、GetstartedのAgentKit memory_storeSDKをOpenAIエージェントSDKのツールとしてラップしています。

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を認証済みエンドユーザーの身元に設定します。 各ユーザーは自分のパーティションを持ち、エージェントはそのユーザーのエントリだけを思い出します。
    • 例: サポート担当者は、あるユーザーのコミュニケーションの好みや過去のチケットを覚えています。
  • グループ共有メモリ:actor_idチーム、プロジェクト、組織IDなど、選択した固定キーに設定します。 みんな同じ記憶を読み書きします。
    • 例: チームエージェントは会社の用語や社内慣習の共通用語集を覚えています。
  • メモリを別のもので分割する場合:テナントIDやuser:project複合データなど、自分の値からactor_idを構築しましょう。
    • 例: マルチテナントアプリは actor_id を {tenant}:{user} に設定し、各顧客のユーザー同士を隔離します。

アプリケーションコード内で actor_id を設定してください。信頼された呼び出し元コンテキストから:ユーザー単位のメモリは検証済みエンドユーザーID、共有メモリは信頼できるチームまたはプロジェクトキーです。 モデルに決めさせてはいけません。 もし戦略がエンドユーザーのアイデンティティに依存している場合は、共有 actor_idに戻るのではなく、エンドユーザーのアイデンティティを含まないリクエストを拒否してください。

Warning

actor_id メモリを分離しますが、アクセス制御ではありません。 マネージドメモリストアはワークスペース単位でスコープ設定されているため、ストアにアクセスできるプリンシパルは、すべてのアクターにまたがるすべてのエントリを読み書きできます。 セキュリティ境界はアクターではなく、ストアです。 テナントやユーザー間の厳密な隔離のために、境界ごとに別々のメモリストアを作成します。

エージェントのサービスプリンシパルのような別のプリンシパルにストアを使わせるには、ストアの付与許可操作(AgentKit SDK内のmemory_store.grant_permission(principal_id) )でアクセス権を付与します。

Limitations

  • マネージドメモリは長期記憶のみを提供します。 短期的な会話履歴については、 マネージドエージェントセッションを参照してください。
  • 検索は関連性ランキング付きの全文(BM25)操作で、最大100エントリのトップNの結果セットを返します。 ページ化やベクトル類似性探索はサポートしていません。
  • 店舗レベルでアクセス制御が施行されます。 エントリごとおよびアクターごとのアクセス制御は利用できません。
  • ストア display_name は作成後は不変です。 更新できるのは description だけです。

次のステップ

  • 最終更新: