작업 예산

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

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

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

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

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

작업 예산 설정하기

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

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-5-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가 턴을 종료한 후의 후속 메시지입니다:

{ "role": "user", "content": "Continue." }

tool_result 블록을 포함하는 사용자 메시지는 현재 턴을 이어갑니다. 클라이언트가 해당 턴에 속한 도구 호출을 처리하고 있기 때문입니다:

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" }
  ]
}

이는 메시지가 도구 결과와 함께 새로운 콘텐츠를 추가하는 경우에도 마찬가지입니다:

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" },
    { "type": "text", "text": "Also check the Dockerfile." }
  ]
}

턴 중에 발생하는 서버 측 압축은 예산을 재설정하지 않습니다. 압축 전에 해당 턴이 소비한 토큰은 여전히 예산에 포함됩니다. 턴이 시작되기 전의 토큰은 턴 시작 시의 압축이 이를 요약하더라도 포함되지 않습니다. 현재로서는 이 제외 규칙이 서버 측 압축을 거쳐 이월되는 예산에만 적용되며, 이전 턴의 기록은 컨텍스트에 남아 있는 동안 여전히 포함됩니다.

예제: 요청 간 예산 계산

작업 예산은 요청 페이로드에 담긴 내용이 아니라 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는 사고와 두 번째 도구 호출(grep -rn "eval(" src/)에 4,000 토큰을 추가로 사용합니다. 카운트다운은 remaining ≈ 88,200 부근에서 끝납니다.

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

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

클라이언트는 원래의 사용자 메시지를 세 번, 첫 번째 어시스턴트 메시지를 두 번 전송했지만, 각각은 한 번만 계산되었습니다. 클라이언트가 전송한 누적 페이로드가 더 컸고 요청 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은 압축하는 요청뿐만 아니라 모든 요청에 전달하세요.

매 요청마다 압축되지 않은 전체 기록을 다시 전송하는 루프의 경우, 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-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를 통해 작업 예산을 직접 사용하세요.

다음 단계

Compatibility