Molayo

© 2026 Molayo

GitHub요약2026. 06. 22. 02:22

Floe-Labs/floe-guard

요약

AI 에이전트의 예산 초과를 방지하기 위한 로컬 가드레일 도구인 floe-guard를 소개합니다. LLM 호출 직전에 비용을 예측하여 한도 초과 시 실행을 강제로 중단함으로써 통제 불능의 루프로 인한 비용 폭증을 막아줍니다.

핵심 포인트

  • LLM 호출 전 비용을 예측하여 한도 초과 시 즉시 중단
  • 계정 생성이나 네트워크 연결 없이 로컬에서 실행 가능
  • 동시성 환경(fan-out)에서도 원자적 예약 방식으로 예산 유지
  • 사후 통보 방식이 아닌 호출 경로 내 강제 집행 방식

AI 에이전트를 위한 로컬 예산 가드레일 (guardrail). 이 도구는 에이전트가 지출 한도를 초과하기 직전의 다음 LLM 호출 전에 실행을 강제 중단합니다. 따라서 통제 불능의 루프가 발생하더라도 $4,000 대신 $0.10에서 멈출 수 있습니다. 계정 생성, 가입, 네트워크 연결이 필요 없습니다. 사용자의 프로세스 내에서 실행됩니다.

pip install floe-guard

from floe_guard import BudgetGuard
guard = BudgetGuard(limit_usd=5.00) # 사용자의 한도 설정
guard.check() # 각 LLM 호출 전 — 한도를 초과할 경우 예외 발생
...

다음 호출이 한도를 초과하게 될 경우, 가드레일은 BudgetExceeded 예외를 발생시키고 다음과 같이 출력합니다:

BUDGET EXCEEDED — call blocked
spent so far: $5.001250 | ceiling: $5.000000
The next call would cross your budget; floe-guard stopped your agent before it ran.

직접 실행해 보세요: python examples/runaway_loop.py — API 키, 계정, 네트워크가 필요 없습니다.

python examples/runaway_loop.py

이 예제는 **스텁 LLM (stub LLM)**을 대상으로 루프를 구성합니다 — 실제 API 키, 계정, 네트워크가 필요하지 않습니다. 각 가짜 gpt-4o 호출 비용을 오프라인에서 계산하며, 가드레일은 몇 번의 반복 후에 루프를 중단합니다. 이것은 재현 가능한 "루프 중단" 데모입니다.

에이전트가 얼마를 쓰는지 이미 확인할 수는 있지만, 문제는 너무 늦게 확인하게 된다는 점입니다. floe-guard는 피해를 보고하는 부분이 아니라, 호출을 중단하는 부분입니다.

max_tokens나 max_rpm이 아닌, 달러 (dollars) 단위로 크기와 속도를 제한하세요 — 루프에 빠진 저렴한 모델도 예산을 계속 소진합니다. 사용 로그 및 제공자 대시보드는 비용이 이미 지출된 후에 무엇을 썼는지 알려줍니다. floe-guard는 한도를 초과하기 전에 호출을 거부합니다. **단순히 로그만 남기는 비용 콜백 (cost callback)**은 사후에 통지되므로 실행을 중단할 수 없습니다. 강제 집행은 반드시 다음 호출 앞에 위치해야 하며, 그것이 floe-guard가 존재하는 이유입니다. 직접 구현한 방식(CrewAI fan-out, 병렬 에이전트 하의 asyncio 또는 Promise.all에서 발생하는 spent += cost 카운터 경합 문제)의 경우: N개의 호출이 한도 미만의 동일한 총액을 읽고 모두 실행되어 버립니다. floe-guard는 원자적으로 예약(reserve() / settle())하므로, 동시성 환경에서도 한도가 유지됩니다.

전체 작업의 핵심: 다음 호출 전에 실행되는 강력한 중단(hard stop), 그리고 팬아웃 (fan-out) 상황에서도 유지되는 제어 —
계정, 네트워크, 암호화 자산 그 무엇도 허용하지 않습니다.

가드(guard)는 이벤트 버스(event bus)가 아닌 호출 경로 (call path) 내에 위치합니다. 수동적인 리스너(passive listener)는 지출 사실을 사후에 전달받을 뿐이며 아무것도 중단할 수 없습니다. 따라서 강제 집행(enforcement)은 반드시 다음 호출의 앞단에 서 있어야 합니다:

check()는 각 LLM 호출 전에 실행됩니다. 이는 이전 호출을 바탕으로 다음 호출의 비용을 예측하며, 만약 예측값이 한도를 초과할 것으로 보이면 BudgetExceeded를 발생시킵니다 — 호출은 아예 실행되지 않습니다. (누적 합계(running-total) 체크 방식은 추정치가 낮게 나왔을 경우 발생하는 초과분도 잡아낼 수 있습니다.)

record(model, prompt_tokens, completion_tokens)는 각 응답 후에 실행됩니다. 이는 번들링된 LiteLLM 비용 맵(cost map)을 통해 **오프라인(offline)**으로 토큰 가격을 산정하고, 해당 USD 금액을 누적 합계에 더합니다.

만약 모델이 비용 맵에 없고 사용자가 가격을 직접 제공하지 않은 경우, 가드는 이를 무료로 조용히 처리하는 대신 강력하게 경고하고 거부(UnpriceableModelError)합니다 — 측정할 수 없는 지출은 제한할 수 없기 때문입니다. 강제 적용을 위해 가격을 직접 제공하십시오:

from floe_guard import BudgetGuard, ManualPrice
guard = BudgetGuard(
    limit_usd=5.00,
    ...
)

강력한 중단(hard-stop)이 보장된 기능이라면, advisory()는 *추가적인 이점(upside)*입니다. 단계를 수행하기 전에 이를 읽어 에이전트가 한도에 도달할 때 **적응(adapt)**할 수 있도록 하십시오. 실행 도중에 끊기는 대신, 더 저렴한 모델로 전환하거나, 작업을 축소하거나, 혹은 작업을 마무리할 수 있습니다.

guard = BudgetGuard(limit_usd=0.10, near_limit_bps=7000) # 70% 사용 시 플래그 발생
adv = guard.advisory()
# BudgetAdvisory(near_limit=False, used_bps=125, remaining_usd=0.0987, ...)

advisory()는 near_limit, used_bps (basis points 단위의 사용률), remaining_usd, 그리고 예산 총액을 반환합니다. 이는 소프트(soft) 신호입니다. 모델이 이를 무시할 수도 있으므로, 한도를 강제하는 것은 check()입니다. 실행 가능한 단계적 축소(taper) 데모를 보려면 examples/budget_aware.py를 참조하십시오 (API 키 불필요).

이는 hosted Floe가 모든 프록시 호출 시 반환하는 것과 동일한 어드바이저리 형태 (advisory shape) (X-Floe-Budget-Advisory 헤더)

헤더)이므로, 여기서 작성한 로직은 변경 없이 그대로 이식됩니다. 서버의 진실(server-truth)을 바탕으로 모든 벤더(vendor)와 한도(cap)에 걸쳐 서버 측 잔액 및 이동 창 리셋 타이밍(rolling-window reset timing)을 관리하므로, 단일 로컬 예산으로는 알 수 없는 정보들을 처리합니다. TS 패키지는 동일한 guard.advisory()를 노출합니다.

pip install floe-guard[crewai]

from crewai import Crew
from floe_guard import BudgetGuard
from floe_guard.integrations.crewai import guard_crew
...

CrewAI는 LiteLLM 위에서 실행되므로, 하나의 콜백(callback)으로 단일 예산 하에 모든 에이전트(agent)와 태스크(task)의 한도를 설정할 수 있습니다.

pip install floe-guard[litellm]

from floe_guard import BudgetGuard
from floe_guard.integrations.litellm import guarded_completion
guard = BudgetGuard(limit_usd=1.00)
...

LiteLLM 네이티브 콜백을 선호하시나요? litellm.callbacks에 budget_guard_callback(guard)를 등록하세요.

pip install floe-guard[langchain] langchain-openai # 아래 ChatOpenAI 예제를 위해서만 langchain-openai 설치

from langchain_openai import ChatOpenAI
from floe_guard import BudgetGuard
from floe_guard.integrations.langchain import budget_guard_callback_handler
...

핸들러(handler)는 LLM 시작 시 예산을 확인하고(BudgetExceeded를 발생시켜 호출이 실행되기 전에 중단), LLM 종료 시 토큰 사용량을 기록합니다.

Vercel AI SDK는 TypeScript 전용이므로, js/ 디렉토리에 위치하는 별도의 npm 패키지로 제공됩니다.

npm i floe-guard ai@4 @ai-sdk/openai

import { wrapLanguageModel } from "ai";
import { openai } from "@ai-sdk/openai";
import { BudgetGuard, budgetGuardMiddleware } from "floe-guard";
...

미들웨어(middleware)는 각 호출 전에 check()를 수행하고(실행을 중단하기 위해 BudgetExceeded를 발생시킴), 호출 후에는 비용이 발생하는 사용량을 record()합니다. 이는 Python 가드(guard)와 동일한 의미론(semantics)을 가집니다. js/README.md를 참조하세요.

floe-guard는 로컬 기반의 추정 방식(local, estimate-based) 가드레일(guardrail)입니다. 이는 프로세스 내부의 벤더 비용 맵(vendored cost map)을 사용하여 토큰 가격을 책정합니다:

  • 벤더가 가격을 변경함에 따라 비용 맵(cost map)이 변동될 수 있으므로, 다른 스냅샷과 마찬가지로 이를 갱신(refresh)해야 합니다.
  • 이 기능은 사용자가 계측(instrument)한 벤더만을 인식합니다.
  • 의도적인 에이전트나 버그가 프로세스 내부의 체크를 우회하여 경로를 설정할 수 있습니다.
  • 과도한 동시성(concurrency) 또는 콜드 스타트(cold-start) 상황에서는 정상 상태(steady-state)의 지출을 제한할 뿐, 첫 번째 병렬 파동(parallel wave)을 제한하지는 않습니다. 예약(Reservations)은 마지막 호출의 비용( 0 부터 첫 번째 record() 까지)을 기준으로 크기를 정하므로, 초기 팬아웃(fan-out) 시점에는 추정할 수 있는 정보가 없습니다. 이를 제한하려면 reserve()에 알려진 호출당 최대값(per-call max)을 전달하거나, 임의의 동시성 상황에서 엄격한 상한선(hard cap)을 적용하기 위해 호스팅된 Floe를 사용하세요.

이 기능은 그 자체로 진정 유용하며, 자신의 한계에 대해 솔직합니다. 부풀려진 지표나 "제로 기본값(zero defaults)" 같은 주장은 하지 않습니다. 이는 무료 로컬 차단 장치(local stop)이지, 금고(vault)가 아닙니다.

상한선이 **우회 불가능(un-bypassable)**하고 **벤더 통합적(cross-vendor)**이어야 할 때, 호스팅된 Floe는 실제 신용 한도(credit line)를 바탕으로 서버 측에서 강제 집행을 수행합니다:

우회 불가능(Un-bypassable)— 프로세스 내부가 아닌 지출 레일(spend rail)에서 강제 집행됩니다. 벤더 통합적(Cross-vendor)— LLM 토큰과 유료(x402) 도구 호출(tool calls)에 대한 하나의 예산을 적용합니다. 팀 예산 + 분석(Team budgets + analytics)— 공유된 상한선, 에이전트별 격리, 지출 내역을 제공합니다.

FLOE_API_KEY(에이전트 키, floe_<hex>)를 설정하면, floe-guard는 라이브 Floe 엔드포인트에서 에이전트의 **서버 측 잔여 예산(server-side remaining budget)**을 읽어올 수 있습니다:

from floe_guard import hosted_enforcement_available, hosted_remaining_usd
if hosted_enforcement_available(): # FLOE_API_KEY가 설정되었을 때 True
    remaining = hosted_remaining_usd() # Floe 서버에서 읽어온 남은 USD 금액

hosted_remaining_usd()는 /v1/agents/credit-remaining을 GET 호출하여 남은 USD 금액을 반환합니다. 이 금액은 자동 차입 여유분(auto-borrow headroom)과 세션 지출 잔액 중 최소값입니다. 잘못되었거나 누락된 키(401), 종료되거나 중지된 에이전트(403), 프로비저닝되지 않은 에이전트(404), 또는 네트워크 실패 시 HostedEnforcementError를 발생시킵니다.

환경 변수:

FLOE_API_KEY — 에이전트 키. 읽기 작업을 위해 필수입니다.
FLOE_API_BASE_URL — API 호스트를 재정의합니다 (기본값: https://credit-api.floelabs.xyz).

솔직한 범위(Honest scope): 이 호출은 남은 예산을 **읽기(read)**만 합니다. 우회할 수 없는 벤더 간 *강제 적용(enforcement)*은 이 클라이언트가 아니라 서버 측에서 실행되는 호스팅된 Floe 제품을 통해 이루어집니다. 이 숫자를 로컬 상한선(local ceiling)을 설정하는 데 참고용으로 사용하십시오. 서버가 신뢰할 수 있는 단일 원천(source of truth)으로 유지됩니다.

→ dev-dashboard.floelabs.xyz ·
floelabs.xyz

프로젝트에서 floe-guard를 사용 중이신가요? 다른 사람들이 찾을 수 있도록 배지를 추가하세요:

[![guarded by floe-guard](https://img.shields.io/badge/guarded%20by-floe--guard-2f81f7.svg)](https://github.com/Floe-Labs/floe-guard)

pip install -e ".[dev]"
pytest
ruff check .

MIT — LICENSE를 참조하세요.

AI 자동 생성 콘텐츠

본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0