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 kenangan menggunakan opsi berikut:
  2. Mengambil kenangan.
  3. Pembersihan.

Sebelum memulai

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

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 kenangan 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_name = "/".join(session_lro.operation.name.split("/")[0:-2])

    Ganti kode berikut:

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

    • 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")]
    )
)

sessions_client.append_event(name=session_name, event=event)

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

    client.agent_engines.generate_memories(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    "session": session_name
  },
  # 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 atau meminta agen Anda menambahkannya 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).

memory = client.agent_engines.create_memory(
    name=agent_engine.api_resource.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

AgentEngineMemoryOperation(
  done=True,
  metadata={
    "@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
    "genericMetadata": {
      "createTime": '2025-06-26T01:15:29.027360Z',
      "updateTime": '2025-06-26T01:15:29.027360Z'
    }
  },
  name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
  response=Memory(
    create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
    fact="This is a fact.",
    name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
    scope={
      "user_id": "123"
    },
    update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
  )
)
"""

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.

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.retrieve_memories(
        name=agent_engine.api_resource.name,
        scope={"user_id": "123"}
    )
)

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 retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(data=retrieved_memories)

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

    agent_engine.delete(force=True)

  2. Hapus semua file yang dibuat secara lokal.

Langkah berikutnya