Memori agen terkelola

Important

Fitur ini ada di Beta.

Memori agen yang dikelola memberikan agen Anda memori jangka panjang yang tahan lama dan bertahan di sepanjang percakapan. Azure Databricks menyimpan memori di Lakebase dan mengelola penyimpanan, pengindeksan, serta pencarian semantik untuk Anda, sehingga agen Anda dapat mengingat preferensi pengguna, keputusan masa lalu, dan konteks yang terkumpul tanpa Anda mengoperasikan basis data.

Note

Selama pratinjau, Anda akan ditagih untuk instance Lakebase yang menyimpan entri memori Anda. Tidak ada biaya tambahan yang berlaku untuk memori agen yang dikelola itu sendiri. Harga dapat berubah seiring berjalannya pratinjau.

Gunakan memori terkelola ketika Anda ingin agen Anda:

  • Ingat preferensi pengguna, fakta, dan keputusan di berbagai percakapan terpisah.
  • Personalisasi respons berdasarkan apa yang dipelajari agen dalam sesi sebelumnya.
  • Bagikan pengetahuan yang terkumpul di antara agen dan proyek.
  • Meningkatkan akurasi dan efisiensi dari waktu ke waktu.

Memori terkelola bekerja dengan agen yang dibangun di atas framework apa pun. Untuk riwayat percakapan jangka pendek dalam satu interaksi, gunakan managed agent sessions.

Persyaratan

  • Instal Python 3.10 atau versi lebih tinggi untuk menggunakan SDK AgentKit. AgentKit SDK adalah klien Databricks Python untuk API agen yang digunakan oleh contoh-contoh di bawah ini. Anda juga dapat memanggil REST API langsung dari bahasa apa saja, tanpa perlu Python.

Cara kerja memori terkelola

Hierarki sumber daya memori agen yang dikelola: penyimpanan memori berisi banyak entri memori, masing-masing diidentifikasi dengan actor_id, session_id opsional, dan jalur, serta menyimpan konten dan deskripsi.

Memori terkelola memiliki dua tingkat:

  • Penyimpanan memori adalah wadah yang dibatasi ruang kerja untuk memori agen. Membuat store akan secara otomatis menyiapkan penyimpanan pendukung Lakebase. Anda menyapa sebuah toko dengan display_name.
  • Entri memori adalah sebuah konten individual di sebuah toko. Setiap entri memiliki teks contentbebas, singkatan description yang digunakan untuk pengambilan, dan sekumpulan bidang yang mengatur serta mempartisinya:
    • actor_id (wajib): Siapa pemilik memori, seperti pengguna akhir atau agen lain.
    • session_id (opsional): mencatat dari sesi mana memori diambil, untuk pelacakan dan provenans. Biarkan kosong untuk memori yang tidak terkait dengan sesi tertentu.
    • path (wajib): jalur mirip sistem file yang mengatur entri dalam sebuah aktor, seperti /preferences/response-style.md.

Sebuah entri diidentifikasi secara unik oleh kombinasi , actor_idsession_id, dan path.

Pengambilan Data

Ambil memori dengan dua cara:

  • Daftar entri untuk aktor, yang opsional difilter berdasarkan session_id atau awalan path. Gunakan ini untuk menelusuri atau menampilkan indeks apa yang diketahui agen.
  • Cari entri aktor dengan kueri bahasa alami. Pencarian mengembalikan entri paling relevan yang diurutkan berdasarkan skor relevansi teks penuh (BM25).

Get started

Contoh-contoh ini mengatur memori terkelola untuk agen dukungan: mereka membuat penyimpanan memori, menyimpan preferensi pengguna, dan mengingatnya dalam percakapan berikutnya. Pilih klien yang sesuai dengan proyek Anda. Penyimpanan memori display_name harus terdiri dari 3 hingga 56 karakter, dimulai dengan huruf kecil, diakhiri dengan huruf atau angka, dan hanya berisi huruf kecil, angka, dan tanda hubung.

AgentKit SDK

AgentKit SDK adalah klien Databricks Python untuk API agen, yang didistribusikan dalam databricks-agentbricks paket. Perangkat ini mengautentikasi dengan SDK WorkspaceClientDatabricks .

  1. Instal AgentKit SDK:

    pip install databricks-agentbricks

  2. Buat penyimpanan memori untuk agen Anda. AgentKitClient Mengautentikasi dengan kredensial Anda WorkspaceClient :

    from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
memory_store = client.memory_stores.create("support-agent-memory")

  3. Simpan memori setelah agen mempelajari sesuatu yang bersifat jangka panjang tentang pengguna. actor_id menunjukkan memori ini milik siapa, path mengaturnya dalam aktor tersebut, dan description meningkatkan proses temu kembali:

    memory_store.add(
    actor_id="user-123",
    path="/preferences/communication.md",
    content="Prefers email over phone. Timezone: PST. Enterprise subscription.",
    description="User 123 communication preferences",
)

  4. Temukan kembali memori pengguna di percakapan berikutnya menggunakan pencarian bahasa alami:

    results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)

REST API

Klien memanggil API REST di bawah ./api/2.0/agents/memory-stores Panggil langsung untuk bahasa selain Python.

  1. Menghasilkan token OAuth dengan CLI Databricks:

    databricks auth login --host ${DATABRICKS_HOST}
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

  2. Buat penyimpanan memori untuk agen Anda:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"display_name": "support-agent-memory", "description": "Support agent memory"}'

  3. Simpan entri memori untuk pengguna. actor_id menunjukkan ingatan milik siapa ini, path mengaturnya, dan description meningkatkan proses temu kembali:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "path": "/preferences/communication.md", "content": "Prefers email over phone.", "description": "Communication preferences"}'

  4. Ingat ingatan pengguna dengan pencarian bahasa alami:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "query": "communication preferences"}'

Berikan alat memori kepada agen Anda

Agar agen dapat memutuskan kapan harus menyimpan dan mengambil kembali memori, jadikan operasi klien sebagai alat dan beri agen instruksi tentang kapan harus menggunakannya dalam prompt sistem. Tetapkan actor_id dalam kode aplikasi tepercaya berdasarkan identitas pengguna akhir yang terverifikasi. Jangan pernah membiarkan model memilih memori milik siapa yang boleh dibaca atau ditulis.

Contoh berikut membungkus AgentKit SDK memory_store dari Get started sebagai alat untuk OpenAI Agents SDK.

from agents import Agent, function_tool

def make_memory_tools(memory_store, actor_id: str):
    @function_tool
    def search_memory(query: str) -> str:
        """Search long-term memory for relevant facts about the user."""
        results = memory_store.search(actor_id=actor_id, query=query, limit=10)
        return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."

    @function_tool
    def save_memory(path: str, content: str, description: str = "") -> str:
        """Save a durable, long-term memory about the user."""
        memory_store.add(actor_id=actor_id, path=path, content=content, description=description)
        return f"Saved memory at {path}"

    return [search_memory, save_memory]

agent = Agent(
    name="Support agent",
    instructions="Save durable user preferences and recall them when relevant.",
    tools=make_memory_tools(memory_store, actor_id="user-123"),
)

Pola yang sama juga dapat diterapkan pada Claude Agent SDK dan kerangka kerja lainnya: bungkus operasi pencarian dan penambahan milik store sebagai jenis alat pada kerangka kerja tersebut.

Partisi dan amankan memori

Di dalam toko, actor_id adalah cara untuk membedakan ingatan milik siapa. Setiap daftar dan pencarian dibatasi ke satu actor_id, jadi pilihlah strategi yang sesuai dengan apa yang perlu diingat agen Anda:

  • Memori pribadi untuk setiap pengguna: Atur actor_id ke identitas pengguna akhir yang terverifikasi. Setiap pengguna mendapatkan partisi sendiri, dan agen hanya menarik kembali entri pengguna tersebut.
    • Contoh: Agen dukungan mengingat preferensi komunikasi dan tiket sebelumnya dari salah satu pengguna.
  • Memori bersama untuk grup: Atur actor_id ke kunci tetap yang Anda pilih, seperti ID tim, proyek, atau organisasi. Semua orang membaca dan menulis kenangan yang sama.
    • Contoh: Agen tim mengingat glosarium bersama tentang istilah perusahaan dan konvensi internal.
  • Memori dipisahkan berdasarkan hal lain: Buat actor_id dari nilai Anda sendiri, seperti ID tenant atau user:project komposit.
    • Contoh: Aplikasi multi-tenant menetapkan actor_id ke {tenant}:{user} agar pengguna dari tiap pelanggan tetap terisolasi satu sama lain.

Tetapkan actor_id dalam kode aplikasi Anda dari konteks pemanggil tepercaya: identitas pengguna akhir yang terverifikasi untuk memori per-pengguna, atau kunci tim atau proyek tepercaya untuk memori bersama. Jangan pernah biarkan model memilihnya. Jika strategi Anda bergantung pada identitas pengguna akhir, tolak permintaan yang tidak membawa identitas tersebut daripada kembali ke identitas bersama actor_id.

Warning

actor_id memisahkan memori, tetapi bukan kontrol akses. Penyimpanan memori terkelola dicakup dalam lingkup ruang kerja, sehingga setiap prinsipal yang dapat mengakses penyimpanan dapat membaca dan menulis setiap entri di semua aktor. Toko, bukan aktor, adalah batas keamanan. Untuk isolasi ketat antara tenant atau pengguna, buat penyimpanan memori terpisah per batas.

Agar principal lain, seperti service principal milik agen Anda, dapat menggunakan store, berikan akses kepadanya melalui operasi grant-permission milik store (memory_store.grant_permission(principal_id) dalam AgentKit SDK).

Limitations

  • Memori terkelola hanya menyediakan memori jangka panjang. Untuk riwayat percakapan jangka pendek, lihat sesi agen terkelola.
  • Pencarian adalah operasi pencarian teks lengkap (BM25) yang diurutkan berdasarkan relevansi dan mengembalikan kumpulan hasil top-N hingga 100 entri. Aplikasi ini tidak mendukung pencarian paginasi atau kesamaan vektor.
  • Kontrol akses ditegakkan di tingkat toko. Kontrol akses per entri dan per aktor tidak tersedia.
  • Toko display_name ini tidak dapat diubah setelah dibuat. Hanya description dapat diperbarui.

Langkah berikutnya

  • Terakhir diperbarui pada