Memori agen

Important

Fitur ini ada di Beta. Untuk menggunakannya, admin workspace harus mengaktifkan Agent Memory Sessions dari halaman Pratinjau . Lihat Kelola Pratinjau Azure Databricks.

Memori agen memberikan agen Anda memori jangka panjang yang bertahan di seluruh percakapan. Azure Databricks menyimpan memori di Lakebase dan mengelola penyimpanan, pengindeksan, serta pencarian untuk Anda, sehingga agen Anda dapat mengingat preferensi pengguna, keputusan sebelumnya, 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 Agent Memory itu sendiri. Harga dapat berubah seiring berjalannya pratinjau.

Gunakan memori agen saat Anda ingin agen Anda melakukan hal berikut:

  • 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 agen bekerja dengan agen yang dibangun di atas kerangka kerja apa pun. Untuk riwayat percakapan jangka pendek dalam satu interaksi, gunakan sesi agen.

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.
  • Untuk menggunakan memory_store.put() atau memory_store.list(path=...), instal databricks-agentbricks 0.6.0 ke atas.

Cara kerja memori agen

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

Memori agen memiliki dua tingkat:

  • Penyimpanan memori adalah wadah yang dibatasi ruang kerja untuk memori agen. Membuat store akan secara otomatis menyiapkan penyimpanan pendukung Lakebase. Anda mereferensikan toko dengan ID tokonya, yang Anda pilih saat membuat toko.
  • 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): sesi tempat ingatan tersebut terkait. Biarkan tidak diatur untuk memori yang berlaku di semua sesi aktor.
    • 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. Jalur yang sama di bawah dua sesi berbeda, atau di bawah satu sesi dan tanpa satu, memiliki dua entri terpisah.

Entri masuk ke store dengan dua cara: agen atau aplikasi Anda menulisnya langsung, atau pipeline memori menyaringnya dari percakapan di session store.

Pengambilan Data

Ambil memori dengan dua cara:

  • Daftar entri untuk aktor, yang secara opsional difilter berdasarkan session_id, path awalan, atau path yang persis. 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.

Filter session_id pada salah satu operasi hanya mengembalikan entri yang disimpan pada sesi tersebut. Ia tidak mengembalikan entri yang disimpan tanpa sesi.

Get started

Contoh AgentKit SDK dan REST API mengatur memori agen untuk agen dukungan: mereka membuat penyimpanan memori, menyimpan preferensi pengguna, dan mengingatnya dalam percakapan berikutnya. Contoh CLI Agent Bricks menghubungkan penyimpanan memori ke agen yang Anda bangun dan deploy bersama CLI. Pilih klien yang sesuai dengan proyek Anda. ID penyimpanan memori 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",
)

    add() gagal dengan ALREADY_EXISTS jika entri sudah ada di jalur tersebut. Untuk membuat entri atau memperbarui yang sudah ada, panggil memory_store.put() dengan argumen yang sama.

  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?managed_memory_store_id=support-agent-memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"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"}'

    Jika entri sudah ada di jalur tersebut, permintaan gagal dengan ALREADY_EXISTS (HTTP 409). Untuk memperbarui entri yang ada, cari berdasarkan jalur. Lookup mengembalikan entri jalur untuk setiap sesi, jadi pilih yang session_id-nya cocok. Segmen terakhir dari name-nya adalah ID entri:

    curl -G "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  --data-urlencode "actor_id=user-123" --data-urlencode "path=/preferences/communication.md"

    Kemudian perbarui isi entri berdasarkan ID-nya:

    curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries/<entry-id>?update_mask=content" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"content": "Prefers email over phone. Timezone: PST."}'

  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"}'

Agen Bricks

Jika Anda membangun agen dengan Agent Bricks CLI, agentbricks init mendeklarasikan penyimpanan memori di agent.toml. agentbricks deploy membuat penyimpanan jika belum ada dan memberikan akses kepadanya kepada agen yang di-deploy.

Pilih jalur:

  • Mulai kosong (sebagian besar agen): Terapkan agen. agentbricks deploy membuat penyimpanan memori yang dideklarasikan oleh agentbricks init. Untuk menyebarkan agen bernama my-agent, jalankan hal berikut:

    agentbricks deploy my-agent

  • Mulailah dengan memori yang sudah ada di store: Buat store terlebih dahulu, tambahkan entri, lalu ikat store ke agen dan terbarkan.

    1. Untuk membuat toko bernama my-agent-memory, jalankan hal berikut. Output mencakup ID toko, yaitu pengenal yang dihasilkan terpisah dari nama toko:

      agentbricks memory stores create --name my-agent-memory

    2. Untuk menambahkan entri, jalankan hal berikut, menggantinya <store-id> dengan ID toko dari langkah sebelumnya:

      agentbricks memory entries create --store <store-id> --actor-id you@example.com \
  --path /preferences/style.md --content "Prefers Python and concise answers with code examples."

    3. Untuk mengaitkan store dan menerapkan agen, jalankan hal berikut. agentbricks memory bind mengganti nama toko di agent.toml, dan agentbricks deploy menemukan toko yang ada berdasarkan nama dan menggunakannya alih-alih membuat toko baru:

      agentbricks memory bind my-agent-memory
agentbricks deploy my-agent

--path adalah kunci entri di dalam penyimpanan, bukan file di mesin Anda. --actor-id adalah pengguna pemilik memori tersebut. Agen yang ditempatkan menggunakan email pengguna yang masuk sebagai ID aktor, jadi inisialisasi setiap entri dengan email pengguna yang mengobrol dengan agen.

Di Agent Bricks CLI, memory bind dan agentbricks deploy merujuk ke sebuah toko berdasarkan namanya. Perintah yang bekerja pada satu store, seperti memory entries create, menggunakan store ID yang dihasilkan.

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, replacing any memory at the same path."""
        memory_store.put(actor_id=actor_id, path=path, content=content, description=description or None)
        return f"Saved memory at {path}"

    @function_tool
    def list_memories() -> str:
        """List the paths and descriptions of the user's long-term memories."""
        memories = memory_store.list(actor_id=actor_id)
        return "\n".join(f"{m.path}: {m.description}" if m.description else m.path for m in memories) or "No memory found."

    @function_tool
    def forget_memory(path: str) -> str:
        """Delete the long-term memory at a path, such as when the user asks you to forget it."""
        memories = list(memory_store.list(actor_id=actor_id, path=path))
        for memory in memories:
            memory.delete()
        return f"Forgot memory at {path}" if memories else f"No memory at {path}"

    return [search_memory, save_memory, list_memories, forget_memory]

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

put() membuat entri, atau menggantikan isi entri yang sudah berada di jalur tersebut. Untuk menambahkan konten sebagai baris baru, berikan append=True. put() tidak atomik, jadi penulisan bersamaan ke jalur yang sama bisa saling menimpa. list(path=...) mengembalikan entri pada jalur yang tepat itu di setiap sesi, sehingga forget_memory juga menghapus entri yang disimpan pada jalur dalam suatu sesi.

Pola yang sama berlaku dengan Claude Agent SDK dan framework lainnya: bungkus operasi search, put, list, dan delete milik store menjadi tipe tool framework.

Jika Anda juga menjalankan pipeline memori di penyimpanan memori yang sama, pipeline dapat menulis ulang, menggabungkan, membagi, atau menghapus entri yang disimpan agen Anda untuk aktor mana pun yang diprosesnya.

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 memiliki cakupan 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). Hanya pembuat toko atau admin workspace yang dapat memberikan akses. Lihat Kelola izin untuk penyimpanan memori agen dan sesi untuk tingkat izin, operasi yang didukung, dan contoh.

Limitations

  • Memori agen hanya menyediakan memori jangka panjang. Untuk riwayat percakapan jangka pendek, lihat sesi agen.
  • Pencarian memberi peringkat entri berdasarkan relevansi, menggabungkan teks lengkap (BM25) dan pencocokan semantik pada konten dan deskripsi setiap entri. Aplikasi ini mengembalikan hingga 100 entri dan tidak mendukung paginasi.
  • Kontrol akses ditegakkan di tingkat toko. Kontrol akses per entri dan per aktor tidak tersedia.
  • Kontrol akses toko mencakup pintu masuk toko. Setiap pengguna workspace dapat melihat daftar dan mendapatkan penyimpanan memori, termasuk ID dan deskripsi mereka.
  • Anda tidak bisa mengubah ID toko setelah Anda membuatnya. Hanya description dapat diperbarui.

Langkah berikutnya

  • Terakhir diperbarui pada