Sesi agen yang dikelola

Important

Fitur ini ada di Beta.

Sesi agen terkelola memberikan agen Anda penyimpanan status sesi yang andal dan tidak bergantung pada kerangka kerja: yakni status yang disimpan agen atau kerangka kerja untuk satu interaksi. Biasanya, ini adalah riwayat percakapan, yaitu transkrip berurutan dari pesan, pemanggilan alat, dan hasil yang dibaca agen pada awal tiap giliran dan ditambahkan ke dalamnya selama proses berjalan. Itu juga bisa berupa keadaan lain yang dipertahankan framework untuk interaksi tersebut, seperti graf LangGraph. Azure Databricks menyimpannya di Lakebase dan mengelola penyimpanan untuk Anda, sehingga Anda tidak perlu membangun atau mengoperasikan database.

Note

Pada masa pratinjau, Anda akan ditagih untuk instans Lakebase dasar yang menyimpan sesi Anda. Tidak ada biaya tambahan yang berlaku untuk sesi agen terkelola itu sendiri. Harga dapat berubah seiring berjalannya pratinjau.

Gunakan sesi terkelola ketika Anda ingin:

  • Simpan riwayat percakapan agen agar tetap bertahan saat restart dan dapat dilanjutkan nanti.
  • Rekonstruksi konteks lengkap (termasuk panggilan alat dan penalaran) pada pesan tindak lanjut.
  • Lihat daftar, lanjutkan, dan buat cabang dari percakapan sebelumnya melalui UI Anda sendiri.

Sesi yang dikelola memegang status satu interaksi (jangka pendek, dalam sesi). Untuk memori jangka panjang yang tahan lama dan bertahan di seluruh percakapan, gunakan memori agen terkelola.

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 sesi yang dikelola

Hierarki sumber daya sesi agen terkelola: sebuah penyimpanan sesi berisi banyak sesi, dan setiap sesi berisi banyak item sesi yang diurutkan.

Sesi yang dikelola memiliki tiga tingkat:

  • Penyimpanan sesi adalah wadah yang dibatasi ruang kerja untuk sesi agen. Membuat store akan secara otomatis menyiapkan penyimpanan pendukung Lakebase. Anda memilih workspace-unique session_store_name.
  • Sesi adalah satu interaksi yang tahan lama (biasanya thread percakapan) di dalam sebuah toko. Sebuah sesi diidentifikasi dengan:
    • actor_id (wajib): Siapa pemilik sesi, seperti pengguna akhir atau agen lain. Aplikasi ini mengelompokkan semua sesi satu subjek sehingga Anda dapat mencantumkan dan memfilter mereka bersama-sama. Saat Anda membangun aplikasi per pengguna, atur actor_id ke ID pengguna (misalnya, identitas pengguna akhir yang terverifikasi dari autentikasi aplikasi Anda) sehingga setiap sesi pengguna tetap dikelompokkan. Tetapkan dari konteks aplikasi tepercaya, jangan pernah menggunakan nilai yang diberikan oleh model atau pengguna.
    • session_id (opsional): ID yang dipilih oleh penelepon untuk interaksi. Layanan akan menghasilkan satu saat Anda menghilangkannya.
    • parent_session_id (opsional): menghubungkan sebuah sesi ke sesi asal tempat sesi tersebut diturunkan, untuk merepresentasikan percakapan bercabang.
  • Item sesi adalah satu entri dalam riwayat urutan sesi. Setiap item memuat nilai opak data yang kompatibel dengan JSON, seperti pesan, pemanggilan alat, hasil alat, atau blok penalaran. Azure Databricks menetapkan setiap item sebuah item_id dan sebuah create_time dan tidak memeriksa atau memvalidasi isinya. Item tidak dapat diubah setelah ditambahkan.

Layanan ini mempertahankan urutan deterministik untuk item-item dalam sesi dan mengautorisasi setiap operasi pada penyimpanan sesi.

Get started

Contoh-contoh ini menyiapkan sesi terkelola untuk agen dukungan: contoh-contoh ini membuat penyimpanan sesi, memulai sesi untuk satu percakapan, menambahkan giliran-giliran percakapan, dan membaca kembali riwayatnya pada permintaan selanjutnya. Pilih klien yang sesuai dengan proyek Anda.

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 sesi, lalu mulai sesi untuk satu percakapan. actor_id adalah milik siapa percakapan tersebut; opsional session_id secara unik mengidentifikasi percakapan ini:

    from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
session_store = client.session_stores.create("support-agent-sessions")
session = session_store.add(actor_id="customer-123", session_id="case-456")

  3. Tambahkan giliran percakapan selama agen berjalan. Setiap item adalah nilai yang kompatibel dengan JSON:

    session.append_items(
    [
        {"type": "message", "role": "user", "content": "I need help with my cluster."},
        {"type": "message", "role": "assistant", "content": "Let's take a look."},
    ]
)

  4. Pada permintaan tindak lanjut, muat ulang sesi dan baca riwayat lengkapnya untuk membangun kembali konteks:

    session = session_store.get("case-456")
# Request chronological order; list_items defaults to newest-first and auto-pages.
history = [item.data for item in session.list_items(order_by="create_time asc")]

REST API

Klien memanggil API REST di bawah ./api/2.0/agents/session-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 sesi untuk agen Anda:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores?session_store_name=support-agent-sessions" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"description": "Support agent conversation history"}'

  3. Mulailah sesi untuk satu percakapan. actor_id menunjukkan percakapan ini milik siapa; session_id secara unik mengidentifikasi percakapan ini:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions?session_id=case-456" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "customer-123"}'

  4. Tambahkan giliran percakapan saat agen berjalan:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions/case-456/items:append" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"items": [{"data": {"type": "message", "role": "user", "content": "I need help with my cluster."}}]}'

  5. Baca sejarah kembali secara kronologis untuk membangun kembali konteks:

    curl -G "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions/case-456/items" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" --data-urlencode "order_by=create_time asc"

Klien juga mendukung penghapusan item terbaru, mengosongkan item dalam sesi, dan menduplikasi percakapan menjadi salinan mandiri (opsional hingga item tertentu). Menghapus sesi yang memiliki sesi anak memerlukan opsi paksa untuk mengalihkan penghapusan ke sesi tersebut (misalnya, session.delete(force=True)).

Dukung sesi kerangka kerja agen dengan sesi yang dikelola

Kerangka kerja agen seperti OpenAI Agents SDK dan Claude Agent SDK membaca riwayat percakapan di awal run dan menambahkan item baru di akhir. Penyimpanan sesi langsung dipetakan ke pola tersebut:

Operasi kerangka kerja Panggilan penyimpanan sesi
Baca riwayat list_items secara kronologis (order_by="create_time asc")
Tambahkan item giliran append item-item baru
Batalkan item terakhir pop item yang paling baru
Bersihkan thread clear item sesi

Ruang lingkup dan akses

Sesi yang dikelola menyimpan item sesi sebagai nilai yang buram dan kompatibel dengan JSON: layanan tetap ada dan mengembalikan apa pun yang ditambahkan oleh agen atau framework Anda, tanpa menginterpretasikannya. Ia tidak menambahkan sumber daya kontrol eksekusi seperti run, checkpoint, atau persetujuan sebagai konsep kelas satu, meskipun framework yang menyerialkan status tersebut dapat mempertahankannya sebagai item.

Penyimpanan sesi bercakupan ruang kerja, dan akses diotorisasi pada tingkat penyimpanan. Kolom actor_id dan metadata hanya mendukung pengelompokan dan penyaringan; kolom tersebut tidak memberikan atau membatasi akses. Tetapkan actor_id dari konteks aplikasi tepercaya, bukan dari nilai yang diberikan oleh model atau pengguna.

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

Sesi yang dikelola dan memori yang dikelola bersifat independen. Menghapus sesi atau penyimpanan sesi tidak menghapus memori yang disimpan dalam penyimpanan memori.

Langkah berikutnya

  • Terakhir diperbarui pada