Menyiapkan lingkungan untuk Memory Bank

Sebelum menggunakan Vertex AI Agent Engine Memory Bank, Anda harus menyiapkan lingkungan. Perhatikan bahwa meskipun Memory Bank adalah bagian dari Agent Engine, Anda tidak perlu men-deploy kode ke Agent Engine Runtime untuk menggunakan Memory Bank.

Menyiapkan project Google Cloud

Setiap project dapat diidentifikasi dengan dua cara: nomor project atau project ID. PROJECT_NUMBER dibuat secara otomatis saat Anda membuat project, sedangkan PROJECT_ID dibuat oleh Anda, atau siapa pun yang membuat project. Untuk menyiapkan project:

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

    8.

    Mendapatkan peran yang diperlukan

    Untuk mendapatkan izin yang Anda perlukan untuk menggunakan Vertex AI Agent Engine, minta administrator Anda untuk memberi Anda peran IAM Vertex AI User (roles/aiplatform.user) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

    Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

    Jika Anda membuat permintaan ke Memory Bank dari agen yang di-deploy di Google Kubernetes Engine atau Cloud Run, pastikan akun layanan Anda memiliki izin yang diperlukan. Agen Layanan Reasoning Engine sudah memiliki izin yang diperlukan untuk membaca dan menulis memori, sehingga permintaan keluar dari Runtime Agent Engine seharusnya sudah memiliki izin untuk mengakses Bank Memori.

    Menyiapkan lingkungan Anda

    Bagian ini mengasumsikan bahwa Anda telah menyiapkan lingkungan pengembangan Python, atau menggunakan runtime dengan lingkungan pengembangan Python (seperti Colab).

    Menginstal library

    Instal Vertex AI SDK:

      pip install google-cloud-aiplatform>=1.104.0

    Autentikasi

    Petunjuk autentikasi bergantung pada apakah Anda menggunakan Vertex AI dalam mode ekspres:

    • Jika Anda tidak menggunakan Vertex AI dalam mode ekspres, ikuti petunjuk di Mengautentikasi ke Vertex AI.

    • Jika Anda menggunakan Vertex AI dalam mode ekspres, siapkan autentikasi dengan menyetel kunci API di lingkungan:

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

    Menyiapkan klien Vertex AI SDK

    Jalankan kode berikut untuk menyiapkan klien Vertex AI SDK:

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

    di mana

    Mengonfigurasi instance Agent Engine

    Untuk mulai menggunakan Memory Bank, Anda memerlukan instance Agent Engine terlebih dahulu.

    Anda dapat melakukan salah satu hal berikut:

    Menggunakan instance yang ada

    Jika Anda tidak perlu mengubah instance Agent Engine yang ada, jalankan perintah berikut untuk mengonfigurasi instance untuk Memory Bank:

    agent_engine = client.agent_engines.get(name="AGENT_ENGINE_NAME")

    Ganti kode berikut:

    • AGENT_ENGINE_NAME: Nama Agent Engine. Harus dalam format projects/.../locations/.../reasoningEngines/.... Lihat region yang didukung untuk Bank Memori.

    Membuat atau mengupdate instance

    Saat membuat atau memperbarui instance Agent Engine, Anda dapat mengganti default Agent Engine untuk melakukan modifikasi berikut:

    Buat

    Bank Memori diaktifkan secara default saat Anda membuat instance Agent Engine. Anda dapat menggunakan instance di lingkungan apa pun, termasuk Google Kubernetes Engine dan Cloud Run. Anda memerlukan nama Agent Engine yang mengidentifikasi Bank Memori dan izin yang memadai untuk memanggil Bank Memori.

      agent_engine = client.agent_engines.create()

    Instance baru kosong kecuali jika Anda membuat atau membuat kenangan terlebih dahulu.

    Perbarui

    Anda dapat memperbarui instance Agent Engine yang ada jika ingin memperbarui Agent Engine sambil tetap mempertahankan memori yang disimpan dalam instance. Anda dapat melakukan update seperti mengubah konfigurasi Bank Memori atau men-deploy agen ke Runtime Agent Engine.

      agent_engine = client.agent_engines.update(
        # If you have an existing AgentEngine, you can access the name using `agent_engine.api_resource.name`.
        name="AGENT_ENGINE_NAME",
        # Optional.
        agent_engine=...,
        # Optional.
        config=...
  )

    Ganti kode berikut:

    • AGENT_ENGINE_NAME: Nama Agent Engine. Harus dalam format projects/.../locations/.../reasoningEngines/.... Lihat region yang didukung untuk Bank Memori.

    Menetapkan konfigurasi Bank Memori Anda

    Anda dapat mengonfigurasi Bank Memori untuk menyesuaikan cara kenangan dibuat dan dikelola. Jika konfigurasi tidak diberikan, Bank Memori akan menggunakan setelan default.

    # Optional.
similarity_search_config = {
        "similarity_search_config": {
                "embedding_model": "EMBEDDING_MODEL",
        }
}

# Optional
generation_config = {
      "generation_config": {
            "model": "LLM_MODEL",
      }
}

context_spec = {
      "context_spec": {
            "memory_bank_config": {
                  **similarity_search_config,
                  **generation_config
            }
      }
}

# Create an Agent Engine with a Memory Bank Config.
agent_engine = client.agent_engines.create(
      config={
            # Optional.
            **context_spec
      }
)

    Ganti kode berikut:

    • EMBEDDING_MODEL: Model embedding teks Google yang akan digunakan untuk penelusuran kesamaan, dalam format projects/{project}/locations/{location}/publishers/google/models/{model}. Memory Bank menggunakan text-embedding-005 sebagai model default. Jika Anda memperkirakan percakapan pengguna akan menggunakan bahasa selain bahasa Inggris, gunakan model yang mendukung beberapa bahasa, seperti gemini-embedding-001 atau text-multilingual-embedding-002, untuk meningkatkan kualitas pengambilan.

    • LLM_MODEL: Model LLM Google yang akan digunakan untuk mengekstrak dan menggabungkan kenangan, dalam format projects/{project}/locations/{location}/publishers/google/models/{model}. Memory Bank menggunakan gemini-2.0-flash-001 sebagai model default.

    Men-deploy agen dengan memori ke Agent Engine

    Meskipun Bank Memori dapat digunakan di runtime apa pun, Anda juga dapat menggunakan Bank Memori dengan Agent Engine Runtime untuk membaca dan menulis memori dari agen yang di-deploy.

    Untuk men-deploy agen dengan Memory Bank di Vertex AI Agent Engine Runtime, pertama-tama siapkan lingkungan Anda untuk runtime Agent Engine. Kemudian, siapkan agen Anda untuk di-deploy di Agent Engine Runtime dengan integrasi memori. Agen yang di-deploy harus melakukan panggilan untuk membaca dan menulis memori sesuai kebutuhan.

    AdkApp

    Jika Anda menggunakan template Agent Development Kit Agent Engine, agen akan menggunakan VertexAiMemoryBankService secara default saat di-deploy ke runtime Agent Engine. Artinya, agen Anda otomatis menggunakan Bank Memori untuk mengelola memori.

    from google.adk.agents import Agent
from vertexai.preview.reasoning_engines import AdkApp

# Develop an agent using the ADK template.
agent = Agent(...)

adk_app = AdkApp(
      agent=adk_agent,
      ...
)

# Deploy the agent to Agent Engine runtime.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket":
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

    Saat dijalankan secara lokal, template ADK menggunakan InMemoryMemoryService secara default. Jika Anda ingin menggunakan instance Agent Engine yang berbeda untuk memori dan deployment, atau menggunakan AdkApp dengan Bank Memori secara lokal, Anda dapat mengganti Bank Memori yang digunakan instance:

    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
)

agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket":
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

    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.

    Untuk mengetahui informasi selengkapnya tentang penggunaan Bank Memori dengan ADK, lihat Panduan memulai dengan Agent Development Kit.

    Agen kustom

    Anda dapat menggunakan Memory Bank dengan agen kustom yang di-deploy di Agent Engine Runtime.

    Jika ingin menggunakan instance Agent Engine yang sama untuk Memory Bank dan Agent Engine Runtime, Anda dapat membaca variabel lingkungan GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION,GOOGLE_CLOUD_AGENT_ENGINE_ID untuk menyimpulkan nama Agent Engine dari lingkungan:

    project = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION")
agent_engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")

agent_engine_name = f"projects/{project}/locations/{location}/reasoningEngines/{agent_engine_id}"

    Langkah berikutnya