저는 Agentic Ledger라는 오픈 소스 도구를 구축해 왔으며, 이제는 저 혼자 보는 것보다 더 많은 사람의 검토가 필요한 단계에 도달했습니다. 이 포스트는 소개이자 요청입니다.

문제점

AI 에이전트(AI agents)는 무인 상태로 실행됩니다. 이들은 루프(loop) 내에서 LLM을 호출하고, 도구(tools)를 사용하며, 하위 에이전트(sub-agents)를 생성하고, 실제 비용을 지출하지만, 그 과정의 대부분은 당신이 볼 수 없는 곳에서 일어납니다. 밤새 실행된 코딩 루프가 동일한 실패 테스트에 막혀 40달러를 낭비하거나, 멀티 에이전트 크루(multi-agent crew)가 조용히 재시도를 반복하며 거대한 청구서를 만들어낼 때, 당신은 보통 청구서를 보고 나서야 그 사실을 알게 됩니다.

기존의 관측성(observability) 도구들은 대부분 SDK를 사용하여 코드를 계측(instrument)하기를 원하며, 각 도구는 하나의 프레임워크만 지원합니다. 저는 그 반대를 원했습니다. 모든 것을 감시하고, 아무것도 변경할 필요가 없으며, 데이터를 내 컴퓨터에 보관하는 무언가를 말이죠.

그것은 무엇인가

Agentic Ledger는 당신의 에이전트와 LLM 제공자(provider) 사이에 위치하는 투명한 프록시(transparent proxy)입니다. 에이전트의 base_url을 이 프록시로 지정하면, 모든 요청(request)과 응답(response)을 기록하고, 각 호출에 액션 ID(action id)를 할당하며, 비용이 얼마인지 계산하고, 응답을 수정 없이 그대로 전달합니다. 당신의 에이전트는 프록시가 거기 있다는 사실을 전혀 알지 못합니다.

당신의 에이전트  ->  Agentic Ledger 프록시  ->  OpenAI / Anthropic / 모든 게이트웨이
                       |
                SQLite 또는 Postgres
...

SDK도, 데코레이터(decorators)도, 몽키 패칭(monkey patching)도 필요 없습니다. 모든 프레임워크와 모든 제공자에서 작동하는데, 그 이유는 이들이 공통적으로 공유하는 유일한 계층인 HTTP 호출(HTTP call) 단계에서 작동하기 때문입니다.

모든 것은 로컬 우선(local-first)입니다. 당신의 프롬프트(prompts)는 당신의 컴퓨터에 있는 SQLite 파일(또는 자체 Postgres)에 머뭅니다. MIT 라이선스로 제공됩니다.

2분 만에 사용해보기

pip install -U agentic-ledger
AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com python -m agenticledger.proxy

또는 Docker를 사용하여 (멀티 아키텍처, non-root, Sigstore 서명 완료):

docker run -p 8000:8000 \
  -e AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com \
  -v $(pwd)/data:/data \
...

그런 다음 당신의 에이전트를 프록시로 지정하세요:

client = OpenAI(
    base_url="http://localhost:8000/v1",
    default_headers={"x-agenticledger-session-id": "run-1"},
...

Claude Code와 같은 코딩 에이전트(coding agents)의 경우, 환경 변수 하나만 설정하면 헤더 설정 없이도 훨씬 더 간단하게 사용할 수 있습니다:

export ANTHROPIC_BASE_URL=http://localhost:8000
claude

대시보드는 http://localhost:8000에서 확인할 수 있습니다.

제공 기능

실제 비용 회계 (Real cost accounting). 프롬프트 캐시(prompt cache) 읽기 및 쓰기를 포함하여, 각 제공업체(provider)의 고유한 방식에 따른 호출당, 세션당, 에이전트당, 일일 비용을 산출합니다. 캐시 트래픽은 코딩 에이전트 실제 지출의 대부분을 차지하지만, 대부분의 도구는 이를 무시합니다. 이 프로젝트의 제 규칙은 다음과 같습니다: 수치는 귀하의 제공업체 청구서와 일치해야 하며, 만약 일치하지 않는다면 그것은 제가 보고받아야 할 버그입니다.

루프 인식 (Loop awareness). 이 부분은 다른 어디에서도 본 적이 없는 기능입니다. 프록시(proxy)는 원시 트래픽(raw traffic)으로부터 에이전트 루프를 추론합니다. 즉, ReAct 스타일의 스레드를 하나로 엮고, 새로운 컨텍스트 반복(Ralph 스타일의 야간 루프)을 실행(run) 단위로 그룹화하며, 동일한 인자(arguments)로 동일한 도구를 반복해서 호출하거나 단계별 예산(step budget)이 한도를 초과하는 것과 같이 비용을 낭비하는 병리적 현상(pathologies)을 식별합니다. 차단 모드(block mode)에서는 회로 차단기(circuit breaker) 역할을 수행하여, 갇힌 루프가 비용을 계속 소모하게 두는 대신 HTTP 429 응답을 반환합니다.

루프 실행기 (A loop runner). agenticledger run --max-iterations 50 --budget 25 -- <your agent command> 명령은 에이전트를 루프 내에서 재실행하고, 모든 호출을 해당 실행(run)에 귀속시키며, 완료 약속(completion promise), 예산 상한선, 또는 반복 횟수 제한 중 가장 먼저 도달하는 시점에 중단합니다.

예산 및 속도 제한 (Budgets and rate limits). 세션당, 에이전트당, 일일 단위로 적용되는 엄격한 USD 상한선을 설정하며, 호출이 제공업체에 도달하기 전 요청 경로(request path)에서 강제 적용됩니다.

MCP 서버. 귀하의 에이전트(또는 Claude Desktop, Cursor)가 원장(ledger)에 자신에 대해 질의할 수 있습니다: 세션 목록 나열, 모든 호출에 대한 설명 요청, 실행이 예산을 초과했는지 확인 등.

OTLP 수집 (OTLP ingest). 이미 OpenTelemetry GenAI 스팬(spans)을 방출하는 프레임워크는 이를 즉시 전송할 수 있습니다.

docs/integrations에는 Claude Code, Codex CLI, opencode, OpenClaw, BMAD-METHOD, LangGraph, CrewAI, OpenAI Agents SDK, Gemini CLI, AutoGen, Pydantic AI, Vercel AI SDK, LiteLLM, 그리고 OpenRouter를 위한 단계별 가이드가 마련되어 있습니다.

프로젝트 현황

솔직한 상태를 말씀드리자면, 이 프로젝트는 현재 0.4.0 버전인 1인 프로젝트입니다. 핵심 기능은 견고하며 테스트를 마쳤습니다 (100개 이상의 테스트, 세 가지 Python 버전에 대한 CI, SBOM이 포함된 서명된 멀티 아키텍처 이미지). 저는 제 자신의 코딩 에이전트들을 대상으로 매일 직접 사용(dogfooding)하고 있습니다. 부족한 점은 다른 사람들의 스택(stack)에서 검증된 경험(mileage)이 부족하다는 것입니다. 바로 그 간극을 여러분이 채워주실 수 있습니다.

요청 사항

에이전트를 운영 중이라면, 테스터가 되어주세요. 하루 동안 여러분의 스택을 이 프록시(proxy)로 연결해 보고, 무엇이 고장 났는지, 무엇이 혼란스러웠는지, 그리고 비용 수치가 제공업체의 콘솔과 일치하는지 알려주세요. 여러분의 트래픽 10분 분량이 제가 일주일 동안 혼자 테스트하는 것보다 더 많은 것을 가르쳐 줍니다.

기여하고 싶다면, 기여할 수 있는 실질적인 영역이 있습니다:

• 프레임워크 가이드 (Framework guides). 사용 중인 프레임워크가 통합 목록에 없거나 가이드에서 누락된 내용이 있다면, 해당 부분에 PR(Pull Request)을 보내는 것은 작업량이 적으면서도 즉시 유용하게 쓰일 수 있습니다.
• 가격 커버리지 (Pricing coverage). 비용 테이블은 새로운 모델과 제공업체에 맞춰 업데이트되어야 합니다. 모델을 추가하는 것은 한 줄의 코드 변경과 테스트만으로 가능합니다.
• 루프 탐지 휴리스틱 (Loop detection heuristics). 플래그(flags)가 놓치는 방식으로 에이전트가 갇혀버린 트랜스크립트(transcripts)가 있다면 보여주세요. 이것은 이 프로젝트에서 가장 흥미로운 미해결 과제입니다.
• 프론트엔드 (Frontend). 대시보드는 작은 React + Vite 앱입니다. 데이터 밀도가 높은 UI 작업을 즐기신다면 개선할 부분이 많습니다.
• 대규모 환경의 Postgres (Postgres at scale). Postgres 백엔드는 작동하지만, 아직 과부하 테스트를 거치지 않았습니다. 더 많은 트래픽을 운영 중이라면 여러분의 발견은 매우 가치 있을 것입니다.

저장소(Repo)에는 기여 가이드(CONTRIBUTING guide)가 있으며, 이슈 트래커(issue tracker)에는 good first issue라는 라벨이 붙은 입문용 작업들을 채워 넣고 있습니다. 만약 위의 사항 중 해당하는 것이 없더라도, 에이전트 관찰성(observability) 도구가 무엇을 해야 하는지에 대한 의견이 있다면 이슈를 생성하여 말씀해 주세요. 현 단계에서는 방향성에 대한 피드백이 코드만큼이나 중요합니다.

Repo: https://github.com/ShekharBhardwaj/AgenticLedger
Site: https://agentic-ledger.dev
Install: pip install -U agentic-ledger

읽어주셔서 감사합니다. 마음껏 테스트하며 망가뜨려 보세요.