기업 내부 인프라나 로컬 환경에 AgentGPT를 직접 구축(셀프 호스팅)하면, 보안 및 엔지니어링 팀은 민감한 프롬프트나 비즈니스 기밀, 고객 데이터를 퍼블릭 클라우드 API로 전송하지 않고도 자율형 AI 에이전트(Autonomous Agents) 워크플로를 안전하게 운영할 수 있습니다. 자율형 에이전트는 목표를 하위 작업으로 재귀 분해하고, 실행 결과를 평가하며, 모델을 반복적으로 호출하므로, 로컬이나 사내 프라이빗 LLM 추론 엔드포인트를 연결하면 클라우드 토큰 과금과 호출 한도 문제도 완벽히 해결됩니다.
Reworkd에서 오픈소스로 공개한 AgentGPT는 Next.js 프론트엔드, FastAPI 플랫폼 백엔드, MySQL 데이터베이스로 구성된 웹 기반 자율 에이전트 플랫폼입니다. 기본적으로는 OpenAI 클라우드에 연결되도록 설계되어 있으나, Docker 네트워크 설정, 환경 변수 구성, 그리고 Ollama, LocalAI, vLLM과 같은 OpenAI 호환 추론 엔진을 올바르게 연동하면 외부 네트워크와 완전히 단절된 고신뢰 에이전트 환경을 구축할 수 있습니다.
아키텍처 개요 및 Docker 컨테이너 네트워크 경계 문제
Docker Compose 기반의 AgentGPT 배포는 세 가지 핵심 서비스로 구성됩니다.
- 프론트엔드 (
next):3000포트로 실행되며, 에이전트 생성, 목표 부여, 실시간 작업 모니터링 대시보드를 제공합니다. - 백엔드 플랫폼 (
platform):8000포트로 실행되며, FastAPI를 기반으로 에이전트 의사결정 루프, 작업 스케줄링, LLM 통신을 담당합니다. - 데이터베이스 (
db):3306포트로 실행되며, MySQL을 통해 에이전트 실행 기록, 태스크 상태, 환경 설정을 저장합니다.
+-------------------------------------------------------------------------+
| Docker 내부 네트워크 (agentgpt-network) |
| |
| [ 프론트엔드: Next.js ] <---> [ 백엔드: FastAPI Platform ] <---> [ DB ]|
| (:3000) (:8000) (:3306) |
+--------------------------------------------|----------------------------+
| (REWORKD_PLATFORM_OPENAI_API_BASE)
v
+--------------------------------------------+
| 호스트 머신 / 사내 프라이빗 GPU 인프라 |
| host.docker.internal:11434/v1 |
| [ Ollama / vLLM / LocalAI 추론 엔드포인트] |
+--------------------------------------------+
컨테이너에서 호스트로의 네트워크 연결 문제
로컬 모델을 연동할 때 가장 자주 발생하는 실수는 API 주소를 http://localhost:11434 또는 http://127.0.0.1:11434로 지정하는 것입니다. Docker 컨테이너 내부에서 localhost는 호스트 운영체제가 아니라 컨테이너 자체의 격리된 네트워크 인터페이스를 의미하므로, 호스트에서 실행 중인 추론 서버에 도달할 수 없습니다.
올바른 통신 구성 방법은 다음과 같습니다.
- macOS 및 Windows (Docker Desktop):
http://host.docker.internal:11434/v1을 사용합니다. - Linux 환경:
docker-compose.yml의platform서비스에extra_hosts: ["host.docker.internal:host-gateway"]를 추가하여 호스트 게이트웨이 IP로 도메인이 변환되도록 설정합니다. - 동일 Compose 네트워크 구성: Ollama나 LocalAI를 동일한 Docker Compose 파일 내에 서비스로 선언할 경우, 서비스 이름(예:
http://ollama:11434/v1)을 직접 사용할 수 있습니다.
1단계: 로컬 또는 프라이빗 LLM 엔드포인트 준비
사용할 추론 엔진은 OpenAI 규격과 호환되는 HTTP REST API(특히 /v1/chat/completions 및 /v1/models)를 제공해야 합니다.
옵션 A: Ollama 활용 (로컬 워크스테이션 및 개발용 권장)
Docker 컨테이너의 접근을 허용하기 위해 Ollama를 전체 네트워크 인터페이스에 바인딩하여 실행합니다.
# Linux 환경 예시 (환경 변수 적용 후 백그라운드 구동)
OLLAMA_HOST=0.0.0.0:11434 ollama serve
지시 이행(Instruction Following)과 구조화된 JSON 추론 능력이 뛰어난 모델을 다운로드합니다.
ollama pull qwen2.5:14b
# 또는
ollama pull llama3.1:8b
cURL을 통해 엔드포인트가 정상 작동하는지 확인합니다.
curl http://localhost:11434/v1/models
옵션 B: vLLM 활용 (GPU 서버 및 고동시성 환경 권장)
GPU가 장착된 서버에서 vLLM의 OpenAI 호환 API 서버를 실행합니다.
python3 -m vllm.entrypoints.openai.api_server \
--model meta-llama/Llama-3.1-8B-Instruct \
--host 0.0.0.0 \
--port 8000
2단계: AgentGPT 저장소 복제 및 환경 변수 구성
공식 저장소를 복제합니다.
git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT
환경 변수 템플릿 파일을 복사합니다.
cp .env.example .env
.env 핵심 설정 항목
프로젝트 루트의 .env 파일(개별 수동 빌드 시 platform/.env 포함)을 열고 다음과 같이 설정합니다.
# ----------------------------------------
# LLM 엔드포인트 설정
# ----------------------------------------
# host.docker.internal을 통해 호스트 추론 엔드포인트 지정
# 주의: 끝에 슬래시(/)를 붙이지 마십시오 (/v1 로 입력, /v1/ 금지)
REWORKD_PLATFORM_OPENAI_API_BASE=http://host.docker.internal:11434/v1
# OpenAI SDK 검증 통과를 위한 더미 키 입력
# 로컬 추론 엔진은 해당 값을 검증하지 않으므로 임의 문자열 사용
OPENAI_API_KEY=local-secret-key
# ----------------------------------------
# 데이터베이스 설정
# ----------------------------------------
DATABASE_URL=mysql://root:password@db:3306/agentgpt
MYSQL_ROOT_PASSWORD=password
MYSQL_DATABASE=agentgpt
# ----------------------------------------
# 세션 인증 키
# ----------------------------------------
NEXTAUTH_SECRET=generate-a-secure-random-32-byte-hex-key
NEXTAUTH_URL=http://localhost:3000
설정 시 주의사항:
REWORKD_PLATFORM_OPENAI_API_BASE끝에/chat/completions나 불필요한 슬래시(/)를 붙이지 마십시오. AgentGPT 백엔드가 내부적으로 경로를 추가하므로 슬래시가 중복되면//chat/completions로 요청되어 HTTP 404 오류가 발생합니다.
3단계: Linux 호스트용 docker-compose.yml 수정
Linux 환경에서는 docker-compose.yml 내의 platform 서비스 항목에 호스트 해석 설정을 명시해야 합니다.
services:
platform:
build:
context: ./platform
dockerfile: Dockerfile
environment:
- REWORKD_PLATFORM_OPENAI_API_BASE=http://host.docker.internal:11434/v1
- OPENAI_API_KEY=local-secret-key
- DATABASE_URL=mysql://root:password@db:3306/agentgpt
ports:
- "8000:8000"
extra_hosts:
- "host.docker.internal:host-gateway"
depends_on:
- db
frontend:
build:
context: ./next
dockerfile: Dockerfile
ports:
- "3000:3000"
environment:
- NEXTAUTH_URL=http://localhost:3000
- NEXTAUTH_SECRET=generate-a-secure-random-32-byte-hex-key
depends_on:
- platform
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: password
MYSQL_DATABASE: agentgpt
ports:
- "3306:3306"
volumes:
- db_data:/var/lib/mysql
volumes:
db_data:
4단계: 컨테이너 빌드 및 실행
Docker Compose로 서비스를 실행합니다.
docker compose up -d --build
백엔드 로그를 확인하여 데이터베이스 및 서비스 초기화가 정상적으로 완료되었는지 확인합니다.
docker compose logs -f platform
모든 컨테이너가 정상 구동되면 웹 브라우저에서 http://localhost:3000으로 접속합니다.
5단계: 웹 인터페이스 설정 및 자율 에이전트 구동
- 설정 창 열기: AgentGPT 왼쪽 하단 네비게이션의 톱니바퀴 아이콘(Settings)을 클릭합니다.
- 모델 태그 입력: 로컬 추론 엔진에서 구동 중인 모델 이름(예:
qwen2.5:14b또는llama3.1:8b)을 입력합니다. - 매개변수 조정:
- Temperature:
0.2~0.4수준으로 낮게 설정합니다. 자율 에이전트는 체계적인 작업 분할과 엄격한 JSON 파싱을 요구하므로 온도가 지나치게 높으면 서식 오류가 발생합니다. - 최대 루프 수(Max Loops): 로컬 장비의 추론 지연 시간을 고려하여 초기에는 5~10회 정도로 설정합니다.
- Temperature:
- 에이전트 실행:
- Agent Name:
Local-DevOps-Analyst - Goal:
온프레미스 AI 에이전트 인프라 구축 시 발생하는 주요 네트워크 병목을 분석하고 3가지 개선안을 우선순위별로 제시하라. - Deploy Agent 버튼을 클릭합니다.
- Agent Name:
- 실행 모니터링: 에이전트가 목표를 하위 태스크로 세분화하고, 로컬 LLM을 호출하여 작업을 순차 수행한 후 최종 요약 보고서를 완성하는 과정을 확인합니다.
실무 핵심 권장사항 및 모델 선정 기준
1. 자율 에이전트가 요구하는 모델 역량
자율형 에이전트는 단순 대화형 챗봇보다 훨씬 엄격한 모델 능력을 필요로 합니다.
- 시스템 지침을 철저히 준수하고 규격화된 JSON 형식으로 결과를 반환해야 합니다.
- 목표 달성 여부를 올바르게 판단하여 동일한 작업을 반복하는 무한 루프에 빠지지 않아야 합니다.
매개변수 70억(7B) 미만의 경량 모델이나 지시 조정이 미흡한 모델은 JSON 파싱 실패로 작업이 중단되기 쉽습니다. 다음과 같은 모델군을 추천합니다.
- 최소 권장 기준: Llama-3.1-8B-Instruct 또는 Qwen-2.5-7B-Instruct
- 프로덕션 권장 기준: Qwen-2.5-14B/32B 또는 Llama-3.1-70B(양자화 적용 모델)
2. 컨텍스트 길이 확보
작업이 여러 단계로 이어지면 대화 이력 메모리가 가파르게 증가합니다.
- Ollama 사용 시 별도의
Modelfile에PARAMETER num_ctx 16384등을 명시하여 컨텍스트가 잘리는 현상을 방지하십시오.
3. 오픈소스 유지보수 현황 참고
GitHub의 reworkd/AgentGPT 저장소는 2026년 1월부로 보관(Archived) 처리되어 읽기 전용 상태입니다. 현재 아키텍처는 자체 에이전트 환경 구축을 위한 레퍼런스로 손색이 없으나, 장기적인 기업 프로덕션 환경에서는 라이브러리 버전을 고정하고 사내 독립 Docker 이미지를 관리하는 것을 권장합니다.