Agent Platform メモリバンク API のクイックスタート

Agent Platform メモリバンクを使用すると、Agent Platform SDK を使用して Sessions とメモリバンクに API 呼び出しを直接行うことができます。エージェントフレームワークに呼び出しをオーケストレートさせたくない場合や、Agent Development Kit（ADK）以外のエージェントフレームワークを Sessions および Memory Bank と統合する場合は、Agent Platform SDK を使用します。

このドキュメントでは、API 呼び出しを使用してメモリを作成、アップロード、取得、削除する方法について説明します。

ADK を使用したクイックスタートについては、ADK を使用したメモリバンクのクイックスタートをご覧ください。

始める前に

このチュートリアルで説明する手順を完了するには、まずメモリバンクの設定の手順に沿って操作する必要があります。

Agent Platform Sessions でメモリを生成する

Agent Platform Sessions とメモリバンクを設定したら、セッションを作成してイベントを追加できます。メモリは、ユーザーとエージェントの会話から事実として生成され、今後のユーザーインタラクションで使用できるようになります。詳細については、メモリを生成するとメモリを取得するをご覧ください。

注: 直接コンテンツソースを使用して、 GenerateMemories ペイロードで会話履歴を直接指定することもできます。

不透明なユーザー ID を使用してセッションを作成します。このセッションから生成されたメモリは、メモリの生成時にスコープを明示的に指定しない限り、スコープ {"user_id": "USER_ID"} によって自動的にキー設定されます。
```
import vertexai

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

# This assumes that you already have an Agent Platform instance. If you don't,
# you can create one using `agent_engine = client.agent_engines.create()`.
session = client.agent_engines.sessions.create(
# The name can be fetched using `agent_engine.api_resource.name`.
name="AGENT_ENGINE_NAME",
user_id="USER_ID"
)
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- LOCATION: リージョン。Memory Bank のサポートされているリージョンをご覧ください。
- AGENT_ENGINE_NAME：作成した Agent Platform インスタンスの名前、または既存の Agent Platform インスタンスの名前。名前は次の形式にする必要があります: 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=agent_engine.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と事前に抽出されたファクトを使用して直接追加させることできます。メモリバンクはコンテンツから情報を抽出するのではなく、ユーザーについて保存すべき事実を直接提供します。

生成されたメモリとの整合性を確保するため、特定のスコープに構成したのと同じ視点で、事前に抽出したファクトを記述してください。デフォルトでは、メモリは一人称視点（例: I am a software engineer）で生成されます。

client.agent_engines.memories.generate(
    name=agent_engine.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 = client.agent_engines.memories.create(
    name=agent_engine.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=agent_engine.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=agent_engine.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=agent_engine.api_resource.name,
    filter="scope.user_id=\"123\""
    force=True
)

セマンティックな意味で削除する

メモリーの生成時に、メモリバンクは、新しく抽出された情報の内容と既存のメモリーに基づいて、メモリーを作成、更新、または削除するかどうかを決定します。新しい情報が矛盾する場合や、抽出されたコンテンツがメモリバンクにトピックを忘れるように指示する場合（EXPLICIT_INSTRUCTIONS メモリトピックの場合）は、メモリが削除されることがあります。

たとえば、次のリクエストは、指定された scope に存在する場合、食事の好みに関する情報を含む既存のメモリを削除します。

from google import genai

client.agent_engines.memories.generate(
    name=agent_engine.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)
```
ローカルで作成したファイルを削除します。

次のステップ

クイックスタート

Agent Development Kit のクイックスタート

Agent Development Kit（ADK）を使ってみる。

Agent Platform メモリバンク API のクイックスタート コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

Agent Platform Sessions でメモリを生成する

メモリをアップロードする

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

メモリを削除する

リソース名で削除する

条件で削除する

セマンティックな意味で削除する

クリーンアップ

次のステップ

Agent Development Kit のクイックスタート

Agent Platform メモリバンク API のクイックスタート