---
title: 세션 예산
url: https://platform.claude.com/docs/ko/managed-agents/budgets
description: 공개 정가 기준으로 적용되는 엄격한 달러 예산으로 세션의 지출 한도를 설정합니다.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
"session budget"(세션 예산)은 [세션을 생성](https://platform.claude.com/docs/ko/managed-agents/sessions)할 때 설정하는 선택적인 엄격한 지출 상한입니다. 플랫폼은 세션이 소비하는 모든 것을 공개 정가(세션의 **list cost**(정가 비용))로 지속적으로 가격을 산정하며, 해당 비용이 예산에 도달하면 새로운 모델 요청 발행을 중단합니다. 상한을 넘는 시점에 진행 중이던 요청은 여전히 완료되므로, 최종 정가 비용은 [예산을 약간 초과](https://platform.claude.com/docs/ko/managed-agents/budgets#when-a-session-reaches-its-budget)할 수 있습니다. 예산에 도달한 세션은 종료되지 않고 일시 중지되어 [idle](https://platform.claude.com/docs/ko/managed-agents/session-operations#session-statuses) 상태가 됩니다. 예산을 변경하거나 제거하면 예산으로 인해 일시 중지된 작업이 재개됩니다. 배포(deployment)도 동일한 예산을 받아 시작하는 각 세션에 적용합니다. [배포의 예산](https://platform.claude.com/docs/ko/managed-agents/budgets#budgets-on-deployments)을 참조하세요.
## 세션 생성 시 예산 설정
세션을 생성할 때 선택적 `budget` (csharp, go: `Budget`) 필드를 전달하세요:
```bash cURL
curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"agent": "'"$AGENT_ID"'",
"environment_id": "'"$ENVIRONMENT_ID"'",
"budget": {
"type": "limit",
"max_list_cost": {"amount": "125", "currency": "USD"}
}
}'
```
```bash CLI
# 금액이 숫자가 아닌 문자열로 전송되도록 따옴표를 유지하세요.
ant beta:sessions create \
--agent "$AGENT_ID" \
--environment-id "$ENVIRONMENT_ID" \
--budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}'
```
```python Python
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
budget={
"type": "limit",
"max_list_cost": {"amount": "125", "currency": "USD"},
},
)
print(session.id, session.budget.max_list_cost.amount) # sesn_01... 125
```
```typescript TypeScript
const session = await client.beta.sessions.create({
agent: agent.id,
environment_id: environment.id,
budget: {
type: "limit",
max_list_cost: { amount: "125", currency: "USD" }
}
});
console.log(session.id, session.budget?.max_list_cost.amount); // sesn_01... 125
```
```csharp C#
var session = await client.Beta.Sessions.Create(new()
{
Agent = agent.ID,
EnvironmentID = environment.ID,
Budget = new()
{
Type = BetaManagedAgentsBudgetLimitType.Limit,
MaxListCost = new() { Amount = "125", Currency = BetaCurrency.Usd },
},
});
Console.WriteLine($"{session.ID} {session.Budget?.MaxListCost.Amount}"); // sesn_01... 125
```
```go Go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfString: anthropic.String(agent.ID),
},
EnvironmentID: environment.ID,
Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
MaxListCost: anthropic.BetaMonetaryAmountParam{
Amount: "125",
Currency: anthropic.BetaCurrencyUsd,
},
},
})
if err != nil {
panic(err)
}
fmt.Println(session.ID, session.Budget.MaxListCost.Amount) // sesn_01... 125
```
```java Java
var session = client.beta().sessions().create(SessionCreateParams.builder()
.agent(agent.id())
.environmentId(environment.id())
.budget(BetaManagedAgentsBudgetLimit.builder()
.type(BetaManagedAgentsBudgetLimit.Type.LIMIT)
.maxListCost(BetaMonetaryAmount.builder()
.amount("125")
.currency(BetaCurrency.USD)
.build())
.build())
.build());
IO.println(session.id() + " " + session.budget().orElseThrow().maxListCost().amount()); // sesn_01... 125
```
```php PHP
$session = $client->beta->sessions->create(
agent: $agent->id,
environmentID: $environment->id,
budget: [
'type' => 'limit',
'max_list_cost' => ['amount' => '125', 'currency' => 'USD'],
],
);
echo "{$session->id} {$session->budget->maxListCost->amount}\n"; // sesn_01... 125
```
```ruby Ruby
session = client.beta.sessions.create(
agent: agent.id,
environment_id: environment.id,
budget: {
type: "limit",
max_list_cost: {amount: "125", currency: "USD"}
}
)
puts "#{session.id} #{session.budget.max_list_cost.amount}" # sesn_01... 125
```
`budget` (csharp, go: `Budget`) 객체에는 두 개의 필드가 있습니다:
* `type` (csharp, go: `Type`)은 항상 `"limit"`입니다.
* `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`)는 상한 자체입니다. `amount` (csharp, go: `Amount`)는 앞자리 0 없이 문자열로 작성된 미국 센트 단위의 정수이며(`"125"`는 $1.25, `"50"`은 50센트), 0보다 커야 합니다. `"25.00"`과 같은 소수 형식은 거부됩니다. 금액은 숫자가 아닌 문자열이므로 부동소수점 반올림이 전혀 적용되지 않습니다. `currency` (csharp, go: `Currency`)는 대문자 ISO-4217 통화 코드이며, 지원되는 통화는 `USD`뿐입니다.
예산은 세션이 생성될 때만 연결할 수 있습니다. 예산이 없는 기존 세션에 예산을 추가하면 400 오류로 거부됩니다. 예산이 설정된 세션의 상한은 언제든지 [변경](https://platform.claude.com/docs/ko/managed-agents/budgets#change-the-budget)하거나 [제거](https://platform.claude.com/docs/ko/managed-agents/budgets#remove-the-budget)할 수 있습니다.
## 정가 비용 측정 방식
플랫폼은 세션이 소비하는 것을 공개 정가 기준으로 지속적으로 가격을 산정합니다:
* **모델 토큰**: 제공된 각 모델의 정가 기준
* **웹 검색**: 검색 1,000회당 $10 USD
* **세션 실행 시간**: 시간당 $0.08 USD
이 누적 달러 합계가 세션의 **정가 비용**이며, 예산은 이 값과 비교됩니다. 정가 비용은 계약 가격이 아닙니다. 조직이 할인을 협상한 경우, 세션은 정가 합계가 상한에 도달할 때 상한에 도달하며, 실제 청구되는 지출은 상한보다 낮을 수 있습니다.
적용에는 반올림되지 않은 정확한 정가 비용이 사용됩니다. 세션과 이벤트에 보고되는 `list_cost` (java, php: `listCost`; csharp, go: `ListCost`) 수치는 가장 가까운 센트로 반올림된 정수 센트이므로, 보고된 수치는 적용에 사용되는 정확한 금액과 최대 0.5센트까지 차이가 날 수 있습니다.
## 세션이 예산에 도달할 때
상한은 요청 도중이 아니라 모델 요청 사이에 적용됩니다. 각 모델 요청 전에 플랫폼은 세션이 소비한 정가 비용을 확인하며, 그 합계가 상한에 도달하면 모든 스레드가 다음 요청 전에 일시 중지됩니다. 합계를 상한 너머로 밀어낸 요청은 세션이 아직 상한 미만일 때 승인되었으므로 끝까지 실행됩니다. 따라서 일시 중지된 세션에 기록된 `list_cost` (java, php: `listCost`; csharp, go: `ListCost`)는 `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`)와 같거나 약간 초과합니다. 예를 들어 `"50"`(50센트)으로 상한이 설정된 세션은 `list_cost` (java, php: `listCost`; csharp, go: `ListCost`)가 `"53"`인 상태로 일시 중지될 수 있습니다. 이는 예상된 동작이며 청구 오류가 아닙니다. 상한을 초과하는 모델 지출은 스레드당 최대 모델 요청 한 건의 비용입니다. 해당 요청의 응답에 포함된 도구 호출은 여전히 실행되며, 그 웹 검색과 실행 시간도 정가 비용에 포함됩니다. 예산을 정확한 중지 지점이 아니라 새로운 작업에 대한 한도로 취급하고, 이러한 여유분을 고려하여 상한을 설정하세요.
예산에 도달한 세션은 `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`)이 `budget_reached`인 idle 상태가 됩니다. 세션은 종료되지 않으며, 다른 idle 세션과 마찬가지로 기록과 샌드박스가 보존됩니다. [이벤트 스트림](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming)에서는 다음 순서로 이벤트를 확인할 수 있습니다:
1. 각 스레드가 일시 중지될 때 `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`)이 `budget_reached`인 `session.thread_status_idle` 이벤트.
2. 세션의 누적 사용량과 정가 비용이 포함된 [`session.usage`](https://platform.claude.com/docs/ko/managed-agents/budgets#monitor-spend) 이벤트
3. `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`)이 `budget_reached`인 `session.status_idle` 이벤트. 사용량 이벤트는 항상 이 idle 이벤트 바로 앞에 옵니다.
[워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#budgets-and-limits)이 열려 있는 경우, 아직 idle 상태가 아닌 각 실행에도 `workflow_run.status_idle` 이벤트가 전송됩니다.
마지막 요청이 상한을 넘는 동시에 턴을 완료한 스레드는 자체 `session.thread_status_idle` 이벤트에서 `end_turn`을 보고하지만, 세션은 여전히 `budget_reached`를 보고합니다. 세션 수준의 `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`)을 세션이 예산에서 일시 중지되었다는 신호로 취급하세요.
### 상한에서 허용되는 이벤트
세션이 예산에 도달했거나 초과한 동안에는 이미 진행 중인 작업을 정리하는 이벤트만 허용됩니다:
* `user.tool_confirmation`
* `user.tool_result`
* `user.custom_tool_result`
* `user.interrupt`
`user.message`와 같이 새 작업을 시작하는 이벤트는 이 목록을 명시하는 400 오류로 거부됩니다. 정리된 결과는 새 모델 요청을 트리거하지 않고 기록되며, 세션은 예산에서 일시 중지된 상태로 유지됩니다.
세션이 예산에 도달하여 일시 중지된 동안(모든 스레드가 상한에서 일시 중지됨) 전송된 `user.interrupt`는 허용되며, 이벤트 목록에 나타나지 않습니다. 모든 스레드가 이미 일시 중지되어 있으므로 어떤 스레드도 중지하지 않습니다. 계속하려면 예산을 변경하거나 제거하세요.
세션에 열려 있는 [워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#interrupt-a-session-with-runs-open)이 있는 경우, 다른 때에 전송된 중단과 마찬가지로 이 중단도 해당 실행을 일시 중지할 수 있습니다. 중단으로 인해 일시 중지된 실행은 예산을 변경하거나 제거해도 재개되지 않습니다. 이러한 실행을 계속하려면 예산을 변경하거나 제거한 다음, 에이전트에게 실행을 계속하도록 요청하는 `user.message`를 전송하세요.
## 예산에 도달한 세션 재개
세션 업데이트로 예산을 변경하거나 제거하세요. 업데이트가 수락되면 예산으로 인해 일시 중지된 작업이 자동으로 재개되며, 클라이언트에서 추가 작업을 할 필요가 없습니다.
예산으로 인해 일시 중지된 각 [워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#budgets-and-limits)에도 `workflow_run.status_running` 이벤트가 전송됩니다. 중단으로 인해 일시 중지된 실행은, 그 중단이 세션이 예산에 도달해 있는 동안 전송되었더라도, 일시 중지된 상태로 유지되며 해당 업데이트로는 `workflow_run.status_running` 이벤트를 받지 않습니다. 이러한 실행을 계속하려면 에이전트에게 실행을 계속하도록 요청하는 `user.message`를 전송하세요. [실행이 열려 있는 세션 중단하기](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#interrupt-a-session-with-runs-open)를 참조하세요.
### 예산 변경
새로운 `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`)로 세션을 업데이트하세요. 새 값은 현재 상한보다 높거나 낮을 수 있지만, 세션이 소비한 정가 비용보다 반드시 커야 합니다. 그렇지 않으면 업데이트가 400 오류로 거부됩니다: `budget.max_list_cost must be greater than the session's consumed list cost`. 세션이 일시 중지될 때 소비된 비용은 보통 [이전 상한을 약간 초과](https://platform.claude.com/docs/ko/managed-agents/budgets#when-a-session-reaches-its-budget)하므로, 새 값은 이전 `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`)가 아니라 세션에 보고된 `usage.list_cost` (java, php: `usage.listCost`; csharp, go: `Usage.ListCost`)를 기준으로 정하세요. 해당 수치보다 1센트 이상 높게 설정하세요. 보고된 값은 반올림되어 있어 검사에 사용되는 정확한 소비 비용보다 약간 낮을 수 있습니다.
```bash cURL
curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"budget": {
"type": "limit",
"max_list_cost": {"amount": "500", "currency": "USD"}
}
}'
```
```bash CLI
ant beta:sessions update \
--session-id "$SESSION_ID" \
--budget '{type: limit, max_list_cost: {amount: "500", currency: USD}}'
```
```python Python
updated_session = client.beta.sessions.update(
session.id,
budget={
"type": "limit",
"max_list_cost": {"amount": "500", "currency": "USD"},
},
)
print(updated_session.budget.max_list_cost.amount) # 500
```
```typescript TypeScript
const updatedSession = await client.beta.sessions.update(session.id, {
budget: {
type: "limit",
max_list_cost: { amount: "500", currency: "USD" }
}
});
console.log(updatedSession.budget?.max_list_cost.amount); // 500
```
```csharp C#
var updatedSession = await client.Beta.Sessions.Update(session.ID, new()
{
Budget = new()
{
Type = BetaManagedAgentsBudgetLimitType.Limit,
MaxListCost = new() { Amount = "500", Currency = BetaCurrency.Usd },
},
});
Console.WriteLine(updatedSession.Budget?.MaxListCost.Amount); // 500
```
```go Go
updatedSession, err := client.Beta.Sessions.Update(ctx, session.ID, anthropic.BetaSessionUpdateParams{
Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
MaxListCost: anthropic.BetaMonetaryAmountParam{
Amount: "500",
Currency: anthropic.BetaCurrencyUsd,
},
},
})
if err != nil {
panic(err)
}
fmt.Println(updatedSession.Budget.MaxListCost.Amount) // 500
```
```java Java
var updatedSession = client.beta().sessions().update(session.id(), SessionUpdateParams.builder()
.budget(BetaManagedAgentsBudgetLimit.builder()
.type(BetaManagedAgentsBudgetLimit.Type.LIMIT)
.maxListCost(BetaMonetaryAmount.builder()
.amount("500")
.currency(BetaCurrency.USD)
.build())
.build())
.build());
IO.println(updatedSession.budget().orElseThrow().maxListCost().amount()); // 500
```
```php PHP
$updatedSession = $client->beta->sessions->update(
$session->id,
budget: [
'type' => 'limit',
'max_list_cost' => ['amount' => '500', 'currency' => 'USD'],
],
);
echo "{$updatedSession->budget->maxListCost->amount}\n"; // 500
```
```ruby Ruby
updated_session = client.beta.sessions.update(
session.id,
budget: {
type: "limit",
max_list_cost: {amount: "500", currency: "USD"}
}
)
puts updated_session.budget.max_list_cost.amount # 500
```
### 예산 제거
상한을 완전히 제거하려면 `"budget": null` (python: `budget=None`; typescript: `budget: null`; ruby: `budget: nil`; go: `Budget: param.NullStruct[anthropic.BetaManagedAgentsBudgetLimitParam]()`; java: `.budget(Optional.empty())`; csharp: `Budget = null`; php: `requestOptions: ['extraBodyParams' => ['budget' => null]]`; cli: `--budget null`)을 전달하세요. 예산으로 인해 일시 중지된 작업이 재개되며, 결과로 발생하는 `session.updated` 이벤트에는 `budget` (csharp, go: `Budget`)이 `null`로 설정되어 있습니다.
```bash cURL
curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{"budget": null}'
```
```bash CLI
ant beta:sessions update --session-id "$SESSION_ID" --budget null
```
```python Python
unbudgeted_session = client.beta.sessions.update(session.id, budget=None)
print(unbudgeted_session.budget) # None
```
```typescript TypeScript
const unbudgetedSession = await client.beta.sessions.update(session.id, { budget: null });
console.log(unbudgetedSession.budget); // null
```
```csharp C#
// null을 할당하면 명시적 null이 전송되며, Budget을 설정하지 않으면 필드가 생략됩니다.
var unbudgetedSession = await client.Beta.Sessions.Update(session.ID, new() { Budget = null });
Console.WriteLine(unbudgetedSession.Budget is null); // True: the session no longer has a budget
```
```go Go
// 값이 0인 Budget은 요청에서 생략됩니다. param.NullStruct(
// github.com/anthropics/anthropic-sdk-go/packages/param 제공)는 명시적인 null을 전송합니다.
unbudgetedSession, err := client.Beta.Sessions.Update(ctx, session.ID, anthropic.BetaSessionUpdateParams{
Budget: param.NullStruct[anthropic.BetaManagedAgentsBudgetLimitParam](),
})
if err != nil {
panic(err)
}
fmt.Println(unbudgetedSession.JSON.Budget.Valid()) // false: the session no longer has a budget
```
```java Java
// 빈 Optional은 명시적 null을 전송합니다. budget을 설정하지 않으면 필드가 생략됩니다.
var unbudgetedSession = client.beta().sessions().update(session.id(), SessionUpdateParams.builder()
.budget(Optional.empty())
.build());
IO.println(unbudgetedSession.budget().isPresent()); // false: the session no longer has a budget
```
```php PHP
// update(budget: null)은 필드를 생략하므로, 명시적 null을 추가 body 매개변수로 전송합니다.
$unbudgetedSession = $client->beta->sessions->update(
$session->id,
requestOptions: ['extraBodyParams' => ['budget' => null]],
);
echo json_encode($unbudgetedSession->budget), "\n"; // null
```
```ruby Ruby
unbudgeted_session = client.beta.sessions.update(session.id, budget: nil)
p unbudgeted_session.budget # nil
```
세션의 예산 제거는 되돌릴 수 없습니다. 예산이 제거된 세션에는 새 예산을 부여할 수 없습니다. 세션에 상한을 유지하려면 대신 예산을 변경하세요.
## 지출 모니터링
세션 객체에는 `budget` (csharp, go: `Budget`)과 추적된 지출이 담긴 `usage` (csharp, go: `Usage`) 객체가 포함됩니다. `usage.list_cost` (java, php: `usage.listCost`; csharp, go: `Usage.ListCost`)는 세션이 소비한 정가 비용이고, `usage.active_seconds` (java, php: `usage.activeSeconds`; csharp, go: `Usage.ActiveSeconds`)는 런타임 비용 산정의 기준이 되는 실행 시간입니다. `budget_reached`로 일시 중지된 세션에서는 `usage.list_cost` (java, php: `usage.listCost`; csharp, go: `Usage.ListCost`)가 `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`)와 같거나 약간 초과할 것으로 예상하세요. [상한을 넘은 요청](https://platform.claude.com/docs/ko/managed-agents/budgets#when-a-session-reaches-its-budget)이 일시 중지 전에 완료되었기 때문입니다. 세션 수준의 `active_seconds` (java, php: `activeSeconds`; csharp, go: `ActiveSeconds`)는 동시 스레드의 겹치는 활동을 한 번만 계산합니다. 스레드 조회 응답에는 스레드 자체의 `usage` (csharp, go: `Usage`)에 동일한 두 필드가 스레드별로 가격이 매겨져 포함됩니다. 스레드별 수치는 독립적으로 반올림되며 세션의 실행 시간 비용을 제외하므로, 합계가 세션의 `list_cost` (java, php: `listCost`; csharp, go: `ListCost`)와 정확히 일치하지 않습니다. 예산 적용의 기준이 되는 것은 세션 수치입니다.
`session.usage` 이벤트는 세션의 누적 사용량과 추적된 정가 비용의 스냅샷입니다. 여기에는 세션의 토큰 합계, `list_cost` (java, php: `listCost`; csharp, go: `ListCost`), `active_seconds` (java, php: `activeSeconds`; csharp, go: `ActiveSeconds`), `server_tool_use` (java, php: `serverToolUse`; csharp, go: `ServerToolUse`) 요청 횟수(요청당 정가 비용에 반영되는 `web_search_requests` (java, php: `webSearchRequests`; csharp, go: `WebSearchRequests`), 그리고 웹 가져오기 요청은 요청당 요금이 없고 계량되지 않으므로 `0`으로 표시되는 `web_fetch_requests` (java, php: `webFetchRequests`; csharp, go: `WebFetchRequests`)), 그리고 세션에 예산이 있는 경우 세션의 `budget` (csharp, go: `Budget`)이 포함됩니다. 이 이벤트는 이벤트 목록과 세션 스트림에 나타납니다. 세션은 중지 이유와 관계없이 idle 상태가 되기 직전에 이 이벤트를 하나 발생시키므로, 예산에 도달한 세션은 항상 예산 도달 idle 이벤트 직전에 이 이벤트를 발생시킵니다.
스트림과 세션 객체에서 사용량을 읽는 방법은 [사용량 추적](https://platform.claude.com/docs/ko/managed-agents/session-observability#track-usage)을 참조하세요.
## 멀티에이전트 세션의 예산
[멀티에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration) 세션은 모든 스레드가 공유하는 단일 예산을 가지며, 스레드별 상한은 없습니다. 각 스레드의 소비는 해당 스레드에 제공된 모델 기준으로 산정되며, 공유 상한에 도달하면 스레드가 독립적으로 일시 중지됩니다. [어드바이저](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#give-the-session-an-advisor) 자문은 어드바이저 모델의 요율로 산정되어 동일한 예산에 포함됩니다. 한 스레드가 `budget_reached`로 일시 중지되는 동안 다른 스레드는 진행 중인 요청을 완료할 수 있습니다.
대기 중인 요청은 상한보다 우선합니다. 한 스레드가 `requires_action`을 기다리고 다른 스레드가 `budget_reached`로 일시 중지된 세션은 세션 수준에서 `requires_action`을 보고합니다. 대기 중인 요청은 여전히 응답이 필요하며, 이에 응답하는 것은 예산이 차단하지 않는 [정리 이벤트](https://platform.claude.com/docs/ko/managed-agents/budgets#events-accepted-at-the-cap)입니다.
## 배포의 예산
[배포](https://platform.claude.com/docs/ko/managed-agents/scheduled-deployments)는 생성하거나 업데이트할 때 동일한 `budget` 객체를 받습니다:
```json
{
"budget": {
"type": "limit",
"max_list_cost": { "amount": "2000", "currency": "USD" }
}
}
```
상한은 배포가 시작하는 각 세션에 복사되므로, 배포의 누적 지출이 아니라 각 실행을 개별적으로 제한합니다. 배포의 예산을 변경하면 이후에 배포가 시작하는 세션에 적용되며, 이미 실행 중인 세션에는 적용되지 않습니다. 세션과 달리 배포의 예산은 `"budget": null` (python: `budget=None`; typescript: `budget: null`; ruby: `budget: nil`; go: `Budget: param.NullStruct[anthropic.BetaManagedAgentsBudgetLimitParam]()`; java: `.budget(Optional.empty())`; csharp: `Budget = null`; php: `requestOptions: ['extraBodyParams' => ['budget' => null]]`; cli: `--budget null`)로 해제한 후 나중에 다시 설정할 수 있습니다. [각 실행에 예산 설정](https://platform.claude.com/docs/ko/managed-agents/scheduled-deployments#set-a-budget-on-each-run)을 참조하세요.
## 정가가 없는 모델
예산은 플랫폼이 가격을 매길 수 있는 소비만 추적할 수 있습니다. 세션의 에이전트, `subagents` (csharp, go: `Subagents`) 또는 `workflows` (csharp, go: `Workflows`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에 있는 에이전트, 또는 [멀티에이전트 구성](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration)에 설정된 어드바이저 중 하나라도 공개 정가가 없는 모델을 사용하는 경우, 예산이 설정된 세션 생성은 해당 모델에 사용 가능한 정가가 없다는 400 오류로 거부됩니다.
예산이 설정된 세션의 사용량에 정가가 없는 모델이 포함되게 되면, 예산은 더 이상 세션의 지출을 측정할 수 없습니다. 세션은 `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`)이 `budget_reached`인 상태로 일시 중지될 수 있으며, 예산 변경은 거부됩니다. 세션을 재개하려면 예산을 제거하세요.
## 오류 참조
예산 관련 요청은 다음 경우에 거부됩니다:
| 조건 | 상태 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- |
| 세션이 예산에 도달했거나 초과한 동안 작업 시작 이벤트(예: `user.message`)가 전송됨. 오류에는 [허용되는 정리 이벤트](https://platform.claude.com/docs/ko/managed-agents/budgets#events-accepted-at-the-cap)가 명시됨 | 400 |
| 예산이 세션의 소비된 정가 비용 이하의 값으로 설정됨 | 400 |
| 예산 없이 생성된 세션에 예산이 추가되거나, 제거 후 다시 추가됨 | 400 |
| `amount` (csharp, go: `Amount`)가 센트 단위 정수가 아니거나(예: `"25.00"`), 0 또는 음수이거나, `currency` (csharp, go: `Currency`)가 `USD`가 아님 | 400 |
| 예산이 설정된 생성 요청이 [공개 정가가 없는](https://platform.claude.com/docs/ko/managed-agents/budgets#models-without-a-list-price) 모델을 참조함 | 400 |
세션 예산은 단일 세션에 대해 플랫폼이 적용하는 미국 달러(센트 단위로 작성) 기준의 엄격한 상한입니다. 이는 Messages API의 [작업 예산](https://platform.claude.com/docs/ko/build-with-claude/task-budgets)과는 다릅니다. 작업 예산은 모델이 하나의 에이전트 루프 내에서 자체 조절하는 데 사용하는 권고적인 토큰 단위 예산입니다.