Kurzanleitung für das Vertex AI Agent Engine SDK

In dieser Anleitung wird gezeigt, wie Sie mit dem Vertex AI Agent Engine SDK API-Aufrufe direkt an Vertex AI Agent Engine-Sitzungen und Memory Bank senden. Verwenden Sie das Vertex AI Agent Engine SDK, wenn Sie kein Agent-Framework zum Orchestrieren von Aufrufen benötigen oder wenn Sie Sitzungen und die Speicherbank in andere Agent-Frameworks als das Agent Development Kit (ADK) einbinden möchten.

Eine Kurzanleitung zur Verwendung des ADK finden Sie unter Kurzanleitung für das Agent Development Kit.

In dieser Anleitung werden die folgenden Schritte ausgeführt:

  1. Sie haben folgende Möglichkeiten, Erinnerungen zu erstellen:
  2. Erinnerungen abrufen
  3. Führen Sie eine Bereinigung durch.

Hinweise

Um die Schritte in dieser Anleitung auszuführen, müssen Sie zuerst die Schritte unter Für Memory Bank einrichten ausführen.

Erinnerungen mit Vertex AI Agent Engine-Sitzungen generieren

Nachdem Sie Vertex AI Agent Engine-Sitzungen und die Memory Bank eingerichtet haben, können Sie Sitzungen erstellen und Ereignisse daran anhängen. Erinnerungen werden als Fakten aus der Unterhaltung des Nutzers mit dem Agent generiert, damit sie für zukünftige Nutzerinteraktionen verfügbar sind. Weitere Informationen finden Sie unter Erinnerungen generieren und Erinnerungen abrufen.

  1. Erstellen Sie eine Sitzung mit einer undurchsichtigen User-ID. Alle Erinnerungen, die aus dieser Sitzung generiert werden, werden automatisch mit dem Bereich {"user_id": "USER_ID"} verschlüsselt, sofern Sie beim Generieren von Erinnerungen nicht explizit einen Bereich angeben.

    import vertexai

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

session = client.agent_engines.create_session(
  name=AGENT_ENGINE_NAME,
  user_id="USER_ID"
)

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Ihre Projekt-ID.

    • LOCATION: Ihre Region. Unterstützte Regionen für Memory Bank

    • AGENT_ENGINE_NAME: Der Name der von Ihnen erstellten Vertex AI Agent Engine-Instanz oder einer vorhandenen Vertex AI Agent Engine-Instanz. Der Name muss das Format projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine} haben.

    • USER_ID: Eine Kennung für Ihren Nutzer. Alle Erinnerungen, die aus dieser Sitzung generiert werden, werden automatisch mit dem Bereich {"user_id": "USER_ID"} verschlüsselt, sofern Sie beim Generieren von Erinnerungen nicht explizit einen Bereich angeben.

  2. Laden Sie Ereignisse iterativ in Ihre Sitzung hoch. Ereignisse können alle Interaktionen zwischen Ihrem Nutzer, dem Agent und den Tools umfassen. Die geordnete Liste der Ereignisse stellt den Unterhaltungsverlauf Ihrer Sitzung dar. Dieser Chatverlauf wird als Quellmaterial für die Generierung von Erinnerungen für den jeweiligen Nutzer verwendet.

    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"}]
    }
  }
)

  3. Wenn Sie Erinnerungen aus Ihrem Unterhaltungsverlauf generieren möchten, lösen Sie eine Anfrage zur Erinnerungsgenerierung für die Sitzung aus:

    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
)

Ersetzen Sie Folgendes:

  • (Optional) SCOPE: Ein Dictionary, das den Umfang der generierten Erinnerungen darstellt. Es enthält maximal 5 Schlüssel/Wert-Paare und keine *-Zeichen. Beispiel: {"session_id": "MY_SESSION"} Für die Konsolidierung werden nur Erinnerungen mit demselben Umfang berücksichtigt. Wenn nicht angegeben, wird {"user_id": session.user_id} verwendet.

Erinnerungen hochladen

Als Alternative zum Generieren von Erinnerungen mit Rohdialogen können Sie Erinnerungen hochladen oder Ihre Agents sie direkt mit GenerateMemories mit vorab extrahierten Fakten hinzufügen lassen. Anstatt dass Memory Bank Informationen aus Ihren Inhalten extrahiert, stellen Sie die Fakten, die über Ihren Nutzer gespeichert werden sollen, direkt bereit. Wir empfehlen, Fakten über Nutzer in der ersten Person zu formulieren (z. B. 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
)

Ersetzen Sie Folgendes:

  • FACT: Die vorab extrahierte Information, die mit vorhandenen Erinnerungen zusammengeführt werden soll. Sie können bis zu fünf vorab extrahierte Fakten in einer Liste wie der folgenden angeben:

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}

  • SCOPE: Ein Dictionary, das den Umfang der generierten Erinnerungen darstellt. Beispiel: {"session_id": "MY_SESSION"}. Für die Konsolidierung werden nur Erinnerungen mit demselben Umfang berücksichtigt.

Alternativ können Sie CreateMemory verwenden, um Erinnerungen hochzuladen, ohne Memory Bank für die Extraktion oder Konsolidierung von Erinnerungen zu nutzen.

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))
  )
)
"""

Erinnerungen abrufen und verwenden

Sie können Erinnerungen für Ihren Nutzer abrufen und in Ihre Systemanweisungen einfügen, um dem LLM Zugriff auf Ihren personalisierten Kontext zu gewähren.

Weitere Informationen zum Abrufen von Erinnerungen mit einer bereichsbasierten Methode finden Sie unter Erinnerungen abrufen.

# 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"}
    )
)

Mit jinja können Sie Ihre strukturierten Erinnerungen in einen Prompt umwandeln:


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>
"""

Erinnerungen löschen

Sie können ein bestimmtes Erinnerungsbild anhand seines Ressourcennamens löschen:

client.agent_engines.delete_memory(name=MEMORY_NAME)

Ersetzen Sie Folgendes:

  • MEMORY_NAME: Der Name des zu löschenden Memes. Der Name muss das Format projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory} haben. Sie können den Namen der Erinnerung abrufen.

Bereinigen

Wenn Sie alle in diesem Projekt verwendeten Ressourcen bereinigen möchten, können Sie das Google Cloud -Projekt löschen, das Sie für den Schnellstart verwendet haben.

Andernfalls können Sie die einzelnen Ressourcen löschen, die Sie in dieser Anleitung erstellt haben:

  1. Verwenden Sie das folgende Codebeispiel, um die Vertex AI Agent Engine-Instanz zu löschen. Dadurch werden auch alle Sitzungen oder Erinnerungen gelöscht, die mit der Vertex AI Agent Engine-Instanz verknüpft sind.

    agent_engine.delete(force=True)

  2. Löschen Sie alle lokal erstellten Dateien.

Nächste Schritte