AgentGPT에서 실시간 웹 검색과 자율적인 정보 검색(Autonomous Information Retrieval)을 활성화하려면, 에이전트의 추론 루프에 외부 검색 프로바이더를 연동해야 합니다. 대형 언어 모델(LLM)은 학습 데이터 마감 시점의 한계로 인해 최신 기술 동향, 제품 가격표, 벤치마크 결과를 다룰 때 사실과 다른 내용을 생성(환각 현상)하기 쉽습니다. AgentGPT는 자율적 작업 분해와 도구 호출(Tool Calling) 메커니즘을 결합하여, Google Serper API를 통해 실시간 웹 검색 스니펫을 수집하고 이를 기반으로 후속 연구 작업을 재귀적으로 실행합니다.
호스팅된 웹 인터페이스를 이용하든 Docker를 통해 자체 호스팅 환경을 구축하든, 올바른 API 자격 증명 확보, 환경 변수 구성, 에이전트의 검색 작업 실행 원리에 대한 이해가 필수적입니다.
AgentGPT 자율 정보 검색의 동작 원리
Reworkd AI가 개발한 오픈소스 자율 에이전트 플랫폼인 AgentGPT는 Next.js, FastAPI, LangChain을 기반으로 구축되었으며, **계획(Plan) → 실행(Execute) → 관찰(Observe) → 반복(Iterate)**으로 이어지는 연속 루프를 통해 작동합니다.
[ 조사 목표 입력 ]
│
▼
[ 작업 계획기 (LLM) ] ──► [ 대기열 검색 작업 생성 ]
│
▼
[ AgentGPT 백엔드 도구 라우터 ]
│
▼
[ Serper API (Google 검색) ]
│
▼
[ 최종 보고서 / 추가 작업 ] ◄── [ 검색 스니펫 및 제목 파싱 ]
사용자가 거시적인 연구 목표를 입력하면 시스템은 다음과 같은 절차로 검색을 진행합니다.
- 자율 작업 분해: 핵심 플래너 모델이 목표를 분석하여 순차적인 하위 작업(경쟁 제품 조사, 최신 사양 문서 조회, 성능 벤치마크 수집 등)으로 나눕니다.
- 도구 선택: 최신 외부 데이터가 필요한 작업에 도달하면, 에이전트 런타임은 내부 파라미터에만 의존하지 않고 백엔드 검색 도구(
reworkd_platform/web/api/agent/tools/search.py)를 호출합니다. - API 요청 전송: 백엔드가 Serper API 엔드포인트(
https://google.serper.dev/search)로 비동기 HTTP POST 요청을 보내어 정제된 검색어를 전달합니다. - 결과 처리 및 요약: 에이전트는 검색 결과, 웹페이지 제목, URL, 텍스트 요약(스니펫)이 포함된 구조화된 JSON 응답을 받습니다. LLM은 이를 검토하여 하위 목표의 달성 여부를 평가하고 주요 사실을 실행 로그에 기록합니다.
- 작업 대기열 재귀 업데이트: 검색 결과에서 추가 조사가 필요한 새로운 의문점이나 공백이 발견되면, 에이전트는 대기열에 새로운 하위 작업을 동적으로 추가하며 최종 결론에 도달할 때까지 작업을 이어갑니다.
필수 자격 증명 및 사전 요구사항
AgentGPT에서 웹 검색 기능을 활성화하려면 다음 두 가지 서비스의 API 키가 필요합니다.
| 구성 요소 | 제공 업체 | AgentGPT 내 역할 | 발급 경로 |
|---|---|---|---|
| 추론 LLM | OpenAI | 목표 계획 수립, 작업 분해, 검색 결과 종합 요약 (gpt-4 또는 gpt-3.5-turbo) | OpenAI Platform API 키 관리 메뉴 |
| 검색 엔진 API | Serper (serper.dev) | 백엔드 검색 도구에 실시간 Google 검색 결과 및 텍스트 스니펫 제공 | Serper 개발자 포털 (신규 가입 시 2,500회 무료 쿼리 제공) |
로컬 LLM 참고사항: 사내 환경에서 Ollama, vLLM, LM Studio 등을 통해 자체 오픈소스 모델을 구동하는 경우 AgentGPT의 LLM 엔드포인트를 로컬 주소로 지정할 수 있습니다. 다만 외부 웹 검색 도구는 인터넷 망에 연결된 유효한 Serper API 키가 반드시 필요합니다.
방법 1: 호스팅 웹 버전 AgentGPT에서 검색 설정하기
웹 브라우저를 통해 agentgpt.reworkd.ai를 직접 사용하는 경우:
- 설정 창 열기: 웹 화면 왼쪽 메뉴 표시줄에서 톱니바퀴 모양의 Settings 아이콘을 클릭합니다.
- 주 모델 키 입력: Model / API Keys 탭으로 이동하여
OPENAI_API_KEY를 입력합니다. 유효한 추론 키가 없으면 작업 분해와 결과 요약이 불가능합니다. - 검색 API 키 등록: 통합 설정 또는 API Keys 영역에서 Serper API Key 입력란을 찾아
serper.dev에서 발급받은 키를 붙여넣습니다. - 설정 저장: Save를 클릭합니다. 호스팅 버전은 사용자의 API 자격 증명을 브라우저의 로컬 스토리지(
localStorage)에만 저장하며 외부 중앙 서버로 전송하지 않습니다. - 테스트 에이전트 실행: 명확한 실시간 조사 목표(예: "웹을 검색하여 2026년에 발표된 주요 오픈소스 AI 에이전트 프레임워크 3종의 핵심 기술 아키텍처와 특징을 비교 분석해줘")를 입력하고 실행 패널에서 검색 호출이 원활히 동작하는지 확인합니다.
방법 2: Docker 기반 자체 호스팅 설정 (개발자 권장)
장기적 연구 파이프라인 운영, 호출 한도 관리, 자체 도구 모듈 확장이 필요한 개발자에게는 Docker Compose를 통한 로컬 배포가 가장 적합합니다.
1단계: 공식 저장소 복제
로컬 환경에 소스 코드를 내려받습니다.
git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT
2단계: 환경 변수 구성
AgentGPT는 환경 변수 파일을 통해 Next.js 프론트엔드와 FastAPI 백엔드(reworkd_platform)에 설정값을 주입합니다.
템플릿 파일을 복사하여 환경 변수 파일을 만듭니다.
cp .env.example .env
텍스트 편집기로 .env 파일을 열고 다음 핵심 설정을 작성합니다.
# 기본 언어 모델 API 키
OPENAI_API_KEY=sk-your-openai-api-key-here
# 자율 웹 탐색용 검색 API 키 (Serper)
SERPER_API_KEY=your_serper_dev_api_key_here
# 선택 사항: 이미지 생성 작업용 Replicate 토큰
REPLICATE_API_TOKEN=
# 에이전트 1회 실행당 최대 루프 제한 (무한 반복 및 비용 방지)
MAX_LOOPS=10
설정 검증:
SERPER_API_KEY에 올바른 토큰이 입력되어 있는지, 백엔드 호출 주소가https://google.serper.dev/search로 지정되어 있는지 확인하세요. 키가 누락되었거나 주소가 틀리면 실행 중 HTTP403 Forbidden에러가 발생합니다.
3단계: 시작 스크립트 또는 Docker Compose 실행
자동 설치 스크립트를 실행합니다.
# Linux / macOS
./setup.sh
# Windows
./setup.bat
또는 Docker Compose 명령어를 직접 입력하여 빌드 및 구동할 수 있습니다.
docker compose up --build
프론트엔드 서비스(기본 포트 3000)와 백엔드 API 서비스(기본 포트 8000)가 정상 실행 상태에 도달할 때까지 대기합니다.
4단계: 검색 도구 로드 확인
FastAPI 기동 로그에서 platform/reworkd_platform/web/api/agent/tools/search.py 파일이 로드되었는지 확인합니다. SERPER_API_KEY가 정의되어 있으면 시스템이 Search 도구를 사용 가능한 도구 목록에 등록합니다.
자율 정보 검색을 위한 목표 프롬프트 작성 지침
자율 에이전트는 목표 지시문의 명확성에 따라 성능 편차가 큽니다. 검색 작업을 수행할 때는 다음 원칙을 권장합니다.
- 조사 범위와 산출물 형식 구체화: *"양자 컴퓨터에 대해 알려줘"*와 같은 모호한 문장 대신, 명확한 기준과 형식을 지정합니다.
목표: 엔터프라이즈 벡터 데이터베이스에 대한 시장 조사를 자율 수행하라. 최신 벤치마크 데이터를 검색하고, 상위 3개 공급 업체를 선정하여 가격 정책과 기술적 장단점을 비교한 뒤 인용한 원문 URL을 함께 제시하라. - 루프 한도(
MAX_LOOPS) 설정: 에이전트가 지나치게 많은 하위 검색을 재귀 생성하지 않도록 5~10회 수준으로 루프를 제한합니다. - 출처 명시 요구: 최종 종합 보고서에 검색된 웹사이트 주소를 함께 표기하도록 프롬프트에 명시하여 교차 검증을 용이하게 합니다.
기술적 제약 사항 및 고려점
AgentGPT를 이용해 실무 연구를 진행할 때 고려해야 할 아키텍처적 한계점은 다음과 같습니다.
- 스니펫 기반 검색과 전체 페이지 스크래핑의 차이: AgentGPT의 기본 검색 도구는 Serper가 제공하는 요약 스니펫, 제목, 메타데이터를 중심으로 추론합니다. 헤드리스 브라우저(Playwright, Puppeteer 등)가 기본 내장되어 있지 않아 복잡한 동적 JavaScript 렌더링이나 긴 PDF 문서의 내부 전문을 읽어오지는 못합니다. 심층 페이지 분석이 필요한 경우
tools/내에 맞춤형 스크래퍼를 구현하거나 외부 크롤러와 연계해야 합니다. - 컨텍스트 창 크기와 토큰 비용: 반복 검색을 통해 수집된 다량의 텍스트는 모델의 컨텍스트 창을 빠르게 채웁니다. 컨텍스트 길이가 짧은 모델을 사용할 경우 초기 정보가 누락되거나 API 사용료가 크게 증가할 수 있습니다.
- 저장소 유지 관리 상태: 공식
reworkd/AgentGPT오픈소스 저장소는 2026년 1월에 공식적으로 아카이브되었습니다. 기존 코드는 로컬 실험과 기본 구현용으로 유용하지만, 브라우저 상호작용이나 복잡한 다단계 자율 워크플로를 요구하는 최신 프로덕션 환경에서는 CrewAI, LangGraph, browser-use 등의 최신 프레임워크와 Serper API를 결합하는 방식이 보편적으로 활용됩니다.