AgentGPT에서 웹 검색 API 및 브라우징 플러그인을 설정하여 자율 웹 리서치를 구현하는 방법

자율형 AI 에이전트(Autonomous Agent)의 가장 큰 가치는 복잡한 목표를 스스로 세부 작업 단위로 분해하고, 이를 반복적으로 실행하며 결과를 학습하는 역량에 있습니다. 하지만 기반 거대언어모델(LLM)의 고정된 사전 학습 지식에만 머물러 있다면, 최신 기술 문서나 실시간 가격 체계, 시장 동향을 조사할 수 없습니다. 오픈소스 브라우저 기반 에이전트 플랫폼인 AgentGPT에서 실효성 있는 자율 웹 조사를 구현하려면 검색 API 연동 및 웹 페이지 본문 분석 도구 구성이 필수적입니다.

인터넷 연동 도구가 구성되지 않은 AgentGPT는 모델 내부 기억에만 의존하므로 최신 정보에 대해 환각(Hallucination)을 일으키기 쉽습니다. 반면 검색 API 키와 브라우징 도구를 적절히 결합하면, 에이전트는 검색어를 생성하고 실시간 Google 검색 결과를 가져와 외부 웹 문서를 검토한 후 구조화된 연구 보고서를 자동으로 작성합니다. 본 가이드에서는 클라우드 웹 환경 및 Docker 로컬 환경에서의 기본 Serper API 설정법, 백엔드 확장을 통한 웹 페이지 본문 스크래핑 도구 구현, 그리고 작업 이탈(Task Drift)을 방지하는 프롬프트 작성법을 체계적으로 살펴봅니다.

1. AgentGPT의 실시간 웹 연동 아키텍처

AgentGPT는 "생각(Think) - 계획(Plan) - 실행(Act) - 평가(Evaluate)"의 재귀 루프로 구동됩니다. 사용자가 "2026년 기준 주요 벡터 데이터베이스의 가격 정책 및 요금 모델 비교 조사"와 같은 목표를 부여하면, 에이전트는 메모리상에서 하위 작업을 순차적으로 도출합니다.

외부 지식이 필요한 작업을 수행할 때 AgentGPT는 Python 백엔드(platform/reworkd_platform/web/api/agent/tools/)의 도구 라우터를 호출합니다. 이 구조는 내부적으로 LangChain의 도구 추상화 인터페이스를 활용합니다.

왜 기본 검색 엔진으로 Serper API를 사용하는가

헤드리스 브라우저를 띄워 검색 엔진 HTML을 직접 파싱하는 방식은 CAPTCHA 차단과 DOM 변경에 매우 취약합니다. 따라서 AgentGPT는 고속 Google 검색 API인 Serper(serper.dev)를 기본 표준으로 내장하고 있습니다. Serper의 장점은 다음과 같습니다:

• 정제된 JSON 반환: 광고나 불필요한 태그 없이 오가닉 검색 스니펫, 페이지 제목, 원본 URL, 지식 그래프 정보만 정제하여 반환합니다.
• 토큰 소모 대폭 절감: 복잡한 HTML 대신 핵심 텍스트 요약만 LLM에 전달하므로 컨텍스트 윈도우 낭비를 막습니다.
• 안정적인 차단 방지: API 서비스 자체에서 프록시 관리와 안티봇 우회를 처리하므로 에이전트의 반복적인 질의에도 중단되지 않습니다.

2. 단계별 설정 가이드: 클라우드 웹과 로컬 Docker 환경

웹 검색 기능을 활성화하는 방법은 공식 호스팅 웹 인터페이스를 사용하는지, 로컬 서버에 Docker로 자체 호스팅하는지에 따라 나뉩니다.

방법 A: 클라우드 웹 인터페이스 (agentgpt.reworkd.ai)

1. 필요한 API 키 발급:
   • Serper에 가입하여 무료 API 키를 발급받습니다(최초 가입 시 2,500회 무료 쿼리 제공).
   • OpenAI 계정에서 유효한 API 키를 준비합니다.
2. 설정 메뉴 진입: 좌측 사이드바 하단의 설정(Settings) 아이콘을 클릭합니다.
3. 모델 및 키 정보 입력:
   • Model 항목에서 GPT-4 또는 gpt-4o를 선택하는 것을 권장합니다. 하위 모델에 비해 외부 도구 호출 시점과 검색 결과 종합 능력이 월등합니다.
   • OpenAI API Key를 입력합니다.
   • Serper API Key 입력란에 발급받은 Serper 키를 붙여넣습니다.
4. 루프 제한(Loop Limit) 설정: 실행 단계를 5~15회 사이로 지정합니다. 이는 충분한 조사 깊이를 보장하면서도 불필요한 무한 루프로 인한 요금 낭비를 방지합니다.

방법 B: Docker 로컬 자체 호스팅

개발자가 자체 인프라나 로컬 환경에서 직접 소스 코드를 구동할 경우:

1. 저장소 복제:

   git clone https://github.com/reworkd/AgentGPT.git
   cd AgentGPT
   

2. 환경 변수 파일 생성: 루트 디렉터리의 예제 파일을 복사합니다:

   cp .env.example .env
   

3. 키 및 실행 변수 입력: .env 파일을 편집하여 아래 핵심 환경 변수를 지정합니다:

   # LLM 설정
   OPENAI_API_KEY=sk-your-openai-api-key-here
   
   # 웹 검색 연동 키
   SERPER_API_KEY=your-serper-api-key-here
   
   # 에이전트 최대 실행 횟수
   NEXT_PUBLIC_MAX_LOOPS=15
   REWORKD_PLATFORM_MAX_LOOPS=15
   

4. 컨테이너 빌드 및 실행: 제공된 설치 스크립트를 실행하거나 Docker Compose로 서비스를 시작합니다:

   ./setup.sh
   # 또는 수동 실행:
   docker compose up --build
   

   실행 후 브라우저에서 http://localhost:3000에 접속합니다. 포트 8000에서 구동되는 FastAPI 백엔드가 .env의 SERPER_API_KEY를 자동으로 감지하여 검색 도구(search.py)에 주입합니다.

3. 심층 기능 확장: 웹 브라우징 및 전문 스크래핑 도구 연동

기본 설정에서 Serper가 반환하는 검색 스니펫은 대략 150~200자 내외입니다. API 코드 예제 확인, 기술 규격서 분석, 상세 계약 조건 검토 등 심층 조사가 필요한 경우에는 스니펫만으로 충분하지 않습니다.

검색 스니펫과 전문 브라우징의 역할 차이

• 검색(Search): 어떤 웹페이지에 원하는 답이 있을지 후보 URL을 신속하게 탐색.
• 브라우징/스크래핑(Browsing/Scraping): 특정 대상 URL에 직접 접근하여 문서의 전체 본문을 추출 및 독해.

커스텀 브라우징 도구 구현 원리

개발자는 platform/reworkd_platform/web/api/agent/tools/ 디렉터리에 새로운 스크래핑 도구를 추가할 수 있습니다. 완성도 높은 브라우징 도구는 다음 요소를 갖추어야 합니다:

1. 본문 추출 및 노이즈 제거: BeautifulSoup이나 trafilatura를 사용하여 내비게이션 바, 푸터, 스크립트 태그를 배제하고 알맹이 본문만 수집.
2. Markdown 변환: 헤더 계층 구조와 표 형식을 보존하여 모델이 읽기 쉬운 Markdown으로 재구성.
3. 토큰 예산 제어: 추출 텍스트를 일정 길이(예: 3,000~4,000자)로 절단(Truncation)하여 모델의 컨텍스트 윈도우 초과를 방지.

Python으로 구현한 브라우징 도구 예시:

from pydantic import BaseModel, Field
import httpx
from bs4 import BeautifulSoup

class BrowseInput(BaseModel):
    url: str = Field(..., description="본문을 읽고 분석할 대상 웹페이지의 HTTPS URL")

async def browse_page(url: str) -> str:
    headers = {"User-Agent": "AgentGPT-ResearchBot/1.0"}
    async with httpx.AsyncClient(timeout=10.0, follow_redirects=True) as client:
        response = await client.get(url, headers=headers)
        if response.status_code != 200:
            return f"오류: 페이지 로드 실패 (HTTP 상태 코드 {response.status_code})"
            
        soup = BeautifulSoup(response.text, "html.parser")
        
        # 불필요한 태그 제거
        for element in soup(["script", "style", "nav", "footer", "header", "aside"]):
            element.decompose()
            
        clean_text = soup.get_text(separator="\n", strip=True)
        # 토큰 효율성을 위해 4000자로 제한
        return clean_text[:4000]

이 도구를 search.py와 함께 백엔드에 등록하면, "Serper로 URL 검색 -> 브라우징 도구로 상세 본문 독해 -> 최종 요약 리포트 작성"의 고도화된 연구 파이프라인이 완성됩니다.

4. 구조화된 프롬프트 작성: 작업 이탈(Task Drift) 차단

자율 에이전트 운용에서 흔히 겪는 문제는 **작업 이탈(Task Drift)**입니다. 에이전트가 지엽적인 꼬리물기식 검색어를 생성하거나 유사한 정보를 끊임없이 반복 검색하는 현상입니다. 명확한 제약 조건을 명시한 초기 프롬프트 작성이 필수적입니다.

성공적인 조사 프롬프트 작성 지침

• 조사 대상 명시: 구체적인 소프트웨어 제품명, 버전, 조사 항목을 정확히 표기.
• 시간 범위 한정: "2026년 최신 기준"과 같이 시점 기준을 엄격하게 전달.
• 출처 우선순위 지정: 공식 문서, GitHub 릴리스 노트 등 신뢰할 수 있는 출처를 우선 참조하도록 유도.
• 출력 서식 강제: 비교 표 및 개조식 요약 형태로 마크다운 작성을 지시.

실무 프롬프트 예시

에이전트 이름: 인프라연구원
목표: Pinecone, Qdrant Cloud, Weaviate Cloud의 벡터 데이터베이스 요금 모델을 심층 비교 조사하십시오.
1. 웹 검색을 활용하여 2026년 현재 각 서비스의 무료 티어 한도, Serverless 읽기/쓰기 단가, 월 기본 클러스터 요금을 조사하십시오.
2. 각 플랫폼의 저장 용량 및 쿼리 연산 단위(Read/Write Units) 과금 산정 방식을 확인하십시오.
3. 세 서비스에 대한 조사가 끝나면 새로운 하위 작업 생성을 즉시 멈추고, 핵심 수치를 마크다운 비교표로 정리한 뒤 공식 참고 링크를 첨부하십시오.

이러한 지침을 받으면 AgentGPT는 다음과 같이 체계적인 순서로 작업을 수행합니다:

• 작업 1: Pinecone의 2026년 Serverless 요금 체계 및 쿼리 유닛 단가 검색.
• 작업 2: Qdrant Cloud의 관리형 클러스터 노드 비용 및 스토리지 요율 검색.
• 작업 3: Weaviate Cloud의 인스턴스 사양별 비용 및 SLA 지원 등급 검색.
• 작업 4: 수집된 데이터를 바탕으로 최종 마크다운 비교표 산출 후 종료.

5. 트러블슈팅 및 오픈소스 생태계 현황

프로젝트 유지보수 현황 안내

Reworkd 공식 개발팀은 2026년 1월 reworkd/AgentGPT 깃허브 저장소를 읽기 전용(Archived) 상태로 전환하였으며, 엔터프라이즈 대상의 대규모 웹 데이터 추출 사업으로 역량을 집중하고 있습니다. 오픈소스 코드에 대한 일상적인 기능 추가는 중단되었으나, 브라우저 기반 자율 에이전트의 모범 아키텍처로서의 가치는 여전히 유효합니다. 프로덕션 환경에서 실시간 연구 에이전트를 구축하려는 팀은 이 설계 패턴을 LangGraph나 CrewAI 같은 최신 에이전트 프레임워크로 이식하고, Firecrawl 등의 전문 크롤링 API를 결합하는 방식을 적극 고려해야 합니다.

참고 자료

• GitHub - reworkd/AgentGPT: 🤖 Assemble, configure, and deploy autonomous AI Agents in your browser. · GitHub
• Serper - The World's Fastest and Cheapest Google Search API
• LangChain Python integrations - Docs by LangChain