시스템 관리자와 개발자는 Docker와 Docker Compose를 사용하여 몇 분 만에 자체 인프라에 AgentGPT를 직접 구축할 수 있습니다. 사내 온프레미스 서버나 프라이빗 가상 클라우드(VPC) 환경에 애플리케이션을 배포하면, 에이전트 목표 설정, 중간 추론 과정, 프롬프트 히스토리, 데이터베이스 기록을 사내 네트워크 경계 내에 완전히 격리하여 다중 테넌트 퍼블릭 SaaS로의 민감 정보 유출 위험을 차단할 수 있습니다.
본 가이드에서는 AgentGPT의 시스템 아키텍처, 사전 준비 사항, 자동화 및 수동 컨테이너 배포 절차, 엔터프라이즈 보안 강화 방안, 그리고 장기 유지보수 관점에서의 고려 사항을 종합적으로 정리합니다.
시스템 아키텍처 및 동작 원리
AgentGPT는 컨테이너화된 다계층 구조를 통해 재귀적 자율 에이전트 루프를 실행합니다.
- 프론트엔드(
frontend): Next.js 13, TypeScript, Tailwind CSS, HeadlessUI 기반의 웹 대시보드입니다. 포트3000으로 서비스되며 사용자가 브라우저에서 에이전트를 생성하고, 최상위 목표를 정의하고, 실시간으로 하위 작업 생성 및 실행 과정을 모니터링하며 결과를 내보낼 수 있도록 지원합니다. - 백엔드 엔진(
platform): 포트8000에서 실행되는 Python FastAPI 서비스입니다. LangChain을 기반으로 목표 분해, 우선순위 큐 관리, 실행 및 평가 루프, 외부 도구 호출을 오케스트레이션합니다. - 데이터 지속성 계층: 웹 계층의 Prisma ORM과 백엔드의 SQLModel을 통해 MySQL 데이터베이스와 연동되며, 에이전트 설정, 사용자 세션, 실행 세부 로그를 안전하게 보관합니다.
- 외부 모델 및 도구 통신: 핵심 오케스트레이션 로직과 세션 데이터는 프라이빗 Docker 호스트 내에 유지되지만, 모델 추론은 OpenAI API로 전송되는 아웃바운드 HTTPS 통신으로 처리됩니다(선택적으로 웹 검색을 위한 Serper API나 이미지 생성을 위한 Replicate API 연동 가능).
사전 필수 구성 요소
배포를 진행하기 전, 호스트 시스템이 다음 요구 사항을 충족하는지 확인합니다.
- Docker 및 Docker Compose: Docker Engine 20.10 이상 또는 Docker Desktop이 설치되어 있고 Compose v2가 정상 구동 중이어야 합니다.
- Git: 공식 소스코드 저장소를 복제하기 위해 필요합니다.
- Node.js 18 이상: 저장소에 포함된 대화형 CLI 설치 스크립트를 실행할 경우 필요합니다.
- API 자격 증명:
- 유효한 OpenAI API 키(GPT-4 또는 GPT-3.5-turbo 모델 호출 권한 및 충분한 쿼터 확보 필요).
- (선택) 자율 웹 검색 기능을 활성화하기 위한 Serper API 키.
- (선택) 이미지 생성 도구를 연동하기 위한 Replicate API 토큰.
방법 1: 대화형 자동 설정 스크립트를 통한 빠른 배포
AgentGPT 저장소에는 환경 변수 설정, 의존성 설치, Docker 이미지 빌드를 대화형으로 안내하는 스크립트가 포함되어 있습니다.
1. 저장소 복제
git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT
2. 설정 스크립트 실행
운영체제에 맞는 스크립트를 실행합니다.
- Linux / macOS:
./setup.sh - Windows(PowerShell 또는 명령 프롬프트):
setup.bat
3. 대화형 질의 입력
스크립트의 안내에 따라 다음 정보를 입력합니다.
- OpenAI API 키
- 선택적 Serper 및 Replicate 키
- 포트 매핑 및 데이터베이스 구성 선호 사항
스크립트가 컨테이너 빌드 및 실행을 완료하면 브라우저에서 http://localhost:3000에 접속하여 대시보드가 정상 구동되는지 확인합니다.
방법 2: Docker Compose를 활용한 수동 배포 및 운영
엔터프라이즈 리눅스 서버, CI/CD 자동화 배포, 비대화형 터미널 환경에서는 표준 Docker Compose 워크플로를 사용하는 것이 안정적입니다.
1. 저장소 복제 및 구성 파일 확인
git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT
루트 디렉터리의 docker-compose.yml에는 frontend(./next/Dockerfile 기반)와 platform(./platform의 prod 빌드 타깃) 두 핵심 서비스가 정의되어 있습니다.
2. 환경 변수 파일 구성
환경 변수 예시 템플릿을 Next.js 런타임 경로에 복사합니다.
cp .env.example ./next/.env
에디터로 ./next/.env 파일을 열고 핵심 매개변수를 설정합니다.
# 과도한 토큰 소모를 방지하기 위한 최대 루프 횟수 제한
NEXT_PUBLIC_MAX_LOOPS="50"
REWORKD_PLATFORM_MAX_LOOPS="50"
# 내부 통신 엔드포인트
NODE_ENV="production"
NEXT_PUBLIC_BACKEND_URL="http://localhost:8000"
# 세션 및 인증 암호화 키
NEXTAUTH_SECRET="32자-이상의-안전한-무작위-문자열을-생성하여-입력"
NEXTAUTH_URL="http://localhost:3000"
# 외부 LLM 및 도구 API 키
OPENAI_API_KEY="sk-your-openai-api-key"
SERPER_API_KEY="your-optional-serper-api-key"
3. 컨테이너 빌드 및 백그라운드 구동
이미지를 빌드하고 백그라운드(데몬) 모드로 컨테이너를 시작합니다.
docker compose up --build -d
4. 서비스 상태 및 실행 로그 확인
컨테이너의 정상 동작 여부를 확인합니다.
docker compose ps
실시간 로그를 추적하여 초기화 과정을 점검합니다.
docker compose logs -f
브라우저에서 http://localhost:3000으로 접속하여 프라이빗 환경에서의 첫 번째 자율 에이전트 작업을 시작합니다.
사내 프로덕션 환경을 위한 보안 강화 가이드
기본 제공되는 Docker Compose 설정은 로컬 개발 환경을 기준으로 구성되어 있습니다. 사내 공유 인프라에 배포할 때는 다음 보안 수칙을 반드시 적용해야 합니다.
1. 호스트 포트 바인딩 제한
기본 설정은 포트 3000과 8000을 모든 네트워크 인터페이스(0.0.0.0)에 바인딩하므로 사내 네트워크의 비인가 사용자가 인증 없이 접근할 위험이 있습니다. docker-compose.yml에서 로컬 루프백 주소(127.0.0.1)로 바인딩을 제한하십시오.
services:
frontend:
ports:
- "127.0.0.1:3000:3000"
platform:
ports:
- "127.0.0.1:8000:8000"
2. 리버스 프록시 및 TLS 암호화 적용
Nginx, Traefik, Caddy 등의 리버스 프록시를 전면에 배치하여 HTTPS 암호화 통신을 강제하고, 기업 SSO(OAuth/LDAP) 인증을 연동합니다. Nginx 기본 설정 예시는 다음과 같습니다.
server {
listen 443 ssl http2;
server_name agent.internal.example.com;
ssl_certificate /etc/ssl/certs/internal.crt;
ssl_certificate_key /etc/ssl/private/internal.key;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
}
3. 에이전트 최대 루프 횟수 엄격 제한
에이전트는 목표가 모호할 경우 무한히 하위 작업을 분해하고 반복 실행하는 루프에 빠질 수 있습니다. NEXT_PUBLIC_MAX_LOOPS와 REWORKD_PLATFORM_MAX_LOOPS 값을 20~50 수준으로 엄격히 지정하여 예기치 못한 API 비용 급증을 예방하십시오.
4. 데이터 프라이버시 경계 이해
AgentGPT를 자체 구축하면 오케스트레이션 로직, 작업 실행 이력, 내부 데이터베이스는 사내 인프라에 완벽히 머무릅니다. 그러나 에이전트가 처리하는 프롬프트와 중간 결과물은 여전히 외부 OpenAI API 엔드포인트로 전송됩니다. 엄격한 기밀 유지가 필요한 업무의 경우 내부 데이터 유출 방지(DLP) 프록시를 적용하거나 전용 Azure OpenAI 프라이빗 엔드포인트를 연동하는 방안을 검토해야 합니다.
프로젝트 라이프사이클 및 장기 유지보수 고려 사항
AgentGPT를 전사 자동화 인프라의 핵심 축으로 채택하기 전, 다음 사항을 검토해야 합니다.
- 저장소 아카이브 상태: GitHub의
reworkd/AgentGPT오픈소스 저장소는 공식 팀의 사업 방향 전환에 따라 2026년 초 공식적으로 아카이브(읽기 전용) 처리되었습니다. 기존 코드는 PoC 및 내부 독립 워크플로 실행에 충분히 안정적이지만, 업스트림 보안 패치 및 취약점 대응은 중단되었습니다. - 종속성 버전 고정: 소스코드로부터 Docker 이미지를 빌드할 때는 베이스 이미지와 Python/Node 패키지 버전을 엄격히 고정하여 외부 패키지 업데이트로 인한 빌드 오류를 방지하십시오.
- 차세대 프레임워크와의 비교: 복잡한 멀티 에이전트 협업, 지속적인 도구 생태계 확장, 정교한 인간 개입 승인(Human-in-the-loop)이 요구되는 핵심 프로덕션 환경의 경우, CrewAI, AutoGen, LangGraph 등 현재 활발히 유지보수되는 오케스트레이션 엔진과의 병행 평가를 권장합니다.