ADK で Memory Bank を使用する

Agent Development Kit(ADK)は、ADK BaseMemoryService インターフェースの実装である VertexAiMemoryBankService を介して、エージェントを Agent Platform メモリーバンクに接続します。このドキュメントでは、メモリ コールバックとメモリ取得ツールを選択する方法と、各 ADK ランタイムでメモリサービスを接続する方法について説明します。

まず実証済みの例を実行するには、ADK を使用したメモリーバンクのクイックスタートをご覧ください。

始める前に

  1. Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  7. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  10. ローカルシェルを使用している場合は、ユーザー アカウントのローカル認証情報を作成します。

    gcloud auth application-default login

    Cloud Shell を使用している場合は、この操作を行う必要はありません。

    認証エラーが返され、外部 ID プロバイダ(IdP)を使用している場合は、フェデレーション ID を使用して gcloud CLI にログインしていることを確認します。

  11. ADK と Agent Platform SDK をインストールします。
    pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
  12. Google Cloud コンソールまたは Agent Platform SDK で Memory Bank インスタンスを作成します。[Memory Bank] ページで、[エージェントにリンク] > [ADK で使用] をクリックして、事前入力されたセットアップ コードを取得します。Agent Runtime がインスタンスを作成する場合は、この手順をスキップします。

必要なロール

Memory Bank インスタンスの作成、メモリの生成と取得に必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

  • メモリーバンク インスタンスを作成または更新する: Agent Platform ユーザー(`roles/aiplatform.user`)
  • 記憶の読み取り、書き込み、生成: メモリーバンク ユーザー(`roles/aiplatform.memoryUser`)

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

ADK コンポーネントと Memory Bank の連携

ADK エージェントは、次のコンポーネントを使用してメモリの読み取りと書き込みを行います。

コンポーネント ロール 必須
Memory Bank インスタンス 記憶を保存して統合する。 ○
VertexAiMemoryBankService エージェントを ADK メモリサービスとして Memory Bank に接続します。 ○
セッション サービス 会話履歴を保存します。任意の ADK セッション サービスを使用できます。 ○
メモリ取得ツール エージェントのメモリを取得します。ツールを使用してメモリを取得するをご覧ください。 思い出を読み取る
メモリ生成コールバック エージェントが応答した後に、会話イベントを Memory Bank に送信します。コールバックを使用してメモリを生成するをご覧ください。 思い出を書き留める
ADK Runner または AdkApp エージェント、サービス、ツール、コールバックをオーケストレートします。 ○

次の図は、エージェントが PreloadMemoryTool とメモリ コールバックを使用するときに、これらのコンポーネントが各ターンでどのように相互作用するかを示しています。

Memory Bank は、エージェントを実行するユーザー ID とアプリ名に各メモリのスコープを設定します({"user_id": USER_ID, "app_name": APP_NAME})。同じユーザー ID とアプリ名を持つリクエストのみが、これらのメモリを取得します。

コールバックを使用してメモリを生成する

メモリ生成コールバックは、会話イベントを Memory Bank に送信します。Memory Bank は、これらのイベントからメモリーを抽出し、既存のメモリーと統合します。イベントを処理する頻度に基づいて方法を選択します。

メソッド 送信済みイベント 使用する状況
callback_context.add_events_to_memory 選択したイベントのサブセット 使用をおすすめします。イベントを段階的に処理する(各ターンの後など)。
callback_context.add_session_to_memory セッション内のすべてのイベント 同じイベントが複数回処理されないように、セッションの終了時に 1 回呼び出します。

次の例では、各エージェントのレスポンスの後に最近のイベントを送信します。

from google.adk.agents.callback_context import CallbackContext


async def generate_memories_callback(
    callback_context: CallbackContext,
) -> None:
    await callback_context.add_events_to_memory(
        events=callback_context.session.events[-5:]
    )
    return None

代わりにセッション全体を送信するには、セッションの終了時にコールバックで await callback_context.add_session_to_memory() を呼び出します。

デフォルトでは、VertexAiMemoryBankService はイベント取り込みを使用してイベントを送信します。テストまたはデモでメモリ生成が完了するまで待機するには、custom_metadata={"wait_for_completion": True} を add_events_to_memory に渡します。

ツールを使用してメモリを取得する

メモリ取得ツールは、エージェントがメモリを取得するタイミングと、メモリがプロンプトに入力される方法を制御します。次のいずれかのツールを選択します。

ツール メモリが取得されるタイミング 使用する状況
PreloadMemoryTool 各ターンの開始時。メモリーは、現在のユーザーのターンの前にモデル リクエスト コンテキストに挿入されます。 すべてのターンでユーザーに関するベースライン コンテキストを確立する。
LoadMemoryTool モデルがクエリに回答するためにメモリが必要であると判断した場合。 メモリが関連するタイミングをモデルに判断させます。
カスタムの FunctionTool モデルがツールの説明に沿ってツールを呼び出すとき。 思い出を取得するタイミングについてエージェントに指示します。

次の例では、PreloadMemoryTool と前のセクションのコールバックを使用するエージェントを作成します。

from google import adk
from google.adk.tools.preload_memory_tool import PreloadMemoryTool

agent = adk.Agent(
    model="gemini-3.5-flash",
    name="stateful_agent",
    instruction="You are a vehicle voice agent. Limit responses to 30 words.",
    tools=[PreloadMemoryTool()],
    after_agent_callback=generate_memories_callback,
)

モデルがメモリを取得するタイミングを決定できるようにするには、google.adk.tools.load_memory_tool から LoadMemoryTool をインポートし、tools で LoadMemoryTool() を渡します。

カスタム取得ツールを作成するには、関数ツールから tool_context.search_memory を呼び出します。

from typing import Any

from google import adk
from google.adk.tools import FunctionTool, ToolContext


async def search_memories(query: str, tool_context: ToolContext) -> Any:
    """Query this tool when you need information about user preferences."""
    return await tool_context.search_memory(query)


agent = adk.Agent(
    model="gemini-3.5-flash",
    name="stateful_agent",
    instruction=(
        "You are a vehicle voice agent. Before you change a setting, call "
        "search_memories to look up the user's preferences. Limit responses "
        "to 30 words."
    ),
    tools=[FunctionTool(func=search_memories)],
    after_agent_callback=generate_memories_callback,
)

メモリサービスをランタイムに接続する

VertexAiMemoryBankService の接続方法は、エージェントの実行場所によって異なります。ランタイムを選択します。

ローカル ランナー

adk.Runner でエージェントを実行する場合は、メモリサービスを作成してランナーに渡します。

import asyncio
import os

from google import adk
from google.adk.memory import VertexAiMemoryBankService
from google.adk.sessions import InMemorySessionService
from google.genai import types

os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id="MEMORY_BANK_ID",
)

# You can use any ADK session service. This example keeps sessions in memory.
# To persist conversation history, use VertexAiSessionService with a
# Sessions instance instead.
session_service = InMemorySessionService()

runner = adk.Runner(
    agent=agent,
    app_name="APP_NAME",
    session_service=session_service,
    memory_service=memory_service,
)

async def main() -> None:
    session = await session_service.create_session(
        app_name="APP_NAME",
        user_id="USER_ID",
    )
    message = types.Content(
        role="user", parts=[types.Part(text="Can you fix the temperature?")]
    )
    async for event in runner.run_async(
        user_id="USER_ID",
        session_id=session.id,
        new_message=message,
    ):
        if event.is_final_response() and event.content:
            print(event.content.parts[0].text)

asyncio.run(main())

次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID(例: my-project)。
  • LOCATION: ロケーション(例: global)。Memory Bank のサポートされているロケーションとグローバル エンドポイントとマルチリージョン エンドポイントをご覧ください。
  • MEMORY_BANK_ID: Memory Bank インスタンス ID。例: projects/my-project/locations/us-central1/reasoningEngines/456 の 456。
  • APP_NAME: ADK アプリの名前(例: my_agent)。Memory Bank は、メモリー スコープにアプリ名を含めるため、メモリーはアプリ間で分離されます。
  • USER_ID: ユーザーの識別子(例: user-123)。このセッションから生成されたメモリは、この識別子にスコープされます。

Gemini Enterprise Agent Platform の Agent Runtime

ADK テンプレート(AdkApp)を使用して ADK エージェントを Agent Runtime にデプロイすると、テンプレートはデフォルトで VertexAiMemoryBankService を使用します。Memory Bank インスタンスを作成し、エージェントを 1 つのステップでデプロイできます。

import asyncio

import agentplatform
from agentplatform.frameworks import AdkApp

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
)

adk_app = AdkApp(agent=agent)

# Create a resource with your agent deployed to Agent Runtime. The
# resource also includes an empty Memory Bank instance.
runtime_instance = client.runtimes.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

async def main() -> None:
    session = await runtime_instance.async_create_session(
        user_id="USER_ID"
    )
    async for event in runtime_instance.async_stream_query(
        user_id="USER_ID",
        session_id=session.get("id"),
        message="Can you fix the temperature?",
    ):
        print(event)

asyncio.run(main())

エージェントを既存のリソースにデプロイし、リソースの既存のメモリを保持するには、代わりに client.runtimes.update を呼び出します。

runtime_instance = client.runtimes.update(
    name="RUNTIME_NAME",
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

AdkApp をローカルで実行すると、デフォルトで InMemoryMemoryService が使用されます。Memory Bank をローカルで使用するには、メモリサービスをオーバーライドします。

from google.adk.memory import VertexAiMemoryBankService

def memory_bank_service_builder() -> VertexAiMemoryBankService:
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="MEMORY_BANK_ID",
    )

adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder,
)

次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID(例: my-project)。
  • LOCATION: Agent Runtime のリージョンまたはマルチリージョン(例: us-central1)。スタンドアロン VertexAiMemoryBankService インスタンスのみが global をサポートし、client.runtimes.create はサポートしません。サポートされているロケーションをご覧ください。
  • STAGING_BUCKET: Agent Runtime のステージングに使用する Cloud Storage バケットの URI(例: gs://my-staging-bucket)。
  • USER_ID: ユーザーの識別子(例: user-123)。
  • RUNTIME_NAME: 既存の Agent Runtime のリソース名(projects/.../locations/.../reasoningEngines/... 形式)。
  • MEMORY_BANK_ID: Memory Bank インスタンス ID。例: projects/my-project/locations/us-central1/reasoningEngines/456 の 456。

Cloud Run

エージェントを Cloud Run にデプロイするには、ADK のドキュメントに沿って、Memory Bank インスタンスをメモリサービスとして渡します。

adk deploy cloud_run \
    ...
    --memory_service_uri=agentengine://MEMORY_BANK_ID

MEMORY_BANK_ID は、Memory Bank インスタンス ID(456 など)に置き換えます。デプロイされたエージェントをテストするには、ADK Cloud Run のデプロイに関するドキュメントをご覧ください。

Google Kubernetes Engine(GKE)

エージェントを GKE にデプロイするには、ADK のドキュメントに沿って、メモリーバンク インスタンスをメモリサービスとして渡します。

adk deploy gke \
    ...
    --memory_service_uri=agentengine://MEMORY_BANK_ID

MEMORY_BANK_ID は、Memory Bank インスタンス ID(456 など)に置き換えます。デプロイされたエージェントをテストするには、ADK GKE デプロイ ドキュメントのエージェントをテストするセクションをご覧ください。

ADK ウェブ

ADK Web は、開発中にエージェントをテストして検査するためのローカル ブラウザ インターフェースです。

ADK Web は、環境変数からプロジェクトとロケーションを読み取ります。エージェント フォルダを含むディレクトリから、ターミナルで次のコマンドを実行します。

export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
adk web --memory_service_uri=agentengine://MEMORY_BANK_ID

次のように置き換えます。

次に、ブラウザで http://localhost:8000 を開きます。デフォルトでは、ADK Web はユーザー ID を user に設定します。別のユーザー ID を使用するには、userId クエリ パラメータ(http://localhost:8000?userId=USER_ID など)を追加します。

リージョン ランタイムでマルチリージョン Memory Bank を使用する

デフォルトでは、組み込みの Memory Bank で Runtime を使用すると、エージェントと Memory Bank は同じリージョンにデプロイされます。リージョン デプロイ全体で 1 つの中央 Memory Bank を維持するには、マルチリージョン Memory Bank(us など)とリージョン ランタイム(us-central1 など)をペアに設定します。

マルチリージョン Memory Bank を使用するには、デフォルトの ADK メモリサービス ビルダーをオーバーライドして、マルチリージョン ロケーションとインスタンス ID を参照するようにします。

import agentplatform
from agentplatform.frameworks import AdkApp
from google.adk.memory import VertexAiMemoryBankService

# Create the Memory Bank instance in a multi-region location.
client_mb = agentplatform.Client(
    project="PROJECT_ID",
    location="us",
)
memory_bank = client_mb.memory_banks.create()
memory_bank_id = memory_bank.name.split("/")[-1]


# Point the memory service to the multi-regional instance.
def memory_bank_service_builder() -> VertexAiMemoryBankService:
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="us",
        agent_engine_id=memory_bank_id,
    )


adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder,
)

# Deploy the runtime to a specific region.
client_runtime = agentplatform.Client(
    project="PROJECT_ID",
    location="us-central1",
)
runtime_instance = client_runtime.runtimes.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID(例: my-project)。
  • STAGING_BUCKET: Agent Runtime のステージングに使用する Cloud Storage バケットの URI(例: gs://my-staging-bucket)。

これらのリソースを削除するには、ランタイムとマルチリージョン インスタンスを削除します。会話の直後にインスタンスを削除すると、メモリ生成が完了するまでリクエストが FAILED_PRECONDITION エラーで失敗することがあります。その場合は、1 分ほど待ってから削除を再度実行してください。

client_runtime.runtimes.delete(
    name=runtime_instance.api_resource.name,
    force=True,
)
client_mb.memory_banks.delete(name=memory_bank.name, force=True)

次のステップ

クイックスタート

ユーザー設定を記憶する ADK エージェントを構築します。

ガイド

Memory Bank でメモリを生成する方法について説明します。

ガイド

メモリーバンクの設定方法をご確認ください。