Mulai cepat dengan Vertex AI Agent Engine SDK

Tutorial ini menunjukkan cara melakukan panggilan API langsung ke Sesi Vertex AI Agent Engine dan Memory Bank menggunakan Vertex AI Agent Engine SDK. Gunakan Vertex AI Agent Engine SDK 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:

Buat kenangan menggunakan opsi berikut:
- Membuat memori menggunakan Bank Memori Vertex AI Agent Engine: Tulis sesi dan peristiwa ke Sesi Vertex AI Agent Engine sebagai sumber untuk Bank Memori Vertex AI Agent Engine guna membuat memori.
- Mengupload kenangan secara langsung: Tulis kenangan Anda sendiri atau minta agen Anda membuat kenangan jika Anda menginginkan kontrol penuh atas informasi yang dipertahankan.
Mengambil kenangan.
Pembersihan.

Sebelum memulai

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

Membuat memori dengan Sesi Agent Engine Vertex AI

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.

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.
```
import vertexai

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

# This assumes that you already have an Agent Engine instance. If you don't,
# you can create one using `agent_engine = client.agent_engines.create()`.
session = client.agent_engines.sessions.create(
  # The name can be fetched using `agent_engine.api_resource.name`.
  name="AGENT_ENGINE_NAME",
  user_id="USER_ID"
)
```
Ganti kode berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region Anda. Lihat wilayah yang didukung untuk fitur Bank Memori.
- 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.

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.

import datetime

client.agent_engines.sessions.events.append(
  name=session.response.name,
  author="user",  # Required by Sessions.
  invocation_id="1",  # Required by Sessions.
  timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required by Sessions.
  config={
    "content": {
      "role": "user",
      "parts": [{"text": "hello"}]
    }
  }
)

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

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...".
    "session": session.response.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 GenerateMemories dengan fakta yang telah diekstrak. Daripada Memory Bank mengekstrak informasi dari konten Anda, Anda memberikan fakta yang harus disimpan tentang pengguna Anda secara langsung.

Untuk memastikan konsistensi dengan kenangan yang dihasilkan, coba tulis fakta yang telah diekstrak sebelumnya dalam perspektif yang sama dengan yang telah Anda konfigurasi untuk cakupan tertentu. Secara default, kenangan dibuat dalam perspektif orang pertama (misalnya, I am a software engineer).

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Ganti kode berikut:

FACT: Fakta yang telah diekstrak sebelumnya yang harus digabungkan dengan memori yang ada. Anda dapat memberikan hingga 5 fakta yang telah diekstrak sebelumnya dalam daftar seperti berikut:
```
{"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
```
SCOPE: Kamus, yang mewakili cakupan kenangan yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya kenangan dengan cakupan yang sama yang dipertimbangkan untuk penggabungan.

Atau, Anda dapat menggunakan CreateMemory untuk mengupload kenangan tanpa menggunakan Bank Memori untuk ekstraksi atau konsolidasi memori.

memory = client.agent_engines.memories.create(
    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 memori untuk pengguna dan menyertakannya dalam petunjuk sistem untuk memberi LLM akses ke konteks yang dipersonalisasi.

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

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.memories.retrieve(
        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>
"""

Menghapus kenangan

Ada beberapa cara untuk menghapus kenangan dari instance Bank Kenangan Anda, bergantung pada cara Anda ingin memilih kenangan yang harus dihapus.

Menghapus berdasarkan nama resource

Jika Anda tahu persis resource memori yang ingin dihapus, Anda dapat menghapus memori tertentu menggunakan nama resource-nya:

client.agent_engines.memories.delete(
    name=MEMORY_NAME,
    config={
        # Set to false (default) if you want to delete the memory asynchronously.
        "wait_for_completion": True
    }
)

Ganti kode berikut:

MEMORY_NAME: Nama Memori yang akan dihapus. Nama harus dalam format berikut: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Anda dapat menemukan nama Kenangan dengan mengambil kenangan.

Menghapus menurut kriteria

Anda dapat menggunakan penghapusan berbasis kriteria untuk menghapus satu atau beberapa kenangan. Hanya kenangan yang cocok dengan filter yang diberikan yang akan dihapus.

operation = client.agent_engines.memories.purge(
    name=agent_engine.api_resource.name,
    filter=FILTER_STRING,
    # Set to false (default) if you want to stage but not execute the purge operation.
    force=True,
    config={
        # Set to false (default) if you want to purge memories asynchronously.
        "wait_for_completion": True
    }
)

Ganti kode berikut:

FILTER_STRING: String yang menggunakan sintaksis EBNF untuk memfilter kolom sistem. Kolom sistem mencakup create_time, update_time, fact, dan topics. Lihat dokumentasi ini untuk mempelajari lebih lanjut cara memfilter kolom sistem.

Operasi ini akan menampilkan jumlah kenangan yang dihapus (jika force=True) atau akan dihapus jika operasi dijalankan (jika force=False).

print(operation.response.purge_count)

Menghapus berdasarkan makna semantik

Selama pembuatan memori, Bank Memori akan memutuskan apakah akan membuat, memperbarui, atau menghapus memori berdasarkan konten informasi yang baru diekstrak dan memori yang ada. Kenangan dapat dihapus jika informasi baru bertentangan dengan kenangan tersebut atau jika konten yang diekstrak menginstruksikan Bank Memori untuk melupakan subjek (dalam kasus topik memori EXPLICIT_INSTRUCTIONS).

Misalnya, permintaan berikut akan menghapus kenangan yang ada yang berisi informasi tentang preferensi diet, jika ada untuk scope tertentu:

from google import genai

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": [{
        "content": genai.types.Content(
          role="user",
          parts=[
            genai.types.Part.from_text(text="Forget my dietary preferences.")
          ]
        )
      }]
    },
    scope={...}
)

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 yang terkait dengan instance Vertex AI Agent Engine.
```
agent_engine.delete(force=True)
```
Hapus semua file yang dibuat secara lokal.

Langkah berikutnya

Mulai cepat dengan Agent Development Kit.

Mulai cepat dengan Vertex AI Agent Engine SDK Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Membuat memori dengan Sesi Agent Engine Vertex AI

Mengupload kenangan

Mengambil dan menggunakan kenangan

Menghapus kenangan

Menghapus berdasarkan nama resource

Menghapus menurut kriteria

Menghapus berdasarkan makna semantik

Pembersihan

Langkah berikutnya

Mulai cepat dengan Vertex AI Agent Engine SDK