AgentGPT에서 실행 루프 제한 설정 및 작업 결과 내보내기로 토큰 낭비 방지하기

자율형 AI 에이전트는 상위 목표를 스스로 하위 작업으로 분해하고 순차적으로 해결해 나가는 데 강력한 강점을 지닙니다. 하지만 적절한 제어 장치가 없는 재귀적 실행 루프는 API 토큰과 개발 예산을 가장 빠르게 소진시키는 원인이 되기도 합니다. 에이전트가 논리적 순환에 빠지거나, 오류가 발생한 웹페이지 파싱을 반복하거나, 무한히 하위 작업을 파생시킬 경우 불과 몇 분 만에 한도 초과 오류를 마주하게 됩니다. Reworkd가 개발한 오픈소스 자율형 에이전트 플랫폼인 AgentGPT에서는 이러한 비용 폭주를 차단하기 위해 엄격한 실행 루프 한도(Loop limits) 설정과 다양한 형식의 작업 결과 내보내기(Task outputs export) 기능을 제공합니다.

에이전트를 배포하기 전 루프 횟수와 토큰 상한을 사전 구성하고, 실행 종료 즉시 구조화된 결과물을 추출하는 방법을 숙지하면 비용 예측성과 안전성을 모두 확보할 수 있습니다.

1. AgentGPT 재귀 루프의 토큰 소모 구조

루프 제한이 필수적인 이유를 이해하려면 AgentGPT의 내부 실행 사이클을 살펴볼 필요가 있습니다:

1. 목표 수신(Goal Ingestion): 사용자가 입력한 핵심 목표를 바탕으로 거대언어모델(GPT-3.5-Turbo 또는 GPT-4)을 호출하여 초기 하위 작업 목록을 생성합니다.
2. 작업 분석 및 실행(Task Execution): 대기열의 첫 번째 작업을 꺼내어 LLM 또는 외부 도구를 호출해 실행하고 중간 결과를 기록합니다.
3. 작업 생성 및 조정(Task Creation): 실행된 결과에 따라 목표 달성을 위해 추가 작업이 필요한지 평가하고 대기열을 갱신합니다.
4. 재귀 루프(Recursive Loop): 모든 작업이 끝나거나 강제 종료 조건에 도달할 때까지 2단계와 3단계를 끊임없이 반복합니다.

이러한 한 번의 순환 과정을 **실행 루프(Loop)**라고 부릅니다. 각 루프마다 1~2회 이상의 LLM API 호출이 발생하며, 누적되는 컨텍스트의 길이도 루프가 거듭될수록 증가합니다. 목표가 모호하거나 에이전트가 오답을 반복 생성하기 시작하면 토큰 소모량이 기하급수적으로 폭증합니다.

2. 사용자 인터페이스(UI)에서 실행 루프 제한 설정하기

AgentGPT 웹 인터페이스와 로컬 인스턴스의 설정 패널을 통해 손쉽게 실행 루프를 제한할 수 있습니다.

고급 설정(Advanced Settings) 접근

1. AgentGPT 웹 화면 좌측 사이드바의 Settings(⚙️ 설정) 아이콘을 클릭하거나 /settings 페이지로 이동합니다.
2. 계정 로그인(GitHub, Google, Discord) 상태이거나 자체 호스팅 인스턴스인지 확인합니다. 공개 호스팅 환경에서는 무분별한 리소스 낭비를 막기 위해 비로그인 방문자에게 Advanced Settings(고급 설정) 메뉴가 비활성화되어 있습니다.

루프 슬라이더 조정(customMaxLoops)

Advanced Settings 영역 내 Loop 항목을 확인합니다:

• 조정 범위: 1회부터 25회까지 1단위로 조정 가능.
• 기본 설정값: 무료 체험 환경은 기본 25회, 사용자 커스텀 API Key를 등록한 경우 기본 10회로 권장 설정됩니다.
• 동작 방식: 단일 실행 세션에서 수행 가능한 최대 작업 사이클 수를 결정합니다. 이 횟수에 도달하면 시스템은 다음 작업을 중단하고 콘솔에 안전 차단 메시지를 띄웁니다:

  The maximum number of loops have been reached, this agent is shutting down.
  

  (초기 버전에서는 "To save your wallet, and our infrastructure costs, this agent is shutting down."이라는 문구가 표시되었습니다.)

작업 유형별 권장 루프 예산

• 요약, 단순 질의응답, 단일 주제 개요 작성: 3 ~ 7 루프.
• 다단계 보고서 작성, 비교 분석, 단계별 기획: 8 ~ 12 루프.
• 다중 출처 심층 웹 조사 및 복합 워크플로: 15 ~ 25 루프.

추가적인 비용 제어 옵션

루프 슬라이더와 함께 다음 항목들을 함께 구성하면 안전망이 더욱 강화됩니다:

• 토큰 한도(Tokens / maxTokens): 슬라이더(200 ~ 모델 최대 한도, 예: 4,000)를 조정하여 단일 API 호출당 최대 생성 길이를 제한합니다.
• 모델 선택(Model): 빠른 실험 단계에서는 단가가 저렴한 gpt-3.5-turbo를 기본으로 두고, 고난도 추론이 필요할 때만 gpt-4로 전환합니다.
• 온도 조절(Temperature): 0.0 또는 0.2로 낮춰 출력의 결정론적 성향을 높이면, 환각으로 인한 무의미한 헛돌기 루프를 효과적으로 줄일 수 있습니다.
• 개인 API 키(API Key): 본인의 OpenAI API 키를 입력한 뒤 Test 버튼으로 유효성을 검증하여 사용량을 직접 모니터링합니다.

3. 실시간 실행 생명주기 제어

사전 설정 외에도 에이전트 실행 창 상단에는 실시간으로 상태를 제어할 수 있는 버튼 모음(AgentControls)이 제공됩니다:

• 일시 중지(Pause / FaPause): 현재 수행 중인 하위 작업이 끝나면 에이전트의 다음 루프 진입을 멈춥니다. 생성된 하위 작업들이 의도대로 설정되었는지 중간 점검할 수 있습니다.
• 재개(Play / FaPlay): 작업 방향이 정상적인 것을 확인한 후 다음 대기 작업을 이어갈 수 있습니다.
• 강제 정지(Stop / FaStop): 에이전트가 엉뚱한 결론을 내거나 무한 루프 징후가 보일 때 빨간색 정지 버튼을 누르면 즉시 상태가 stopped로 전환되며 진행 중인 스트리밍 연결이 차단되어 추가 과금을 막습니다.

4. 자체 호스팅 백엔드 및 환경 변수 구성

Docker를 활용해 사내 환경이나 로컬 머신에서 AgentGPT를 운영하는 개발팀은 백엔드 및 소스코드 차원에서 안전 한도를 강제할 수 있습니다.

백엔드 환경 변수 차단

AgentGPT의 Python 백엔드(reworkd_platform)는 Pydantic 기반 설정 체계를 따르며, 전역 루프 한도를 환경 변수로 직접 설정할 수 있습니다:

# .env 파일에 작성
REWORKD_PLATFORM_MAX_LOOPS=20

이는 platform/reworkd_platform/settings.py의 settings.max_loops에 반영되어 클라이언트 요청 여부와 무관하게 서버 단에서 강제 차단벽으로 기능합니다.

프론트엔드 슬라이더 한도 변경

필요에 따라 슬라이더의 범위를 확장하거나 축소하고자 할 때는 Next.js 프론트엔드 소스코드를 직접 수정합니다:

• next/src/pages/settings.tsx 파일 내 속성 수정:

  <Input
    label={`${t("LOOP")}`}
    value={settings.customMaxLoops}
    name="loop"
    type="range"
    onChange={(e) => updateSettings("customMaxLoops", parseFloat(e.target.value))}
    attributes={{
      min: 1,
      max: 50, // 필요에 따라 확장
      step: 1,
    }}
    helpText={t("CONTROL_THE_MAXIMUM_NUM_OF_LOOPS")}
    icon={<FaSyncAlt />}
    disabled={disableAdvancedSettings}
  />
  

• next/src/utils/constants.ts 파일 내 기본값 조정:

  export const DEFAULT_MAX_LOOPS_FREE = 25 as const;
  export const DEFAULT_MAX_LOOPS_CUSTOM_API_KEY = 10 as const;
  

5. 작업 결과물 및 실행 로그 내보내기

에이전트가 작업을 마쳤거나 루프 한도로 인해 멈췄을 때, 작업 데이터를 즉시 내보내면 브라우저를 새로고침하더라도 결과를 안전하게 보존할 수 있으며 동일 작업을 다시 실행하는 낭비를 방지할 수 있습니다.

콘솔 창 기본 내보내기 메뉴

작업 콘솔 창의 우측 상단 헤더(MacWindowHeader)에서 Export(내보내기) 아이콘(CgExport)을 클릭하면 3가지 추출 옵션이 제공됩니다:

1. 클립보드 복사(Copy):
   • 현재 대화 영역의 전체 텍스트(innerText)를 추출합니다.
   • 입력된 목표, 생성된 모든 하위 작업, 각 단계의 실행 결과 텍스트가 클립보드로 복사되어 즉시 다른 문서나 메신저에 붙여넣을 수 있습니다.
2. 이미지 저장(Image / PNG):
   • html-to-image 라이브러리를 통해 스크롤 가능한 전체 콘솔 화면(element.scrollHeight)을 렌더링합니다.
   • agent-gpt-output.png 파일로 다운로드되며, 실행 타임라인을 시각적으로 보존하거나 보고서에 첨부하기에 용이합니다.
3. 구조화된 PDF(PDF):
   • @react-pdf/renderer와 PDFButton 컴포넌트를 기반으로 메시지 데이터를 항목별로 재구성합니다:
     • Agent Goal: 최종 목표.
     • Adding Task: 생성된 하위 작업 목록.
     • Executing: 실제 작업 수행 결과 및 수집된 본문.
   • 가독성이 뛰어난 my-document.pdf로 바로 내려받아 인쇄나 문서 보관용으로 활용할 수 있습니다.

플랫폼 대량 내보내기 및 데이터베이스 조회

• 대량 내보내기(Bulk Exports): Reworkd 플랫폼 서비스에서는 app.reworkd.ai/exports를 통해 전체 작업 그룹이나 배치 작업의 결과물을 CSV나 JSON 파일로 한 번에 다운로드할 수 있습니다.
• DB 직접 연동: 자체 호스팅 환경에서는 실행 세션 데이터가 MySQL/SQLite 데이터베이스의 agent_run 및 agent_task 테이블에 지속 기록됩니다. FastAPI의 /api/agent/execute 엔드포인트를 통하거나 SQL 쿼리를 실행하여 결과 데이터를 사내 데이터 파이프라인으로 곧바로 연계할 수 있습니다.

6. 비용 최적화 핵심 요약

1. 배포 전 루프 점검 필수: 목표를 입력하기 전 항상 Settings에서 Loop 값을 확인하고, 초기 테스트는 5~10회 수준으로 제한하십시오.
2. 이중 비용 방어벽 적용: Loop 횟수와 maxTokens(1250~2000 수준)를 함께 제한하여 호출 횟수와 응답 길이를 동시에 묶어두십시오.
3. 초기 하위 작업 모니터링: 첫 2~3개 작업이 진행되는 동안 에이전트의 방향성을 지켜보고, 이상 징후가 보이면 Pause나 Stop으로 신속히 개입하십시오.
4. 중단 즉시 결과 백업: 루프 한도에 도달해 멈춘 즉시 Copy나 PDF 기능을 통해 결과물을 로컬에 저장해 두십시오.

(참고: 오픈소스 reworkd/AgentGPT 리포지토리는 2026년 1월부로 읽기 전용 아카이브 처리되었습니다. 포크 버전을 독자적으로 운영하는 개발팀은 위와 같은 아키텍처 제어 파라미터를 유지하여 안정적인 운영 환경을 구축하시기 바랍니다.)

참고 자료

• AgentGPT
• GitHub - reworkd/AgentGPT: 🤖 Assemble, configure, and deploy autonomous AI Agents in your browser.
• AgentGPT Settings Page Component
• AgentGPT Console Window Header Component
• AgentGPT PDF Export Implementation
• AgentGPT Backend Platform Settings
• AgentGPT Bulk Exports Documentation