---
title: 작업 예산
url: https://platform.claude.com/docs/ko/build-with-claude/task-budgets
description: 긴 에이전트 작업에서 모델이 스스로 조절할 수 있도록 전체 에이전트 루프에 대한 권고용 토큰 예산을 Claude에게 제공합니다.
featureMetadata:
  status: beta
  betaHeader: task-budgets-2026-03-13
  supportedModels:
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-opus-5-5
    - claude-opus-5
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-sonnet-5-5
    - claude-haiku-5-5
---

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

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

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

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

작업 예산은 [effort 매개변수](https://platform.claude.com/docs/ko/build-with-claude/effort)를 보완합니다. effort는 Claude가 각 단계를 얼마나 철저하게 추론하는지를 제어하는 반면, 작업 예산은 Claude가 에이전트 루프 전체에서 수행할 수 있는 총 작업량에 상한을 둡니다.

## 작업 예산 설정하기

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

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -N \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: task-budgets-2026-03-13" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 128000,
      "stream": true,
      "messages": [{
        "role": "user",
        "content": "Review the codebase and propose a refactor plan."
      }],
      "output_config": {
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 64000}
      }
    }'
  ```

  ```bash CLI
  ant beta:messages create --beta task-budgets-2026-03-13 \
    --stream --format jsonl <<'YAML' | jq 'select(.type == "message_delta").usage'
  model: claude-opus-5-5
  max_tokens: 128000
  messages:
    - role: user
      content: Review the codebase and propose a refactor plan.
  output_config:
    effort: high
    task_budget:
      type: tokens
      total: 64000
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const stream = 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"]
  });

  const response = await stream.finalMessage();
  console.log(response.usage);
  ```

  ```csharp C#

  var client = new AnthropicClient();

  var responseUpdates = client.Beta.Messages.CreateStreaming(new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 128000,
      Messages = [new() { Role = Role.User, Content = "Review the codebase and propose a refactor plan." }],
      OutputConfig = new BetaOutputConfig
      {
          Effort = Effort.High,
          TaskBudget = new BetaTokenTaskBudget { Total = 64000 },
      },
      Betas = ["task-budgets-2026-03-13"],
  });

  var response = await responseUpdates.Aggregate();
  Console.WriteLine(response.Usage);
  ```

  ```go Go
  client := anthropic.NewClient()

  stream := client.Beta.Messages.NewStreaming(context.TODO(), anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 128000,
  	Betas:     []anthropic.AnthropicBeta{"task-budgets-2026-03-13"},
  	Messages: []anthropic.BetaMessageParam{{
  		Role: anthropic.BetaMessageParamRoleUser,
  		Content: []anthropic.BetaContentBlockParamUnion{{
  			OfText: &anthropic.BetaTextBlockParam{Text: "Review the codebase and propose a refactor plan."},
  		}},
  	}},
  	OutputConfig: anthropic.BetaOutputConfigParam{
  		Effort: anthropic.BetaOutputConfigEffortHigh,
  		TaskBudget: anthropic.BetaTokenTaskBudgetParam{
  			Total: 64000,
  		},
  	},
  })

  message := anthropic.BetaMessage{}
  for stream.Next() {
  	event := stream.Current()
  	if err := message.Accumulate(event); err != nil {
  		panic(err)
  	}
  }
  if stream.Err() != nil {
  	panic(stream.Err())
  }

  fmt.Printf("Usage: input_tokens=%d, output_tokens=%d\n", message.Usage.InputTokens, message.Usage.OutputTokens)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(128000L)
      .addUserMessage("Review the codebase and propose a refactor plan.")
      .outputConfig(BetaOutputConfig.builder()
          .effort(BetaOutputConfig.Effort.HIGH)
          .taskBudget(BetaTokenTaskBudget.builder().total(64000L).build())
          .build())
      .addBeta("task-budgets-2026-03-13")
      .build();

  BetaMessageAccumulator accumulator = BetaMessageAccumulator.create();
  try (StreamResponse<BetaRawMessageStreamEvent> stream =
          client.beta().messages().createStreaming(params)) {
      stream.stream().forEach(accumulator::accumulate);
  }

  BetaMessage response = accumulator.message();
  IO.println(response.usage());
  ```

  ```php PHP
  use Anthropic\Beta\Messages\BetaRawMessageDeltaEvent;

  $client = new Client();

  $stream = $client->beta->messages->createStream(
      model: 'claude-opus-5-5',
      maxTokens: 128000,
      messages: [
          ['role' => 'user', 'content' => 'Review the codebase and propose a refactor plan.'],
      ],
      outputConfig: [
          'effort' => 'high',
          'taskBudget' => ['type' => 'tokens', 'total' => 64000],
      ],
      betas: ['task-budgets-2026-03-13'],
  );

  // 마지막 message_delta 이벤트에는 요청의 누적 토큰 사용량이 포함됩니다.
  $usage = null;
  foreach ($stream as $event) {
      if ($event instanceof BetaRawMessageDeltaEvent) {
          $usage = $event->usage;
      }
  }

  echo $usage;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  stream = client.beta.messages.stream(
    model: "claude-opus-5-5",
    max_tokens: 128_000,
    messages: [
      { role: "user", content: "Review the codebase and propose a refactor plan." }
    ],
    output_config: {
      effort: :high,
      task_budget: { type: :tokens, total: 64_000 }
    },
    betas: ["task-budgets-2026-03-13"]
  )

  response = stream.accumulated_message

  puts response.usage
  ```
</CodeGroup>

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

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

## 예산 카운트다운의 작동 방식

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

<Note>
  **카운트다운은 모델에게만 표시됩니다.** API 응답에는 남은 예산 필드가 포함되지 않습니다. 응답의 `usage` 객체에는 `task_budget` 정보가 없으며, SDK에도 이를 위한 접근자가 없습니다. 클라이언트 측에서 사용량을 추적하려면 [현재 사용량 측정하기](https://platform.claude.com/docs/ko/build-with-claude/task-budgets#measure-your-current-usage)에 나온 것처럼 루프 내 요청 전체의 토큰 사용량을 합산하거나, [압축 간에 예산을 이월할 때](https://platform.claude.com/docs/ko/build-with-claude/task-budgets#carrying-a-budget-across-compaction-with-remaining) `remaining`으로 직접 계산한 값을 전달하세요.
</Note>

<Warning>
  **카운트다운은 요청 간에 다시 전송하는 토큰이 아니라, 현재 에이전트 루프에서 Claude가 처리한 토큰을 반영합니다.** 클라이언트가 모든 후속 요청에서 전체 대화 기록을 전송하는 경우, 클라이언트 측 토큰 수는 Claude가 추적하는 예산과 다를 수 있습니다. 전체 기록을 다시 전송하면서 `remaining`도 차감하면 모델은 실제보다 적게 보고된 예산을 보게 되고 카운트다운이 필요 이상으로 빠르게 줄어들어, Claude가 예산이 실제로 허용하는 것보다 일찍 작업을 마무리하게 됩니다. 클라이언트 측에서 카운트다운을 그대로 따라 하려 하기보다는 넉넉한 예산을 설정하고 모델이 카운트다운에 맞춰 스스로 조절하도록 하세요.
</Warning>

### 턴으로 간주되는 범위

예산은 하나의 에이전트 턴, 즉 에이전트 루프를 대상으로 합니다. 이는 도구 결과를 포함하지 않는 하나의 사용자 메시지에 대한 응답으로 Claude가 수행하는 모든 작업을 의미합니다. 하나의 턴은 여러 요청에 걸쳐 있을 수 있습니다.

도구 결과를 포함하지 않는 사용자 메시지는 새로운 예산으로 새 턴을 시작합니다. 현재는 이전 턴의 기록이 컨텍스트에 남아 있는 동안 카운트다운에 여전히 포함됩니다. 흔한 사례는 예산이 소진되는 등의 이유로 Claude가 턴을 종료한 후의 후속 메시지입니다:

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

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

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

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

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

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

### 예제: 요청 간 예산 계산

작업 예산은 요청 페이로드에 담긴 내용이 아니라 Claude가 **보는** 내용(사고, 도구 호출 및 결과, 텍스트)을 계산합니다. 에이전트 루프에서 클라이언트는 매 요청마다 전체 대화를 다시 전송하므로 페이로드는 계속 커지지만, 예산은 새로운 부분, 즉 Claude가 생성하는 토큰과 이전에 보지 못한 콘텐츠만큼만 차감됩니다. 다음 예제는 세 개의 요청으로 구성된 하나의 [에이전트 턴](https://platform.claude.com/docs/ko/build-with-claude/task-budgets#what-counts-as-a-turn)입니다. 첫 번째 요청은 사용자 메시지를 전달하고, 다음 두 요청은 각각 도구 결과를 덧붙여 기록을 다시 전송합니다.

`task_budget: {type: "tokens", total: 100000}`과 단일 `bash` 도구가 있는 루프를 생각해 보세요.

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

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

Claude는 사고한 다음 도구 호출을 내보내고 `stop_reason: "tool_use"`로 멈춥니다:

```json
{
  "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.** 클라이언트가 도구를 실행한 다음, 도구 결과를 덧붙여 전체 기록을 다시 전송합니다:

```json
{
  "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입니다.

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

| 요청     | 요청 페이로드(전송한 대략적인 입력 토큰)      | 이 요청에서 예산에 포함된 토큰                          | 이후 예산 `remaining` |
| ------ | ---------------------------- | ------------------------------------------ | ----------------- |
| 1      | \~20                         | 5,000(사고 + `tool_use`)                     | \~95,000          |
| 2      | \~7,800(요청 1의 메시지 + 도구 결과)   | 6,800(도구 결과 2,800 + 사고 및 `tool_use` 4,000) | \~88,200          |
| 3      | \~13,000(전체 기록 + 두 번째 도구 결과) | 7,200(도구 결과 1,200 + `text` 6,000)          | \~81,000          |
| **합계** | **요청 전체에 걸쳐 \~20,820 전송**    | **예산에 19,000 포함**                          | 해당 없음             |

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

### `remaining`으로 컴팩션을 거쳐 예산 이어가기

자체 코드에서 요청 사이에 메시지 기록을 압축하거나 다시 작성하는 경우(예: 이전 메시지를 요약하는 경우), 서버는 압축 이전에 예산이 얼마나 사용되었는지 기억하지 못합니다. 카운트다운이 `total`로 초기화되지 않고 중단된 지점부터 이어지도록 다음 요청에 `remaining`을 전달하세요:

<CodeGroup exclude="shell">
  ```python Python
  # 압축 전에 사용된 토큰, 클라이언트 측에서 추적
  tokens_spent_so_far = 45000

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

  ```typescript TypeScript
  // 압축 전에 사용된 토큰, 클라이언트 측에서 추적
  const tokensSpentSoFar = 45000;

  const outputConfig = {
    effort: "high",
    task_budget: {
      type: "tokens",
      total: 128000,
      remaining: 128000 - tokensSpentSoFar
    }
  };
  ```

  ```csharp C#
  // 압축 전에 사용된 토큰 수, 클라이언트 측에서 추적
  var tokensSpentSoFar = 45000;

  var outputConfig = new BetaOutputConfig
  {
      Effort = Effort.High,
      TaskBudget = new BetaTokenTaskBudget
      {
          Total = 128000,
          Remaining = 128000 - tokensSpentSoFar,
      },
  };
  ```

  ```go Go
  // 압축 전에 사용된 토큰 수, 클라이언트 측에서 추적
  tokensSpentSoFar := int64(45000)

  outputConfig := anthropic.BetaOutputConfigParam{
  	Effort: anthropic.BetaOutputConfigEffortHigh,
  	TaskBudget: anthropic.BetaTokenTaskBudgetParam{
  		Total:     128000,
  		Remaining: anthropic.Int(128000 - tokensSpentSoFar),
  	},
  }
  ```

  ```java Java
  // 압축 전에 사용된 토큰, 클라이언트 측에서 추적
  long tokensSpentSoFar = 45000;

  BetaOutputConfig outputConfig = BetaOutputConfig.builder()
      .effort(BetaOutputConfig.Effort.HIGH)
      .taskBudget(BetaTokenTaskBudget.builder()
          .total(128000L)
          .remaining(128000L - tokensSpentSoFar)
          .build())
      .build();
  ```

  ```php PHP
  // 압축 전에 사용된 토큰 수, 클라이언트 측에서 추적
  $tokensSpentSoFar = 45000;

  $outputConfig = [
      'effort' => 'high',
      'taskBudget' => [
          'type' => 'tokens',
          'total' => 128000,
          'remaining' => 128000 - $tokensSpentSoFar,
      ],
  ];
  ```

  ```ruby Ruby
  # 압축 전에 사용된 토큰, 클라이언트 측에서 추적
  tokens_spent_so_far = 45_000

  output_config = {
    effort: :high,
    task_budget: {
      type: :tokens,
      total: 128_000,
      remaining: 128_000 - tokens_spent_so_far
    }
  }
  ```
</CodeGroup>

이 예제에서 압축 이전에 사용된 토큰은 지금까지 기록에서 제거한 모든 메시지의 사용량이며, [현재 사용량 측정하기](https://platform.claude.com/docs/ko/build-with-claude/task-budgets#measure-your-current-usage)에서와 같은 방식으로 측정합니다. 추가한 요약을 포함하여 전송하는 메시지에 여전히 남아 있는 내용은 제외하세요. 서버가 해당 토큰을 직접 계산하기 때문입니다. 이 값은 이런 방식으로 기록을 교체할 때만 업데이트하고, 요청마다 차감하지 마세요. 계산된 `remaining`은 압축하는 요청뿐만 아니라 모든 요청에 전달하세요.

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

## 대화 중간에 예산 변경하기

`task_budget`은 요청 수준의 설정입니다. 작업 도중에 예산을 변경하려면(예: 사용자가 요청 범위를 넓혔을 때 예산을 늘리려면) 다음 요청의 `output_config`에 새 `task_budget`을 설정하세요. 캐싱에 미치는 영향을 염두에 두세요. 예산 값은 렌더링된 프롬프트에 포함되므로, 변경된 값은 이전 값으로 생성된 캐시 항목과 일치하지 않습니다(아래 [기능 지원](https://platform.claude.com/docs/ko/build-with-claude/task-budgets#feature-support) 참조).

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

작업 예산은 **하드 캡이 아닌 소프트 힌트**입니다. Claude가 중단하는 것이 마무리하는 것보다 더 지장을 주는 작업을 진행 중인 경우, 때때로 예산을 초과할 수 있습니다. 총 출력 토큰에 대한 강제 한도는 여전히 `max_tokens`이며, 이에 도달하면 `stop_reason: "max_tokens"`로 응답이 잘립니다.

비용이나 지연 시간에 하드 캡을 두려면 작업 예산을 적절한 `max_tokens` 값과 함께 사용하세요:

* `task_budget`을 사용하여 Claude가 속도를 맞출 목표를 제공하세요.
* `max_tokens`를 무제한 생성을 방지하는 절대 상한으로 사용하세요.

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

<Warning>
  **작업에 비해 너무 작은 예산은 거부와 유사한 동작을 유발할 수 있습니다.** Claude가 요청된 작업에 명백히 부족한 예산을 보면(예: 여러 시간이 걸리는 에이전트 코딩 작업에 20,000토큰 예산), 끝낼 수 없는 작업을 시작하기보다는 작업 시도 자체를 거부하거나, 범위를 공격적으로 축소하거나, 부분적인 결과로 일찍 멈출 수 있습니다. 예산을 설정한 후 예상치 못한 거부나 조기 중단이 관찰되면, 다른 매개변수를 디버깅하기 전에 예산을 늘리세요. 고정된 기본값이 아니라 실제 작업 길이 분포에 맞춰 예산 크기를 정하세요. [예산 선택하기](https://platform.claude.com/docs/ko/build-with-claude/task-budgets#choosing-a-budget)를 참조하세요.
</Warning>

## 예산 선택하기

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

### 현재 사용량 측정하기

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

<CodeGroup exclude="shell:cURL">
  ```bash CLI
  ant messages create --transform 'usage.output_tokens' <<'YAML'
  model: claude-opus-5-5
  max_tokens: 4096
  messages:
    - role: user
      content: Review the codebase and propose a refactor plan.
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await 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(텍스트 + 사고 + 도구 호출)를 합산합니다.
  console.log(response.usage.output_tokens);
  ```

  ```csharp C#

  var client = new AnthropicClient();

  var response = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [new() { Role = Role.User, Content = "Review the codebase and propose a refactor plan." }],
  });

  // 루프의 모든 요청에 걸쳐 OutputTokens(텍스트 + 사고 + 도구 호출)를 합산합니다.
  Console.WriteLine(response.Usage.OutputTokens);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Review the codebase and propose a refactor plan.")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  // 루프의 모든 요청에 걸쳐 OutputTokens(텍스트 + 사고 + 도구 호출)를 합산합니다.
  fmt.Println(response.Usage.OutputTokens)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(4096L)
      .addUserMessage("Review the codebase and propose a refactor plan.")
      .build();

  Message response = client.messages().create(params);
  // 루프의 모든 요청에 걸쳐 outputTokens(텍스트 + 사고 + 도구 호출)를 합산합니다.
  IO.println(response.usage().outputTokens());
  ```

  ```php PHP
  $client = new Client();

  $response = $client->messages->create(
      model: 'claude-opus-5-5',
      maxTokens: 4096,
      messages: [
          ['role' => 'user', 'content' => 'Review the codebase and propose a refactor plan.'],
      ],
  );

  // 루프의 모든 요청에 걸쳐 outputTokens(텍스트 + 사고 + 도구 호출)를 합산합니다.
  echo $response->usage->outputTokens . "\n";
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  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(텍스트 + 사고 + 도구 호출)를 합산합니다.
  puts response.usage.output_tokens
  ```
</CodeGroup>

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

허용되는 최소 `task_budget.total`은 작업 예산을 지원하는 모든 모델에서 **20,000 토큰**입니다([기능 지원](https://platform.claude.com/docs/ko/build-with-claude/task-budgets#feature-support) 참조). 이보다 작은 값은 400 오류를 반환합니다.

## 다른 매개변수와의 상호작용

* **`max_tokens`:** 작업 예산과 독립적입니다. `max_tokens`는 생성 토큰에 대한 요청별 엄격한 상한인 반면, `task_budget`은 전체 에이전트 루프(잠재적으로 여러 요청에 걸침)에 대한 권고성 상한입니다. `xhigh` 또는 `max` effort에서는 Claude가 각 요청에서 사고하고 행동할 여유를 갖도록 `max_tokens`를 최소 64k로 설정하세요.
* **[Effort](https://platform.claude.com/docs/ko/build-with-claude/effort):** effort는 Claude가 단계별로 얼마나 깊이 추론할지를 제어합니다. 작업 예산은 에이전트 루프 전체에서 Claude가 수행하는 총 작업량을 제어합니다. 두 기능은 상호 보완적입니다. effort는 깊이를, 작업 예산은 폭을 조정합니다.
* **[적응형 사고](https://platform.claude.com/docs/ko/build-with-claude/thinking):** 작업 예산은 사고 토큰을 계산에 포함하므로, 예산이 줄어들수록 적응형 사고도 축소됩니다.
* **[프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching):** 예산 카운트다운 마커는 각 요청마다 서버 측에서 삽입되므로 요청 간에 일치하지 않습니다. 클라이언트가 후속 요청마다 `task_budget.remaining`을 차감하면, 변경된 값이 해당 값을 포함하는 모든 캐시 접두사를 무효화합니다. 캐싱을 유지하려면 초기 요청에서 예산을 한 번만 설정하고, 클라이언트 측에서 예산을 변경하는 대신 모델이 서버 측 카운트다운에 맞춰 스스로 조절하도록 하세요.

## 기능 지원

| 모델                | 지원                                  |
| ----------------- | ----------------------------------- |
| Claude Fable 5.1  | 베타(`task-budgets-2026-03-13` 헤더 설정) |
| Claude Mythos 5.1 | 베타(`task-budgets-2026-03-13` 헤더 설정) |
| Claude Opus 5.5   | 베타(`task-budgets-2026-03-13` 헤더 설정) |
| Claude Opus 5     | 베타(`task-budgets-2026-03-13` 헤더 설정) |
| Claude Fable 5    | 베타(`task-budgets-2026-03-13` 헤더 설정) |
| Claude Mythos 5   | 베타(`task-budgets-2026-03-13` 헤더 설정) |
| Claude Sonnet 5.5 | 베타(`task-budgets-2026-03-13` 헤더 설정) |
| Claude Sonnet 5   | 지원되지 않음                             |
| Claude Haiku 5.5  | 베타(`task-budgets-2026-03-13` 헤더 설정) |
| Claude Opus 4.8   | 베타(`task-budgets-2026-03-13` 헤더 설정) |
| Claude Opus 4.7   | 베타(`task-budgets-2026-03-13` 헤더 설정) |
| Claude Opus 4.6   | 지원되지 않음                             |
| Claude Sonnet 4.6 | 지원되지 않음                             |
| Claude Haiku 4.5  | 지원되지 않음                             |

작업 예산은 [Claude Code](https://code.claude.com/docs/ko/overview) 또는 Cowork 환경에서는 지원되지 않습니다. [지원되는 모델](https://platform.claude.com/docs/ko/build-with-claude/task-budgets#feature-support)에서 Messages API를 통해 작업 예산을 직접 사용하세요.

## 다음 단계

<CardGroup>
  <Card title="Effort" icon="gauge" href="https://platform.claude.com/docs/ko/build-with-claude/effort">
    Claude가 에이전트 루프의 각 단계에 대해 얼마나 철저하게 추론하는지 제어합니다.
  </Card>

  <Card title="적응형 사고" icon="brain" href="https://platform.claude.com/docs/ko/build-with-claude/thinking">
    확장 사고를 언제, 얼마나 사용할지 Claude가 결정하도록 합니다.
  </Card>

  <Card title="압축" icon="arrows-clockwise" href="https://platform.claude.com/docs/ko/build-with-claude/compaction">
    서버 측 압축으로 장시간 실행되는 대화의 컨텍스트를 관리합니다.
  </Card>

  <Card title="프롬프트 캐싱" icon="database" href="https://platform.claude.com/docs/ko/build-with-claude/prompt-caching">
    프롬프트 접두사를 캐싱하여 반복되는 프롬프트의 비용과 지연 시간을 줄입니다.
  </Card>
</CardGroup>