Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.
작업 예산을 사용하면 Claude가 사고, 도구 호출, 도구 결과 및 출력을 포함한 전체 에이전트 루프에 사용할 수 있는 토큰 수를 알려줄 수 있습니다. 모델은 실시간 카운트다운을 보고 이를 사용하여 작업의 우선순위를 정하고 예산이 소비될 때 우아하게 마칠 수 있습니다.
작업 예산은 Claude Opus 4.7에서 공개 베타 상태입니다. task-budgets-2026-03-13 베타 헤더를 설정하여 옵트인하세요.
작업 예산은 Claude가 여러 도구 호출과 결정을 한 후 다음 사용자 응답을 기다리기 위해 출력을 최종화하는 에이전트 워크플로우에 가장 적합합니다. 다음과 같은 경우에 사용하세요:
작업 예산은 노력 매개변수를 보완합니다: 노력은 Claude가 각 단계에 대해 얼마나 철저히 추론하는지를 제어하고, 작업 예산은 Claude가 에이전트 루프 전체에서 수행할 수 있는 총 작업을 제한합니다.
output_config에 task_budget을 추가하고 베타 헤더를 포함하세요:
Was this page helpful?
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"],
)task_budget 객체는 세 가지 필드를 가집니다:
type: 항상 "tokens".total: Claude가 사고, 도구 호출, 도구 결과 및 출력을 포함한 에이전트 루프 전체에서 사용할 수 있는 토큰 수.remaining (선택사항): 이전 요청에서 이월된 예산 잔액. 생략하면 total로 기본값 설정됨.Claude는 대화 전체에서 서버 측에 주입된 예산 카운트다운 마커를 봅니다. 마커는 현재 에이전트 루프에 남은 토큰 수를 표시하고 모델이 사고, 도구 호출 및 출력을 생성하고 도구 결과를 처리할 때 업데이트됩니다. Claude는 이 신호를 사용하여 자신의 속도를 조절하고 예산이 소비될 때 우아하게 마칩니다.
카운트다운은 Claude가 현재 에이전트 루프에서 처리한 토큰을 반영하며, 턴 사이에 재전송하는 토큰이 아닙니다. 클라이언트가 모든 후속 요청에서 전체 대화 기록을 보내면 클라이언트 측 토큰 수가 Claude가 추적 중인 예산과 다를 수 있습니다. 전체 기록을 재전송하면서 remaining을 감소시키면 모델은 과소 보고된 예산을 보고 카운트다운이 실제 허용보다 빠르게 떨어져 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.
세 턴을 나란히 놓으면 페이로드 크기와 예산 지출 간의 구분이 명확해집니다:
| 턴 | 요청 페이로드 (약 전송한 입력 토큰) | 이번 턴에 예산에 계산된 토큰 | 이후 예산 remaining |
|---|---|---|---|
| 1 | ~20 | 5,000 (사고 + tool_use) | ~95,000 |
| 2 | ~7,800 (턴 1 기록 + 도구 결과) | 6,800 (2,800 도구 결과 + 4,000 사고 및 tool_use) | ~88,200 |
| 3 | ~13,000 (전체 기록 + 두 번째 도구 결과) | 7,200 (1,200 도구 결과 + 6,000 text) | ~81,000 |
| 합계 | ~20,820 요청 전체에서 전송 | 예산에 계산된 19,000 | — |
클라이언트는 턴 1 사용자 메시지를 세 번, 턴 1 어시스턴트 메시지를 두 번 보냈지만 각각 한 번씩만 계산되었습니다. 예산은 100,000개 중 19,000개를 사용했으며, 클라이언트가 전송한 누적 페이로드가 더 크고 턴 2와 3의 프롬프트 캐시된 입력이 더 컸음에도 불구하고 그렇습니다.
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은 각 개별 요청을 제한하므로 두 값은 독립적입니다. 하나가 다른 하나에서 또는 아래에 있어야 할 필요는 없습니다.
작업에 너무 작은 예산은 거부와 유사한 동작을 유발할 수 있습니다. Claude가 요청된 작업에 명확히 불충분한 예산을 보면(예: 다중 시간 에이전트 코딩 작업에 대한 20,000토큰 예산) 작업을 시도하지 않거나 공격적으로 범위를 축소하거나 마칠 수 없는 작업을 시작하기보다는 부분 결과로 일찍 중지할 수 있습니다. 예산을 설정한 후 예상치 못한 거부 또는 조기 중지를 관찰하면 다른 매개변수를 디버깅하기 전에 예산을 올리세요. 고정 기본값이 아닌 실제 작업 길이 분포에 대해 예산을 크기 조정하세요. 예산 선택을 참조하세요.
올바른 예산은 에이전트 루프가 현재 수행하는 작업의 양에 따라 다릅니다. 추측하기보다는 먼저 기존 토큰 사용량을 측정한 후 거기서 조정하세요.
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:
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)},
]대표적인 작업 세트 전체에서 이를 실행하고 분포를 기록하세요. 작업 예산을 제공하면 모델의 동작이 어떻게 변할 수 있는지 이해하기 위해 작업당 토큰 지출의 p99로 시작한 후 필요에 따라 위 또는 아래로 테스트하세요.
최소 허용 task_budget.total은 20,000토큰입니다. 최소값 이하의 값은 400 오류를 반환합니다.
max_tokens: 작업 예산과 직교합니다. max_tokens은 생성된 토큰에 대한 하드 요청당 캡이고 task_budget은 전체 에이전트 루프(잠재적으로 많은 요청에 걸쳐)에 대한 권장 캡입니다. xhigh 또는 max 노력에서 Claude가 각 요청에서 생각하고 행동할 수 있는 공간을 주기 위해 max_tokens을 최소 64k로 설정하세요.task_budget.remaining을 감소시키면 변경된 값은 이를 포함하는 캐시 접두사를 무효화합니다. 캐싱을 유지하려면 초기 요청에서 예산을 한 번 설정하고 클라이언트 측에서 예산을 변경하기보다는 모델이 서버 측 카운트다운에 대해 자체 조절하도록 하세요.| 모델 | 지원 |
|---|---|
| Claude Opus 4.7 | 공개 베타 (task-budgets-2026-03-13 헤더 설정) |
| Claude Opus 4.6 | 지원되지 않음 |
| Claude Sonnet 4.6 | 지원되지 않음 |
| Claude Haiku 4.5 | 지원되지 않음 |
작업 예산은 출시 시 Claude Code 또는 Cowork 표면에서 지원되지 않습니다. Claude Opus 4.7에서 Messages API를 통해 직접 작업 예산을 사용하세요.