Panduan memulai dengan Agent Development Kit

Setelah Anda mengonfigurasi agen Agent Development Kit (ADK) untuk menggunakan Bank Memori, agen Anda akan mengatur panggilan ke Bank Memori untuk mengelola memori jangka panjang untuk Anda.

Tutorial ini menunjukkan cara menggunakan Bank Memori dengan ADK untuk mengelola memori jangka panjang:

  1. Buat agen dan peluncur ADK lokal Anda.

  2. Berinteraksi dengan agen Anda untuk membuat memori jangka panjang secara dinamis yang dapat diakses di seluruh sesi.

  3. Pembersihan.

Untuk melakukan panggilan langsung ke Memory Bank tanpa orkestrasi ADK, lihat Mulai Cepat dengan Agent Engine SDK. Penggunaan Agent Engine SDK berguna untuk memahami cara Memory Bank membuat memori atau untuk memeriksa isi Memory Bank.

Sebelum memulai

Untuk menyelesaikan langkah-langkah yang ditunjukkan dalam tutorial ini, Anda harus mengikuti langkah-langkah dalam Menyiapkan Bank Memori terlebih dahulu.

Menetapkan variabel lingkungan

Untuk menggunakan ADK, tetapkan variabel lingkungan Anda:

import os

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

Ganti kode berikut:

Buat agen ADK Anda

  1. Saat mengembangkan agen ADK, sertakan alat Memory yang mengontrol kapan agen mengambil memori dan cara memori disertakan dalam perintah. Agen contoh menggunakan PreloadMemoryTool, yang selalu mengambil memori di awal setiap giliran dan menyertakan memori dalam petunjuk sistem:

    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. Buat layanan memori VertexAiMemoryBankService, yang digunakan peluncur ADK untuk mengambil kenangan. Opsi ini bersifat opsional jika Anda menggunakan template ADK Agent Engine, bukan menentukan runtime ADK Anda sendiri.

    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 adalah wrapper ADK di sekitar Memory Bank yang ditentukan oleh BaseMemoryServiceADK dan menggunakan antarmuka yang berbeda dengan Agent Engine SDK. Anda dapat menggunakan Agent Engine SDK untuk melakukan panggilan API langsung ke Memory Bank. Antarmuka VertexAiMemoryBankService mencakup:

    • memory_service.add_session_to_memory yang memicu permintaan GenerateMemories ke Memory Bank menggunakan adk.Session yang disediakan sebagai konten sumber. Panggilan ke metode ini tidak diatur oleh runner ADK. Jika Anda ingin mengotomatiskan pembuatan memori dengan ADK, Anda perlu menentukan fungsi callback Anda sendiri.

    • memory_service.search_memory yang memicu permintaan RetrieveMemories ke Memory Bank untuk mengambil kenangan yang relevan untuk user_id dan app_name saat ini. Panggilan ke metode ini diatur oleh runner ADK saat Anda menyediakan alat Memori ke agen Anda.

  3. Buat ADK Runtime, yang mengorkestrasi eksekusi agen, alat, dan callback Anda. Penyiapan ADK Runner bergantung pada lingkungan deployment yang Anda gunakan:

adk.Runner

adk.Runner umumnya digunakan di lingkungan lokal, seperti Colab. Sebagian besar opsi deployment, seperti Agent Engine Runtime, menawarkan runtime-nya sendiri untuk 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)

Ganti kode berikut:

  • APP_NAME: Nama aplikasi ADK Anda.

Template ADK Agent Engine

Template ADK Agent Engine (AdkApp) dapat digunakan secara lokal dan untuk men-deploy agen ADK ke Runtime Agent Engine. Saat di-deploy di Agent Engine Runtime, template ADK Agent Engine menggunakan VertexAiMemoryBankService sebagai layanan memori default, menggunakan instance Agent Engine yang sama untuk Memory Bank dengan Agent Engine Runtime. Dalam hal ini, Anda tidak perlu memberikan layanan memori secara eksplisit.

Lihat Mengonfigurasi Agent Engine untuk mengetahui detail selengkapnya tentang cara menyiapkan Runtime Agent Engine, termasuk cara menyesuaikan perilaku Bank Memori Anda.

Gunakan kode berikut untuk men-deploy agen ADK ke Agent Engine Runtime:

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)

Ganti kode berikut:

  • PROJECT_ID: Project ID Anda.
  • LOCATION: Region Anda. Lihat region yang didukung untuk Bank Memori.
  • AGENT_ENGINE_ID: ID Agent Engine yang akan digunakan untuk Memory Bank. Misalnya, 456 di projects/my-project/locations/us-central1/reasoningEngines/456.
  • STAGING_BUCKET: Bucket Cloud Storage Anda yang akan digunakan untuk menyiapkan Runtime Agent Engine.

Saat dijalankan secara lokal, template ADK menggunakan InMemoryMemoryService sebagai layanan memori default. Namun, Anda dapat mengganti layanan memori default untuk menggunakan VertexAiMemoryBankService:

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)

Ganti kode berikut:

  • PROJECT_ID: Project ID Anda.
  • LOCATION: Region Anda. Lihat region yang didukung untuk Bank Memori.
  • AGENT_ENGINE_ID: ID Agent Engine yang akan digunakan untuk Memory Bank. Misalnya, 456 di projects/my-project/locations/us-central1/reasoningEngines/456.

Berinteraksi dengan agen Anda

Setelah menentukan agen dan menyiapkan Bank Memori, Anda dapat berinteraksi dengan agen.

  1. Buat sesi pertama Anda. Karena tidak ada memori yang tersedia selama sesi pertama dengan pengguna, agen tidak mengetahui preferensi pengguna, seperti suhu yang diinginkan:

    adk.Runner

    Saat menggunakan adk.Runner, Anda dapat memanggil layanan memori dan sesi ADK secara langsung.

    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.

    Ganti kode berikut:

    • APP_NAME: Nama aplikasi untuk pelari Anda.
    • USER_ID: ID untuk pengguna Anda. Kenangan yang dihasilkan dari sesi ini diberi kunci oleh ID buram ini. Cakupan kenangan yang dihasilkan disimpan sebagai {"user_id": "USER_ID"}.

    Template ADK Agent Engine

    Saat menggunakan template ADK Agent Engine, Anda dapat memanggil Runtime Agent Engine untuk berinteraksi dengan memori dan sesi.

    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.

    Ganti kode berikut:

    • USER_ID: ID untuk pengguna Anda. Kenangan yang dihasilkan dari sesi ini diberi kunci oleh ID buram ini. Cakupan kenangan yang dihasilkan disimpan sebagai {"user_id": "USER_ID"}.

  2. Membuat kenangan untuk sesi Anda saat ini. Jika Memory Bank mengekstrak kenangan dari percakapan, kenangan tersebut akan disimpan dalam cakupan {"user_id": USER_ID, "app_name": APP_NAME}.

    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)

    Template ADK Agent Engine

    await agent_engine.async_add_session_to_memory(session=session)

  3. Buat sesi kedua Anda. Jika Anda menggunakan PreloadMemoryTool, agen akan mengambil memori di awal setiap giliran untuk mengakses preferensi yang sebelumnya dikomunikasikan pengguna kepada agen.

    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?

    Anda juga dapat menggunakan memory_service.search_memory untuk mengambil kenangan secara langsung:

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

    Template ADK 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?

    Anda juga dapat menggunakan agent_engine.async_search_memory untuk mengambil kenangan secara langsung: Catatan: Untuk menggunakan async_search_memory, AdkApp Anda harus dibuat dengan google-cloud-aiplatform versi 1.110.0 atau yang lebih baru. Jika tidak, Anda dapat mengambil kenangan dengan melakukan panggilan langsung ke Bank Memori.

    await agent_engine.async_search_memory(
    user_id="USER_ID",
    query="Fix the temperature!",
)

Pembersihan

Untuk membersihkan semua resource yang digunakan dalam project ini, Anda dapat menghapus Google Cloud project yang Anda gunakan untuk panduan memulai.

Atau, Anda dapat menghapus setiap resource yang dibuat dalam tutorial ini, sebagai berikut:

  1. Gunakan contoh kode berikut untuk menghapus instance Vertex AI Agent Engine, yang juga menghapus Sesi atau Memori apa pun yang dimiliki Vertex AI Agent Engine tersebut.

    agent_engine.delete(force=True)

  2. Hapus semua file yang dibuat secara lokal.

Langkah berikutnya