Operasi sesi

Setelah sesi dibuat, gunakan operasi ini untuk membaca, memperbarui, mengarsipkan, atau menghapusnya. Lihat Memulai sesi untuk membuat sesi dan mengirimkan pekerjaan ke dalamnya.



Status sesi

Sesi berjalan 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, di tengah sesi tanpa membuat versi agen baru. Pembaruan bersifat lokal untuk sesi dan tidak disebarkan kembali ke agen yang mendasarinya.

Hanya tools dan mcp_servers milik agen yang dapat diubah 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 miliknya, juga tidak dapat diubah di tengah sesi: atur pin tersebut saat Anda menyimpan agen, atau atur atau hapus 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 masih 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 sudah ada, lakukan GET pada sesi, modifikasi array-nya, lalu POST kembali.

Sesi harus dalam status idle untuk memperbarui agen. Interupsi sesi jika Anda perlu memperbarui agen saat sesi sedang berjalan.

ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
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
YAML



Memperbarui anggaran sesi

Sesi yang dibuat dengan anggaran menerima dua jenis pembaruan anggaran: mengganti batas dengan max_list_cost baru, dan menghapusnya dengan mengatur budget ke null. 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 lebih besar secara ketat dari list cost yang telah dikonsumsi sesi, dan penghapusan bersifat satu arah: budget non-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 list cost.



Mengambil sesi

ant beta:sessions retrieve --session-id "$SESSION_ID"



Membuat daftar sesi

Hasil dari GET /v1/sessions dipaginasi. Gunakan parameter kueri 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 mengenkode order dari permintaan yang menghasilkannya. Parameter kueri order mengatur 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 kueri lainnya, termasuk filter yang tersisa dan limit, dapat berubah di antara permintaan yang dipaginasi. Untuk field paginasi yang digunakan bersama di seluruh endpoint daftar, lihat Paginasi.

# --format raw mengembalikan satu amplop halaman dengan kursor prev_page dan
# next_page-nya; output default melakukan paginasi otomatis dan hanya mengeluarkan sesi.
cursors=$(ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --format raw \
  --transform '{prev_page,next_page}')
printf '%s\n' "$cursors"

# Teruskan kursor next_page kembali sebagai --page untuk mengambil halaman berikutnya.
NEXT_PAGE=$(jq -r '.next_page' <<< "$cursors")
ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --page "$NEXT_PAGE" \
  --format raw \
  --transform '{prev_page,next_page}'
# Teruskan prev_page dari respons itu sebagai --page untuk kembali dengan cara yang sama.



Mengarsipkan sesi

Arsipkan sesi untuk mencegah event baru dikirim sambil mempertahankan riwayatnya. Sesi dengan status running tidak dapat diarsipkan; kirim event interupsi jika Anda perlu mengarsipkannya segera.

ant beta:sessions archive \
  --session-id "$SESSION_ID"



Menghapus sesi

Hapus sesi untuk menghapus secara permanen catatan, event, dan sandbox terkaitnya. Sesi dengan status running tidak dapat dihapus; kirim event interupsi jika Anda perlu menghapusnya segera.

Memory store, vault, skill, environment, dan agent 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 akan dihapus secara permanen bersama dengan filesystem-nya. Unduh apa pun yang perlu Anda simpan sebelum menghapus sesi.

ant beta:sessions delete \
  --session-id "$SESSION_ID"