PentAGI 딥다이브
— "펜테스터 팀"을 통째로 코드로 옮긴다: 격리 컨테이너 안에서 스스로 계획·실행하는 자율 보안 에이전트

1프로젝트 한 줄 요약

PentAGI는 "침투 테스트(모의 해킹)를 스스로 계획하고 실행하는 자율 멀티 에이전트 시스템"이다. 이름은 Penetration testing(침투 테스트) + AGI(범용 인공지능)의 합성어다. 사용자가 "이 서버의 보안 취약점을 점검해줘" 같은 목표(goal) 하나만 주면, 시스템이 알아서 계획을 세우고 → 필요한 도구를 설치하고 → 격리된 리눅스 환경에서 점검을 수행하고 → 발견한 문제를 보고서로 정리한다.

2왜 지금 주목받는가

"AI가 해킹을 자동화한다"는 콘셉트 자체는 새롭지 않다. PentAGI가 트렌딩에 오른 이유는 콘셉트가 아니라 완성도와 자기호스팅(self-hosted) 스택의 깊이에 있다. 데모 수준이 아니라, 실무에서 돌릴 수 있게 관측성·메모리·격리·다중 LLM 지원까지 전부 갖춰 놓은 점이 눈에 띈다.

주목 포인트 1 — "아무 LLM이나 꽂아 쓴다"는 극단적 유연성

OpenAI·Anthropic·Gemini·Bedrock·DeepSeek·GLM·Kimi·Qwen·Ollama 등 10개 제공자를 기본 내장하고, 그 위에 OpenAI 호환 엔드포인트라면 무엇이든(custom) 붙일 수 있다. OpenRouter·DeepInfra 같은 애그리게이터도 지원한다. 심지어 vLLM + Qwen3.5-27B 로컬 배포 가이드까지 제공해, 외부에 데이터를 안 보내고 사내에서 완전히 돌리는 시나리오를 문서화했다. 보안 도구에서 "데이터가 밖으로 안 나간다"는 건 결정적 장점이다.

주목 포인트 2 — 역할별로 모델을 따로 배정

14개 에이전트 역할(primary_agent, pentester, coder, searcher …) 각각에 서로 다른 모델·파라미터를 바인딩할 수 있다. 판단이 중요한 펜테스터엔 고성능 모델을, 단순 검색·요약엔 저렴한 모델을 붙여 비용과 성능을 역할 단위로 최적화한다. 이 발상은 일반 에이전트 앱 설계에도 그대로 응용된다.

주목 포인트 3 — "돌리고 나서 무슨 일이 있었는지" 완전 추적

모든 LLM 호출·토큰·비용은 Langfuse로, 시스템 트레이스·메트릭·로그는 OpenTelemetry → Jaeger / VictoriaMetrics / Loki → Grafana로 흘러간다. 자율 에이전트는 "블랙박스"라는 불신을 받기 쉬운데, PentAGI는 관측성 스택을 1급 시민으로 내장해 그 불신을 정면으로 해소한다.

주목 포인트 4 — 격리를 타협하지 않는다

에이전트가 실행하는 모든 명령은 오직 Docker 컨테이너 안에서만 돈다. 기본 이미지는 보안 도구가 잔뜩 든 vxcontrol/kali-linux. Docker-in-Docker가 필요하면 TLS 인증으로 감싸고, 웹 스크래핑도 별도 격리 브라우저 컨테이너에서 한다. "자율 AI가 내 호스트를 건드리면?"이라는 가장 큰 공포를 설계 단계에서 봉쇄했다.

3기술 스택 전체 지도

백엔드 — Go 1.24.1 단일 모노레포

심장부는 순수 Go로 쓰였다. 웹 서버는 Gin, API는 REST와 GraphQL(gqlgen, 스키마 우선) 두 가지를 동시에 제공하며, GraphQL 구독(subscription)은 웹소켓(gorilla/websocket)으로 실시간 스트리밍한다.

프론트엔드 — React 19 SPA (Vite)

UI는 최신 React 19.2 + TypeScript + Vite 조합. 데이터 통신은 Apollo Client v4로 GraphQL을 쓰고, 실시간 업데이트는 graphql-ws(웹소켓)로 받는다. 컴포넌트는 Radix UI + Tailwind(shadcn 스타일).

가장 인상적인 부분은 브라우저 안에 진짜 터미널이 떠 있다는 것 — xterm.js v6(fit·search·webgl·web-links 애드온)로 에이전트가 컨테이너에서 실행하는 명령의 출력이 실시간으로 흘러간다. 여기에 코드 편집용 Monaco, 리치 텍스트 TipTap v3, PDF 보고서 렌더링 @react-pdf/renderer v4, 차트 Recharts v3까지 얹었다.

인프라 — "조립식" 다중 Docker Compose

가장 배울 점이 많은 부분. PentAGI는 하나의 거대한 compose가 아니라 목적별로 쪼갠 여러 개의 compose 파일을 겹쳐 쓴다. 필요 없는 스택은 빼고 돌릴 수 있는 "모듈식" 배포다.

실제 명령 실행용 샌드박스 기본 이미지는 vxcontrol/kali-linux이며, 작업 성격에 따라 이미지를 자동 선택한다. 벡터 저장소는 vxcontrol/pgvector(PostgreSQL + pgvector 확장), 웹 정찰용 브라우저는 격리된 vxcontrol/scraper 컨테이너가 맡는다.

4아키텍처 심화 분석

PentAGI 아키텍처를 이해하는 열쇠는 딱 두 폴더다: backend/pkg/controller/(일감을 계층으로 쪼개는 Worker들)와 backend/pkg/providers/(실제 LLM을 굴리는 두뇌). 이 둘이 어떻게 맞물리는지 먼저 전체 그림부터 보자.

4-1. Worker 계층 — 큰 일을 자동으로 잘게 쪼갠다

일감은 Flow → Task → Subtask 3단계로 내려간다. controller/flow.go의 FlowWorker가 최상위이고, 이벤트 루프(worker() → processInput() → runTask() → execTask())를 돈다. 하나의 Task는 최대 15개(TasksNumberLimit = 15)의 Subtask로 쪼개지는데, 이 분해를 generator 에이전트가 하고 refiner 에이전트가 다듬는다. 별도로 AssistantWorker(assistant.go)는 자율 파이프라인과 분리된 대화형 채팅 에이전트다.

4-2. 멀티 에이전트를 "도구 호출"로 구현했다 (핵심 설계)

여기가 PentAGI 설계에서 가장 배울 점이 많은 부분이다. 14개 역할은 pkg/providers/pconfig/config.go의 ProviderOptionsType에 열거돼 있다: primary_agent · assistant · simple · simple_json · adviser · generator · refiner · searcher · enricher · coder · installer · pentester · reflector. 각 역할은 서로 다른 모델/제공자/파라미터에 바인딩될 수 있다.

그런데 이 에이전트들이 어떻게 협업할까? 정답은 "전문가를 하나의 도구(tool)로 노출한다"는 것. pkg/tools/tools.go에서 primary_agent의 도구 목록에는 advice · coder · maintenance(installer) · memorist · pentester · search가 들어 있다. 즉 지휘자가 pentester라는 이름의 도구를 호출하면, 그게 곧 펜테스터 에이전트에게 일을 위임하는 것이다. 위임받은 전문가는 자기만의 제한된 도구 세트로 짧은 체인을 돌고, *_result라는 배리어 도구(hack_result, code_result, search_result …)를 호출해 결과를 반납하며 체인을 끝낸다.

# 개념적 흐름 (실제 코드가 아니라 설계 요약)
primary_agent
  ├─ tool: pentester   # → 펜테스터 에이전트에게 위임
  │     └─ 자기 도구: hack_result·advice·coder·terminal·file …
  │           └─ hack_result(...)   # 배리어 → 체인 종료, 결과 반납
  ├─ tool: coder       # → 코더 에이전트에게 위임
  │     └─ code_result(...)
  └─ tool: search      # → 검색기 에이전트에게 위임
        └─ search_result(...)

4-3. 도구 호출 루프 — performer.go (엔진의 심장)

가장 정독할 가치가 있는 파일은 pkg/providers/performer.go의 performAgentChain이다. 자율 에이전트가 "생각 → 도구 실행 → 결과 반영 → 다시 생각"을 반복하는 루프의 실체가 여기 있다. 대략 이렇게 돈다:

이 루프가 담고 있는 실전 노하우들이 배울 거리다:

• 리플렉터(reflector): 모델이 도구를 안 쓰고 잡담만 하면, "텍스트 응답은 작업 완료로 인정 안 됨. 함수 호출로 실행하라"고 다시 밀어넣어 궤도로 되돌린다.
• 배리어 도구: done · ask · subtask_list · subtask_patch와 *_result 세트가 호출되면 체인을 끝낸다. "언제 멈출지"를 도구로 명시화한 것.
• 체인 요약(csum): 대화가 상한(generator 150KB, refiner/reporter 100KB, summarizer 32KB)을 넘으면 히스토리를 LLM으로 압축해 컨텍스트 폭발을 막는다.
• 반복 감지 + 실행 모니터: 작은 모델(32B 미만)은 같은 행동을 무한 반복하기 쉬운데, 이를 감지해 끊어준다.

4-4. 제공자 추상화 — 10개 LLM을 하나의 인터페이스로

pkg/providers/provider/provider.go의 Provider 인터페이스가 10개 백엔드(openai · anthropic · gemini · bedrock · ollama · custom · deepseek · glm · kimi · qwen)를 통일한다. 핵심 메서드는 Call · CallEx · CallWithTools(스트리밍) 그리고 비용 추적용 GetUsage / GetPriceInfo다.

재미있는 디테일: 제공자마다 도구 호출 ID 형식이 제각각이라, GetToolCallIDTemplate이 이를 정규화한다(sync.Once로 캐시). 여러 LLM을 섞어 쓸 때 실제로 부딪히는 "사소하지만 치명적인" 호환성 문제를 어떻게 흡수하는지 보여주는 좋은 사례다.

4-5. 격리 · 기억 · 관측성 (설계 패턴 3종)

5디렉토리 구조 해부

구조를 읽는 요령: "일감을 쪼개는 곳"은 controller/, "LLM을 굴리는 곳"은 providers/, "손발이 되는 도구"는 tools/. 이 세 폴더만 이해하면 시스템의 80%가 보인다. 나머지(server·database·observability)는 그 셋을 떠받치는 인프라다.

6학습 포인트

Go로 LLM 에이전트 오케스트레이션 짜기

파이썬 LangGraph 없이도 계층형 Worker + 도구 위임만으로 견고한 멀티 에이전트를 만들 수 있다는 증명. 특히 "에이전트를 도구로 노출"하는 발상, 배리어 도구로 종료 조건을 명시하는 방식, 리플렉터로 궤도 이탈을 교정하는 기법은 언어 불문하고 응용 가능하다.

다중 LLM 제공자 추상화

Provider 인터페이스 하나로 10개 백엔드를 통일하고, 제공자별 도구 호출 ID 포맷 차이 같은 미묘한 비호환까지 흡수하는 방법. "우리 서비스를 특정 LLM에 종속시키지 않으려면?"의 실전 답안이다.

컨테이너 격리 설계

docker SDK로 샌드박스를 프로그래밍적으로 띄우고, host/bridge 네트워크 모드를 상황에 맞게 고르고, DinD를 TLS로 감싸는 실전 패턴. "위험한 코드를 안전하게 실행"하는 모든 시스템(온라인 저지, CI 러너, 코드 인터프리터)에 그대로 적용된다.

RAG + 지식 그래프 이중 메모리

벡터 검색(유사도)과 그래프(관계)를 함께 쓰는 이유를 코드로 확인할 수 있다. "무엇과 비슷한가"는 pgvector가, "무엇과 연결됐는가"는 Graphiti가 답한다.

에이전트 관측성

Langfuse로 LLM 비용·토큰을, OTEL로 시스템 트레이스를 나눠 잡는 2트랙 관측성. LLM 앱을 운영하려면 반드시 필요한 인프라를 어떻게 붙이는지 참고서가 된다.

실습 아이디어 (가볍게)

레포를 클론해 backend/pkg/providers/pconfig/config.go에서 14개 역할을 눈으로 확인하고, pkg/templates/prompts/의 .tmpl들을 읽으며 "각 역할에게 뭐라고 시켰는지"를 자연어로 파악해보라. 코드를 돌리지 않고도 에이전트 설계 철학의 절반은 프롬프트에 담겨 있다.

7하드웨어 · 시스템 요구사항

주의: 위 최소 사양은 본체(pentagi + pgvector + scraper)만 돌릴 때다. 관측성(Grafana·Loki·ClickHouse·Jaeger…)·Langfuse·Graphiti 스택을 추가로 켜면 각각 여러 컨테이너를 더 띄우므로 RAM이 훨씬 더 필요하다. 도커 소켓 접근이 필요한데, README는 이것이 사실상 root 권한과 동등함을 경고한다 — 신뢰할 수 있는 호스트에서만 돌릴 것.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크