Kurzanleitung für das Agent-Entwicklungs-Kit

Vorschau

Diese Funktion unterliegt den Bedingungen für Pre‑GA-Angebote im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie gesehen“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

Nachdem Sie Ihren ADK-Agent (Agent Development Kit) für die Verwendung von Memory Bank konfiguriert haben, orchestriert Ihr Agent Aufrufe an Memory Bank, um Langzeitgedächtnisse für Sie zu verwalten.

In dieser Anleitung wird gezeigt, wie Sie Memory Bank mit dem ADK verwenden können, um langfristige Erinnerungen zu verwalten:

1. Lokalen ADK-Agenten und Runner erstellen ADK-Runner verbinden Ihren Agenten mit Diensten, die die Sitzungs- und Speicherverwaltung übernehmen.

2. Interagieren Sie mit Ihrem Agenten, um dynamisch langfristig gemerkte Informationen zu generieren, auf die über Sitzungen hinweg zugegriffen werden kann.

3. Führen Sie eine Bereinigung durch.

Wenn Sie Memory Bank ohne ADK-Orchestrierung direkt aufrufen möchten, lesen Sie die Kurzanleitung zum Agent Engine SDK. Das Agent Engine SDK ist hilfreich, um zu verstehen, wie Memory Bank Erinnerungen generiert, oder um den Inhalt von Memory Bank zu prüfen.

Wichtig :Im ADK werden hauptsächlich asynchrone Funktionen verwendet. Wenn Sie Code in einem Notebook wie Colab ausführen, können Sie await-Async-Funktionen direkt aufrufen, da bereits eine Ereignisschleife ausgeführt wird. Wenn Sie diesen Code als Standard-Python-Skript ausführen, müssen Sie Ihre asynchronen Funktionsaufrufe mit asyncio.run() umschließen, um eine Ereignisschleife zum Ausführen Ihrer asynchronen Funktionen zu erstellen und zu verwalten. Andernfalls wird möglicherweise ein Fehler wie 'await' outside function angezeigt.

Wenn Sie ein Beispiel für die Verwendung von Memory Bank mit dem ADK sehen möchten, führen Sie das Notebook „Erste Schritte mit Memory Bank im ADK“ in einer der folgenden Umgebungen aus:

In Colab öffnen | In Colab Enterprise öffnen | In Vertex AI Workbench öffnen | Auf GitHub ansehen

Hinweise

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

Hinweis :Wenn Sie bereits ein Google Cloud -Projekt haben, können Sie der Anleitung mit Ihrer Projektnummer und Ihrem Standort folgen und die Anleitung für dasGoogle Cloud -Projekt verwenden. Wenn Sie Google Cloud zum ersten Mal Nutzer sind, können Sie sich mit Ihrem Gmail-Konto registrieren, um ein Express Mode-Projekt und einen API-Schlüssel ohne Abrechnung über die Express Mode-Registrierung zu erhalten. Folgen Sie dann der Anleitung mit den Anweisungen für den „Vertex AI Express Mode“.

Umgebungsvariablen festlegen

So legen Sie Umgebungsvariablen für die Verwendung des ADK fest:

Google Cloud Projekt

import os

os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

Ersetzen Sie Folgendes:

• PROJECT_ID: Ihre Projekt-ID.
• LOCATION: Ihre Region. Unterstützte Regionen für Memory Bank

Vertex AI Express-Modus

import os

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

Ersetzen Sie Folgendes:

• API_KEY: Ihr Vertex AI Express-Modus-API-Schlüssel. Wenn Sie Google Cloudzum ersten Mal nutzen, können Sie sich mit Ihrem Gmail-Konto registrieren, um über die Express-Registrierung einen API-Schlüssel zu erhalten.

ADK-Agent erstellen

1. Wenn Sie Ihren ADK-Agenten entwickeln, fügen Sie ein Memory-Tool ein, mit dem gesteuert wird, wann der Agent Erinnerungen abruft und wie Erinnerungen in den Prompt aufgenommen werden. Der Beispiel-KI-Agent verwendet PreloadMemoryTool, wodurch Erinnerungen immer zu Beginn jedes Turns abgerufen und in die Systemanweisung aufgenommen werden:

   from google import adk
   
   agent = adk.Agent(
       model="gemini-2.0-flash",
       name='stateful_agent',
       instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.
   
   1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
   2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
   3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
   4.  **Brevity:** Limit responses to under 30 words.
   """,
       tools=[adk.tools.preload_memory_tool.PreloadMemoryTool()]
   )
   

2. Erstellen Sie einen VertexAiMemoryBankService-Speicherdienst, den der ADK-Runner zum Abrufen von Erinnerungen verwendet. Dies ist optional, wenn Sie die Agent Engine ADK-Vorlage verwenden, anstatt eine eigene ADK-Laufzeit zu definieren. Wenn Sie das Verhalten Ihrer Memory Bank-Instanz konfigurieren möchten, lesen Sie die Einrichtungsanleitung.

   Google Cloud Projekt

   from google.adk.memory import VertexAiMemoryBankService
   import vertexai
   
   client = vertexai.Client(
     project="PROJECT_ID",
     location="LOCATION"
   )
   # If you don't have an Agent Engine instance already, create an Agent Engine
   # Memory Bank instance using the default configuration.
   agent_engine = client.agent_engines.create()
   
   # Optionally, print out the Agent Engine resource name. You will need the
   # resource name to interact with your Agent Engine instance later on.
   print(agent_engine.api_resource.name)
   
   agent_engine_id = agent_engine.api_resource.name.split("/")[-1]
   
   memory_service = VertexAiMemoryBankService(
       project="PROJECT_ID",
       location="LOCATION",
       agent_engine_id=agent_engine_id
   )
   

   Ersetzen Sie Folgendes:

   • PROJECT_ID: Ihre Projekt-ID.
   • LOCATION: Ihre Region. Unterstützte Regionen für Memory Bank

   Vertex AI Express-Modus

   from google.adk.memory import VertexAiMemoryBankService
   import vertexai
   
   client = vertexai.Client(
     api_key="API_KEY",
   )
   # If you don't have an Agent Engine instance already, create an Agent Engine
   # Memory Bank instance using the default configuration.
   agent_engine = client.agent_engines.create()
   
   # Optionally, print out the Agent Engine resource name. You will need the
   # resource name to interact with your Agent Engine instance later on.
   print(agent_engine.api_resource.name)
   
   agent_engine_id = agent_engine.api_resource.name.split("/")[-1]
   
   # Make sure your environment variables are set. VertexAiMemoryBankService
   # will read your api key from the GOOGLE_API_KEY environment variable.
   memory_service = VertexAiMemoryBankService(
       agent_engine_id=agent_engine_id
   )
   

   Ersetzen Sie Folgendes:

   • API_KEY: Ihr Vertex AI Express-Modus-API-Schlüssel. Wenn Sie Google Cloudzum ersten Mal nutzen, können Sie sich mit Ihrem Gmail-Konto registrieren, um über die Express-Registrierung einen API-Schlüssel zu erhalten.

   VertexAiMemoryBankService ist ein ADK-Wrapper für Memory Bank, der durch das BaseMemoryService des ADK definiert wird und eine andere Schnittstelle als das Agent Engine SDK verwendet. Mit dem Agent Engine SDK können Sie direkte API-Aufrufe an Memory Bank senden. Die VertexAiMemoryBankService-Schnittstelle umfasst:

   • memory_service.add_session_to_memory, wodurch eine GenerateMemories-Anfrage an Memory Bank mit dem bereitgestellten adk.Session als Quellinhalt ausgelöst wird. Aufrufe dieser Methode werden nicht vom ADK-Runner orchestriert. Wenn Sie die Erstellung von Erinnerungen mit dem ADK automatisieren möchten, müssen Sie eigene Callback-Funktionen definieren.

   • memory_service.search_memory, wodurch eine RetrieveMemories-Anfrage an Memory Bank ausgelöst wird, um relevante Erinnerungen für die aktuelle user_id und app_name abzurufen. Aufrufe dieser Methode werden vom ADK-Runner orchestriert, wenn Sie Ihrem Agenten ein Memory-Tool zur Verfügung stellen.

3. Erstellen Sie eine ADK-Laufzeit, die die Ausführung Ihrer Agents, Tools und Callbacks orchestriert. Die Einrichtung des ADK-Runners hängt von der verwendeten Bereitstellungsumgebung ab:

adk.Runner

adk.Runner wird in der Regel in einer lokalen Umgebung wie Colab verwendet. Die meisten Bereitstellungsoptionen, z. B. Agent Engine Runtime, bieten eine eigene Laufzeit für das ADK.

import asyncio

from google.adk.sessions import VertexAiSessionService
from google.genai import types

# You can use any ADK session service. This example uses Agent Engine Sessions.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

# For Express Mode users, ensure your environment variables are set and
# initialize VertexAiSessionService as follows:
#
# session_service = VertexAiSessionService(
#    agent_engine_id=agent_engine_id
# )

app_name="APP_NAME"

runner = adk.Runner(
    agent=agent,
    app_name=app_name,
    session_service=session_service,
    memory_service=memory_service
)

async def call_agent(query, session, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run_async(
    user_id=user_id, session_id=session, new_message=content)

  async for event in events:
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

Ersetzen Sie Folgendes:

• APP_NAME: Der Name Ihrer ADK-App.

ADK-Vorlage für Agent Engine

Die Agent Engine ADK-Vorlage (AdkApp) kann sowohl lokal als auch zum Bereitstellen eines ADK-Agents in der Agent Engine-Laufzeit verwendet werden. Wenn das Agent Engine ADK-Template in der Agent Engine-Laufzeit bereitgestellt wird, wird VertexAiMemoryBankService als Standardspeicherdienst verwendet. Dabei wird dieselbe Agent Engine-Instanz für die Memory Bank wie für die Agent Engine-Laufzeit verwendet. In diesem Fall müssen Sie keinen Speicherdienst explizit angeben.

Weitere Informationen zum Einrichten der Agent Engine-Laufzeit, einschließlich der Anpassung des Verhaltens Ihrer Memory Bank, finden Sie unter Agent Engine konfigurieren.

Verwenden Sie den folgenden Code, um Ihren ADK-Agenten in der Agent Engine-Laufzeit bereitzustellen:

Hinweis: Nutzer des Express-Modus sollten die Anleitung unter Über Quellcode bereitstellen befolgen, um ihre ADK-App bereitzustellen.

import asyncio

import vertexai
from vertexai.agent_engines import AdkApp

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

adk_app = AdkApp(agent=agent)

# Create a new Agent Engine with your agent deployed to Agent Engine Runtime.
# The Agent Engine instance will also include an empty Memory Bank.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

# Alternatively, update an existing Agent Engine to deploy your agent to Agent Engine Runtime.
# Your agent will have access to the Agent Engine instance's existing memories.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

async def call_agent(query, session_id, user_id):
    async for event in agent_engine.async_stream_query(
        user_id=user_id,
        session_id=session_id,
        message=query,
    ):
        print(event)

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.
• STAGING_BUCKET: Ihr Cloud Storage-Bucket, der für das Staging Ihrer Agent Engine-Laufzeit verwendet werden soll.

Bei der lokalen Ausführung verwendet die ADK-Vorlage InMemoryMemoryService als Standardspeicherdienst. Sie können den Standardspeicherdienst jedoch überschreiben, um VertexAiMemoryBankService zu verwenden:

# For Google Cloud Project users:
def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="AGENT_ENGINE_ID"
    )
# For Express Mode users, ensure your environment variables are set.
#
# def memory_bank_service_builder():
#    return VertexAiMemoryBankService(
#        agent_engine_id="AGENT_ENGINE_ID"
#    )

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

async def call_agent(query, session_id, user_id):
  # adk_app is a local agent. If you want to deploy it to Agent Engine Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Engine instance instead.
  async for event in adk_app.async_stream_query(
      user_id=user_id,
      session_id=session_id,
      message=query,
  ):
      print(event)

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 die Memory Bank verwendet werden soll. Beispiel: 456 in projects/my-project/locations/us-central1/reasoningEngines/456.

Mit dem Agent interagieren

Nachdem Sie Ihren Agenten definiert und die Memory Bank eingerichtet haben, können Sie mit ihm interagieren.

1. Erstellen Sie Ihre erste Sitzung. Da in der ersten Sitzung mit einem Nutzer keine Erinnerungen verfügbar sind, kennt der Agent keine Nutzerpräferenzen, z. B. die bevorzugte Temperatur:

   Hinweis :Je nach verwendetem Modell können die Antworten des Agents und der Memory Bank variieren.

   adk.Runner

   Wenn Sie adk.Runner verwenden, können Sie die ADK-Speicher- und ‑Sitzungsdienste direkt aufrufen.

   # Use `asyncio.run(session_service.create(...))` if you're running this
   # code as a standard Python script.
   session = await session_service.create_session(
       app_name="APP_NAME",
       user_id="USER_ID"
   )
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await call_agent(
       "Can you update the temperature to my preferred temperature?",
       session.id,
       "USER_ID"
   )
   # Agent response: "What is your preferred temperature?"
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await call_agent(
     "I like it at 71 degrees", session.id, "USER_ID")
   # Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
   # Temperature successfully changed.
   

   Ersetzen Sie Folgendes:

   • APP_NAME: App-Name für Ihren Runner.
   • USER_ID: Eine Kennung für Ihren Nutzer. Erinnerungen, die aus dieser Sitzung generiert werden, werden mit dieser intransparenten Kennung versehen. Der Umfang der generierten Erinnerungen wird als {"user_id": "USER_ID"} gespeichert.

   ADK-Vorlage für Agent Engine

   Wenn Sie die ADK-Vorlage für die Agent Engine verwenden, können Sie die Agent Engine-Laufzeit aufrufen, um mit dem Speicher und den Sitzungen zu interagieren.

   # Use `asyncio.run(agent_engine.async_create_session(...))` if you're
   # running this code as a standard Python script.
   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await call_agent(
       "Can you update the temperature to my preferred temperature?",
       session.get("id"),
       "USER_ID"
   )
   # Agent response: "What is your preferred temperature?"
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await call_agent("I like it at 71 degrees", session.get("id"), "USER_ID")
   # Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
   # Temperature successfully changed.
   

   Ersetzen Sie Folgendes:

   • USER_ID: Eine Kennung für Ihren Nutzer. Erinnerungen, die aus dieser Sitzung generiert werden, werden mit dieser intransparenten Kennung versehen. Der Umfang der generierten Erinnerungen wird als {"user_id": "USER_ID"} gespeichert.

2. Erinnerungen für die aktuelle Sitzung erstellen Wenn Memory Bank Erinnerungen aus dem Gespräch extrahiert, werden sie unter dem Bereich {"user_id": USER_ID, "app_name": APP_NAME} gespeichert.

   adk.Runner

   async def trigger_memory_generation(app_name, session):
       # Refresh your `session` object so that all of the session events locally available.
       session = await session_service.get_session(
           app_name=app_name,
           user_id="USER_ID",
           session_id=session.id
       )
       await memory_service.add_session_to_memory(session)
   
   # Use `asyncio.run(trigger_memory_generation(...))` if you're running this
   # code as a standard Python script.
   await trigger_memory_generation(app_name, session)
   

   ADK-Vorlage für Agent Engine

   Hinweis: Damit Sie async_add_session_to_memory verwenden können, muss Ihr AdkApp mit google-cloud-aiplatform-Version 1.110.0 oder höher erstellt worden sein. Andernfalls können Sie die Generierung von Erinnerungen durch direkte Aufrufe von Memory Bank auslösen.

   # Use `asyncio.run(agent_engine.async_add_session_to_memory(...))` if
   # you're running this code as a standard Python script.
   await agent_engine.async_add_session_to_memory(session=session)
   

3. Erstellen Sie die zweite Sitzung. Wenn Sie PreloadMemoryTool verwendet haben, ruft der Agent zu Beginn jeder Runde Erinnerungen ab, um auf Einstellungen zuzugreifen, die der Nutzer dem Agent zuvor mitgeteilt hat.

   adk.Runner

   # Use `asyncio.run(session_service.create_session(...))` if you're running
   # this code as a standard Python script.
   session = await session_service.create_session(
       app_name=app_name,
       user_id="USER_ID"
   )
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await call_agent("Fix the temperature!", session.id, "USER_ID")
   # Agent Response:  Setting temperature to 71 degrees.  Is that correct?
   

   Sie können auch memory_service.search_memory verwenden, um Erinnerungen direkt abzurufen:

   # Use `asyncio.run(memory_service.search_memory(...))` if you're running
   # this code as a standard Python script.
   await memory_service.search_memory(
       app_name="APP_NAME",
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

   ADK-Vorlage für Agent Engine

   # Use `asyncio.run(agent_engine.async_add_session_to_memory(...))` if
   # you're running this code as a standard Python script.
   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await call_agent("Fix the temperature!", session.get("id"), "USER_ID")
   # Agent Response:  Setting temperature to 71 degrees.  Is that correct?
   

   Sie können auch agent_engine.async_search_memory verwenden, um Erinnerungen direkt abzurufen: Hinweis: Damit Sie async_search_memory verwenden können, muss Ihr AdkApp mit google-cloud-aiplatform-Version 1.110.0 oder höher erstellt worden sein. Andernfalls können Sie Erinnerungen abrufen, indem Sie Memory Bank direkt aufrufen.

   # Use `asyncio.run(agent_engine.async_search_memory(...))` if you're
   # running this code as a standard Python script.
   await agent_engine.async_search_memory(
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

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 zu dieser Vertex AI Agent Engine gehören.

   agent_engine.delete(force=True)
   

2. Löschen Sie alle lokal erstellten Dateien.

Nächste Schritte

• Kurzanleitung für das Agent Engine SDK