Diese Seite wurde von der Cloud Translation API übersetzt.

Kurzanleitung für die REST API

In dieser Anleitung wird gezeigt, wie Sie REST API-Aufrufe direkt an Vertex AI Agent Engine-Sitzungen und Memory Bank senden, um Sitzungen und Langzeitgedächtnisse zu erstellen und zu verwenden. Verwenden Sie die REST API, wenn Sie nicht möchten, dass ein Agent-Framework Aufrufe für Sie orchestriert, oder wenn Sie Sessions und Memory Bank 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:

Erstellen Sie Ihre Vertex AI Agent Engine-Instanz, um auf Vertex AI Agent Engine-Sitzungen und die Memory Bank zuzugreifen.
Sie haben folgende Möglichkeiten, Erinnerungen zu erstellen:
- Erinnerungen mit Vertex AI Agent Engine Memory Bank generieren: Sitzungen und Ereignisse in Vertex AI Agent Engine-Sitzungen als Quellen für Vertex AI Agent Engine Memory Bank schreiben, um Erinnerungen zu generieren.
- Erinnerungen direkt hochladen: Sie können Ihre eigenen Erinnerungen schreiben oder von Ihrem Agenten erstellen lassen, wenn Sie die volle Kontrolle darüber haben möchten, welche Informationen gespeichert werden.
Erinnerungen abrufen
Führen Sie eine Bereinigung durch.

Hinweise

Um die in dieser Anleitung beschriebenen Schritte auszuführen, müssen Sie zuerst Ihr Projekt und Ihre Umgebung einrichten.

Projekt einrichten

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

Wenn Sie ein Projekt ausgewählt haben, müssen Sie die IAM-Rolle Vertex AI-Nutzer (roles/aiplatform.user) für das Projekt haben.

Bei Vertex AI authentifizieren

Wenn Sie die Python Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, installieren und initialisieren Sie die gcloud CLI und richten dann die Standardanmeldedaten für Anwendungen mit Ihren Nutzeranmeldedaten ein.

Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Weitere Informationen finden Sie in der Dokumentation zur Google Cloud -Authentifizierung unter ADC für eine lokale Entwicklungsumgebung einrichten.

Bibliotheken importieren

Vertex AI SDK installieren:

pip install google-cloud-aiplatform>=1.100.0

Vertex AI Agent Engine-Instanz erstellen

Wenn Sie auf Vertex AI Agent Engine-Sitzungen und die Vertex AI Agent Engine Memory Bank zugreifen möchten, müssen Sie zuerst eine Vertex AI Agent Engine-Instanz erstellen. Sie müssen keinen Agent bereitstellen, um Sitzungen und Memory Bank zu verwenden. Ohne die Bereitstellung von Agents sollte die Erstellung einer Vertex AI Agent Engine-Instanz nur wenige Sekunden dauern.

import vertexai

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

agent_engine = client.agent_engines.create()

Ersetzen Sie Folgendes:

PROJECT_ID: Ihre Projekt-ID.
LOCATION: Ihre Region. Für die Memory Bank von Vertex AI Agent Engine wird nur us-central1 unterstützt.

Erinnerungen aus Vertex AI Agent Engine-Sitzungen generieren

Nachdem Sie Vertex AI Agent Engine-Sitzungen und 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 abrufen.

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.
```
from google.cloud import aiplatform_v1beta1

sessions_client = aiplatform_v1beta1.SessionServiceClient(
  client_options={
    "api_endpoint": "https://LOCATION-aiplatform.googleapis.com"
  },
  transport="rest"
)

session_lro = sessions_client.create_session(
  parent=AGENT_ENGINE_NAME,
  session={"user_id": "USER_ID"}
)
session_name = "/".join(session_lro.operation.name.split("/")[0:-2])
```
Ersetzen Sie Folgendes:
- LOCATION: Ihre Region. Für die Memory Bank von Vertex AI Agent Engine wird nur us-central1 unterstützt.
- 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.

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.

event = aiplatform_v1beta1.SessionEvent(
    author="user",  # Required by Sessions.
    invocation_id="1",  # Required by Sessions.
    timestamp=datetime.now().strftime('%Y-%m-%dT%H:%M:%SZ'),  # Required by Sessions.
    content = aiplatform_v1beta1.Content(
        role="user",
        parts=[aiplatform_v1beta1.Part(text="Hello")]
    )
)

sessions_client.append_event(name=session_name, event=event)

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": session_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 rohem Dialog können Sie Erinnerungen hochladen oder Ihre Agents direkt mit CreateMemory hinzufügen lassen. Bei Memory Bank werden die Informationen nicht aus Ihren Inhalten extrahiert, sondern Sie geben die Fakten, die über Ihren Nutzer gespeichert werden sollen, direkt an. Wir empfehlen, Fakten über Nutzer in der ersten Person zu formulieren (z. B. I am a software engineer).

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 ermöglichen.

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

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:

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)
```
Löschen Sie alle lokal erstellten Dateien.

Nächste Schritte

Kurzanleitung für das Agent Development Kit