Umgebung für Memory Bank einrichten

Bevor Sie mit der Speicherbank der Vertex AI Agent Engine arbeiten, müssen Sie Ihre Umgebung einrichten. Memory Bank ist zwar Teil von Agent Engine, Sie müssen Ihren Code aber nicht in der Agent Engine-Laufzeitumgebung bereitstellen, um Memory Bank zu verwenden.

Ihr Google Cloud -Projekt einrichten

Jedes Projekt kann auf zwei Arten identifiziert werden: über die Projektnummer oder die Projekt-ID. Die PROJECT_NUMBER wird beim Erstellen des Projekts automatisch erstellt, während die PROJECT_ID von Ihnen oder dem Ersteller des Projekts erstellt wird. So richten Sie ein Projekt ein:

  1. 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.

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

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

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

    8.

    Erforderliche Rollen abrufen

    Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Vertex AI-Nutzer (roles/aiplatform.user) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie für die Verwendung von Vertex AI Agent Engine benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

    Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

    Wenn Sie Anfragen an Memory Bank von einem Agent senden, der in Google Kubernetes Engine oder Cloud Run bereitgestellt wird, muss Ihr Dienstkonto die erforderlichen Berechtigungen haben. Der Reasoning Engine-Dienst-Agent hat bereits die erforderlichen Berechtigungen zum Lesen und Schreiben von Erinnerungen. Ausgehende Anfragen von Agent Engine Runtime sollten also bereits die Berechtigung für den Zugriff auf Memory Bank haben.

    Umgebung einrichten

    In diesem Abschnitt wird davon ausgegangen, dass Sie eine Python-Entwicklungsumgebung eingerichtet haben oder eine Laufzeit mit einer Python-Entwicklungsumgebung verwenden (z. B. Colab).

    Bibliotheken installieren

    Installieren Sie das Vertex AI SDK:

      pip install google-cloud-aiplatform>=1.104.0

    Authentifizierung

    Die Authentifizierungsanleitung hängt davon ab, ob Sie Vertex AI im Express-Modus verwenden:

    • Wenn Sie Vertex AI nicht im Express-Modus verwenden, folgen Sie der Anleitung unter Bei Vertex AI authentifizieren.

    • Wenn Sie Vertex AI im Express-Modus verwenden, richten Sie die Authentifizierung ein, indem Sie den API-Schlüssel in der Umgebung festlegen:

        os.environ["GOOGLE_API_KEY"] = "API_KEY"

    Vertex AI SDK-Client einrichten

    Führen Sie den folgenden Code aus, um einen Vertex AI SDK-Client einzurichten:

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

    Dabei gilt:

    Agent Engine-Instanz konfigurieren

    Wenn Sie Memory Bank verwenden möchten, benötigen Sie zuerst eine Agent Engine-Instanz.

    Sie haben folgende Möglichkeiten:

    Vorhandene Instanz verwenden

    Wenn Sie eine vorhandene Agent Engine-Instanz nicht ändern müssen, führen Sie Folgendes aus, um die Instanz für Memory Bank zu konfigurieren:

    agent_engine = client.agent_engines.get(name="AGENT_ENGINE_NAME")

    Ersetzen Sie Folgendes:

    Instanz erstellen oder aktualisieren

    Wenn Sie eine Agent Engine-Instanz erstellen oder aktualisieren, können Sie die Standardeinstellungen von Agent Engine überschreiben, um die folgenden Änderungen vorzunehmen:

    Erstellen

    Memory Bank ist standardmäßig aktiviert, wenn Sie eine Agent Engine-Instanz erstellen. Sie können die Instanz in jeder Umgebung verwenden, einschließlich Google Kubernetes Engine und Cloud Run. Sie benötigen den Namen der Agent Engine, mit dem die Memory Bank identifiziert wird, und die Berechtigung zum Aufrufen der Memory Bank.

      agent_engine = client.agent_engines.create()

    Neue Instanzen sind leer, sofern Sie nicht zuerst Erinnerungen erstellen oder generieren.

    Aktualisieren

    Sie können eine vorhandene Agent Engine-Instanz aktualisieren, wenn Sie die Agent Engine aktualisieren und gleichzeitig die in der Instanz gespeicherten Erinnerungen beibehalten möchten. Sie können Änderungen vornehmen, z. B. die Konfiguration des Memory Bank ändern oder Ihren Agent in der Agent Engine-Laufzeitumgebung bereitstellen.

      agent_engine = client.agent_engines.update(
        # If you have an existing AgentEngine, you can access the name using `agent_engine.api_resource.name`.
        name="AGENT_ENGINE_NAME",
        # Optional.
        agent_engine=...,
        # Optional.
        config=...
  )

    Ersetzen Sie Folgendes:

    Memory Bank-Konfiguration festlegen

    Sie können Ihre Memory Bank konfigurieren, um anzupassen, wie Erinnerungen generiert und verwaltet werden. Wenn die Konfiguration nicht angegeben ist, verwendet Memory Bank die Standardeinstellungen.

    # Optional.
similarity_search_config = {
        "similarity_search_config": {
                "embedding_model": "EMBEDDING_MODEL",
        }
}

# Optional
generation_config = {
      "generation_config": {
            "model": "LLM_MODEL",
      }
}

context_spec = {
      "context_spec": {
            "memory_bank_config": {
                  **similarity_search_config,
                  **generation_config
            }
      }
}

# Create an Agent Engine with a Memory Bank Config.
agent_engine = client.agent_engines.create(
      config={
            # Optional.
            **context_spec
      }
)

    Ersetzen Sie Folgendes:

    • EMBEDDING_MODEL: Das Google-Texteinbettungsmodell, das für die Ähnlichkeitssuche verwendet werden soll, im Format projects/{project}/locations/{location}/publishers/google/models/{model}. Memory Bank verwendet text-embedding-005 als Standardmodell. Wenn Sie erwarten, dass Nutzerunterhaltungen in anderen Sprachen als Englisch stattfinden, verwenden Sie ein Modell, das mehrere Sprachen unterstützt, z. B. gemini-embedding-001 oder text-multilingual-embedding-002, um die Qualität des Abrufs zu verbessern.

    • LLM_MODEL: Das Google LLM-Modell, das zum Extrahieren und Konsolidieren von Erinnerungen verwendet werden soll, im Format projects/{project}/locations/{location}/publishers/google/models/{model}. Memory Bank verwendet gemini-2.0-flash-001 als Standardmodell.

    Agent mit Arbeitsspeicher in Agent Engine bereitstellen

    Memory Bank kann in jeder Laufzeit verwendet werden. Sie können Memory Bank aber auch mit der Agent Engine Runtime verwenden, um Erinnerungen aus Ihrem bereitgestellten Agent zu lesen und in ihn zu schreiben.

    Wenn Sie einen Agent mit Memory Bank in der Vertex AI Agent Engine-Laufzeit bereitstellen möchten, müssen Sie zuerst Ihre Umgebung für die Agent Engine-Laufzeit einrichten. Bereiten Sie dann Ihren Agent für die Bereitstellung in der Agent Engine-Laufzeit mit Speicherintegration vor. Ihr bereitgestellter Agent sollte bei Bedarf Aufrufe zum Lesen und Schreiben von Erinnerungen ausführen.

    AdkApp

    Wenn Sie die Vorlage für das Agent Engine Agent Development Kit verwenden, nutzt der Agent standardmäßig VertexAiMemoryBankService, wenn er in der Agent Engine-Laufzeitumgebung bereitgestellt wird. Das bedeutet, dass Ihr Agent automatisch die Memory Bank verwendet, um Erinnerungen zu verwalten.

    from google.adk.agents import Agent
from vertexai.preview.reasoning_engines import AdkApp

# Develop an agent using the ADK template.
agent = Agent(...)

adk_app = AdkApp(
      agent=adk_agent,
      ...
)

# Deploy the agent to Agent Engine runtime.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket":
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

    Bei der lokalen Ausführung verwendet die ADK-Vorlage standardmäßig InMemoryMemoryService. Wenn Sie verschiedene Agent Engine-Instanzen für Erinnerungen und die Bereitstellung verwenden möchten oder eine AdkApp mit Memory Bank lokal verwenden möchten, können Sie die von Memory Bank verwendete Instanz überschreiben:

    def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="AGENT_ENGINE_ID"
    )

adk_app = AdkApp(
      agent=adk_agent,
      # Override the default memory service.
      memory_service_builder=memory_bank_service_builder
)

agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket":
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Ihre Projekt-ID.
    • LOCATION: Ihre Region. Unterstützte Regionen für Memory Bank
    • AGENT_ENGINE_ID: Die Agent Engine-ID, die für Memory Bank verwendet werden soll. Beispiel: 456 in projects/my-project/locations/us-central1/reasoningEngines/456.

    Weitere Informationen zur Verwendung von Memory Bank mit dem ADK finden Sie im Schnellstart mit dem Agent Development Kit.

    Benutzerdefinierter Agent

    Sie können Memory Bank mit Ihrem benutzerdefinierten Agenten verwenden, der in der Agent Engine-Laufzeit bereitgestellt wird.

    Wenn Sie dieselbe Agent Engine-Instanz sowohl für Memory Bank als auch für die Agent Engine-Laufzeit verwenden möchten, können Sie die Umgebungsvariablen GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION,GOOGLE_CLOUD_AGENT_ENGINE_ID lesen, um den Namen der Agent Engine aus der Umgebung abzuleiten:

    project = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION")
agent_engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")

agent_engine_name = f"projects/{project}/locations/{location}/reasoningEngines/{agent_engine_id}"

    Nächste Schritte