만약 당신이 함수 호출 (function calling, 도구 사용)을 사용하여 AI 에이전트를 구축해 본 적이 있다면, 그 순수한 공포의 감정을 정확히 알고 있을 것입니다. 에이전트를 테스트하고, 괜찮아 보여서 커피를 한 잔 마시러 갔다가 돌아왔더니, 에이전트가 무한 루프 (infinite loop)에 빠져 똑같은 도구를 호출하고, 실패하고, 500번이나 재시도하는 것을 목격하게 됩니다.

갑자기, 당신의 OpenAI API 잔액이 완전히 바닥나 버립니다. 💸

제 자신의 크레딧을 너무 여러 번 낭비한 끝에, 저는 이제 충분하다고 결정했습니다. 저는 이러한 루프를 포착하고, 지갑을 보호하며, 에이전트 디버깅 (debugging)을 고통 없이 만들어 주기 위해 특별히 설계된 오픈 소스 MITM 프록시(proxy)인 PromptShark를 구축했습니다.

🦈 PromptShark란 무엇인가요?

PromptShark는 당신의 코드와 LLM 제공자 사이에 위치하는 드롭인 (drop-in) 로컬 프록시입니다. 가장 좋은 점은 무엇일까요? 코드 변경이 전혀 필요 없다는 것입니다.

에이전트를 다시 작성하거나 무거운 SDK를 설치할 필요가 없습니다. 그저 base_url을 http://localhost:8080/v1로 변경하고 API 키는 그대로 유지하면 됩니다. PromptShark가 트래픽을 가로채 마법을 부립니다.

주요 기능은 다음과 같습니다:

1. 🛑 무한 루프 탐지 (Infinite Loop Detection)

PromptShark는 에이전트의 세션을 추적하고 요청 페이로드 (request payloads)를 해싱 (hash)합니다. 만약 에이전트가 반복적인 루프에 빠진 것을 감지하면 (예: 도구에 반복적으로 정확히 동일한 잘못된 인자를 전달하고 실패하는 경우), OpenAI API에 도달하기 전에 즉시 요청을 차단합니다. 더 이상의 돈 낭비는 없습니다.

2. ⏪ 타임 트래블 재생 및 캐싱 (Time-Travel Replay & Caching) (킬러 기능)

다단계 에이전트를 디버깅하는 것은 비용이 많이 듭니다. 왜냐하면 10단계에서 실패했을 때, 보통 1~9단계를 처음부터 다시 시작하고 비용을 지불해야 하기 때문입니다.

PromptShark는 세션을 SQLite에 로컬로 캐싱 (caching)합니다. 에이전트가 실수를 하면 다음과 같은 작업을 할 수 있습니다:

• UI로 이동하여 세션을 되감기 (rewind) 합니다.
• JSON 페이로드를 편집합니다 (프롬프트 (prompt)를 수정하거나 도구 응답을 가짜로 만듭니다).
• 실행을 재개합니다. 1~9단계는 캐시에서 즉시 무료로 제공되며, API는 10단계에 대해서만 호출됩니다.

3. 📊 실시간 대시보드 (Real-time Dashboard)

깔끔한 다크 모드 UI가 함께 제공되어, 첫 번째 토큰 생성 시간 (Time-To-First-Token (TTFT))을 추적하고, 토큰 사용량 (단계별로 분리된 프롬프트 (prompt) 대 완료 (completion) 토큰)을 모니터링하며, 정확한 비용을 USD 단위로 실시간 확인할 수 있습니다.

🛠️ 내부 구조 (Under the Hood)

저는 이 도구가 빠르고, 신뢰할 수 있으며, 로컬에서 실행하기 쉽기를 원했습니다:

• Go가 프록시 (proxying), 스트리밍 (streaming), 그리고 웹소켓 (WebSockets)을 처리합니다 (네트워크 I/O에 최적화).
• C++ 엔진이 프로세스 간 통신 (IPC)을 통해 퍼지 루프 탐지 (fuzzy loop-detection) 로직을 구동합니다.
• **SQLite (WAL 모드)**는 Postgres를 실행할 필요 없이 매우 빠른 캐싱 (caching)을 보장합니다.

직접 체험해 보세요!

지금 바로 Docker Compose를 사용하여 실행할 수 있습니다.

만약 AI 에이전트를 구축하고 있으며, 통제되지 않는 도구 호출 (tool calls)로 인해 API 크레딧을 낭비하는 것에 지쳤다면, 꼭 한번 사용해 보시길 권합니다.

🔗 GitHub 저장소 (GitHub Repository): apvcode/PromptShark