Halaman ini diterjemahkan oleh Cloud Translation API.

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:

Buat agen dan peluncur ADK lokal Anda. Runner ADK menghubungkan agen Anda ke layanan yang menyediakan pengelolaan sesi dan memori.
Berinteraksi dengan agen Anda untuk membuat memori jangka panjang secara dinamis yang dapat diakses di seluruh sesi.
Pembersihan.

Untuk melakukan panggilan langsung ke Memory Bank tanpa orkestrasi ADK, lihat Panduan memulai 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 terlebih dahulu mengikuti langkah-langkah dalam Menyiapkan Bank Memori.

Menetapkan variabel lingkungan

Untuk menggunakan ADK, tetapkan variabel lingkungan Anda:

Google Cloud Project

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.

Mode Ekspres Vertex AI

import os

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

Ganti kode berikut:

API_KEY: Kunci API Mode Ekspres Vertex AI Anda. Anda dapat mendaftar dengan akun Gmail untuk mendapatkan kunci API melalui Pendaftaran Mode Ekspres jika Anda adalah pengguna baru Google Cloud.

Buat agen ADK Anda

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()]
)

Buat layanan memori VertexAiMemoryBankService, yang digunakan runner ADK untuk mengambil kenangan. Opsi ini bersifat opsional jika Anda menggunakan template ADK Agent Engine, bukan menentukan runtime ADK Anda sendiri. Jika Anda ingin mengonfigurasi perilaku instance Memory Bank, lihat panduan penyiapan.

Google Cloud Project

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
)

Ganti kode berikut:

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

Mode Ekspres Vertex AI

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
)

Ganti kode berikut:

API_KEY: Kunci API Mode Ekspres Vertex AI Anda. Anda dapat mendaftar dengan akun Gmail untuk mendapatkan kunci API melalui Pendaftaran Mode Ekspres jika Anda adalah pengguna baru Google Cloud.

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 peluncur ADK. Jika Anda ingin mengotomatiskan pembuatan memori dengan ADK, Anda harus 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 diorkestrasi oleh runner ADK saat Anda menyediakan alat Memori ke agen.

Buat ADK Runtime, yang mengatur 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.

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)

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 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.
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 yang akan digunakan untuk menyiapkan 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:

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

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.

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.

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

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.

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

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

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`

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)

Template ADK Agent Engine

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

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`

# 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?

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

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

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

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.

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

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:

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)
```
Hapus semua file yang dibuat secara lokal.

Langkah berikutnya

Panduan memulai dengan Agent Engine SDK.

Panduan memulai dengan Agent Development Kit Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Menetapkan variabel lingkungan

Google Cloud Project

Mode Ekspres Vertex AI

Buat agen ADK Anda

Google Cloud Project

Mode Ekspres Vertex AI

adk.Runner

Template ADK Agent Engine

Berinteraksi dengan agen Anda

adk.Runner

Template ADK Agent Engine

adk.Runner

Template ADK Agent Engine

adk.Runner

Template ADK Agent Engine

Pembersihan

Langkah berikutnya

Panduan memulai dengan Agent Development Kit

`adk.Runner`

`adk.Runner`

`adk.Runner`

`adk.Runner`