Anda dapat menggunakan Memory Bank untuk membuat profil terstruktur, yang merupakan struktur data dengan skema statis yang diisi dan diperbarui menggunakan LLM. Dengan menentukan skema tetap, Anda memastikan agen memiliki akses langsung dan latensi rendah ke informasi yang terus berkembang tanpa memerlukan operasi penelusuran yang mahal selama sesi.
Untuk menyelesaikan langkah-langkah yang ditunjukkan dalam panduan ini, Anda harus terlebih dahulu mengikuti langkah-langkah dalam Menyiapkan Bank Memori.
Ringkasan
Dengan menggunakan profil terstruktur bersama agen Anda, informasi yang diekstrak—seperti stack teknologi atau preferensi pengguna—dapat tersedia dengan cepat, ringkas, dan dalam format yang konsisten. Misalnya, Anda dapat mengambil profil yang menyertakan konten seperti:
MemoryProfile(
profile={
"technical_stacks": "ADK, Python",
"preferred_language": "Python",
"tone_preference": "Succinct"
},
schema_id="user-profile"
)
Profil terstruktur dioptimalkan untuk pengambilan data dengan latensi rendah, karena pekerjaan berat dalam menyeleksi informasi dilakukan pada waktu pembuatan. Chip ini sangat cocok untuk memulai interaksi antara agen dan pengguna.
Memahami profil memori terstruktur
Profil terstruktur dibuat melalui metode yang sama (GenerateMemories dan IngestEvents) yang Anda gunakan untuk memori bahasa alami. Setelah Anda menentukan skema, Memory Bank akan otomatis mencoba membuat profil yang sesuai dengan skema Anda menggunakan sumber data yang diberikan.
Saat menggunakan profil terstruktur, Memory Bank melakukan operasi berikut selama pembuatan memori:
- Ekstraksi: Mengekstrak informasi dan konteks yang sesuai dengan skema dari sumber data. Hanya informasi yang sesuai dengan skema yang akan diekstrak. Anda dapat memeriksa informasi dan konteks yang diekstrak menggunakan revisi memori.
- Konsolidasi: Memperbarui (jika perlu) kolom yang ada di profil. LLM akan menilai cara memperbarui konten yang ada berdasarkan informasi dan konteks yang baru diekstrak. Jika kolom belum ada di profil, penggabungan akan dilewati, dan kolom akan diperbarui langsung dengan informasi yang diekstrak.
Profil diisolasi berdasarkan scope (seperti {"user_id": "123"}) yang Anda berikan saat memasukkan data ke Memory Bank. Untuk setiap skema dan cakupan, Memory Bank mempertahankan satu profil sebagai sumber tepercaya. Profil yang dibuat terdiri dari satu atau beberapa instance Memory. Setiap instance Memory mewakili satu kolom dalam profil yang dapat Anda gunakan untuk memeriksa metadata dan histori revisi kolom, seperti:
Memory(
create_time=datetime.datetime(...),
memory_type=<MemoryType.STRUCTURED_PROFILE: 'STRUCTURED_PROFILE'>,
name='projects/.../locations/.../reasoningEngines/.../memories/...',
scope={
'user_id': '123'
},
structured_content=MemoryStructuredContent(
data={
'language_preference': 'Java'
},
schema_id='user-profile'
),
update_time=datetime.datetime(...),
expire_time=datetime.datetime(...),
metadata={...}
)
Definisi skema
Profil yang dihasilkan Memory Bank sesuai dengan skema yang ditentukan saat instance Agent Platform dibuat atau diperbarui. Anda dapat menggunakan model pydantic untuk menentukan kolom yang ingin diekstrak dan dikelola oleh Memory Bank. Contoh:
from pydantic import BaseModel, Field
from typing import Literal
class UserProfile(BaseModel):
name: str = Field(
description="Name of the user.")
technical_stack: str = Field(
description="Comma-separated list tools or languages used by the user.")
primary_goal: str = Field(
description="The main objective the user is pursuing.")
expertise_level: str = Field(
description="Current skill level (e.g., Junior, Senior).")
job_status: Literal['unemployed', 'part_time', 'full_time', 'student'] = Field(
description="The job status of the individual")
Upload skema ke Memory Bank saat Anda membuat atau mengupdate instance Agent Platform. Anda dapat menentukan beberapa skema profil independen; setiap skema harus diidentifikasi oleh ID unik:
schema_config = {
"id": "user-profile",
"memory_schema": UserProfile.model_json_schema()
}
memory_bank = client.agent_engines.create(
config={
"context_spec": {
"memory_bank_config": {
"structured_memory_configs": [
{
"schema_configs": [schema_config]
}
]
}
}
}
)
Secara default, Memory Bank akan selalu mencoba mengekstrak memori bahasa alami. Anda dapat menonaktifkan pembuatan memori bahasa alami jika hanya ingin Memory Bank membuat profil:
memory_bank = client.agent_engines.create(
config={
"context_spec": {
"memory_bank_config": {
"structured_memory_configs": [
{
"schema_configs": [schema_config]
}
],
# Optional: Disable natural language memories.
"customization_configs": [
{"disable_natural_language_memories": True}
]
}
}
}
)
Pembuatan profil
Anda memicu pembuatan memori terstruktur dengan memberikan histori percakapan (peristiwa) ke metode GenerateMemories atau IngestEvents. Seperti halnya memori bahasa alami, Bank Memori menggunakan LLM untuk mengekstrak informasi yang bermakna dari sumber data dan menggabungkannya dengan memori yang ada.
Contoh
Contoh berikut menjelaskan pembuatan profil memori menggunakan skema yang ditentukan sebelumnya.
Dalam kumpulan peristiwa pertama yang dikirim ke Memory Bank untuk cakupan {"user_id": "123"}, pengguna menunjukkan bahwa mereka bekerja dengan agen ADK:
client.agent_engines.memories.generate(
name=memory_bank.api_resource.name,
scope={"user_id": "123"},
direct_contents_source={
"events": [
{"content": {
"parts": [{
"text": "Can you help me build an ADK agent that organizes my daily tasks?"}]}}]
}
)
Memory Bank mengekstrak "ADK" untuk kolom technical_stack dalam skema. Tidak ada kolom lain yang diisi karena peristiwa yang diproses tidak berisi informasi yang relevan untuk skema lainnya. Karena ini adalah interaksi pertama untuk cakupan ini, penggabungan dilewati dan profil diinisialisasi dengan nilai awal ini.
result = client.agent_engines.memories.retrieve_profiles(
name=memory_bank.api_resource.name,
scope={"user_id": "123"},
)
"""
Returns:
RetrieveProfilesResponse(
profiles={
'user-profile': MemoryProfile(
profile={
'technical_stack': 'ADK'
},
schema_id='user-profile'
)
}
)
"""
Dalam kumpulan peristiwa berikutnya yang dikirim ke Memory Bank, pengguna menunjukkan bahwa dia adalah seorang siswa dan terutama membuat kode di Python:
client.agent_engines.memories.generate(
name=memory_bank.api_resource.name,
scope={"user_id": "123"},
direct_contents_source={
"events": [
{"content": {
"parts": [
{"text": "Do you have any career recommendations for students that specialize in Python?"}]}}]
}
)
Memory Bank mengekstrak "Python" dan status "siswa" dari interaksi. Fragmen technical_stack digabungkan, dengan menambahkan "Python" ke entri "ADK" yang ada. Sistem mengisi kolom job_status yang sebelumnya kosong dengan enum "student" dan melewati langkah penggabungan.
result = client.agent_engines.memories.retrieve_profiles(
name=memory_bank.api_resource.name,
scope=scope
)
"""
Returns:
RetrieveProfilesResponse(
profiles={
'user-profile': MemoryProfile(
profile={
'technical_stack': 'ADK, Python',
'job_status': 'student'
},
schema_id='user-profile'
)
}
)
"""
Pengambilan profil
Setelah dibuat, Anda dapat mengambil profil gabungan untuk cakupan tertentu menggunakan metode RetrieveProfiles. Tindakan ini akan menampilkan data terbaru yang dipetakan ke skema Anda.
result = client.agent_engines.memories.retrieve_profiles(
name=memory_bank.api_resource.name,
scope={"user_id": "123"},
)
# Accessing the data
for profile in result.profiles.values():
print(profile)
# Output: {'technical_stack': 'ADK, Python', 'job_status': 'student', ...}
Pemeriksaan profil
Di balik layar, profil terdiri dari kenangan individu berjenis STRUCTURED_PROFILE. Setiap kolom dalam skema Anda dipetakan ke satu memori per cakupan, sehingga memungkinkan pengamatan terperinci.
Meskipun RetrieveProfiles adalah metode utama untuk pengambilan profil produksi, Anda dapat memeriksa setiap memori untuk mengaudit evolusi profil. Hal ini memberikan akses ke:
- Metadata Tingkat Kolom: Lihat dan perbarui waktu aktif (TTL) dan
Memory.metadatatertentu untuk setiap kolom dalam profil. - Histori Revisi: Lacak silsilah kolom untuk melihat nilai historis dan konteks percakapan spesifik yang memicu setiap perubahan.
Misalnya, Anda dapat menggunakan RetrieveMemories untuk mengambil semua kenangan yang berisi fragmen profil pengguna. Secara default, RetrieveMemories hanya mengambil memori bahasa alami, jadi Anda harus meminta memori STRUCTURED_PROFILE secara eksplisit:
client.agent_engines.memories.retrieve(
name="...",
scope={"user_id": "123"},
config={
"memory_types": ["STRUCTURED_PROFILE"]
}
)
"""
Returns:
[RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
create_time=datetime.datetime(...),
memory_type=<MemoryType.STRUCTURED_PROFILE: 'STRUCTURED_PROFILE'>,
name='projects/.../locations/.../reasoningEngines/.../memories/...',
scope={
'user_id': '1'
},
structured_content=MemoryStructuredContent(
data={
'technical_stack': 'ADK, Python'
},
schema_id='user'
),
update_time=datetime.datetime(...)
)
)]
"""
Kemudian, Anda dapat mengambil histori revisi fragmen profil terstruktur ini untuk memeriksa bagaimana perubahan kolom profil dari waktu ke waktu dan konteks di sekitar setiap perubahan tersebut:
for retrieved_memory in list(results):
list(client.agent_engines.memories.revisions.list(
name=retrieved_memory.memory.name
))
"""
Returns:
[MemoryRevision(
create_time=datetime.datetime(...),
expire_time=datetime.datetime(...),
extracted_memories=[
IntermediateExtractedMemory(
context='The user indicated that they have expertise in Python when asking about career options.',
structured_data={
'technical_stack': 'Python'
}
),
],
name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...',
structured_data={
'technical_stack': 'ADK, Python'
}
),
MemoryRevision(
create_time=datetime.datetime(...),
expire_time=datetime.datetime(...),
extracted_memories=[
IntermediateExtractedMemory(
context='The user indicated that they need help building an ADK agent',
structured_data={
'technical_stack': 'ADK'
}
),
],
name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...',
structured_data={
'technical_stack': 'ADK'
}
)]
"""