autogen_ext.agents.web_surfer — AutoGen: MultimodalWebSurfer 완벽 정리 🚀

1. 개요 및 역할

MultimodalWebSurfer는 웹을 탐색하고, 웹페이지를 방문하며, 다양한 상호작용(검색, 클릭, 스크롤, 폼 입력 등)을 수행할 수 있는 멀티모달 에이전트입니다.
이 에이전트는 크로미움(Chromium) 브라우저를 자동으로 실행하고, Playwright를 통해 브라우저를 제어합니다.
주로 GPT-4o와 같은 멀티모달 모델과 함께 사용되며, 웹페이지의 스크린샷, 상호작용 가능한 요소 추출, 텍스트 요약, 질문 응답 등 다양한 기능을 제공합니다.

"웹 브라우저에 접근할 수 있는 유용한 어시스턴트입니다. 웹 검색, 페이지 열기, 콘텐츠와의 상호작용(링크 클릭, 스크롤, 폼 입력 등)을 요청할 수 있습니다. 전체 페이지 요약이나 페이지 내용을 바탕으로 한 질문에도 답할 수 있습니다."
— 기본 설명(DEFAULT_DESCRIPTION) 중

2. 설치 방법

pip install "autogen-ext[web-surfer]"

Playwright와 관련된 추가 패키지가 자동으로 설치됩니다.

3. 주요 동작 흐름 (시간순)

1) 에이전트 생성 및 초기화

MultimodalWebSurfer 객체를 생성할 때, 다양한 파라미터(아래 참고)를 설정할 수 있습니다.
실제 브라우저는 최초 호출 시에만 실행되며, 이후에는 재사용됩니다.

"브라우저는 에이전트가 처음 호출될 때 실행되며, 이후 호출에서는 재사용됩니다."

주요 파라미터

name: 에이전트 이름
model_client: 멀티모달 모델 클라이언트 (예: GPT-4o)
downloads_folder: 다운로드 파일 저장 폴더
description: 에이전트 설명
debug_dir: 디버그 정보 저장 폴더
headless: 브라우저를 화면 없이 실행할지 여부 (기본값: True)
start_page: 시작 페이지 (기본값: https://www.bing.com/)
animate_actions: 동작 애니메이션 여부
to_save_screenshots: 스크린샷 저장 여부
use_ocr: OCR 사용 여부
browser_channel: 브라우저 채널
browser_data_dir: 브라우저 데이터 디렉토리
to_resize_viewport: 뷰포트 크기 조정 여부

2) 메시지 처리 및 웹 상호작용

on_messages() / on_messages_stream() 호출 시 동작

브라우저 초기화 및 페이지 로드
- 최초 호출이면 _lazy_init()을 통해 브라우저와 페이지를 초기화합니다.
- 브라우저는 close()가 호출될 때까지 계속 열려 있습니다.
응답 생성
- _generate_reply()가 호출되어 최종 응답을 생성합니다.
스크린샷 및 상호작용 요소 추출
- 페이지의 스크린샷을 찍고, 클릭/입력 등 상호작용 가능한 요소를 추출합니다.
- 이 요소들에 바운딩 박스를 표시한 스크린샷도 준비합니다.
모델 호출 및 응답 처리
- SOM(Screen-Of-Mark) 스크린샷, 메시지 히스토리, 사용 가능한 도구 목록을 모델에 전달합니다.
- 모델이 문자열을 반환하면, 해당 문자열이 최종 응답이 됩니다.
- 모델이 도구 호출 목록을 반환하면, _execute_tool()을 통해 PlaywrightController로 실제 동작을 수행합니다.
- 최종적으로 스크린샷, 페이지 메타데이터, 수행한 동작 설명, 웹페이지의 텍스트가 포함된 응답을 반환합니다.
오류 처리
- 동작 중 오류가 발생하면, 에러 메시지를 최종 응답으로 반환합니다.

"에이전트는 페이지의 스크린샷을 찍고, 상호작용 가능한 요소를 추출한 뒤, 바운딩 박스가 표시된 스크린샷을 준비합니다."

3) 상태 관리 및 리셋

에이전트는 상태(stateful)를 유지합니다.
즉, 이전 메시지 히스토리를 기억하고, 다음 응답에 반영합니다.
**on_reset()**을 호출하면, 에이전트가 초기 상태로 리셋됩니다.

"에이전트는 상태를 유지하므로, 이 메서드에 전달되는 메시지는 이전 호출 이후의 새 메시지여야 합니다."

4) 브라우저 종료

더 이상 에이전트가 필요 없을 때는 **close()**를 호출해 브라우저와 페이지를 종료해야 합니다.

4. PlaywrightController: 웹 상호작용 도우미

PlaywrightController는 Playwright를 통해 실제 웹페이지에서 다양한 동작을 수행하는 헬퍼 클래스입니다.

주요 기능 및 메서드

add_cursor_box: 특정 요소에 빨간색 커서 박스 추가
back: 이전 페이지로 이동
click_id: 특정 요소 클릭
fill_id: 입력란에 값 입력
get_focused_rect_id: 현재 포커스된 요소의 ID 반환
get_interactive_rects: 상호작용 가능한 영역 정보 추출
get_page_markdown: 페이지의 마크다운 내용 추출 (아직 미구현)
get_page_metadata: 페이지 메타데이터 추출
get_visible_text: 현재 뷰포트의 텍스트 추출
get_visual_viewport: 뷰포트 정보 추출
get_webpage_text: 전체 페이지 텍스트 추출 (라인 수 지정 가능)
gradual_cursor_animation: 커서 이동 애니메이션
hover_id: 특정 요소에 마우스 오버
on_new_page: 새 페이지에서의 동작 처리
page_down / page_up: 페이지 스크롤
remove_cursor_box: 커서 박스 제거
scroll_id: 특정 요소 스크롤
sleep: 지정 시간만큼 대기
visit_page: 특정 URL로 이동

"특정 요소에 빨간색 커서 박스를 추가합니다."
"페이지를 한 뷰포트 높이만큼 아래로 스크롤합니다."
"지정한 URL로 이동합니다."

5. 예제 코드

아래는 실제로 MultimodalWebSurfer를 사용하는 예시입니다.

import asyncio
from autogen_agentchat.ui import Console
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.agents.web_surfer import MultimodalWebSurfer

async def main() -> None:
    # 에이전트 정의
    web_surfer_agent = MultimodalWebSurfer(
        name="MultimodalWebSurfer",
        model_client=OpenAIChatCompletionClient(model="gpt-4o-2024-08-06"),
    )
    # 팀 정의
    agent_team = RoundRobinGroupChat([web_surfer_agent], max_turns=3)
    # 팀 실행 및 콘솔에 메시지 스트리밍
    stream = agent_team.run_stream(task="GitHub에서 AutoGen readme로 이동하세요.")
    await Console(stream)
    # 브라우저 종료
    await web_surfer_agent.close()

asyncio.run(main())

6. 중요 상수 및 설정값

DEFAULT_DESCRIPTION:

"웹 브라우저에 접근할 수 있는 유용한 어시스턴트입니다. ... (생략)"

DEFAULT_START_PAGE:
https://www.bing.com/
VIEWPORT_WIDTH / HEIGHT:
기본 뷰포트 크기 (1440 x 900)
MLM_WIDTH / HEIGHT:
멀티모달 모델용 스크린샷 크기 (1224 x 765)
SCREENSHOT_TOKENS:
스크린샷 토큰 수 (1105)

7. 윈도우 환경 주의사항

윈도우에서 사용할 경우, 이벤트 루프 정책을 아래와 같이 설정해야 합니다.

import sys
import asyncio
if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())

8. 보안 및 주의사항

에이전트가 인간을 위해 설계된 디지털 세계와 상호작용하므로,
때때로 위험한 행동(예: 쿠키 동의, 인간에게 도움 요청 등)을 시도할 수 있습니다.
항상 에이전트를 모니터링하고, 통제된 환경에서 실행해야 합니다.
프롬프트 인젝션 공격에 취약할 수 있으니, 웹페이지의 입력값에 주의하세요.

"MultimodalWebSurfer를 사용할 때는, 인간을 위해 설계된 디지털 세계와 상호작용한다는 점을 유념하세요. 에이전트가 때때로 위험한 행동을 시도할 수 있으니, 항상 모니터링하고 통제된 환경에서 실행해야 합니다."

9. 구성 및 확장

_from_config(config):
설정 객체로부터 새 인스턴스 생성
_to_config():
현재 인스턴스의 설정을 객체로 반환

10. 핵심 키워드 요약

멀티모달 에이전트
웹 브라우저 자동화
Playwright
GPT-4o
스크린샷/상호작용 요소 추출
상태 유지(Stateful)
도구 호출(Function/Tool Calling)
보안 주의(프롬프트 인젝션 등)

11. 마무리

MultimodalWebSurfer는 웹 자동화와 AI의 결합을 통해,
웹페이지를 실제로 탐색하고 상호작용할 수 있는 강력한 도구입니다.
실제 사용 시에는 보안과 모니터링에 각별히 신경 써야 하며,
다양한 파라미터와 메서드를 통해 원하는 대로 커스터마이징할 수 있습니다.
궁금한 점이 있다면 언제든 질문해 주세요! 😊