Panduan memulai dengan REST API

Tutorial ini menunjukkan cara melakukan panggilan REST API langsung ke Vertex AI Agent Engine Sessions dan Memory Bank untuk membuat dan menggunakan sesi serta memori jangka panjang. Gunakan REST API jika Anda tidak ingin framework agen mengatur panggilan untuk Anda, atau Anda ingin mengintegrasikan Sesi dan Bank Memori dengan framework agen selain Agent Development Kit (ADK).

Untuk panduan memulai menggunakan ADK, lihat Panduan memulai dengan Agent Development Kit.

Tutorial ini menggunakan langkah-langkah berikut:

  1. Buat instance Vertex AI Agent Engine untuk mengakses Sesi Vertex AI Agent Engine dan Bank Memori.
  2. Buat kenangan menggunakan opsi berikut:
  3. Mengambil kenangan.
  4. Pembersihan.

Sebelum memulai

Untuk menyelesaikan langkah-langkah yang ditunjukkan dalam tutorial ini, Anda harus menyiapkan project dan lingkungan terlebih dahulu.

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. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

    5.

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

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

    8.
  8. Jika Anda memilih project, pastikan Anda memiliki peran IAM Vertex AI user (roles/aiplatform.user) di project tersebut.

    9. Melakukan autentikasi ke Vertex AI

    Untuk menggunakan contoh Python di halaman ini dalam lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI, lalu siapkan Kredensial Default Aplikasi dengan kredensial pengguna Anda.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

  12. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    13. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan ADC untuk lingkungan pengembangan lokal dalam dokumentasi autentikasi Google Cloud .

    Buat instance Vertex AI Agent Engine Anda

    Untuk mengakses Sesi Vertex AI Agent Engine dan Bank Memori Vertex AI Agent Engine, Anda harus membuat instance Vertex AI Agent Engine terlebih dahulu. Anda tidak perlu men-deploy agen untuk mulai menggunakan Sesi dan Bank Memori. Tanpa deployment agen, pembuatan instance Vertex AI Agent Engine akan memerlukan waktu beberapa detik.

    Jika Anda ingin Vertex AI Agent Engine Memory Bank membuat memori untuk Anda menggunakan model bahasa besar (LLM), berikan memoryBankConfig.generationConfig dan sertakan model yang Anda inginkan untuk digunakan Memory Bank dalam membuat memori. Agen Layanan Reasoning Engine Vertex AI project Anda harus memiliki izin aiplatform.endpoints.predict untuk menggunakan model.

    import requests

import google.auth
import google.auth.transport.requests

credentials, _ = google.auth.default()
auth_req = google.auth.transport.requests.Request()
credentials.refresh(auth_req)

url = "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines"

response = requests.post(
    url=url,
    json={
        "contextSpec": {
            "memoryBankConfig": {
                "generationConfig": {
                    "model": f"projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_NAME"
                },
                "similaritySearchConfig": {
                    "embeddingModel": f"projects/PROJECT_ID/locations/LOCATION/publishers/google/models/EMBEDDING_MODEL_NAME"
                }
            }
        }
    },
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {credentials.token}"
    }

)

split_name = response.json()["name"].split("/")
agent_engine_name = "/".join(split_name[:-2])

    Ganti kode berikut:

    • PROJECT_ID: Project ID Anda.
    • LOCATION: Region Anda. Hanya us-central1 yang didukung untuk Bank Memori dan Sesi Agent Engine Vertex AI.
    • MODEL_NAME: Model LLM untuk membuat kenangan. Anda dapat menggunakan model Gemini atau Model Garden.
    • EMBEDDING_MODEL_NAME: (Opsional) Model penyematan untuk menemukan kenangan serupa bagi pengguna tertentu. Anda dapat menggunakan model yang didukung API Embedding yang mendukung panjang vektor 768 sebagai dimensi output.

    Membuat memori dari Sesi Vertex AI Agent Engine

    Setelah menyiapkan Sesi Vertex AI Agent Engine dan Bank Memori, Anda dapat membuat sesi dan menambahkan peristiwa ke sesi tersebut. Memori dibuat sebagai fakta dari percakapan pengguna dengan agen sehingga tersedia untuk interaksi pengguna di masa mendatang. Untuk mengetahui informasi selengkapnya, lihat Membuat dan mengambil kenangan.

    1. Buat sesi dengan ID pengguna yang tidak transparan. Semua kenangan yang dihasilkan dari sesi ini otomatis diberi kunci berdasarkan cakupan {"user_id": "USER_ID"}, kecuali jika Anda secara eksplisit memberikan cakupan saat membuat kenangan.

      from google.cloud import aiplatform_v1beta1

sessions_client = aiplatform_v1beta1.SessionServiceClient(
  client_options={
    "api_endpoint": "https://LOCATION-aiplatform.googleapis.com"
  },
  transport="rest")

session_lro = sessions_client.create_session(
  parent=AGENT_ENGINE_NAME,
  session={"user_id": "USER_ID"}
)
session_id = session_lro.operation.name.split("/")[-3]

      Ganti kode berikut:

      • LOCATION: Region Anda. Hanya us-central1 yang didukung untuk Bank Memori dan Sesi Agent Engine Vertex AI.

      • AGENT_ENGINE_NAME: Nama instance Vertex AI Agent Engine yang Anda buat atau instance Vertex AI Agent Engine yang sudah ada. Nama harus dalam format berikut: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

      • USER_ID: ID untuk pengguna Anda. Semua kenangan yang dihasilkan dari sesi ini otomatis diberi kunci berdasarkan cakupan {"user_id": "USER_ID"}, kecuali jika Anda secara eksplisit memberikan cakupan saat membuat kenangan.

    2. Upload acara secara berulang ke sesi Anda. Peristiwa dapat mencakup interaksi apa pun antara pengguna, agen, dan alat Anda. Daftar peristiwa yang diurutkan mewakili histori percakapan sesi Anda. Histori percakapan ini digunakan sebagai materi sumber untuk membuat kenangan bagi pengguna tertentu tersebut.

      event = aiplatform_v1beta1.SessionEvent(
    author="user",  # Required by Sessions.
    invocation_id="1",  # Required by Sessions.
    timestamp=datetime.now().strftime('%Y-%m-%dT%H:%M:%SZ'),  # Required by Sessions.
    content = aiplatform_v1beta1.Content(
        role="user",
        parts=[aiplatform_v1beta1.Part(text="Hello")]
    )
)

client.append_event(name=f"{agent_engine_name}/sessions/{session_id}", event=event)

    3. Untuk membuat kenangan dari histori percakapan Anda, picu permintaan pembuatan kenangan untuk sesi:

      credentials, _ = google.auth.default()
auth_req = google.auth.transport.requests.Request()
credentials.refresh(auth_req)

url = "https://LOCATION-aiplatform.googleapis.com/v1beta1/AGENT_ENGINE_NAME"

response = requests.post(
  url=f"{url}/memories:generate",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Bearer {credentials.token}",
  },
  json={
    "vertex_session_source": {
      "session": f"{agent_engine_name}/sessions/{session_id}"
    },
    # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
    "scope": SCOPE
  }
)

    Ganti kode berikut:

    • (Opsional) SCOPE: Kamus yang merepresentasikan cakupan kenangan yang dihasilkan, dengan maksimum 5 key-value pair dan tanpa karakter *. Misalnya, {"session_id": "MY_SESSION"}. Hanya kenangan dengan cakupan yang sama yang dipertimbangkan untuk penggabungan. Jika tidak diberikan, {"user_id": session.user_id} akan digunakan.

    Mengupload kenangan

    Sebagai alternatif untuk membuat kenangan menggunakan dialog mentah, Anda dapat mengupload kenangan secara langsung menggunakan CreateMemory. Daripada Memory Bank mengekstrak informasi dari konten Anda, Anda memberikan fakta yang harus disimpan tentang pengguna Anda secara langsung. Sebaiknya tulis fakta tentang pengguna dalam orang pertama (misalnya, I am a software engineer).

    credentials, _ = google.auth.default()
auth_req = google.auth.transport.requests.Request()
credentials.refresh(auth_req)

url = "https://LOCATION-aiplatform.googleapis.com/v1beta1/AGENT_ENGINE_NAME"

response = requests.post(
  url=f"{url}/memories",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Bearer {credentials.token}",
  },
  json={
    "fact": "This is a fact",
    "scope": {"user_id": "USER_ID"}
  }
)

    Mengambil dan menggunakan kenangan

    Anda dapat mengambil kenangan untuk pengguna dan menyertakannya dalam petunjuk sistem untuk memberi LLM akses ke konteks yang dipersonalisasi.

    Untuk mengetahui informasi selengkapnya tentang mengambil memori menggunakan metode berbasis cakupan, lihat Mengambil memori.

    response = requests.post(
  url=f"{url}/memories:retrieve",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Bearer {credentials.token}",
  },
  json={
    "scope": {"user_id": "USER_ID"}
  }
)

    Anda dapat menggunakan jinja untuk mengonversi kenangan terstruktur Anda menjadi perintah:

    
from jinja2 import Template

template = Template("""
<MEMORIES>
Here is some information about the user:
{% for memory in data.memories %}* {{ memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(data=response.json())

"""
Output:

<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""

    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 yang terkait dengan instance Vertex AI Agent Engine.

      credentials, _ = google.auth.default()
auth_req = google.auth.transport.requests.Request()
credentials.refresh(auth_req)

url = "https://LOCATION-aiplatform.googleapis.com/v1beta1/AGENT_ENGINE_NAME"

response = requests.delete(
    url=url,
    json={"force": True},
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {credentials.token}"
    }

)

    2. Hapus semua file yang dibuat secara lokal.

    Langkah berikutnya