Anggaran tugas

"Task budgets" (anggaran tugas) memungkinkan Anda memberi tahu Claude berapa banyak token yang dimilikinya untuk seluruh loop agentik, termasuk pemikiran, pemanggilan alat, hasil alat, dan output. Model melihat hitung mundur yang terus berjalan dan menggunakannya untuk memprioritaskan pekerjaan serta menyelesaikannya dengan baik seiring anggaran terpakai.

Kapan menggunakan anggaran tugas

Anggaran tugas paling cocok untuk alur kerja agentik di mana Claude melakukan beberapa pemanggilan alat dan pengambilan keputusan sebelum memfinalisasi outputnya untuk menunggu respons manusia berikutnya. Gunakan ketika:

• Anda ingin Claude mengatur sendiri pengeluaran token pada tugas berjangka panjang.
• Anda memiliki batas atas biaya atau latensi per tugas yang dapat diprediksi dan perlu ditegakkan.
• Anda ingin model menyelesaikan dengan baik (merangkum temuan, melaporkan kemajuan) saat mendekati anggaran, alih-alih terputus di tengah tindakan.

Anggaran tugas melengkapi parameter effort: effort mengontrol seberapa teliti Claude bernalar tentang setiap langkah, sedangkan anggaran tugas membatasi total pekerjaan yang dapat dilakukan Claude di seluruh loop agentik.

Menetapkan anggaran tugas

Tambahkan task_budget ke output_config dan sertakan header beta:

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-5-5",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 64000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
) as stream:
    response = stream.get_final_message()

print(response.usage)

Objek task_budget memiliki tiga field:

• type: selalu "tokens".
• total: jumlah token yang dapat digunakan Claude di seluruh loop agentik, termasuk pemikiran, pemanggilan alat, hasil alat, dan output.
• remaining (opsional): sisa anggaran yang dibawa dari permintaan sebelumnya. Secara default bernilai total jika dihilangkan.

Cara kerja hitung mundur anggaran

Claude melihat penanda hitung mundur anggaran yang disisipkan di sisi server di sepanjang percakapan. Penanda tersebut menunjukkan berapa banyak token yang tersisa dalam loop agentik saat ini dan diperbarui saat model menghasilkan pemikiran, pemanggilan alat, dan output, serta saat model memproses hasil alat. Claude menggunakan sinyal ini untuk mengatur kecepatannya dan menyelesaikan tugas dengan baik seiring anggaran terpakai.

Apa yang dihitung sebagai satu giliran

Anggaran mencakup satu giliran agentik, yang juga disebut loop agentik: semua yang dilakukan Claude sebagai respons terhadap satu pesan pengguna yang tidak membawa hasil alat. Satu giliran dapat mencakup beberapa permintaan.

Pesan pengguna yang tidak membawa hasil alat memulai giliran baru dengan anggaran baru. Saat ini, hitung mundur masih menghitung riwayat giliran sebelumnya selama riwayat tersebut masih ada dalam konteks. Kasus yang umum adalah pesan lanjutan setelah Claude mengakhiri gilirannya, misalnya karena anggaran habis:

{ "role": "user", "content": "Continue." }

Pesan pengguna yang berisi blok tool_result melanjutkan giliran saat ini, karena klien Anda sedang menyelesaikan pemanggilan alat yang merupakan bagian dari giliran tersebut:

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" }
  ]
}

Hal itu tetap berlaku bahkan ketika pesan tersebut menambahkan konten baru di samping hasil alat:

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" },
    { "type": "text", "text": "Also check the Dockerfile." }
  ]
}

"Compaction" (pemadatan) di sisi server selama satu giliran tidak mengatur ulang anggaran: token yang digunakan giliran tersebut sebelum compaction tetap dihitung terhadap anggaran. Token dari sebelum giliran dimulai tidak dihitung, bahkan ketika compaction di awal giliran merangkumnya. Saat ini, pengecualian tersebut hanya berlaku untuk anggaran yang dibawa melintasi compaction di sisi server; riwayat giliran sebelumnya tetap dihitung selama masih berada dalam konteks.

Contoh lengkap: penghitungan anggaran di seluruh permintaan

Anggaran tugas menghitung apa yang dilihat Claude (pemikiran, pemanggilan dan hasil alat, serta teks), bukan apa yang ada dalam payload permintaan Anda. Dalam loop agentik, klien Anda mengirim ulang seluruh percakapan pada setiap permintaan, sehingga payload terus bertambah, tetapi anggaran hanya berkurang sebesar apa yang baru: token yang dihasilkan Claude dan konten yang belum pernah dilihatnya. Contoh berikut adalah satu giliran agentik yang terdiri dari tiga permintaan: yang pertama membawa pesan pengguna, dan dua berikutnya masing-masing mengirim ulang riwayat dengan hasil alat yang ditambahkan.

Pertimbangkan sebuah loop dengan task_budget: {type: "tokens", total: 100000} dan satu alat bash.

Permintaan 1. Anda mengirim permintaan awal:

{
  "messages": [
    { "role": "user", "content": "Audit this repo for security issues and report findings." }
  ]
}

Claude berpikir, lalu mengeluarkan pemanggilan alat dan berhenti dengan stop_reason: "tool_use":

{
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "I'll start by listing dependencies to look for known-vulnerable packages..."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "bash",
      "input": { "command": "cat package.json && npm audit --json" }
    }
  ]
}

Misalkan pesan asisten ini (pemikiran ditambah pemanggilan alat) berjumlah total 5.000 token yang dihasilkan. Hitung mundur yang dilihat Claude selama pembuatan berakhir di sekitar remaining ≈ 95.000.

Permintaan 2. Klien Anda menjalankan alat, lalu mengirim ulang seluruh riwayat dengan hasil alat yang ditambahkan:

{
  "messages": [
    { "role": "user", "content": "Audit this repo for security issues and report findings." },
    {
      "role": "assistant",
      "content": [
        { "type": "thinking", "thinking": "I'll start by listing dependencies..." },
        {
          "type": "tool_use",
          "id": "toolu_01",
          "name": "bash",
          "input": { "command": "cat package.json && npm audit --json" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01",
          "content": "<2,800 tokens of npm audit output>"
        }
      ]
    }
  ]
}

Pesan yang dikirim ulang dari permintaan 1 tidak dihitung lagi, tetapi hasil alat sebesar 2.800 token adalah konten baru dan dihitung terhadap anggaran. Claude menggunakan 4.000 token lagi untuk pemikiran dan pemanggilan alat kedua (grep -rn "eval(" src/). Hitung mundur berakhir di sekitar remaining ≈ 88.200.

Permintaan 3. Seluruh riwayat dikirim ulang lagi dengan hasil alat kedua (1.200 token output grep) yang ditambahkan. Claude menulis laporan temuan akhir sebesar 6.000 token dan berhenti dengan stop_reason: "end_turn". remaining ≈ 81.000.

Menempatkan ketiga permintaan secara berdampingan memperjelas perbedaan antara ukuran payload dan penggunaan anggaran:

Klien Anda mengirim pesan pengguna asli sebanyak tiga kali dan pesan asisten pertama sebanyak dua kali, tetapi masing-masing hanya dihitung sekali. Anggaran yang terpakai adalah 19.000 dari 100.000 token, meskipun payload kumulatif yang dikirimkan klien Anda lebih besar dan input yang di-cache melalui caching prompt pada permintaan 2 dan 3 bahkan lebih besar lagi.

Membawa anggaran melewati compaction dengan remaining

Jika kode Anda sendiri memadatkan atau menulis ulang riwayat pesan di antara permintaan (misalnya, dengan merangkum pesan-pesan sebelumnya), server tidak memiliki ingatan tentang berapa banyak anggaran yang telah digunakan sebelum compaction. Teruskan remaining pada permintaan berikutnya agar hitung mundur berlanjut dari titik terakhir Anda, alih-alih diatur ulang ke total:

# Token yang digunakan sebelum pemadatan, dilacak di sisi klien
tokens_spent_so_far = 45000

output_config = {
    "effort": "high",
    "task_budget": {
        "type": "tokens",
        "total": 128000,
        "remaining": 128000 - tokens_spent_so_far,
    },
}

Dalam contoh ini, token yang digunakan sebelum compaction adalah penggunaan dari semua pesan yang telah Anda hapus dari riwayat sejauh ini, diukur seperti pada Mengukur penggunaan Anda saat ini. Jangan sertakan apa pun yang masih ada dalam pesan yang Anda kirim, termasuk ringkasan apa pun yang Anda tambahkan, karena server menghitung token tersebut sendiri. Perbarui angka ini hanya ketika Anda mengganti riwayat dengan cara ini; jangan menguranginya per permintaan. Teruskan remaining yang dihasilkan pada setiap permintaan, bukan hanya pada permintaan yang melakukan compaction.

Untuk loop yang mengirim ulang seluruh riwayat yang tidak dipadatkan pada setiap permintaan, hilangkan remaining dan biarkan server melacak hitung mundur.

Mengubah anggaran di tengah percakapan

task_budget adalah pengaturan tingkat permintaan. Untuk mengubah anggaran di tengah tugas, misalnya untuk memperpanjangnya ketika pengguna memperluas permintaan, tetapkan task_budget baru di output_config pada permintaan berikutnya. Perhatikan konsekuensi caching-nya: nilai anggaran ikut serta dalam prompt yang dirender, sehingga nilai yang berubah tidak cocok dengan entri cache yang dibuat dengan nilai lama (lihat Dukungan fitur di bawah).

Anggaran tugas bersifat saran, bukan ditegakkan

Anggaran tugas adalah petunjuk lunak, bukan batas keras. Claude terkadang dapat melampaui anggaran jika sedang berada di tengah tindakan yang akan lebih mengganggu jika dihentikan daripada diselesaikan. Batas yang ditegakkan untuk total token output tetaplah max_tokens, yang memotong respons dengan stop_reason: "max_tokens" ketika tercapai.

Untuk batas keras pada biaya atau latensi, gabungkan anggaran tugas dengan nilai max_tokens yang wajar:

• Gunakan task_budget untuk memberi Claude target sebagai acuan kecepatan.
• Gunakan max_tokens sebagai batas atas absolut yang mencegah pembuatan yang tak terkendali.

Karena task_budget mencakup seluruh loop agentik (berpotensi banyak permintaan) sedangkan max_tokens membatasi setiap permintaan individual, kedua nilai ini independen; yang satu tidak harus sama dengan atau di bawah yang lain.

Memilih anggaran

Anggaran yang tepat bergantung pada seberapa banyak pekerjaan yang saat ini dilakukan loop agentik Anda. Daripada menebak, ukur penggunaan token Anda yang ada terlebih dahulu, lalu sesuaikan dari sana.

Ukur penggunaan Anda saat ini

Jalankan sampel tugas yang representatif tanpa menetapkan task_budget dan catat total token yang dihabiskan Claude per tugas. Untuk loop agentik, jumlahkan usage.output_tokens di setiap permintaan dalam loop, ditambah token dari hasil alat yang Anda tambahkan di antara permintaan:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
)

# Jumlahkan output_tokens (teks + thinking + panggilan alat) dari setiap permintaan dalam loop Anda.
print(response.usage.output_tokens)

Jalankan ini pada sekumpulan tugas yang representatif dan catat distribusinya. Mulailah dengan p99 dari pengeluaran token per tugas Anda untuk memahami bagaimana pemberian anggaran tugas kepada model dapat mengubah perilaku model, lalu uji naik atau turun sesuai kebutuhan.

Nilai minimum task_budget.total yang diterima adalah 20.000 token pada setiap model yang mendukung anggaran tugas (lihat Dukungan fitur). Nilai yang lebih kecil akan menghasilkan error 400.

Interaksi dengan parameter lain

• max_tokens: Tidak berkaitan langsung dengan anggaran tugas. max_tokens adalah batas keras per permintaan untuk token yang dihasilkan, sedangkan task_budget adalah batas anjuran di sepanjang loop agentik penuh (yang berpotensi mencakup banyak permintaan). Pada effort xhigh atau max, tetapkan max_tokens setidaknya 64k untuk memberi Claude ruang untuk berpikir dan bertindak pada setiap permintaan.
• Effort: Effort mengontrol seberapa dalam Claude bernalar per langkah. Anggaran tugas mengontrol seberapa banyak total pekerjaan yang dilakukan Claude di sepanjang loop agentik. Keduanya saling melengkapi: effort menyesuaikan kedalaman, anggaran tugas menyesuaikan keluasan.
• "Adaptive thinking" (pemikiran adaptif): Anggaran tugas menyertakan token pemikiran dalam penghitungan, sehingga pemikiran adaptif akan berkurang seiring anggaran menipis.
• "Prompt caching" (caching prompt): Penanda hitung mundur anggaran disisipkan di sisi server pada setiap permintaan, sehingga tidak cocok di antara permintaan. Jika klien Anda mengurangi task_budget.remaining pada setiap permintaan lanjutan, nilai yang berubah akan membatalkan prefiks cache apa pun yang memuatnya. Untuk mempertahankan caching, tetapkan anggaran sekali pada permintaan awal dan biarkan model mengatur dirinya sendiri berdasarkan hitung mundur di sisi server, alih-alih mengubah anggaran di sisi klien.

Dukungan fitur

Anggaran tugas tidak didukung di Claude Code atau permukaan Cowork. Gunakan anggaran tugas secara langsung melalui Messages API pada model yang didukung.

Langkah selanjutnya

Compatibility