このページは Cloud Translation API によって翻訳されました。

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 セッションでメモリを生成する

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

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

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

session = client.agent_engines.create_session(
  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.append_session_event(
  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.generate_memories(
  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.generate_memories(
    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.create_memory(
    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.retrieve_memories(
        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>
"""

メモリーを削除する

特定メモリは、リソース名を使用して削除できます。

client.agent_engines.delete_memory(name=MEMORY_NAME)

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

MEMORY_NAME: 削除する Memory の名前。名前は projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory} の形式にする必要があります。メモリ名は、メモリを取得することで確認できます。

クリーンアップ

このプロジェクトで使用しているすべてのリソースをクリーンアップするには、クイックスタートで使用した Google Cloud プロジェクトを削除します。

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

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

次のステップ

エージェント開発キットのクイックスタート。

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

始める前に

Vertex AI Agent Engine セッションでメモリを生成する

思い出をアップロードする

思い出を取得して使用する

メモリーを削除する

クリーンアップ

次のステップ

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