Anggaran tugas

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



Kapan menggunakan anggaran tugas

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

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

Anggaran tugas melengkapi parameter effort: effort mengontrol seberapa menyeluruh Claude bernalar tentang setiap langkah, sementara 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",
    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. Default-nya adalah total jika dihilangkan.



Cara kerja hitungan mundur anggaran

Claude melihat penanda hitungan mundur anggaran yang disisipkan di sisi server 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 memproses hasil alat. Claude menggunakan sinyal ini untuk mengatur kecepatannya dan menyelesaikan dengan baik saat anggaran terpakai.



Contoh terperinci: penghitungan anggaran di seluruh giliran

Anggaran tugas menghitung apa yang dilihat Claude (pemikiran, pemanggilan alat dan hasilnya, serta teks), bukan apa yang ada dalam payload permintaan Anda. Dalam loop agentik, klien Anda mengirim ulang percakapan lengkap pada setiap permintaan, sehingga payload bertambah dari giliran ke giliran, tetapi anggaran hanya berkurang sebesar token yang dilihat Claude pada giliran ini.

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

Giliran 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 giliran asisten ini (pemikiran ditambah pemanggilan alat) berjumlah 5.000 token yang dihasilkan. Hitungan mundur yang dilihat Claude selama pembuatan berakhir di sekitar remaining ≈ 95.000.

Giliran 2. Klien Anda menjalankan alat tersebut, lalu mengirim ulang riwayat lengkap dengan hasil alat 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 user dan assistant giliran 1 yang dikirim ulang tidak dihitung lagi, tetapi hasil alat sebesar 2.800 token adalah konten baru yang dilihat Claude pada giliran ini dan dihitung terhadap anggaran. Claude menghabiskan 4.000 token lagi untuk pemikiran dan pemanggilan alat kedua (grep -rn "eval(" src/). Hitungan mundur berakhir di sekitar remaining ≈ 88.200.

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

Menempatkan ketiga giliran berdampingan membuat perbedaan antara ukuran payload dan pengeluaran anggaran menjadi eksplisit:

Klien Anda mengirim pesan user giliran 1 sebanyak tiga kali dan pesan assistant giliran 1 sebanyak dua kali, tetapi masing-masing dihitung satu kali. Anggaran menghabiskan 19.000 dari 100.000 token, meskipun payload kumulatif yang dikirimkan klien Anda lebih besar dan input yang di-cache prompt pada giliran 2 dan 3 lebih besar lagi.



Membawa anggaran melintasi pemadatan dengan remaining

Jika loop agentik Anda memadatkan atau menulis ulang konteks di antara permintaan (misalnya, dengan merangkum giliran sebelumnya), server tidak memiliki memori tentang berapa banyak anggaran yang dihabiskan sebelum pemadatan. Teruskan remaining pada permintaan berikutnya agar hitungan mundur berlanjut dari tempat Anda berhenti, alih-alih direset 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,
    },
}

Untuk loop yang mengirim ulang riwayat lengkap yang tidak dipadatkan pada setiap giliran, hilangkan remaining dan biarkan server melacak hitungan 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: nilai anggaran berpartisipasi dalam prompt yang dirender, sehingga nilai yang diubah tidak cocok dengan entri cache yang dibuat di bawah nilai lama (lihat Dukungan fitur di bawah).



Anggaran tugas bersifat saran, bukan paksaan

Anggaran tugas adalah petunjuk lunak, bukan batas keras. Claude terkadang dapat melebihi anggaran jika sedang di tengah tindakan yang akan lebih mengganggu jika diinterupsi daripada diselesaikan. Batas yang dipaksakan pada total token output tetap max_tokens, yang memotong respons dengan stop_reason: "max_tokens" ketika tercapai.

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

• Gunakan task_budget untuk memberi Claude target untuk mengatur kecepatannya.
• Gunakan max_tokens sebagai batas absolut yang mencegah pembuatan yang tidak terkendali.

Karena task_budget mencakup seluruh loop agentik (berpotensi banyak permintaan) sementara max_tokens membatasi setiap permintaan individual, kedua nilai tersebut independen; yang satu tidak diharuskan berada pada atau di bawah yang lain.



Memilih anggaran

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



Ukur penggunaan Anda saat ini

Jalankan sampel tugas yang representatif tanpa task_budget ditetapkan dan catat total token yang dihabiskan Claude per tugas. Untuk loop agentik, jumlahkan usage.output_tokens di seluruh 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",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
)

# Jumlahkan output_tokens (teks + pemikiran + panggilan alat) di 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 memberikan anggaran tugas kepada model dapat memodifikasi perilaku model, lalu uji naik atau turun sesuai kebutuhan.

Nilai minimum task_budget.total yang diterima bersifat spesifik per model; pada setiap model yang saat ini mendukung anggaran tugas (lihat Dukungan fitur) nilainya adalah 20.000 token, dan nilai di bawah minimum mengembalikan error 400.



Interaksi dengan parameter lain

• max_tokens: Ortogonal terhadap anggaran tugas. max_tokens adalah batas keras per permintaan pada token yang dihasilkan, sementara task_budget adalah batas yang bersifat saran di seluruh loop agentik penuh (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 seluruh loop agentik. Keduanya saling melengkapi: effort menyetel kedalaman, anggaran tugas menyetel keluasan.
• Adaptive thinking: Anggaran tugas menyertakan token pemikiran dalam hitungan, sehingga adaptive thinking secara alami menurun seiring anggaran habis.
• Caching prompt: Penanda hitungan mundur anggaran disisipkan di sisi server per giliran, sehingga tidak cocok di seluruh permintaan. Jika klien Anda mengurangi task_budget.remaining pada setiap permintaan lanjutan, nilai yang diubah membatalkan prefiks cache apa pun yang memuatnya. Untuk mempertahankan caching, tetapkan anggaran sekali pada permintaan awal dan biarkan model mengatur dirinya sendiri terhadap hitungan mundur sisi server, alih-alih mengubah anggaran di sisi klien.



Dukungan fitur

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



Langkah selanjutnya