Anggaran tugas

"Task budgets" (anggaran tugas) memungkinkan Anda memberi tahu Claude berapa banyak token yang dimilikinya untuk satu loop agentik penuh, termasuk pemikiran, panggilan 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 bekerja paling baik untuk alur kerja agentik di mana Claude melakukan beberapa panggilan alat dan keputusan sebelum memfinalisasi outputnya untuk menunggu respons manusia berikutnya. Gunakan anggaran tugas ketika:

• Anda ingin Claude mengatur sendiri pengeluaran token pada tugas berdurasi panjang.
• Anda memiliki batas biaya atau latensi per tugas yang dapat diprediksi untuk 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 menyeluruh Claude bernalar tentang setiap langkah, sementara anggaran tugas membatasi total pekerjaan yang dapat dilakukan Claude di sepanjang 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-4-8",
    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 dihabiskan Claude di sepanjang loop agentik, termasuk pemikiran, panggilan alat, hasil alat, dan output.
• remaining (opsional): sisa anggaran yang dibawa dari permintaan sebelumnya. Secara default bernilai total jika dihilangkan.



Cara kerja hitungan mundur anggaran

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



Contoh terperinci: penghitungan anggaran antar giliran

Anggaran tugas menghitung apa yang dilihat Claude (pemikiran, panggilan alat dan hasilnya, serta teks), bukan apa yang ada dalam payload permintaan Anda. Dalam loop agentik, klien Anda mengirim ulang seluruh percakapan 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 panggilan 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 panggilan alat) berjumlah 5.000 token yang dihasilkan. Hitungan mundur yang dilihat Claude selama pembuatan berakhir di sekitar remaining ≈ 95.000.

Giliran 2. Klien Anda mengeksekusi alat, lalu mengirim ulang riwayat penuh 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 panggilan alat kedua (grep -rn "eval(" src/). Hitungan mundur berakhir di sekitar remaining ≈ 88.200.

Giliran 3. Riwayat penuh 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 hanya dihitung sekali. Anggaran menghabiskan 19.000 dari 100.000 token, meskipun payload kumulatif yang ditransmisikan klien Anda lebih besar dan input yang di-cache prompt pada giliran 2 dan 3 bahkan lebih besar lagi.



Membawa anggaran melintasi kompaksi dengan remaining

Jika loop agentik Anda mengompaksi atau menulis ulang konteks di antara permintaan (misalnya, dengan merangkum giliran-giliran sebelumnya), server tidak memiliki memori tentang berapa banyak anggaran yang telah dihabiskan sebelum kompaksi. Teruskan remaining pada permintaan berikutnya agar hitungan mundur berlanjut dari titik terakhir Anda alih-alih diatur ulang ke total:

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

Untuk loop yang mengirim ulang seluruh riwayat yang tidak dikompaksi pada setiap giliran, hilangkan remaining dan biarkan server melacak hitungan mundur.



Anggaran tugas bersifat anjuran, bukan ditegakkan

Anggaran tugas adalah petunjuk lunak, bukan batas keras. Claude terkadang dapat melebihi anggaran jika sedang berada di tengah tindakan yang akan lebih mengganggu jika diinterupsi daripada diselesaikan. Batas yang ditegakkan pada total token output tetaplah max_tokens, yang memotong respons dengan stop_reason: "max_tokens" saat 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 tempo.
• 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 harus 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 menyetel task_budget dan catat total token yang dihabiskan Claude per tugas. Untuk loop agentik, jumlahkan usage.output_tokens ditambah token pemikiran dan hasil alat di setiap permintaan dalam loop:

def run_task_and_count_tokens(messages: list) -> int:
    """Runs an agentic loop to completion and returns total tokens spent."""
    total_spend = 0
    while True:
        with client.beta.messages.stream(
            model="claude-opus-4-8",
            max_tokens=128000,
            messages=messages,
            tools=tools,
            betas=["task-budgets-2026-03-13"],
        ) as stream:
            response = stream.get_final_message()
        # Hitung apa yang dihasilkan Claude pada giliran ini (output mencakup teks + pemikiran + panggilan alat).
        # Token hasil alat juga dihitung terhadap anggaran; tambahkan jumlah token dari
        # blok tool_result yang Anda tambahkan di bawah jika Anda ingin pelacakan sisi klien cocok
        # dengan hitung mundur sisi server.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # Tambahkan giliran asisten dan hasil alat Anda, lalu lanjutkan loop.
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": run_tools(response.content)},
        ]

Jalankan ini pada serangkaian tugas yang representatif dan catat distribusinya. Mulailah dengan p99 dari pengeluaran token per tugas Anda untuk memahami bagaimana memberikan 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; 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 anjuran di sepanjang loop agentik penuh (berpotensi mencakup banyak permintaan). Pada effort xhigh atau max, setel max_tokens ke 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 berapa banyak total pekerjaan yang dilakukan Claude di sepanjang loop agentik. Keduanya saling melengkapi: effort menyetel kedalaman, anggaran tugas menyetel keluasan.
• Pemikiran adaptif: Anggaran tugas menyertakan token pemikiran dalam hitungan, sehingga pemikiran adaptif secara alami berkurang saat anggaran menipis.
• Caching prompt: Penanda hitungan mundur anggaran disisipkan di sisi server per giliran, sehingga tidak cocok antar permintaan. Jika klien Anda mengurangi task_budget.remaining pada setiap permintaan lanjutan, nilai yang berubah tersebut 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 di sisi server alih-alih mengubah anggaran di sisi klien.



Dukungan fitur

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