Vertex AI Agent Engine SDK のクイックスタート

このチュートリアルでは、Vertex AI Agent Engine SDK を使用して Vertex AI Agent Engine Sessions と Memory Bank に API 呼び出しを直接行う方法について説明します。エージェントフレームワークに呼び出しをオーケストレートさせたくない場合や、Agent Development Kit（ADK）以外のエージェントフレームワークを Sessions および Memory Bank と統合する場合は、Vertex AI Agent Engine SDK を使用します。

ADK を使用したクイックスタートについては、Agent Development Kit を使用したクイックスタートをご覧ください。

このチュートリアルでは、次の手順を使用します。

次のオプションを使用してメモリを作成します。
- Vertex AI Agent Engine Memory Bank を使用してメモリを生成する: Vertex AI Agent Engine Memory Bank のソースとして、Vertex AI Agent Engine Sessions にセッションとイベントを書き込み、メモリを生成します。
- メモリを直接アップロードする: 保持する情報を完全に制御したい場合は、自分でメモリを作成するか、エージェントにメモリを作成してもらいます。
メモリを取得する。
クリーンアップします。

始める前に

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

Vertex AI Agent Engine Sessions でメモリを生成する

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

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

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

# This assumes that you already have an Agent Engine 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: 作成した Vertex AI Agent Engine インスタンスの名前、または既存の Vertex AI Agent Engine インスタンスの名前。名前は 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 Agent Engine 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=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 Bank を使用せずにメモリをアップロードすることもできます。

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 つ以上の思い出を削除できます。指定されたフィルタに一致するメモリのみが削除されます。

operation = client.agent_engines.memories.purge(
    name=agent_engine.api_resource.name,
    filter=FILTER_STRING,
    # 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、update_time、fact、topics があります。システムフィールドに対するフィルタリングについて詳しくは、こちらのドキュメントをご覧ください。

このオペレーションは、パージされたメモリの数（force=True の場合）またはオペレーションが実行された場合にパージされるメモリの数（force=False の場合）を返します。

print(operation.response.purge_count)

意味に基づいて削除する

メモリの生成中、Memory Bank は、新しく抽出された情報の内容と既存のメモリに基づいて、メモリを作成、更新、削除するかどうかを決定します。新しい情報が矛盾している場合や、抽出されたコンテンツで Memory Bank に対象を忘れるよう指示されている場合（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 プロジェクトを削除します。

それ以外の場合は、このチュートリアルで作成した個々のリソースを次のように削除できます。

次のコードサンプルを使用して Vertex AI Agent Engine インスタンスを削除します。これにより、Vertex AI Agent Engine インスタンスに関連付けられているセッションやメモリも削除されます。
```
agent_engine.delete(force=True)
```
ローカルで作成したファイルを削除します。

次のステップ

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

Vertex AI Agent Engine SDK のクイックスタート コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

Vertex AI Agent Engine Sessions でメモリを生成する

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

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

思い出を削除する

リソース名で削除する

条件で削除する

意味に基づいて削除する

クリーンアップ

次のステップ

Vertex AI Agent Engine SDK のクイックスタート