Operasi sesi

Setelah sebuah sesi ada, gunakan operasi-operasi ini untuk membaca, memperbarui, mengarsipkan, atau menghapusnya. Lihat Memulai sesi untuk membuat sesi dan mengirimkan pekerjaan kepadanya.

Status sesi

Sesi berkembang melalui status-status berikut. Lihat Memulai sesi untuk siklus hidup sesi.

Memperbarui konfigurasi agen

Anda dapat memperbarui agent.tools dan agent.mcp_servers milik sesi, termasuk kebijakan izin dan pengaturan web per alat seperti filter domain, di tengah sesi tanpa membuat versi agen baru. Pembaruan bersifat lokal untuk sesi dan tidak diteruskan kembali ke agen yang mendasarinya. allowed_domains dan blocked_domains yang diperbarui berlaku untuk sisa sesi.

Hanya tools dan mcp_servers milik agen yang dapat berubah setelah sesi dibuat. Untuk menjalankan sesi dengan nilai model, system, atau skills yang berbeda dari milik agen, gunakan override konfigurasi agen saat Anda membuat sesi. Konfigurasi model agen, termasuk pin inference_geo-nya, juga tidak dapat berubah di tengah sesi: tetapkan pin saat Anda menyimpan agen, atau tetapkan atau hapus pin untuk satu sesi dengan override model saat Anda membuatnya. Field system yang dikonfigurasi pada agen bersifat tetap selama masa hidup sesi. Pada model yang mendukungnya, Anda tetap dapat menambahkan panduan tingkat sistem di tengah sesi dengan mengirimkan event system.message.

Semantik pembaruan tools atau mcp_servers adalah penggantian penuh: array yang diberikan menjadi nilai baru. Untuk mempertahankan entri yang ada, lakukan GET pada sesi, ubah array-nya, lalu POST kembali.

Sesi harus berstatus idle untuk memperbarui agen. Untuk memperbarui agen saat sesi sedang berjalan, kirimkan event user.interrupt secara tersendiri dan tunggu hingga sesi menjadi idle. Jika sebuah eksekusi workflow terbuka, baik sedang berjalan maupun dijeda, pembaruan akan mengembalikan kesalahan 400, bahkan ketika sesi berstatus idle. Interupsi tidak mengakhiri eksekusi, sehingga pembaruan tetap gagal setelah Anda menginterupsi sesi. Kirimkan user.message yang meminta agen untuk menghentikan eksekusinya, atau tunggu hingga setiap eksekusi berakhir.

client.beta.sessions.update(
    session.id,
    agent={
        "tools": [
            {"type": "agent_toolset_20260401"},
            {"type": "mcp_toolset", "mcp_server_name": "linear"},
        ],
        "mcp_servers": [
            {"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}
        ],
    },
)

Memperbarui anggaran sesi

Sesi yang dibuat dengan anggaran menerima dua jenis pembaruan anggaran: mengganti batas dengan max_list_cost baru, dan menghapusnya dengan meneruskan budget=None. Keduanya secara otomatis melanjutkan pekerjaan yang dijeda ketika sesi mencapai batasnya. Batas pengganti dapat lebih tinggi atau lebih rendah dari batas saat ini, tetapi harus benar-benar lebih besar dari biaya daftar (list cost) yang telah dikonsumsi sesi, dan penghapusan bersifat satu arah: budget yang tidak null hanya diterima pada sesi yang saat ini memilikinya, sehingga Anda tidak dapat menambahkan kembali anggaran yang telah dihapus atau menambahkannya ke sesi yang dibuat tanpa anggaran. Lihat Anggaran sesi untuk contoh permintaan, perilaku kesalahan, dan apa saja yang dihitung dalam biaya daftar.

Mengambil sesi

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

Mendaftar sesi

Hasil dari GET /v1/sessions dipaginasi. Gunakan parameter query limit untuk mengontrol ukuran halaman. Setiap respons menyertakan kursor next_page; teruskan sebagai parameter page pada permintaan berikutnya untuk mengambil halaman selanjutnya. next_page bernilai null ketika tidak ada hasil lagi.

Untuk kembali satu halaman, teruskan prev_page sebagai parameter page. prev_page bernilai null ketika Anda berada di halaman pertama.

Kursor page bersifat opaque dan mengodekan order dari permintaan yang menghasilkannya. Parameter query order menetapkan arah pengurutan hasil, asc atau desc berdasarkan waktu pembuatan; nilai default-nya adalah desc (terbaru lebih dulu). Menggunakan kembali kursor dengan order yang berbeda akan mengembalikan kesalahan 400, begitu pula mengubah filter created_at sehingga mengecualikan posisi kursor. Parameter query lainnya, termasuk filter-filter yang tersisa dan limit, dapat berubah di antara permintaan yang dipaginasi. Untuk field paginasi yang digunakan bersama di seluruh endpoint daftar, lihat Paginasi.

# Setel `limit` rendah agar hasil mencakup lebih dari satu halaman.
first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
# `prev_page` bernilai None di halaman pertama; `next_page` bernilai None di halaman terakhir.
print(f"prev_page: {first_page.prev_page}")
print(f"next_page: {first_page.next_page}")

# Teruskan kembali `next_page` sebagai `page` untuk mengambil halaman berikutnya.
second_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=first_page.next_page
)
for listed_session in second_page.data:
    print(f"{listed_session.id}: {listed_session.status}")

# Teruskan kembali `prev_page` sebagai `page` untuk kembali ke halaman sebelumnya.
previous_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=second_page.prev_page
)
for listed_session in previous_page.data:
    print(f"{listed_session.id}: {listed_session.status}")
# Untuk iterasi maju saja, objek halaman juga dapat diiterasi secara langsung.

Mengarsipkan sesi

Arsipkan sesi untuk mencegah event baru dikirim sambil tetap mempertahankan riwayatnya. Sesi yang berstatus running tidak dapat diarsipkan; untuk mengarsipkannya, kirimkan event user.interrupt secara tersendiri dan tunggu hingga sesi menjadi idle. Jika sebuah eksekusi workflow terbuka, pengarsipan mungkin mengembalikan kesalahan 400, bahkan ketika sesi berstatus idle, atau mungkin berhasil dan mengakhiri eksekusi tersebut. Sebelum Anda mengarsipkan, kirimkan user.message yang meminta agen untuk menghentikan eksekusinya, atau tunggu hingga setiap eksekusi berakhir. Kemudian arsipkan sesi setelah berstatus idle.

client.beta.sessions.archive(session.id)

Menghapus sesi

Hapus sesi untuk menghapus secara permanen catatan, event, dan sandbox terkaitnya. Sesi yang berstatus running tidak dapat dihapus; untuk menghapusnya, kirimkan event user.interrupt secara tersendiri dan tunggu hingga sesi menjadi idle. Jika sebuah eksekusi workflow terbuka, penghapusan mungkin mengembalikan kesalahan 400, bahkan ketika sesi berstatus idle, atau mungkin berhasil. Setelah penghapusan berhasil, tidak ada event workflow_run yang melaporkan berakhirnya eksekusi milik sesi tersebut. Sebelum Anda menghapus, kirimkan user.message yang meminta agen untuk menghentikan eksekusinya, atau tunggu hingga setiap eksekusi berakhir. Kemudian hapus sesi setelah berstatus idle.

Memory store, vault, skill, environment, dan agen adalah sumber daya independen dan tidak terpengaruh oleh penghapusan sesi. File yang Anda unggah melalui Files API juga tidak terpengaruh, tetapi file yang dihasilkan oleh sesi itu sendiri terikat pada sesi tersebut dan dihapus secara permanen bersama sistem file-nya. Unduh apa pun yang perlu Anda simpan sebelum menghapus sesi. File output yang ditulis di akhir giliran terakhir dapat memerlukan beberapa detik setelah sesi menjadi idle untuk muncul di daftar file sesi, jadi periksa terlebih dahulu bahwa file yang Anda harapkan sudah terdaftar.

client.beta.sessions.delete(session.id)