Agent Platform SDK を使用して、Memory Bank に API を直接呼び出すことが可能です。エージェント フレームワークに呼び出しをオーケストレートさせたくない場合や、Agent Development Kit（ADK）以外のエージェント フレームワークを Memory Bank と統合する場合は、Agent Platform SDK を使用します。
このドキュメントでは、API 呼び出しを使用してメモリを作成、アップロード、取得、削除する方法について説明します。
ADK を使用したクイックスタートについては、ADK を使用した Memory Bank のクイックスタート をご覧ください。
始める前に
このチュートリアルで説明する手順を完了するには、まず Memory Bank の設定の手順に沿って操作する必要があります。このクイックスタートを開始する前に、次の例に示すように、Memory Bank インスタンスと Sessions インスタンスを作成していることを確認してください。
import vertexai
client = vertexai.Client(
project="PROJECT_ID",
location="LOCATION"
)
memory_bank = client.agent_engines.create()
sessions = client.agent_engines.create()
Agent Platform Sessions でメモリを生成する
Agent Platform Sessions を設定したら、セッションを作成してイベントを追加できます。次に、Memory Bank を使用して、ユーザーとエージェントの会話からメモリを生成し、今後のユーザー インタラクションで使用できるようにします。詳細については、 メモリを生成する とメモリを取得するをご覧ください。
を使用して、GenerateMemories ペイロードで会話履歴を直接指定することもできます。
不透明なユーザー ID を使用してセッションを作成します。この セッションから生成されたメモリは、メモリの生成時にスコープ を明示的に指定しない限り、スコープ
{"user_id": "USER_ID"}によって自動的にキー設定されます。import vertexai client = vertexai.Client( project="PROJECT_ID", location="LOCATION" ) session = client.agent_engines.sessions.create( # The name can be fetched using `sessions.api_resource.name`. name="SESSIONS_NAME", user_id="USER_ID" )次のように置き換えます。
PROJECT_ID: プロジェクト ID。
LOCATION: リージョン。Memory Bank のサポートされている リージョンをご覧ください。
SESSIONS_NAME: 作成した Sessions インスタンスの名前、または既存の Sessions インスタンス。名前は 次の形式にする必要があります:
projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.USER_ID: ユーザーの識別子。このセッションから生成されたメモリは、メモリの生成時にスコープを明示的に指定しない限り、スコープ
{"user_id": "USER_ID"}によって自動的にキー設定されます。
イベントをセッションに繰り返しアップロードします。イベントには、ユーザー、エージェント、ツール間のあらゆるやり取りを含めることができます。イベントの順序付きリストは、セッションの会話履歴を表します。この会話履歴は、特定のユーザーのメモリを生成するためのソース資料として使用されます。
import datetime client.agent_engines.sessions.events.append( name=session.response.name, author="user", # Required by Sessions. invocation_id="1", # Required by Sessions. timestamp=datetime.datetime.now(tz=datetime.timezone.utc), # Required by Sessions. config={ "content": { "role": "user", "parts": [{"text": "hello"}] } } )会話履歴からメモリを生成するには、セッションのメモリ生成リクエストをトリガーします。
client.agent_engines.memories.generate( name=memory_bank.api_resource.name, vertex_session_source={ # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...". "session": session.response.name }, # Optional when using Sessions. Defaults to {"user_id": session.user_id}. scope=SCOPE )
次のように置き換えます。
- （省略可）SCOPE: 生成されたメモリのスコープを表す辞書。最大 5 つの Key-Value ペアを指定でき、
*文字は使用できません。例:{"session_id": "MY_SESSION"}。統合の対象となるのは、同じスコープのメモリのみです。指定しない場合は、{"user_id": session.user_id}が使用されます。
メモリをアップロードする
生の会話を使用してメモリを生成する代わりに、メモリのアップロードや、
エージェントにGenerateMemoriesと事前に抽出された
ファクトを使用して直接追加させることできます。Memory Bank
はコンテンツから情報を抽出するのではなく、ユーザーについて保存すべき事実を直接提供します。
生成されたメモリとの整合性を確保するため、特定のスコープ用に構成した
のと同じ視点で、事前に抽出したファクトを記述してください。デフォルトでは、メモリは一人称視点で生成されます（例: I
am a software engineer）。
client.agent_engines.memories.generate(
name=memory_bank.api_resource.name,
direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
scope=SCOPE
)
次のように置き換えます。
FACT: 既存のメモリと統合する必要がある 事前抽出された事実。次のようなリストで、最大 5 個の事前抽出された事実を指定できます。
{"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}SCOPE: 生成されたメモリのスコープを表す辞書。例:
{"session_id": "MY_SESSION"}。統合の対象となるのは、同じスコープのメモリのみです。
または、CreateMemory を使用して、メモリの抽出や統合に Memory Bank を使用せずにメモリをアップロードすることもできます。
memory = client.agent_engines.memories.create(
name=memory_bank.api_resource.name,
fact="This is a fact.",
scope={"user_id": "123"}
)
"""
Returns an AgentEngineMemoryOperation containing the created Memory like:
AgentEngineMemoryOperation(
done=True,
metadata={
"@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
"genericMetadata": {
"createTime": '2025-06-26T01:15:29.027360Z',
"updateTime": '2025-06-26T01:15:29.027360Z'
}
},
name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
response=Memory(
create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
fact="This is a fact.",
name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
scope={
"user_id": "123"
},
update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
)
)
"""
メモリを取得して使用する
ユーザーのメモリを取得してシステム指示に含め、LLM にパーソナライズされたコンテキストへのアクセス権を付与できます。
スコープベースのメソッドを使用してメモリを取得する方法について詳しくは、 メモリを取得するをご覧ください。
# Retrieve all memories for User ID 123.
retrieved_memories = list(
client.agent_engines.memories.retrieve(
name=memory_bank.api_resource.name,
scope={"user_id": "123"}
)
)
jinja を使用して、構造化されたメモリをプロンプトに変換できます。
from jinja2 import Template
template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")
prompt = template.render(data=retrieved_memories)
"""
Output:
<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""
メモリを削除する
削除するメモリの選択方法に応じて、Memory Bank インスタンスからメモリを削除する方法は複数あります。
リソース名で削除する
削除するメモリリソースがわかっている場合は、リソース名を使用して特定のメモリを削除できます。
client.agent_engines.memories.delete(
name=MEMORY_NAME,
config={
# Set to false (default) if you want to delete the memory asynchronously.
"wait_for_completion": True
}
)
次のように置き換えます。
- MEMORY_NAME: 削除するメモリの名前。名前は
次の形式にする必要があります。
projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}。 メモリ名を確認するには、メモリを取得します 。
条件で削除する
条件ベースの削除を使用して、1 つ以上のメモリを削除できます。指定したフィルタに一致するメモリのみが削除されます。
`filter`（システム フィールドに適用）または filter（
メタデータ フィールドに適用）のいずれかを 1 つ以上指定する必要があります。filter_groups
operation = client.agent_engines.memories.purge(
name=memory_bank.api_resource.name,
# Specify at least one of `filter` or `filter_groups`.
filter="FILTER_STRING",
filter_groups=FILTER_GROUPS,
# Set to false (default) if you want to stage but not execute the purge operation.
force=True,
config={
# Set to false (default) if you want to purge memories asynchronously.
"wait_for_completion": True
}
)
次のように置き換えます。
- FILTER_STRING: システム フィールドに対して
フィルタリングするための
EBNF 構文を使用する文字列。システム フィールドには、
create_time、 、fact、およびtopicsがあります。update_timeシステム フィールドに対するフィルタリングの詳細については、メモリを取得するページのメタデータ フィールドで フィルタ するをご覧ください。 - FILTER_GROUPS: メモリ メタデータに対してフィルタリングするための辞書またはオブジェクトのリスト。メタデータ フィールドに対するフィルタリングの詳細については、メモリを取得するページのシステム フィールドでフィルタするをご覧ください。
このオペレーションは、削除されたメモリの数（force=True の場合）またはオペレーションが実行された場合に削除されるメモリの数（force=False の場合）を返します。
print(operation.response.purge_count)
たとえば、user_id「123」のスコープに属するすべてのメモリを削除できます。
operation = client.agent_engines.memories.purge(
name=memory_bank.api_resource.name,
filter="scope.user_id=\"123\""
force=True
)
セマンティックな意味で削除する
メモリの生成時に、
Memory Bank は、作成、更新、削除するかどうかを決定します
新しく抽出された情報の内容と
既存のメモリに基づいて、メモリを。新しい情報が矛盾する場合や、抽出されたコンテンツで Memory Bank にトピックを忘れるように指示した場合（EXPLICIT_INSTRUCTIONSメモリ
トピックの場合）は、メモリが削除されることがあります。
たとえば、次のリクエストは、指定された scope に存在する場合、食事の好みに関する情報を含む既存のメモリを削除します。
from google import genai
client.agent_engines.memories.generate(
name=memory_bank.api_resource.name,
direct_contents_source={
"events": [{
"content": genai.types.Content(
role="user",
parts=[
genai.types.Part.from_text(text="Forget my dietary preferences.")
]
)
}]
},
scope={...}
)
クリーンアップ
このプロジェクトで使用しているすべてのリソースをクリーンアップするには、クイックスタートで使用したプロジェクト Google Cloud を削除します 。
それ以外の場合は、このチュートリアルで作成した個々のリソースを次のように削除できます。
次のコードサンプルを使用して Agent Platform インスタンスを削除します。これにより、Agent Platform インスタンスに関連付けられているセッションやメモリも削除されます。
agent_engine.delete(force=True)ローカルで作成したファイルを削除します。