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 sebuah sesi, termasuk kebijakan izin dan pengaturan web per alat seperti filter domain, di tengah sesi tanpa membuat versi agen baru. Pembaruan bersifat lokal pada sesi dan tidak disebarkan 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 tersebut 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, 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.

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 menetapkan budget ke null. Keduanya secara otomatis melanjutkan pekerjaan yang terjeda 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 bukan 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 ke dalam biaya daftar.

Mengambil sesi

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

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.

# --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 tetap mempertahankan riwayatnya. Sesi yang berstatus running tidak dapat diarsipkan; untuk mengarsipkannya, kirimkan event user.interrupt secara tersendiri dan tunggu hingga sesi menjadi idle.

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

Menghapus sesi

Hapus sesi untuk menghilangkan 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.

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.

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