Anggaran sesi

"Session budget" (anggaran sesi) adalah batas atas pengeluaran ketat opsional yang Anda tetapkan saat membuat sesi. Platform secara terus-menerus menghitung harga semua yang dikonsumsi sesi berdasarkan tarif daftar publik (list cost atau biaya daftar sesi) dan berhenti mengeluarkan permintaan model baru setelah biaya tersebut mencapai anggaran. Permintaan yang sedang berjalan saat batas terlampaui tetap diselesaikan, sehingga biaya daftar akhir dapat berakhir sedikit melewati anggaran. Sesi yang mencapai anggarannya akan dijeda dan menjadi idle alih-alih dihentikan; mengubah atau menghapus anggaran akan melanjutkan pekerjaan yang dijeda oleh anggaran tersebut. Deployment menerima anggaran yang sama dan menerapkannya ke setiap sesi yang dimulainya; lihat Anggaran pada deployment.

Menetapkan anggaran saat pembuatan sesi

Berikan field opsional budget saat Anda membuat sesi:

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"},
    },
)
print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125

Objek budget memiliki dua field:

• type selalu bernilai "limit".
• max_list_cost adalah batas itu sendiri: amount adalah bilangan bulat dalam sen AS yang ditulis sebagai string tanpa nol di depan ("125" adalah $1,25 dan "50" adalah 50 sen) dan harus lebih besar dari nol. Bentuk desimal seperti "25.00" ditolak. Jumlah ini berupa string, bukan angka, sehingga tidak pernah ada pembulatan float yang diterapkan padanya. currency adalah kode mata uang ISO-4217 dalam huruf besar; USD adalah satu-satunya mata uang yang didukung.

Anggaran hanya dapat dilampirkan saat sesi dibuat. Menambahkan anggaran ke sesi yang sudah ada dan belum memilikinya akan ditolak dengan error 400. Batas pada sesi yang memiliki anggaran dapat diubah atau dihapus kapan saja.

Cara biaya daftar diukur

Platform menghitung harga apa yang dikonsumsi sesi, secara terus-menerus, berdasarkan tarif daftar publik:

• Token model, berdasarkan harga daftar setiap model yang dilayani
• Pencarian web, seharga $10 USD per 1.000 pencarian
• Waktu berjalan sesi, seharga $0,08 USD per jam

Total dolar berjalan ini adalah biaya daftar (list cost) sesi, dan inilah yang dibandingkan dengan anggaran. Biaya daftar bukanlah harga kontrak Anda: jika organisasi Anda telah menegosiasikan diskon, sesi mencapai batasnya ketika total harga daftar mencapainya, dan pengeluaran yang ditagihkan kepada Anda mungkin lebih rendah dari batas tersebut.

Pemberlakuan menggunakan biaya daftar yang tepat dan tidak dibulatkan. Angka list_cost yang dilaporkan pada sesi dan event-nya berupa sen bulat, dibulatkan ke sen terdekat, sehingga angka yang dilaporkan dapat berselisih hingga setengah sen di atas atau di bawah jumlah tepat yang digunakan pemberlakuan.

Ketika sesi mencapai anggarannya

Batas diberlakukan di antara permintaan model, bukan di tengah permintaan. Sebelum setiap permintaan model, platform memeriksa biaya daftar yang telah dikonsumsi sesi, dan setelah total tersebut mencapai batas, setiap thread dijeda sebelum permintaan berikutnya. Permintaan yang membawa total melewati batas diterima saat sesi masih di bawah batas dan berjalan hingga selesai, sehingga list_cost yang tercatat pada sesi yang dijeda bernilai sama dengan atau sedikit melewati max_list_cost: sesi dengan batas "50" (50 sen) dapat dijeda dengan list_cost sebesar "53". Ini memang diharapkan, bukan kesalahan penagihan. Pengeluaran model yang melewati batas paling banyak sebesar biaya satu permintaan model untuk setiap thread. Pemanggilan alat dalam respons permintaan tersebut tetap dijalankan, dan pencarian web serta waktu berjalannya juga dihitung dalam biaya daftar. Perlakukan anggaran sebagai batas untuk pekerjaan baru, bukan titik berhenti yang tepat, dan tentukan besar batas dengan mempertimbangkan margin tersebut.

Sesi yang mencapai anggarannya menjadi idle dengan stop_reason bernilai budget_reached; sesi tidak dihentikan, dan riwayat serta sandbox-nya dipertahankan seperti sesi idle lainnya. Pada event stream Anda akan melihat, secara berurutan:

1. Event session.thread_status_idle dengan stop_reason bernilai budget_reached saat setiap thread dijeda.
2. Event session.usage dengan penggunaan kumulatif dan biaya daftar sesi.
3. Event session.status_idle dengan stop_reason bernilai budget_reached. Event penggunaan selalu tepat mendahului event idle ini.

Jika ada eksekusi workflow yang terbuka, setiap eksekusi yang belum idle juga mendapatkan event workflow_run.status_idle.

Thread yang permintaan terakhirnya sekaligus melewati batas dan menyelesaikan gilirannya melaporkan end_turn pada event session.thread_status_idle miliknya sendiri, sementara sesi tetap melaporkan budget_reached; perlakukan stop_reason tingkat sesi sebagai sinyal bahwa sesi dijeda pada anggarannya.

Event yang diterima pada batas

Selama sesi berada pada atau melebihi anggarannya, sesi hanya menerima event yang menyelesaikan pekerjaan yang sudah berjalan:

• user.tool_confirmation
• user.tool_result
• user.custom_tool_result
• user.interrupt

Event apa pun yang akan memulai pekerjaan baru, seperti user.message, ditolak dengan error 400 yang menyebutkan daftar ini. Hasil yang diselesaikan dicatat tanpa memicu permintaan model baru; sesi tetap dijeda pada anggarannya.

user.interrupt yang dikirim saat sesi dijeda pada anggarannya (semua thread dijeda pada batas) diterima, dan event tersebut tidak muncul dalam daftar event. Event ini tidak menghentikan thread mana pun, karena setiap thread sudah dijeda. Ubah atau hapus anggaran untuk melanjutkan.

Jika sesi memiliki eksekusi workflow yang terbuka, interupsi tersebut dapat menjedanya, seperti halnya interupsi pada waktu lain mana pun. Eksekusi yang dijeda oleh interupsi tidak dilanjutkan ketika Anda mengubah atau menghapus anggaran. Untuk melanjutkannya, ubah atau hapus anggaran, lalu kirim user.message yang meminta agen melanjutkan eksekusinya.

Melanjutkan sesi yang mencapai anggarannya

Ubah atau hapus anggaran dengan pembaruan sesi. Pembaruan yang diterima akan secara otomatis melanjutkan pekerjaan yang dijeda oleh anggaran; tidak diperlukan tindakan klien lebih lanjut.

Setiap eksekusi workflow yang dijeda oleh anggaran juga mendapatkan event workflow_run.status_running. Eksekusi yang dijeda oleh interupsi, bahkan interupsi yang dikirim saat sesi berada pada anggarannya, tetap dijeda dan tidak mendapatkan event workflow_run.status_running dari pembaruan tersebut. Untuk melanjutkannya, kirim user.message yang meminta agen melanjutkan eksekusinya. Lihat Menginterupsi sesi dengan eksekusi yang terbuka.

Mengubah anggaran

Perbarui sesi dengan max_list_cost yang baru. Nilai baru dapat lebih tinggi atau lebih rendah dari batas saat ini, tetapi harus benar-benar lebih besar dari biaya daftar yang telah dikonsumsi sesi; jika tidak, pembaruan ditolak dengan error 400: budget.max_list_cost must be greater than the session's consumed list cost. Karena biaya yang dikonsumsi biasanya berada sedikit melewati batas lama saat sesi dijeda, dasarkan nilai baru pada usage.list_cost yang dilaporkan sesi, bukan pada max_list_cost yang lama. Tetapkan nilainya satu sen atau lebih di atas angka tersebut: nilai yang dilaporkan dibulatkan dan dapat berada sedikit di bawah biaya terkonsumsi tepat yang digunakan pemeriksaan.

updated_session = client.beta.sessions.update(
    session.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "500", "currency": "USD"},
    },
)
print(updated_session.budget.max_list_cost.amount)  # 500

Menghapus anggaran

Berikan budget=None untuk menghapus batas sepenuhnya. Pekerjaan yang dijeda oleh anggaran dilanjutkan, dan event session.updated yang dihasilkan membawa budget yang diatur ke null.

unbudgeted_session = client.beta.sessions.update(session.id, budget=None)
print(unbudgeted_session.budget)  # None

Memantau pengeluaran

Objek sesi membawa budget miliknya dan objek usage dengan pengeluaran yang dilacak: usage.list_cost adalah biaya daftar yang telah dikonsumsi sesi, dan usage.active_seconds adalah waktu berjalan yang menjadi dasar penghitungan biaya runtime-nya. Pada sesi yang dijeda dengan budget_reached, perkirakan usage.list_cost bernilai sama dengan atau sedikit melewati max_list_cost: permintaan yang melewati batas selesai sebelum jeda. active_seconds tingkat sesi menghitung aktivitas yang tumpang tindih dari thread yang berjalan bersamaan hanya sekali. Respons pengambilan thread membawa dua field yang sama pada usage milik thread itu sendiri, dihitung per thread. Angka per thread dibulatkan secara independen dan tidak mencakup biaya waktu berjalan sesi, sehingga jumlahnya tidak persis sama dengan list_cost sesi; angka sesi adalah angka yang menjadi acuan pemberlakuan anggaran.

Event session.usage adalah snapshot dari penggunaan kumulatif sesi dan biaya daftar yang dilacak. Event ini membawa total token sesi, list_cost, active_seconds, jumlah permintaan server_tool_use (web_search_requests, yang dihitung ke dalam biaya daftar per permintaan, dan web_fetch_requests, yang bernilai 0 karena permintaan web fetch tidak dikenakan biaya per permintaan dan tidak diukur), serta budget sesi jika sesi memilikinya. Event ini muncul dalam daftar event dan stream sesi. Sesi memancarkan satu event ini tepat sebelum menjadi idle, apa pun alasan berhentinya, sehingga sesi yang mencapai anggarannya selalu memancarkan satu event ini tepat sebelum event idle karena anggaran tercapai.

Untuk membaca penggunaan dari stream dan objek sesi, lihat Melacak penggunaan.

Anggaran dalam sesi multiagen

Sesi multiagen memiliki satu anggaran yang dibagi di antara semua thread-nya; tidak ada batas per thread. Konsumsi setiap thread dihitung berdasarkan model yang dilayaninya sendiri, dan thread dijeda secara independen saat batas bersama tercapai. Konsultasi advisor dihitung terhadap anggaran yang sama, dengan harga berdasarkan tarif model advisor. Satu thread dapat dijeda pada budget_reached sementara thread lain menyelesaikan permintaannya yang sedang berjalan.

Permintaan yang tertunda lebih diutamakan daripada batas: sesi dengan satu thread yang menunggu pada requires_action dan thread lain yang dijeda pada budget_reached melaporkan requires_action di tingkat sesi. Permintaan yang tertunda tetap memerlukan jawaban, dan menjawabnya merupakan event penyelesaian yang tidak diblokir oleh anggaran.

Anggaran pada deployment

Deployment menerima objek budget yang sama saat Anda membuat atau memperbaruinya:

{
  "budget": {
    "type": "limit",
    "max_list_cost": { "amount": "2000", "currency": "USD" }
  }
}

Batas disalin ke setiap sesi yang dimulai oleh deployment, sehingga batas tersebut membatasi setiap eksekusi secara terpisah, bukan pengeluaran kumulatif deployment. Mengubah anggaran deployment berlaku untuk sesi yang dimulai deployment setelahnya, bukan untuk sesi yang sudah berjalan. Tidak seperti sesi, anggaran deployment dapat dihapus dengan budget=None dan ditetapkan lagi nanti. Lihat Menetapkan anggaran untuk setiap eksekusi.

Model tanpa harga daftar

Anggaran hanya dapat melacak konsumsi yang dapat dihitung harganya oleh platform. Membuat sesi beranggaran yang agennya, atau agen mana pun yang tercantum dalam daftar predefined_agents dari subagents atau workflows, atau advisor yang ditetapkan dalam konfigurasi multiagennya, menggunakan model tanpa harga daftar publik akan ditolak dengan error 400 yang menyatakan bahwa tidak ada harga daftar yang tersedia untuk model tersebut.

Jika penggunaan sesi beranggaran kemudian mencakup model tanpa harga daftar, anggaran tidak lagi dapat mengukur pengeluaran sesi: sesi dapat dijeda dengan stop_reason bernilai budget_reached, dan perubahan anggaran ditolak. Hapus anggaran untuk melanjutkan sesi.

Referensi error

Permintaan terkait anggaran ditolak dalam kasus-kasus berikut: