[에이전트] 1. 시작 : 폐쇄망에는 왜 자체 AI 에이전트가 필요한가

(폐쇄망 사내 에이전트 ①) 시작

클로드 코드 같은 AI 에이전트로 일하는 재미를 알아버린 뒤, 문제는 회사 자리였다. 내 사무 PC는 인터넷이 안 되는 폐쇄망이다. API 키를 넣을 곳도, 모델을 내려받을 길도 없다. 그렇다고 파일 정리, 엑셀 취합, 코드 검색 같은 반복 작업이 사라지는 건 아니다. 클라우드 AI를 못 쓰면 방법은 하나다 — 에이전트를 직접 만들어서 들고 들어가는 것. 이 시리즈는 그렇게 만든 물건(가칭 ‘에어’)의 개발기를, 실제 커밋 기록을 따라가며 풀어놓는 기록이다.

폐쇄망이라는 조건을 먼저 정리하면

만들기 전에 제약부터 적었다. 이 제약들이 이후 모든 설계 결정의 근거가 된다.

제약	의미
인터넷 차단	클라우드 API·CDN·패키지 저장소 전부 불가 — 반입 매체로만
데이터 반출 금지	문서·코드를 밖으로 보내는 순간 사고 — 추론도 안에서
평범한 사무 PC	16GB RAM, 내장 GPU, 관리자 권한 제한
감사 요구	‘AI가 뭘 실행했는지’를 증명할 수 있어야 함

특히 마지막 줄이 중요하다. 규제가 엄격한 환경에서 도구가 파일을 지우고 명령을 실행한다면, “누가 언제 무엇을 허락해서 실행됐는가”에 답할 수 없는 물건은 애초에 반입이 안 된다. 그래서 이 프로젝트는 시작부터 에이전트이기 이전에 감사 가능한 실행기여야 했다.

답: 로컬 소형 LLM + 자체 런타임

결론은 이렇게 잡혔다. 모델은 Qwen 4B GGUF(Q4_K_M) — 8GB 프로세스 예산 안에서 도는 몇 안 되는 선택지다. 추론은 llama.cpp 계열로 로컬에서. 그리고 그 위에 파일·검색·Git·엑셀·PDF·셸을 다루는 Tool 35종과 승인·감사 게이트를 얹은 런타임을 직접 짰다. 첫 커밋 메시지가 이 물건의 정의다.

commit 04d3a0f  (2026-08-01)
feat: Air Runtime 0.1.0 — 폐쇄망 로컬 LLM Agent Runtime

이후 8일 동안 45개의 커밋이 쌓였다. Java로 시작해 이틀 만에 TypeScript로 갈아엎었고, 별도 서버 없이 프로세스 안에서 추론하도록 바꿨고, 4B 모델의 한계와 씨름했고, 컨텍스트 압축 버그를 잡다가 방향을 통째로 되돌리기도 했다. 그 과정이 커밋 메시지에 수치와 함께 고스란히 남아 있어서, 이 시리즈는 그 diff를 따라 읽는 개발기가 된다.

클라우드 에이전트와 뭐가 다른가

이 시리즈를 읽는 법 — diff가 곧 본문이다

일반적인 튜토리얼과 접근이 다르다. 각 편은 실제 커밋 한두 개를 열고, 그 커밋이 왜 필요했는지(대부분 실사용 로그), 무엇을 바꿨는지(코드), 무엇을 재서 확인했는지(실측 수치)를 따라간다. 예를 들어 9편에서 다룰 revert 커밋은 이렇게 시작한다 — “동작은 했지만 방향이 틀렸다.” 완성된 결과만 보여주는 글에서는 절대 안 나오는 문장이다. 실패와 되돌림까지가 기록이고, 그게 이 시리즈의 값어치라고 생각한다.

기술 스택을 미리 요약하면 — TypeScript + Bun(빌드 없이 소스 실행, 단일 바이너리 컴파일), 추론은 node-llama-cpp로 프로세스 안에서(GGUF 직접 로드), 웹 UI는 Svelte 5 + SSE, 감사는 SQLite. 전부 “폐쇄망 반입”이라는 한 가지 요구에서 역산된 선택이다.

적용해 보기 — 내 환경의 제약표부터

비슷한 걸 만들 생각이라면, 코드보다 먼저 자기 환경의 제약표를 채워보길 권한다. 위 표의 네 줄(네트워크·데이터·하드웨어·감사)에 자기 환경의 답을 적으면, 그 답이 곧 아키텍처다. 예컨대 “프록시로 API는 열려 있음”이면 이 시리즈의 절반(로컬 추론)이 필요 없고, “감사 요구 없음”이면 6~7편의 게이트를 승인 다이얼로그 하나로 줄여도 된다. 제약이 헐거운데 무거운 구조를 따라 하는 게 제일 흔한 낭비다.

✅ 확인

• 내 환경에서 무엇이 왜 막혀 있는지(네트워크·데이터·권한) 한 줄씩 적을 수 있다.
• 그 제약이 요구하는 것이 로컬 추론인지, 감사인지, 둘 다인지 구분했다.
• 다음 편에서 볼 ‘모델과 실행기의 분리’가 왜 첫 결정인지 감이 온다.

클로드 코드 같은 클라우드 에이전트는 거대 모델의 지능으로 많은 걸 해결한다. 폐쇄망 로컬 에이전트는 반대다 — 모델이 작으니 런타임이 똑똑해야 한다. 모델이 같은 도구를 무한 반복하면 런타임이 끊고, 컨텍스트가 모자라면 런타임이 접고, 위험한 실행은 런타임이 막는다. “큰 모델이면 프롬프트로 해결됐을 일”을 코드로 해결하는 것, 그게 이 시리즈 전체를 관통하는 주제다. 컨텍스트 엔지니어링 시리즈에서 다룬 원칙들이 여기서 전부 실전으로 등판한다.

시리즈 지도

1. 시작 — 왜 폐쇄망엔 자체 에이전트인가 (이 글)
2. 설계 — 모델과 실행기를 분리한다
3. 피벗 — Java로 시작해 이틀 만에 TypeScript+Bun으로
4. 추론 — 별도 서버 없이 프로세스 안에서 LLM 돌리기
5. 도구 — Tool 35종과 화이트리스트 셸
6. 승인 — 감사 가능한 승인 게이트와 권한 모드
7. 규칙 — “다시 묻지 않기”를 안전하게
8. 소형모델 — 4B로 버티는 설계
9. 컨텍스트 — KV 캐시와 압축의 사투
10. 배포 — 단일 바이너리와 폐쇄망 반입
11. UX — 기다림을 설계하다
12. 회고 — 8일 45커밋이 남긴 것

자주 묻는 질문 (FAQ)

폐쇄망에서는 정말 클라우드 AI를 전혀 못 쓰나요?

물리적으로 외부 네트워크가 차단된 환경이라면 API 호출 자체가 불가능합니다. 프록시로 일부 열어주는 조직도 있지만, 데이터 반출 규정 때문에 업무 문서를 외부 모델에 보내는 것 자체가 금지인 경우가 많습니다. 그래서 추론까지 내부에서 도는 로컬 LLM이 답이 됩니다.

사무용 PC에서 LLM이 돌아가긴 하나요?

4B급 양자화 모델(GGUF Q4_K_M)이면 CPU만으로 돕니다. 빠르진 않지만(수십 초), 파일 정리·문서 요약·코드 검색 같은 작업엔 충분합니다. 대신 모델이 작아서 생기는 빈틈을 런타임 설계로 메워야 하는데, 그게 이 시리즈의 내용입니다.