작업 예산

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



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

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

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

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



작업 예산 설정하기

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

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)

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으로 압축 간 예산 이월하기

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

# 압축 전에 사용된 토큰, 클라이언트 측에서 추적됨
tokens_spent_so_far = 45000

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

모든 턴에서 압축되지 않은 전체 기록을 재전송하는 루프의 경우, remaining을 생략하고 서버가 카운트다운을 추적하도록 하세요.



대화 중간에 예산 변경하기

task_budget은 요청 수준 설정입니다. 작업 도중에 예산을 변경하려면(예: 사용자가 요청 범위를 확장할 때 예산을 늘리려면) 다음 요청의 output_config에 새로운 task_budget을 설정하세요. 캐싱에 미치는 영향을 염두에 두세요. 예산 값은 렌더링된 프롬프트에 포함되므로, 변경된 값은 이전 값으로 생성된 캐시 항목과 일치하지 않습니다(아래 기능 지원 참조).



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

작업 예산은 하드 캡이 아닌 소프트 힌트입니다. Claude는 완료하는 것보다 중단하는 것이 더 방해가 되는 작업 중간에 있는 경우 가끔 예산을 초과할 수 있습니다. 총 출력 토큰에 대해 강제되는 제한은 여전히 max_tokens이며, 이 값에 도달하면 stop_reason: "max_tokens"로 응답이 잘립니다.

비용이나 지연 시간에 대한 하드 캡을 원하는 경우, 작업 예산을 적절한 max_tokens 값과 함께 사용하세요.

• task_budget을 사용하여 Claude에게 속도를 조절할 목표를 제공하세요.
• max_tokens를 사용하여 과도한 생성을 방지하는 절대 상한으로 설정하세요.

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



예산 선택하기

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



현재 사용량 측정하기

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

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."}
    ],
)

# 루프의 모든 요청에서 output_tokens(텍스트 + 사고 + 도구 호출)를 합산하세요.
print(response.usage.output_tokens)

대표적인 작업 세트에서 이를 실행하고 분포를 기록하세요. 모델에 작업 예산을 제공하는 것이 모델의 동작을 어떻게 변경할 수 있는지 이해하기 위해 작업당 토큰 소비의 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를 통해 직접 작업 예산을 사용하세요.



다음 단계