에이전트 반복 예산

에이전트 반복 예산 (Iteration Budgets)

에이전틱 루프에서 발생하는 예상 밖의 비용을 세션별 반복 및 예산 상한으로 제어해요.

개요

에이전트가 에이전틱 루프를 실행할 때 무제한의 LLM 호출을 만들어 예상치 못한 비용이 발생할 수 있어요. LiteLLM은 두 가지 제어 방법을 제공합니다:

두 제어 모두 세션 내 호출을 추적하려면 session_id가 필요해요 (x-litellm-trace-id 헤더 또는 metadata.session_id로 전송).

Trace-ID 강제

LiteLLM은 에이전트의 litellm_params에 설정되는 두 개의 독립적인 trace-id 플래그를 지원해요:

출처: 문서

본문

UI로 구성하기

LiteLLM Admin UI에서 에이전트를 만들 때:

1. Agents 탭으로 이동하고 Add Agent 를 클릭
2. Agent Settings 단계에서 Tracing 섹션을 확장
3. Require x-litellm-trace-id on calls BY this agent 를 켜 세션 추적 활성화
4. Max Iterations 을 설정해 세션당 LLM 호출 수 제한
5. Max Budget Per Session ($) 을 설정해 세션당 지출 제한

trace-id 플래그는 에이전트의 litellm_params에 저장됩니다. 예산 제어(max_iterations, max_budget_per_session)는 가상 키의 metadata에 저장돼요.

API로 구성하기

에이전트 자체에 trace-id 강제를 설정하세요:

curl -X POST 'http://localhost:4000/v1/agents' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_name": "my-research-agent",
    "agent_card_params": {
      "name": "my-research-agent",
      "description": "A research agent with budget controls",
      "url": "http://my-agent:8080",
      "version": "1.0.0"
    },
    "litellm_params": {
      "require_trace_id_on_calls_to_agent": true,
      "require_trace_id_on_calls_by_agent": true
    }
  }'

예산 제어는 (개별 키가 아닌) 에이전트의 litellm_params에 설정되므로, 에이전트의 모든 키에 적용돼요:

curl -X POST 'http://localhost:4000/v1/agents' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_name": "my-research-agent",
    "agent_card_params": {
      "name": "my-research-agent",
      "description": "A research agent with budget controls",
      "url": "http://my-agent:8080",
      "version": "1.0.0"
    },
    "litellm_params": {
      "require_trace_id_on_calls_by_agent": true,
      "max_iterations": 25,
      "max_budget_per_session": 5.00
    }
  }'

동작 방식

세션 추적

호출자는 다음 방법 중 하나로 session_id를 포함해 세션을 식별해요:

• 헤더: x-litellm-trace-id: my-session-123
• 메타데이터: {"metadata": {"session_id": "my-session-123"}}

Max Iterations

에이전트 litellm_params에 max_iterations가 설정되면:

• 세션의 각 LLM 호출이 카운터를 증가시킵니다
• 카운터가 max_iterations를 초과하면 요청이 429 Too Many Requests를 받아요
• 카운터는 기본적으로 1시간 후 만료됩니다 (LITELLM_MAX_ITERATIONS_TTL env var로 설정 가능)

Max Budget Per Session

에이전트 litellm_params에 max_budget_per_session이 설정되면:

• 각 성공적인 LLM 호출 후 응답 비용이 세션에 누적됩니다
• 각 호출 전에 누적된 지출이 예산과 대조 확인됩니다
• 지출이 예산을 초과하면 요청이 429 Too Many Requests를 받아요
• 세션 지출 카운터는 기본적으로 1시간 후 만료됩니다 (LITELLM_MAX_BUDGET_PER_SESSION_TTL env var로 설정 가능)

예시

최대 25회 반복과 $5 예산 상한을 가진 에이전트를 만들어 봅시다:

1. Agents → Add Agent 로 이동
2. 에이전트 구성 (이름, 모델 등)
3. Agent Settings 에서 Tracing 섹션을 확장
4. Require x-litellm-trace-id on calls BY this agent 를 켬
5. Max Iterations 을 25로 설정
6. Max Budget Per Session 을 5.00으로 설정
7. 에이전트용 새 키를 만듭니다
8. Create Agent 클릭

# 1. Create the agent with trace-id enforcement
curl -X POST 'http://localhost:4000/v1/agents' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_name": "my-research-agent",
    "agent_card_params": {
      "name": "my-research-agent",
      "description": "A research agent with budget controls",
      "url": "http://my-agent:8080",
      "version": "1.0.0"
    },
    "litellm_params": {
      "require_trace_id_on_calls_by_agent": true
    }
  }'

# 2. Create a key for the agent
curl -X POST 'http://localhost:4000/key/generate' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "<agent_id_from_step_1>",
    "key_alias": "my-research-agent-key"
  }'

세션 추적으로 호출하기

curl -X POST 'http://localhost:4000/chat/completions' \
  -H 'Authorization: Bearer ***' \
  -H 'x-litellm-trace-id: session-abc-123' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

이 세션에서 25회 호출 또는 $5 지출 후에, 이후 요청은 다음을 받게 됩니다:

{
  "error": {
    "message": "Session budget exceeded for session session-abc-123. Current spend: $5.0032, max_budget_per_session: $5.00.",
    "type": "budget_exceeded",
    "code": 429
  }
}

환경 변수

더 알아보기 (Learn more)

• Agent Gateway (A2A Protocol)
• Invoking A2A Agents