작업 예산

"Task budget"(작업 예산)을 사용하면 사고, 도구 호출, 도구 결과, 출력을 포함한 전체 에이전틱 루프에 대해 Claude가 사용할 수 있는 토큰 수를 알려줄 수 있습니다. 모델은 실시간 카운트다운을 확인하고 이를 사용하여 작업의 우선순위를 정하고 예산이 소진됨에 따라 원활하게 마무리합니다.



작업 예산을 사용해야 하는 경우

작업 예산은 Claude가 다음 사람의 응답을 기다리기 전에 출력을 확정하기까지 여러 도구 호출과 결정을 내리는 에이전틱 워크플로에 가장 적합합니다. 다음과 같은 경우에 사용하세요:

• 장기 작업에서 Claude가 토큰 사용량을 스스로 조절하기를 원하는 경우.
• 작업당 예측 가능한 비용 또는 지연 시간 상한을 적용해야 하는 경우.
• 예산에 근접할 때 모델이 작업 도중에 끊기는 대신 원활하게 마무리(결과 요약, 진행 상황 보고)하기를 원하는 경우.

작업 예산은 effort 파라미터를 보완합니다. effort는 Claude가 각 단계에 대해 얼마나 철저하게 추론하는지를 제어하는 반면, 작업 예산은 에이전틱 루프 전체에서 Claude가 수행할 수 있는 총 작업량을 제한합니다.



작업 예산 설정하기

output_config에 task_budget을 추가하고 베타 헤더를 포함하세요:

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)

task_budget 객체에는 세 개의 필드가 있습니다:

• type: 항상 "tokens"입니다.
• total: 사고, 도구 호출, 도구 결과, 출력을 포함하여 에이전틱 루프 전체에서 Claude가 사용할 수 있는 토큰 수입니다.
• remaining (선택 사항): 이전 요청에서 이월된 예산 잔액입니다. 생략하면 기본값은 total입니다.



예산 카운트다운 작동 방식

Claude는 대화 전반에 걸쳐 서버 측에서 삽입되는 예산 카운트다운 마커를 확인합니다. 이 마커는 현재 에이전틱 루프에 남아 있는 토큰 수를 보여주며, 모델이 사고, 도구 호출, 출력을 생성하고 도구 결과를 처리함에 따라 업데이트됩니다. Claude는 이 신호를 사용하여 속도를 조절하고 예산이 소진됨에 따라 원활하게 마무리합니다.



실습 예제: 턴 간 예산 계산

작업 예산은 요청 페이로드에 있는 내용이 아니라 Claude가 보는 내용(사고, 도구 호출 및 결과, 텍스트)을 계산합니다. 에이전틱 루프에서 클라이언트는 모든 요청에서 전체 대화를 다시 전송하므로 페이로드는 턴마다 커지지만, 예산은 이번 턴에 Claude가 보는 토큰만큼만 감소합니다.

task_budget: {type: "tokens", total: 100000}과 단일 bash 도구가 있는 루프를 생각해 보겠습니다.

턴 1. 초기 요청을 전송합니다:

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

Claude는 사고한 다음 도구 호출을 내보내고 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" }
    }
  ]
}

이 어시스턴트 턴(사고와 도구 호출)이 총 5,000개의 생성 토큰이라고 가정합니다. 생성 중에 Claude가 본 카운트다운은 remaining ≈ 95,000 근처에서 끝났습니다.

턴 2. 클라이언트가 도구를 실행한 다음 도구 결과를 추가하여 전체 기록을 다시 전송합니다:

{
  "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>"
        }
      ]
    }
  ]
}

다시 전송된 턴 1의 사용자 및 어시스턴트 메시지는 다시 계산되지 않지만, 2,800 토큰의 도구 결과는 이번 턴에 Claude가 보는 새로운 콘텐츠이므로 예산에 반영됩니다. Claude는 사고와 두 번째 도구 호출(grep -rn "eval(" src/)에 4,000 토큰을 추가로 사용합니다. 카운트다운은 remaining ≈ 88,200 근처에서 끝납니다.

턴 3. 두 번째 도구 결과(1,200 토큰의 grep 출력)를 추가하여 전체 기록을 다시 전송합니다. Claude는 6,000 토큰의 최종 결과 보고서를 작성하고 stop_reason: "end_turn"으로 중지합니다. remaining ≈ 81,000.

세 턴을 나란히 놓고 보면 페이로드 크기와 예산 사용량의 차이가 명확해집니다:

클라이언트는 턴 1의 사용자 메시지를 세 번, 턴 1의 어시스턴트 메시지를 두 번 전송했지만 각각 한 번만 계산되었습니다. 클라이언트가 전송한 누적 페이로드가 더 크고 턴 2와 3에서 프롬프트 캐싱된 입력이 훨씬 더 컸음에도 불구하고, 예산은 100,000 토큰 중 19,000 토큰을 사용했습니다.



remaining으로 컴팩션 간 예산 이월하기

에이전틱 루프가 요청 사이에 컨텍스트를 컴팩션하거나 다시 작성하는 경우(예: 이전 턴을 요약하는 경우), 서버는 컴팩션 이전에 얼마나 많은 예산이 사용되었는지 기억하지 못합니다. 다음 요청에서 remaining을 전달하여 카운트다운이 total로 재설정되지 않고 중단된 지점부터 계속되도록 하세요:

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

매 턴마다 컴팩션되지 않은 전체 기록을 다시 전송하는 루프의 경우, remaining을 생략하고 서버가 카운트다운을 추적하도록 하세요.



작업 예산은 권고 사항이며 강제되지 않습니다

작업 예산은 엄격한 상한이 아닌 부드러운 힌트입니다. Claude는 중단하는 것이 완료하는 것보다 더 큰 혼란을 초래하는 작업 도중에 있는 경우 가끔 예산을 초과할 수 있습니다. 총 출력 토큰에 대한 강제 제한은 여전히 max_tokens이며, 도달하면 stop_reason: "max_tokens"로 응답이 잘립니다.

비용이나 지연 시간에 대한 엄격한 상한을 원한다면 작업 예산을 적절한 max_tokens 값과 결합하세요:

• task_budget을 사용하여 Claude가 속도를 조절할 목표를 제공합니다.
• max_tokens를 폭주 생성을 방지하는 절대 상한으로 사용합니다.

task_budget은 전체 에이전틱 루프(잠재적으로 여러 요청)에 걸쳐 적용되는 반면 max_tokens는 각 개별 요청을 제한하므로, 두 값은 독립적입니다. 한 값이 다른 값 이하일 필요는 없습니다.



예산 선택하기

적절한 예산은 에이전틱 루프가 현재 수행하는 작업량에 따라 달라집니다. 추측하기보다는 먼저 기존 토큰 사용량을 측정한 다음 거기서부터 조정하세요.



현재 사용량 측정하기

task_budget을 설정하지 않고 대표적인 작업 샘플을 실행하고 작업당 Claude가 사용하는 총 토큰을 기록하세요. 에이전틱 루프의 경우, 루프 내 모든 요청에 걸쳐 usage.output_tokens와 사고 및 도구 결과 토큰을 합산하세요:

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()
        # 이번 턴에서 Claude가 생성한 내용을 계산합니다 (출력에는 텍스트 + 사고 + 도구 호출이 포함됩니다).
        # 도구 결과 토큰도 예산에 포함됩니다. 클라이언트 측 추적을
        # 서버 측 카운트다운과 일치시키려면 아래에 추가하는
        # tool_result 블록의 토큰 수를 더하세요.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # 어시스턴트 턴과 도구 결과를 추가한 다음 루프를 계속합니다.
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": run_tools(response.content)},
        ]

대표적인 작업 집합에 대해 이를 실행하고 분포를 기록하세요. 작업당 토큰 사용량의 p99에서 시작하여 모델에 작업 예산을 제공하는 것이 모델의 동작을 어떻게 변화시킬 수 있는지 파악한 다음, 필요에 따라 위아래로 테스트하세요.

허용되는 최소 task_budget.total은 20,000 토큰입니다. 최소값 미만의 값은 400 오류를 반환합니다.



다른 파라미터와의 상호 작용

• max_tokens: 작업 예산과 직교합니다. max_tokens는 생성된 토큰에 대한 요청당 엄격한 상한인 반면, task_budget은 전체 에이전틱 루프(잠재적으로 여러 요청에 걸쳐)에 대한 권고성 상한입니다. xhigh 또는 max effort에서는 Claude가 각 요청에서 사고하고 행동할 여유를 주기 위해 max_tokens를 최소 64k로 설정하세요.
• Effort: Effort는 Claude가 단계별로 얼마나 깊이 추론하는지를 제어합니다. 작업 예산은 에이전틱 루프 전체에서 Claude가 수행하는 총 작업량을 제어합니다. 둘은 상호 보완적입니다. effort는 깊이를 조정하고, 작업 예산은 폭을 조정합니다.
• 적응형 사고: 작업 예산은 사고 토큰을 계산에 포함하므로, 예산이 소진됨에 따라 적응형 사고가 자연스럽게 축소됩니다.
• 프롬프트 캐싱: 예산 카운트다운 마커는 턴마다 서버 측에서 삽입되므로 요청 간에 일치하지 않습니다. 클라이언트가 각 후속 요청에서 task_budget.remaining을 감소시키면, 변경된 값이 이를 포함하는 모든 캐시 접두사를 무효화합니다. 캐싱을 유지하려면 초기 요청에서 예산을 한 번 설정하고 클라이언트 측에서 예산을 변경하는 대신 모델이 서버 측 카운트다운에 맞춰 스스로 조절하도록 하세요.



기능 지원

작업 예산은 Claude Code 또는 Cowork 환경에서는 지원되지 않습니다. 지원되는 모델에서 Messages API를 통해 작업 예산을 직접 사용하세요.