agent-gov 내부 살펴보기: 에이전트 비용 거버넌스 플랫폼의 아키텍처

AI 에이전트(AI agents)는 LLM 호출, 페이지 스크래핑, 데이터베이스 쿼리, 이메일 전송 등 복잡한 워크플로우(workflows)를 조율합니다. 각 호출에는 실제 비용이 발생합니다. 거버넌스 계층(governance layer)이 없다면, 단 하나의 버그가 있는 루프(buggy loop)가 누군가 알아차리기도 전에 예산을 모두 소진해 버릴 수 있습니다.

agent-gov는 에이전트가 수행하는 모든 도구 호출(tool call)을 가로채고, 실시간으로 예산을 집행하며, 통제 불능 상태의 에이전트를 자동으로 일시 중지하는 오픈 소스 리버스 프록시(reverse proxy)입니다. SQLite 영속성(persistence)을 갖춘 FastAPI 서비스로 구축되었으며, 0.3초 만에 45개의 테스트를 실행합니다.

이 포스트에서는 프록시 패턴(proxy pattern), 4단계 의사결정 트리(decision tree), 도구 레지스트리(tool registry)를 통한 비용 추적, 워크스페이스(workspaces)를 통한 멀티 테넌시(multi-tenancy), 그리고 레이지 자동 재설정 패턴(lazy auto-reset pattern) 등 아키텍처를 살펴봅니다.

프록시 패턴 (The Proxy Pattern)

모든 AI 에이전트의 도구 호출은 실제 도구에 도달하기 전에 agent-gov를 통과합니다. 에이전트는 API 키, 도구 이름, 예상 비용을 포함하여 POST /proxy/call을 전송합니다. agent-gov는 이를 검증, 예산 확인 및 로깅(logging)한 후, 승인을 위해 200을 반환하거나 거부를 위해 429를 반환합니다.

class ToolCall(BaseModel):
    agent_key: str = Field(...)
    tool_name: str = Field(...)
...

프록시는 도구 자체를 실행하지 않고 액세스(access)를 보호합니다. 에이전트는 프록시가 200을 반환할 때만 진행합니다. 이것이 바로 **게이트키퍼 패턴 (gatekeeper pattern)**입니다. 즉, 에이전트와 외부 세계 사이의 경량화된 의사결정 계층입니다.

Agent -> POST /proxy/call -> agent-gov -> 200/429 -> Agent decides
                                                      |
                                                 Calls actual tool
...

왜 라이브러리 대신 프록시를 사용할까요? 라이브러리는 몽키 패치(monkey-patched)되거나, 제거되거나, 잊힐 수 있습니다. 프록시는 에이전트가 반드시 통과해야 하는 네트워크 경계(network boundary)이며, 우회할 수 없습니다.

의사결정 트리: 인증(Auth) -> 확인(Check) -> 예산(Budget) -> 로깅(Log)

모든 프록시 호출은 4단계 파이프라인(pipeline)을 거칩니다:

@app.post("/proxy/call")
async def proxy_tool_call(call: ToolCall):
    key_hash = db.hash_key(call.agent_key)
...

단계 (Stage)	확인 사항 (Check)	종료 (Exit)
인증 (Auth)	API 키 해시가 일치하는가?	401 — 유효하지 않은 키
...

비용 추적 (Cost Tracking): 레지스트리 (Registry) vs. 추정치 (Estimate)

가장 까다로운 설계 결정은 비용 결정 (cost determination)이었습니다. 에이전트의 estimated_cost (추정 비용)를 신뢰하는 것은 취약합니다. 에이전트가 비용을 과소 보고할 수 있기 때문입니다.

agent-gov는 **도구 레지스트리 (tool registry)**를 사용합니다. 이는 호출당 실제 비용이 기록된, 알려진 도구들의 UPSERT 가능한 테이블입니다.

registered_tool = await db.get_tool(call.tool_name)
actual_cost = (registered_tool["cost_per_call"]
               if registered_tool else call.estimated_cost)

도구가 등록되어 있다면, 해당 도구의 **실제 비용 (true cost)**이 사용됩니다. 응답에는 클라이언트가 어떤 경로가 사용되었는지 알 수 있도록 cost_source 필드가 포함됩니다.

테스트를 통해 에이전트가 거버넌스(governance)를 속여 통과할 수 없음을 증명했습니다. 예를 들어, 100달러의 예산을 가진 에이전트가 호출당 500달러로 등록된 도구에 대해 1달러라고 주장하면, 429 오류와 함께 차단됩니다.

멀티 테넌시 (Multi-Tenancy): 워크스페이스 격리 (Workspace Isolation)

v0.5에서는 워크스페이스 (workspaces)를 도입했습니다. 이는 자체적인 에이전트, 도구, 비용 이벤트(cost events)를 가진 격리된 테넌트 (tenants)입니다. 각 워크스페이스는 고유한 ID와 API 키를 부여받습니다. 모든 데이터베이스 행은 workspace_id 외래 키 (FK) 컬럼을 가집니다.

스키마 마이그레이션 (Schema migration)은 PRAGMA table_info를 사용하여 컬럼이 누락된 경우에만 추가합니다. SQLite는 ALTER TABLE 문에서 IF NOT EXISTS를 지원하지 않기 때문입니다.

테스트를 통해 워크스페이스 격리를 검증합니다. 두 개의 워크스페이스와 각 워크스페이스에 속한 에이전트들은 서로의 데이터를 볼 수 없습니다.

자동 리셋 패턴 (The Auto-Reset Pattern): 지연된 일일 예산 (Lazy Daily Budgets)

자정마다 크론 잡 (cron job)을 실행하여 대규모 요청이 한꺼번에 몰리는 '천둥 치는 들소 떼 (thundering herd)' 현상을 만드는 대신, agent-gov는 **지연 평가 (lazy evaluation)**를 사용합니다. 모든 프록시 호출 시 리셋이 필요한지 확인합니다.

async def check_and_reset_budget(agent: dict) -> dict:
    today = date.today().isoformat()
    if agent["last_reset"] == today:
...

호출을 하지 않는 에이전트는 리셋이 필요하지 않습니다. 이로 인해 '천둥 치는 들소 떼' 현상은 완만한 흐름으로 바뀝니다.

향후 계획 (What's Next)

다음 진화 단계는 도구별 예산 상한 (per-tool budget caps), 웹훅 (webhook) 기반 알림, 그리고 관리 API (management API)입니다. 하지만 단순하고 테스트 가능하며 비동기(async) 방식인 거버넌스 프록시라는 기초는 견고하게 다져졌습니다.

agent-gov는 오픈 소스(open source)이며 MIT 라이선스를 따릅니다. 45개의 테스트를 포함하며, 별도의 데이터베이스 설정(database setup)이 필요 없습니다.