Panduan memulai dengan Agent Development Kit

Tutorial ini menunjukkan cara menggunakan Bank Memori dengan ADK untuk mengelola memori jangka panjang. 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.

Penggunaan Memory Bank dengan ADK melibatkan langkah-langkah berikut:

1. Buat agen dan peluncur ADK Anda. Runner ADK menghubungkan agen Anda ke layanan yang menyediakan pengelolaan sesi dan memori.

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.

Penting: ADK terutama menggunakan fungsi asinkron. Jika menjalankan kode di notebook seperti Colab, Anda dapat langsung await fungsi asinkron karena loop peristiwa sudah berjalan. Jika menjalankan kode ini sebagai skrip Python standar, Anda harus membungkus panggilan fungsi asinkron dengan asyncio.run() untuk membuat dan mengelola loop peristiwa guna menjalankan fungsi asinkron. Jika tidak, Anda mungkin akan mendapatkan error seperti 'await' outside function.

Untuk melihat contoh penggunaan Memory Bank dengan ADK, jalankan notebook "Mulai menggunakan Memory Bank di ADK" di salah satu lingkungan berikut:

Buka di Colab | Buka di Colab Enterprise | Buka di Vertex AI Workbench | Lihat di GitHub

Mengelola kenangan dengan layanan memori ADK dan Bank Memori

VertexAiMemoryBankService adalah wrapper ADK di sekitar Bank Memori yang ditentukan oleh BaseMemoryService ADK. Anda dapat menentukan callback dan alat yang berinteraksi dengan layanan memori untuk membaca dan menulis memori.

Antarmuka VertexAiMemoryBankService mencakup:

• memory_service.add_session_to_memory memicu permintaan GenerateMemories ke Memory Bank menggunakan semua peristiwa dalam adk.Session yang diberikan sebagai konten sumber. Anda dapat mengatur panggilan ke metode ini menggunakan callback_context.add_session_to_memory di callback.

  from google.adk.agents.callback_context import CallbackContext
  
  async def add_session_to_memory_callback(callback_context: CallbackContext):
      await callback_context.add_session_to_memory()
      return None
  

• memory_service.add_events_to_memory yang memicu permintaan GenerateMemories ke Memory Bank menggunakan subset peristiwa. Anda dapat mengatur panggilan ke metode ini menggunakan callback_context.add_events_to_memory di callback.

  from google.adk.agents.callback_context import CallbackContext
  
  async def add_events_to_memory_callback(callback_context: CallbackContext):
      await callback_context.add_events_to_memory(events=callback_context.session.events[-5:-1])
      return None
  

• memory_service.search_memory memicu permintaan RetrieveMemories ke Memory Bank untuk mengambil kenangan yang relevan untuk user_id dan app_name saat ini. Anda dapat mengatur panggilan ke metode ini menggunakan alat memori bawaan (LoadMemoryTool atau PreloadMemoryTool) atau alat kustom yang memanggil tool_context.search_memory.

Sebelum memulai

Untuk menyelesaikan langkah-langkah yang ditunjukkan dalam tutorial ini, Anda harus mengikuti langkah-langkah di bagian Mulai di halaman Siapkan 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:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region Anda. Lihat wilayah yang didukung untuk fitur Bank Memori.

Buat agen ADK Anda

Untuk membuat agen yang mendukung memori, siapkan alat dan callback yang mengatur panggilan ke layanan memori Anda.

Menentukan callback pembuatan memori

Untuk mengatur panggilan pembuatan memori, buat fungsi callback yang memicu pembuatan memori. Anda dapat mengirim subset peristiwa (dengan callback_context.add_events_to_memory) atau semua peristiwa dalam sesi (dengan callback_context.add_session_to_memory) untuk diproses di latar belakang:

  from google.adk.agents.callback_context import CallbackContext

  async def generate_memories_callback(callback_context: CallbackContext):
      # Option 1 (Recommended): Send events to Memory Bank for memory generation,
      # which is ideal for incremental processing of events.
      await callback_context.add_events_to_memory(
        events=callback_context.session.events[-5:-1])

      # Option 2: Send the full session to Memory Bank for memory generation.
      # It's recommended to only call this at the end of a session to minimize
      # how many times a single event is re-processed.
      await callback_context.add_session_to_memory()

      return None

Menentukan alat pengambilan memori

Saat mengembangkan agen ADK, sertakan alat memori yang mengontrol kapan agen mengambil memori dan cara memori disertakan dalam perintah.

Jika Anda menggunakan PreloadMemoryTool, agen Anda akan mengambil memori di awal setiap giliran dan menyertakan memori yang diambil dalam petunjuk sistem, yang bagus untuk membuat konteks dasar tentang pengguna. Jika Anda menggunakan LoadMemoryTool, model akan memanggil alat ini saat memutuskan bahwa memori diperlukan untuk menjawab kueri pengguna.

  from google import adk
  from google.adk.tools.load_memory_tool import LoadMemoryTool
  from google.adk.tools.preload_memory_tool import PreloadMemoryTool

  memory_retrieval_tools = [
    # Option 1: Retrieve memories at the start of every turn.
    PreloadMemoryTool(),
    # Option 2: Retrieve memories via tool calls. The model will only call this tool
    # when it decides that memories are necessary to respond to the user query.
    LoadMemoryTool()
  ]

  agent = adk.Agent(
      model="gemini-2.5-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=memory_retrieval_tools,
      after_agent_callback=generate_memories_callback
  )

Atau, Anda dapat membuat alat kustom sendiri untuk mengambil kenangan, yang berguna saat Anda ingin memberikan petunjuk kepada agen tentang kapan harus mengambil kenangan:

  from google import adk
  from google.adk.tools import ToolContext, FunctionTool

  async def search_memories(query: str, tool_context: ToolContext):
    """Query this tool when you need to fetch information about user preferences."""
    return await tool_context.search_memory(query)

  agent = adk.Agent(
      model="gemini-2.5-flash",
      name='stateful_agent',
      instruction="""...""",
      tools=[FunctionTool(func=search_memories)],
      after_agent_callback=generate_memories_callback
  )

Menentukan layanan dan runtime memori ADK Memory Bank

Setelah membuat agen yang mendukung memori, Anda harus menautkannya ke layanan memori. Proses mengonfigurasi layanan memori ADK bergantung pada tempat jalannya agen ADK, yang mengatur eksekusi agen, alat, dan callback Anda.

Membuat instance Agent Engine

Catatan: Lewati bagian ini jika Anda sudah memiliki instance Agent Engine yang ingin digunakan untuk Bank Memori.

Pertama-tama, Anda perlu membuat instance Agent Engine untuk digunakan di Bank Memori. Langkah ini bersifat opsional jika Anda menggunakan Agent Engine Runtime untuk men-deploy agen. Untuk mengetahui informasi selengkapnya tentang cara menyesuaikan perilaku Bank Memori, lihat bagian Mengonfigurasi instance Agent Engine untuk Bank Memori di halaman Menyiapkan Bank Memori.

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 if you want 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]

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region Anda. Lihat wilayah yang didukung untuk fitur Bank Memori.

Membuat runtime ADK

Teruskan ID Agent Engine ke skrip runtime atau deployment agar agen Anda menggunakan Memory Bank sebagai layanan memori ADK.

Pelari lokal

adk.Runner umumnya digunakan di lingkungan lokal, seperti Colab. Dalam hal ini, Anda perlu membuat layanan dan pelaksana memori secara langsung.

import asyncio

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

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id="AGENT_ENGINE_ID",
)

# 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",
)

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)

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region Anda. Lihat wilayah yang didukung untuk fitur Bank Memori.
• APP_NAME: Nama aplikasi ADK. Nama aplikasi akan disertakan dalam kamus scope kenangan yang dihasilkan sehingga kenangan diisolasi di seluruh pengguna dan aplikasi.
• AGENT_ENGINE_ID: ID Agent Engine yang akan digunakan untuk Bank Memori dan Sesi. Misalnya, 456 di projects/my-project/locations/us-central1/reasoningEngines/456.

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. Jadi, Anda dapat membuat instance Bank Memori dan men-deploy ke runtime dalam satu langkah.

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 yang mendukung memori ke Runtime Agent Engine:

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)

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region Anda. Lihat wilayah yang didukung untuk fitur Bank Memori.
• STAGING_BUCKET: Bucket Cloud Storage Anda yang akan digunakan untuk melakukan staging Agent Engine Runtime.

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 wilayah yang didukung untuk fitur 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.

Cloud Run

Untuk melihat contoh penggunaan Memory Bank dengan Cloud Run, jalankan notebook "Get started with Sessions and Memory Bank for ADK agents in Cloud Run" di salah satu lingkungan berikut:

Buka di Colab | Buka di Colab Enterprise | Buka di Vertex AI Workbench | Lihat di GitHub

Untuk men-deploy agen ke Cloud Run, lihat petunjuk di dokumentasi ADK untuk mempelajari cara menentukan agen yang akan di-deploy ke Cloud Run.

adk deploy cloud_run \
    ...
    --memory_service_uri=agentengine://AGENT_ENGINE_ID

GKE

Untuk melihat contoh penggunaan Memory Bank dengan Google Kubernetes Engine, jalankan notebook "Get started with Sessions and Memory Bank for ADK agents in Google Kubernetes Engine" di salah satu lingkungan berikut:

Buka di Colab | Buka di Colab Enterprise | Buka di Vertex AI Workbench | Lihat di GitHub

Untuk men-deploy agen ke Google Kubernetes Engine (GKE), lihat petunjuk di dokumentasi ADK untuk mempelajari cara menentukan agen yang akan di-deploy ke GKE.

adk deploy gke \
    ...
    --memory_service_uri=agentengine://AGENT_ENGINE_ID

Web ADK

Penting: ADK Web tidak dimaksudkan untuk digunakan dalam deployment produksi. Anda hanya boleh menggunakan ADK Web untuk tujuan pengembangan dan proses debug.

Antarmuka web ADK memungkinkan Anda menguji agen secara langsung di browser.

export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="LOCATION"

adk web --memory_service_uri=agentengine://AGENT_ENGINE_ID

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region Anda. Lihat wilayah yang didukung untuk fitur 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. Jika Anda memberikan callback untuk memicu pembuatan memori saat menginisialisasi agen, pembuatan memori akan dipicu setiap kali agen dipanggil.

Memori akan disimpan menggunakan cakupan {"user_id": USER_ID, "app_name": APP_NAME} yang sesuai dengan ID pengguna dan nama aplikasi yang digunakan untuk menjalankan agen Anda.

Metode berinteraksi dengan agen Anda bergantung pada lingkungan eksekusinya:

Pelari lokal

# 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 fix the temperature?",
    session.id,
    "USER_ID"
)

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

Agent Engine

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

# 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 fix the temperature?",
    session.get("id"),
    "USER_ID"
)

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

Cloud Run

Lihat bagian Menguji agen Anda dalam dokumentasi deployment ADK Cloud Run.

GKE

Lihat bagian Menguji agen Anda dalam dokumentasi deployment ADK GKE.

Web ADK

Untuk menggunakan ADK Web, buka server lokal di http://localhost:8000.

Secara default, ADK Web akan menyetel ID pengguna ke user. Untuk mengganti ID pengguna default, sertakan userId dalam parameter kueri, seperti http://localhost:8000?userId=YOUR_USER_ID.

Untuk mengetahui informasi selengkapnya, lihat halaman ADK Web dalam dokumentasi ADK.

Contoh interaksi

Sesi pertama

Jika Anda menggunakan PreloadMemoryTool, agen akan mencoba mengambil memori di awal setiap giliran untuk mengakses preferensi yang sebelumnya dikomunikasikan pengguna kepada agen. Selama interaksi pertama agen dengan pengguna, tidak ada memori yang tersedia untuk diambil. Jadi, agen tidak mengetahui preferensi pengguna, seperti suhu yang diinginkan, seperti yang ditunjukkan dalam contoh berikut:

1. Giliran pertama:

   • Pengguna: "Bisakah Anda mengatur suhu?"

   • (Panggilan Alat): ADK mencoba mengambil kenangan; tidak ada kenangan yang tersedia.

   • Model: "Berapa suhu yang Anda inginkan?"

   • (Callback): ADK memicu pembuatan memori. Tidak ada kenangan yang diekstrak.

2. Giliran kedua:

   • Pengguna: Saya merasa nyaman pada suhu 22 derajat Celcius.

   • (Panggilan Alat): ADK mencoba mengambil kenangan; tidak ada kenangan yang tersedia.

   • Model: Oke, saya telah memperbarui suhu menjadi 71 derajat.

   • (Callback): ADK memicu pembuatan memori. Memori "Saya suka suhu 71 derajat" dibuat.

Sesi kedua

Memori yang diekstrak akan tersedia untuk sesi berikutnya dengan nama aplikasi dan ID pengguna yang sama. Jika pengguna memberikan informasi yang serupa atau bertentangan dengan kenangan yang ada, informasi baru akan digabungkan dengan kenangan yang ada.

1. Giliran pertama

   • Pengguna: Perbaiki suhu. Sangat tidak nyaman!

   • (Panggilan Alat): ADK mencoba mengambil kenangan. Memori "Saya suka suhu 71 derajat" diambil.

   • Model: Oke, saya telah memperbarui suhu menjadi 71 derajat.

   • (Callback): ADK memicu pembuatan memori. Tidak ada kenangan yang diekstrak, karena pengguna tidak membagikan apa pun yang bermakna untuk dipertahankan.

2. Giliran kedua

   • Pengguna: Sebenarnya, saya lebih suka suhu yang lebih hangat di pagi hari.

   • (Panggilan Alat): ADK mencoba mengambil kenangan. Memori "Saya suka suhu 71 derajat" diambil.

   • Model: Oke, saya sudah menaikkan suhu.

   • (Callback): ADK memicu pembuatan memori. Memori yang ada "Saya suka suhu 71 derajat" diperbarui menjadi "Saya biasanya suka suhu 71 derajat, tetapi saya suka suhu yang lebih hangat di pagi hari".

Catatan: Mungkin ada beberapa perbedaan dalam respons agen dan Bank Memori, bergantung pada model yang digunakan.

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, seperti 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

• Mulai cepat dengan Agent Engine SDK.