Anggaran tugas

Anggaran tugas memungkinkan Anda memberi tahu Claude berapa banyak token yang dimilikinya untuk loop agentic penuh, termasuk pemikiran, panggilan alat, hasil alat, dan output. Model melihat hitungan mundur yang berjalan dan menggunakannya untuk memprioritaskan pekerjaan dan menyelesaikan dengan anggun saat anggaran dikonsumsi.

Kapan menggunakan anggaran tugas

Anggaran tugas bekerja terbaik untuk alur kerja agentic di mana Claude membuat beberapa panggilan alat dan keputusan sebelum menyelesaikan outputnya untuk menunggu respons manusia berikutnya. Gunakan ketika:

• Anda ingin Claude mengatur diri sendiri pengeluaran token pada tugas horizon panjang.
• Anda memiliki biaya per-tugas yang dapat diprediksi atau batas latensi untuk diterapkan.
• Anda ingin model menyelesaikan dengan anggun (merangkum temuan, melaporkan kemajuan) saat mendekati anggaran daripada memotong di tengah-aksi.

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 agentic.

Menetapkan anggaran tugas

Tambahkan task_budget ke output_config dan sertakan header beta:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"],
)

Objek task_budget memiliki tiga bidang:

• type: selalu "tokens".
• total: jumlah token yang dapat dihabiskan Claude di seluruh loop agentic, termasuk pemikiran, panggilan alat, hasil alat, dan output.
• remaining (opsional): sisa anggaran yang dibawa dari permintaan sebelumnya. Defaultnya adalah total saat dihilangkan.

Cara kerja hitungan mundur anggaran

Claude melihat penanda hitungan mundur anggaran yang disuntikkan sisi server di seluruh percakapan. Penanda menunjukkan berapa banyak token yang tersisa dalam loop agentic saat ini dan diperbarui saat model menghasilkan pemikiran, panggilan alat, dan output, serta saat memproses hasil alat. Claude menggunakan sinyal ini untuk mengatur kecepatan dirinya dan menyelesaikan dengan anggun saat anggaran dikonsumsi.

Contoh yang dikerjakan: penghitungan anggaran di seluruh giliran

Anggaran tugas menghitung apa yang Claude lihat (pemikiran, panggilan alat dan hasil, serta teks), bukan apa yang ada dalam muatan permintaan Anda. Dalam loop agentic, klien Anda mengirim kembali percakapan lengkap pada setiap permintaan, sehingga muatan tumbuh giliran demi giliran, tetapi anggaran hanya berkurang dengan token yang Claude lihat giliran ini.

Pertimbangkan 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, kemudian memancarkan 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 Claude lihat selama generasi berakhir dekat remaining ≈ 95.000.

Giliran 2. Klien Anda menjalankan alat, kemudian mengirim kembali 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 pengguna dan asisten giliran 1 yang dikirim kembali tidak dihitung lagi, tetapi hasil alat 2.800-token adalah konten baru yang Claude lihat 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 dekat remaining ≈ 88.200.

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

Meletakkan tiga giliran berdampingan membuat perbedaan antara ukuran muatan dan pengeluaran anggaran eksplisit:

Klien Anda mengirim pesan pengguna giliran 1 tiga kali dan pesan asisten giliran 1 dua kali, tetapi masing-masing dihitung sekali. Anggaran menghabiskan 19.000 dari 100.000 token, meskipun muatan kumulatif yang dikirim klien Anda lebih besar dan input yang disimpan cache pada giliran 2 dan 3 lebih besar lagi.

Membawa anggaran di seluruh pemadatan dengan remaining

Jika loop agentic Anda memadatkan atau menulis ulang konteks antara permintaan (misalnya, dengan merangkum giliran sebelumnya), server tidak memiliki memori tentang berapa banyak anggaran yang dihabiskan sebelum pemadatan. Lewatkan remaining pada permintaan berikutnya sehingga hitungan mundur berlanjut dari tempat Anda tinggalkan daripada mengatur ulang ke total:

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

Untuk loop yang mengirim kembali riwayat lengkap yang tidak dipadatkan pada setiap giliran, hilangkan remaining dan biarkan server melacak hitungan mundur.

Anggaran tugas bersifat penasihat, bukan diterapkan

Anggaran tugas adalah petunjuk lembut, bukan batas keras. Claude mungkin kadang-kadang melampaui anggaran jika berada di tengah-tengah tindakan yang akan lebih mengganggu untuk dihentikan daripada diselesaikan. Batas yang diterapkan pada total token output masih max_tokens, yang memotong respons dengan stop_reason: "max_tokens" saat tercapai.

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

• Gunakan task_budget untuk memberikan Claude target untuk mengatur kecepatan.
• Gunakan max_tokens sebagai batas absolut yang mencegah generasi liar.

Karena task_budget mencakup loop agentic penuh (berpotensi banyak permintaan) sementara max_tokens membatasi setiap permintaan individual, kedua nilai tersebut independen; satu tidak diperlukan untuk berada di atau di bawah yang lain.

Memilih anggaran

Anggaran yang tepat tergantung pada berapa banyak pekerjaan yang dilakukan loop agentic Anda saat ini. Daripada menebak, ukur penggunaan token yang ada terlebih dahulu dan kemudian sesuaikan dari sana.

Ukur penggunaan saat ini Anda

Jalankan sampel tugas yang representatif tanpa task_budget yang ditetapkan dan catat total token yang dihabiskan Claude per tugas. Untuk loop agentic, jumlahkan usage.output_tokens ditambah pemikiran dan token hasil alat di seluruh 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:
        response = client.beta.messages.create(
            model="claude-opus-4-7",
            max_tokens=128000,
            messages=messages,
            tools=tools,
            betas=["task-budgets-2026-03-13"],
        )
        # Count what Claude generated this turn (output covers text + thinking + tool calls).
        # Tool-result tokens also count against the budget; add the token count of the
        # tool_result blocks you append below if you want client-side tracking to match
        # the server-side countdown.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # Append the assistant turn and your tool results, then continue the loop.
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": run_tools(response.content)},
        ]

Jalankan ini di seluruh set tugas yang representatif dan catat distribusinya. Mulai dengan p99 pengeluaran token per-tugas Anda untuk memahami bagaimana memberikan model dengan anggaran tugas dapat mengubah perilaku model, kemudian uji naik atau turun sesuai kebutuhan.

Minimum yang diterima task_budget.total adalah 20.000 token; nilai di bawah minimum mengembalikan kesalahan 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 penasihat di seluruh loop agentic penuh (berpotensi mencakup banyak permintaan). Pada effort xhigh atau max, atur 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 seluruh loop agentic. Keduanya saling melengkapi: effort menyesuaikan kedalaman, anggaran tugas menyesuaikan luas.
• Adaptive thinking: Anggaran tugas termasuk token pemikiran dalam hitungan, sehingga pemikiran adaptif secara alami berkurang saat anggaran habis.
• Prompt caching: Penanda hitungan mundur anggaran disuntikkan sisi server per giliran, sehingga tidak cocok di seluruh permintaan. Jika klien Anda mengurangi task_budget.remaining pada setiap permintaan tindak lanjut, nilai yang berubah membatalkan awalan cache apa pun yang memuatnya. Untuk mempertahankan caching, atur anggaran sekali pada permintaan awal dan biarkan model mengatur diri sendiri terhadap hitungan mundur sisi server daripada memutasi anggaran sisi klien.

Dukungan fitur

Anggaran tugas tidak didukung di permukaan Claude Code atau Cowork saat peluncuran. Gunakan anggaran tugas langsung melalui Messages API di Claude Opus 4.7.