Kurzanleitung für das Agent-Entwicklungs-Kit

Vorabversion

Diese Funktion unterliegt den Pre-GA-Angebotsbedingungen im Abschnitt mit den allgemeinen Dienstbedingungen der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Markteinführungsphase.

Nachdem Sie Ihren ADK-Agenten (Agent Development Kit) für die Verwendung von Memory Bank konfiguriert haben, orchestriert er 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-Agent und -Runner erstellen

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.

Informationen dazu, wie Sie Memory Bank ohne ADK-Orchestrierung direkt aufrufen, finden Sie im Schnellstart mit dem 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.

Hinweise

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

Umgebungsvariablen festlegen

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

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

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-Agent verwendet PreloadMemoryTool, wodurch zu Beginn jeder Runde immer Erinnerungen 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.

   from google.adk.memory import VertexAiMemoryBankService
   
   agent_engine_id = agent_engine.api_resource.name.split("/")[-1]
   
   memory_service = VertexAiMemoryBankService(
       project="PROJECT_ID",
       location="LOCATION",
       agent_engine_id=agent_engine_id
   )
   

   VertexAiMemoryBankService ist ein ADK-Wrapper für Memory Bank, der durch das ADK-BaseMemoryServicedefiniert 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 Erinnerungserstellung 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 Agenten, Tools und Callbacks orchestriert. Die Einrichtung von ADK Runner 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.

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

# You can use any ADK session service.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    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
)

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

  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-Laufzeitumgebung bereitgestellt wird, wird VertexAiMemoryBankService als Standardspeicherdienst verwendet. Dabei wird dieselbe Agent Engine-Instanz für Memory Bank wie für die Agent Engine-Laufzeitumgebung 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-Agent in der Agent Engine-Laufzeit bereitzustellen:

import vertexai
from vertexai.preview.reasoning_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:

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
)

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

   session = await session_service.create_session(
       app_name="APP_NAME",
       user_id="USER_ID"
   )
   
   call_agent(
       "Can you update the temperature to my preferred temperature?",
       session.id,
       "USER_ID"
   )
   
   # Agent response: "What is your preferred temperature?"
   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 Agent Engine ADK-Vorlage verwenden, können Sie die Agent Engine-Laufzeit aufrufen, um mit dem Arbeitsspeicher und den Sitzungen zu interagieren.

   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   await call_agent(
       "Can you update the temperature to my preferred temperature?",
       session.get("id"),
       "USER_ID"
   )
   
   # Agent response: "What is your preferred temperature?"
   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

   session = await session_service.get_session(
       app_name=app_name,
       user_id="USER_ID",
       session_id=session.id
   )
   memory_service.add_session_to_memory(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.

   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

   session = await session_service.create_session(
       app_name=app_name,
       user_id="USER_ID"
   )
   
   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:

   await memory_service.search_memory(
       app_name="APP_NAME",
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

   ADK-Vorlage für Agent Engine

   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   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.

   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