Bright Data를 AG2(AutoGen) 다중 에이전트 AI 아키텍처에 통합하기

이 가이드에서는 다음을 확인하실 수 있습니다:

• AG2의 정의와 단일 에이전트 및 다중 에이전트 시스템 개발 지원 방식, Bright Data 연동 시 확장성 이점.
• 이 통합을 시작하기 위한 필수 조건.
• 맞춤형 도구를 통해 Bright Data로 AG2 다중 에이전트 아키텍처를 구동하는 방법.
• AG2를 Bright Data의 Web MCP에 연결하는 방법.

자, 시작해 보겠습니다!

AG2(구 AutoGen) 소개

AG2는 복잡한 작업을 해결하기 위해 자율적으로 협력할 수 있는 AI 에이전트 및 다중 에이전트 시스템을 구축하기 위한 오픈소스 AgentOS 프레임워크입니다. 단일 에이전트 워크플로우를 구성하고, 여러 전문 에이전트를 조정하며, 외부 도구를 모듈식 생산 환경에 바로 적용 가능한 파이프라인에 통합할 수 있습니다.

AG2(구 AutoGen)는 Microsoft AutoGen 라이브러리의 진화판입니다. 기존 아키텍처와 하위 호환성을 유지하면서 다중 에이전트 워크플로, 도구 통합, 인간 개입형 AI를 지원합니다. Python으로 작성되었으며 GitHub에서 4,000개 이상의 스타를 보유하고 있습니다.

(Bright Data와 AutoGen 통합 가이드가 필요하신 경우, 전용 블로그 게시물을 참조하세요.)

AG2는 에이전트 기반 AI 프로젝트를 실험 단계에서 생산 환경으로 전환하는 데 필요한 유연성과 고급 오케스트레이션 패턴을 제공합니다.

핵심 기능으로는 다중 에이전트 대화 패턴, 인간 개입 지원, 도구 통합, 구조화된 워크플로 관리 등이 있습니다. 궁극적인 목표는 최소한의 오버헤드로 정교한 AI 시스템을 구축하도록 돕는 것입니다.

이러한 뛰어난 기능에도 불구하고 AG2 에이전트는 여전히 핵심 LLM 한계에 직면합니다: 훈련 데이터의 정적 지식과 실시간 웹 정보에 대한 기본적인 접근 불가!

Bright Data와 같은 웹 데이터 공급자와 AG2를 통합하면 이러한 모든 문제를 해결할 수 있습니다. AG2 에이전트를 Bright Data의 웹 스크래핑, 검색, 브라우저 자동화 API에 연결하면 실시간 구조화된 웹 데이터를 활용하여 에이전트의 지능, 자율성 및 실용성을 향상시킬 수 있습니다.

필수 조건

이 가이드를 따라하려면 다음이 필요합니다:

• 로컬 머신에설치된 Python 3.10 이상
• Web Unlocker API, SERP API 및 API 키가 구성된 Bright Data 계정. (본 튜토리얼에서 필요한 모든 설정을 안내합니다.)
• OpenAI API 키 (또는 AG2에서 지원하는 다른 LLM의 API 키).

Bright Data 제품 및 서비스에 대한 기본적인 이해와 AG2 도구 시스템 작동 방식에 대한 기초 지식이 있으면 도움이 됩니다.

Bright Data를 AG2 다중 에이전트 워크플로에 통합하는 방법

이 단계별 섹션에서는 Bright Data 서비스를 기반으로 한 다중 에이전트 AG2 워크플로를 구축합니다. 특히 웹 데이터 수집 전용 에이전트가 커스텀 AG2 도구 기능을 통해 Bright Data의 Web Unlocker 및 SERP API에 접근합니다.

이 다중 에이전트 시스템은 새로운 유형의 햄버거 홍보를 지원하기 위해 Twitch와 같은 플랫폼에서 식품 산업의 주요 인플루언서를 식별합니다. 이 예시는 AG2가 수동 작업 없이 데이터 수집을 자동화하고, 구조화된 비즈니스 보고서를 생성하며, 정보에 기반한 의사 결정을 가능하게 하는 방법을 보여줍니다.

구현 방법을 확인하세요!

1단계: AG2 프로젝트 생성

터미널을 열고 AG2 프로젝트용 새 폴더를 생성합니다. 예를 들어 ag2-bright-data-agent로 명명합니다:

mkdir ag2-bright-data-agent

ag2-bright-data-agent/ 폴더에는 Bright Data 기능과 통합되는 AG2 에이전트를 구현하고 조정하는 Python 코드가 포함됩니다.

다음으로 프로젝트 디렉토리로 이동하여 가상 환경을 생성합니다:

cd ag2-bright-data-agent
python -m venv .venv

프로젝트 루트에 agent. py라는 새 파일을 추가합니다. 이제 프로젝트 구조는 다음과 같아야 합니다:

ag2-bright-data-agent/
├── .venv/
└── agent.py # <----

agent.py 파일에는 AG2 에이전트 정의와 오케스트레이션 로직이 포함됩니다.

Visual Studio Code(Python 확장 기능 포함 ) 또는 PyCharm Community Edition과 같은 선호하는 Python IDE로 프로젝트 폴더를 엽니다.

이제 방금 생성한 가상 환경을 활성화하세요. Linux 또는 macOS에서는 다음 명령을 실행합니다:

source .venv/bin/activate

Windows에서는 다음과 같이 실행하세요:

.venv/Scripts/activate

가상 환경이 활성화된 상태에서 필요한 PyPI 종속성을 설치합니다:

pip install ag2[openai] requests python-dotenv

이 애플리케이션은 다음 라이브러리에 의존합니다:

• ag2[openai]: OpenAI 모델 기반의 다중 에이전트 AI 워크플로우 구축 및 오케스트레이션을 위한 라이브러리.
• requests: 커스텀 도구를 통해 Bright Data 서비스에 HTTP 요청을 수행하기 위한 라이브러리입니다.
• python-dotenv: .env 파일에 정의된 환경 변수에서 필요한 비밀 정보를 불러오기 위해 사용됩니다.

잘하셨습니다! 이제 AG2를 활용한 다중 에이전트 AI 개발을 위한 사용 준비 완료된 Python 환경을 갖추셨습니다.

2단계: LLM 통합 구성

다음 단계에서 구축할 AG2 에이전트에는 LLM이 제공하는 ‘두뇌’가 필요합니다. 각 에이전트는 자체 LLM 구성을 사용할 수 있지만, 간편함을 위해 모든 에이전트를 동일한 OpenAI 모델에 연결하겠습니다.

AG2에는 전용 구성 파일에서 LLM 설정을 불러오는 내장 메커니즘이 포함되어 있습니다. 이를 위해 agent.py에 다음 코드를 추가하세요:

from autogen import LLMConfig

# OpenAI 구성 목록 파일에서 LLM 설정 불러오기
llm_config = LLMConfig.from_json(path="OAI_CONFIG_LIST")

이 코드는 OAI_CONFIG_LIST.json이라는 파일에서 LLM 구성을 로드합니다. 프로젝트 루트 디렉터리에 이 파일을 생성하세요:

ag2-bright-data-agent/
├── .venv/
├── OAI_CONFIG_LIST.json # <----
└── agent.py

이제 OAI_CONFIG_LIST.json에 다음 내용을 입력하세요:

[
  {
    "model": "gpt-5-mini",
    "api_key": "<YOUR_OPENAI_API_KEY>"
  }
]

<YOUR_OPENAI_API_KEY> 자리 표시자를 실제 OpenAI API 키로 교체하세요. 이 구성은 GPT-5 Mini 모델을 사용하여 AG2 에이전트를 구동하지만, 필요 시 다른 지원되는 OpenAI 모델로 교체할 수 있습니다.

llm_config 변수는 에이전트와 그룹 채팅 오케스트레이터에 전달됩니다. 이를 통해 에이전트들은 설정된 LLM을 활용하여 추론하고, 소통하며, 작업을 실행할 수 있습니다. 멋지네요!

3단계: 환경 변수 읽기 관리

이제 AG2 에이전트가 OpenAI에 연결할 수 있지만, Bright Data라는 다른 타사 서비스에도 접근할 수 있어야 합니다. OpenAI와 마찬가지로 Bright Data도 외부 API 키를 사용하여 요청을 인증합니다.

보안 위험을 방지하려면 코드에 API 키를 직접 하드코딩해서는 안 됩니다. 대신 환경 변수에서 불러오는 것이 모범 사례입니다. 바로 이 때문에 앞서 python-dotenv를 설치한 것입니다.

먼저 agent.py에서 python-dotenv를 임포트하세요. load_dotenv() 함수를 사용해 .env 파일에서 환경 변수를 불러오도록 합니다:

from dotenv import load_dotenv
import os

# .env 파일에서 환경 변수 불러오기
load_dotenv()

다음으로 프로젝트 루트 디렉터리에 .env 파일을 추가하세요. 내용은 다음과 같아야 합니다:

ag2-bright-data-agent/
├── .venv/
├── OAI_CONFIG_LIST.json
├── .env # <----
└── agent.py

.env 파일에 비밀값을 추가한 후, 코드 내에서 os.getenv()를 사용하여 해당 값에 접근할 수 있습니다:

ENV_VALUE = os.getenv("ENV_NAME")

멋지네요! 이제 스크립트가 환경 변수에서 제3자 통합 비밀값을 안전하게 불러올 수 있습니다.

4단계: Bright Data 서비스 설정

소개에서 예상했듯이, 웹 데이터 에이전트는 웹 검색 및 웹 페이지 콘텐츠 검색을 처리하기 위해 Bright Data의 SERP API와 Web Unlocker API에 연결됩니다. 이 두 서비스는 에이전트에게 에이전트형 RAG 스타일 데이터 검색 계층에서 실시간 웹 데이터를 가져올 수 있는 기능을 제공합니다.

이 두 서비스와 상호작용하려면 나중에 두 개의 커스텀 AG2 도구를 정의해야 합니다. 그 전에 Bright Data 계정에서 모든 설정을 완료해야 합니다.

아직 계정이 없다면 Bright Data 계정을 생성하세요. 이미 계정이 있다면 로그인하여 대시보드로 이동합니다. 대시보드에서 “프록시 및 스크래핑” 페이지로 이동하여 프로필에 구성된 서비스를 나열한 “내 영역” 테이블을 확인하세요:

위와 같이 테이블에 Web Unlocker API 영역(이 경우 web_unlocker)과 SERP API 영역(이 경우 serp_api)이 이미 포함되어 있다면 준비가 완료된 것입니다. 이 두 영역은 사용자 정의 AG2 도구가 필요한 Bright Data 서비스를 호출하는 데 사용됩니다.

하나 이상의 존이 누락된 경우, 아래로 스크롤하여 “Unblocker API” 및 “SERP API” 카드를 찾아 각각에 대해 “존 생성”을 클릭하세요. 설정 마법사를 따라 두 존을 생성하십시오:

자세한 단계별 안내는 공식 문서를 참조하세요:

• SERP API 시작하기
• Bright Data 웹 언락커 API 빠른 시작 가이드

중요: 이후 설명에서는 존 이름을 각각 serp_api와 web_unlocker로 가정합니다.

존 설정이 완료되면 Bright Data API 키를 생성하세요. .env 파일의 환경 변수로 저장합니다:

BRIGHT_DATA_API_KEY="<YOUR_BRIGHT_DATA_API_KEY>"

그런 다음 아래와 같이 agent.py에서 불러옵니다:

BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

완벽합니다! 이제 사용자 정의 도구를 통해 AG2 에이전트를 Bright Data의 SERP API 및 Web Unlocker 서비스에 연결할 모든 구성 요소를 갖추셨습니다.

5단계: AG2 에이전트를 위한 Bright Data 도구 정의하기

AG2에서 도구는 에이전트가 작업을 수행하고 결정을 내리기 위해 호출할 수 있는 특수 기능을 제공합니다. 내부적으로 도구는 AG2가 구조화된 방식으로 에이전트에 노출하는 맞춤형 Python 함수에 불과합니다.

이 단계에서는 agent.py에 두 가지 도구 함수를 구현합니다:

• serp_api_tool(): Bright Data SERP API에 연결하여 Google 검색을 수행합니다.
• web_unlocker_api_tool(): Bright Data 웹 언락커 API에 연결하여 모든 안티봇 시스템을 우회하고 웹 페이지 콘텐츠를 가져옵니다.

두 도구 모두 문서에 기반하여 Bright Data에 인증된 POST 요청을 수행하기 위해 Requests Python HTTP 클라이언트를 사용합니다:

• Bright Data SERP API로 첫 요청 보내기
• Bright Data의 Web Unlocker API로 첫 요청 보내기

두 도구 함수를 정의하려면 agent.py에 다음 코드를 추가하세요:

from typing import Annotated
import requests
import urllib.parse

def serp_api_tool(
    query: Annotated[str, "Google 검색 쿼리"],)
 -> str:
    payload = {
        "zone": "serp_api",  # Bright Data SERP API 존 이름으로 대체
        "url": f"https://www.google.com/search?q={urllib.parse.quote_plus(query)}&brd_json=1",
        "format": "raw",
    }

    headers = {
        "Authorization": f"Bearer {BRIGHT_DATA_API_KEY}",
        "Content-Type": "application/json",
    }

    response = requests.post(
        "https://api.brightdata.com/request",
        json=payload,
        headers=headers,
    )
    response.raise_for_status()

    return response.text


def web_unlocker_api_tool(
    url_to_fetch: Annotated[str, "가져올 대상 페이지 URL"],
    data_format: Annotated[
        str | None,
        "출력 페이지 형식 (예: 'markdown', 생 HTML은 생략)"
    ] = "markdown",)
 -> str:
    payload = {
        "zone": "web_unlocker",  # Bright Data Web Unlocker 영역 이름으로 교체
        "url": url_to_fetch,
        "format": "raw",
        "data_format": data_format,
    }

    headers = {
        "Authorization": f"Bearer {BRIGHT_DATA_API_KEY}",
        "Content-Type": "application/json",
    }

    response = requests.post(
        "https://api.brightdata.com/request",
        json=payload,
        headers=headers
    )
    response.raise_for_status()

    return response.text

두 도구는 Bright Data API 키를 사용하여 요청을 인증하고 Bright Data API 엔드포인트로 POST 요청을 전송합니다:

• serp_api_tool() 은 brd_json=1 매개변수를 활성화하여 Google을 쿼리하고 구조화된 JSON 형식의 검색 결과를 가져옵니다.
• web_unlocker_api_tool() 은 모든 웹 페이지를 가져와 마크다운 (또는 원하는 경우 원시 HTML) 형식으로 콘텐츠를 반환합니다.

중요: JSON과 마크다운 모두 AI 에이전트에서 LLM(대규모 언어 모델)을 활용하기에 탁월한 형식입니다.

두 함수 모두 Python 타입과 Annotated를 사용하여 인수를 설명합니다. 타입은 이 함수들을 적절한 AG2 도구로 변환하는 데 필요하며, 주석 설명은 에이전트 내부에서 도구를 호출할 때 LLM이 각 인수를 어떻게 채워야 하는지 이해하는 데 도움이 됩니다.

훌륭합니다! 이제 AG2 애플리케이션에 두 개의 Bright Data 도구가 포함되어 AI 에이전트에서 구성 및 활용할 준비가 되었습니다.

6단계: AG2 에이전트 구현

도구 설정이 완료되었으므로, 이제 소개 부분에서 설명한 AI 에이전트 구조를 구축할 차례입니다. 이 설정은 세 가지 상호 보완적인 에이전트로 구성됩니다:

1. user_proxy: 실행 계층 역할을 하며, 도구 호출을 안전하게 실행하고 인간 개입 없이 워크플로를 조정합니다. 이는 UserProxyAgent의 인스턴스로, 사용자를 대리하는 특수 AG2 에이전트로서 코드를 실행하고 필요 시 다른 에이전트에 피드백을 제공합니다.
2. web_data_agent: 웹 데이터 탐색 및 수집을 담당합니다. 이 에이전트는 Bright Data SERP API를 사용하여 웹을 검색하고 Web Unlocker API를 통해 페이지 콘텐츠를 가져옵니다. ConversableAgent로서 다른 에이전트 및 인간과 소통하고, 정보를 처리하며, 시스템 메시지에 정의된 지시를 따르는 등의 작업을 수행할 수 있습니다.
3. reporting_agent: 수집된 데이터를 분석하여 의사 결정권자를 위한 구조화된 비즈니스용 마크다운 보고서로 변환합니다.

이 에이전트들은 함께 Twitch 스트리머 식별 및 타깃 제품 홍보를 위해 설계된 완전 자율형 다중 에이전트 파이프라인을 구성합니다.

agent.py에서 다음 코드로 세 에이전트를 모두 지정합니다:

from autogen import (
    UserProxyAgent,
    ConversableAgent,)


# 도구 호출을 실행하고 인간 개입 없이 워크플로를 조정합니다
user_proxy = UserProxyAgent(
    name="user_proxy",
    code_execution_config=False,
    human_input_mode="NEVER",
    llm_config=llm_config,
)

# 웹 데이터 검색 및 수집 담당
web_data_agent = ConversableAgent(
    name="web_data_agent",
    code_execution_config=False,
    llm_config=llm_config,
    system_message=(
        """
        당신은 웹 데이터 수집 에이전트입니다.
        Bright Data SERP API 도구를 사용하여 웹을 검색하고
        Web Unlocker API 도구를 사용하여 페이지 콘텐츠를 검색합니다.
        """
    ),
)

# 수집된 데이터를 분석하고 구조화된 보고서를 생성합니다
reporting_agent = ConversableAgent(
    name="reporting_agent",
    code_execution_config=False,
    system_message=(
        """
        당신은 마케팅 분석가입니다.
        당신은 의사 결정권자를 위한 구조화되고 비즈니스에 바로 활용 가능한
        Markdown 보고서를 생성합니다.
        """
    ),
    llm_config=llm_config,
    # "보고서" 단어가 나타나면 대화를 자동 종료
    is_termination_msg=lambda msg: "report" in (msg.get("content", "") or "").lower()
)

위 코드에서 다음 사항을 유의하십시오:

• AG2 에이전트는 메시지 내 포함된코드 (예: 코드 블록)를실행하고 결과를 다음 에이전트에 전달할수 있습니다. 본 설정에서는 보안상 code_execution_config=False로 코드 실행이 비활성화됩니다.
• 모든 에이전트는 2단계에서 로드된 llm_config로 구동됩니다.
• reporting_agent에는 메시지에 “report” 단어가 포함되면 최종 출력이 생성되었음을 알리는 신호로 워크플로를 자동 종료하는is_termination_msg 함수가 포함되어 있습니다.

다음으로, 웹 데이터 수집을 활성화하기 위해 Bright Data 도구를 web_data_agent 에 등록할 것입니다!

7단계: AG2 Bright Data 도구 등록

Bright Data 함수를 도구로 등록하고 register_function()을 통해 web_data_agent에 할당합니다. AG2 아키텍처 요구사항에 따라 user_proxy 에이전트가 해당 도구의 실행자로 작동합니다:

from autogen import register_function

# 웹 데이터 에이전트를 위한 SERP 검색 도구 등록
register_function(
    serp_api_tool,
    caller=web_data_agent,
    executor=user_proxy,
    description="Bright Data의 SERP API를 사용하여 Google 검색을 수행하고 원시 결과를 반환합니다."
)

# 보호된 페이지 가져오기용 Web Unlocker 도구 등록
register_function(
    web_unlocker_api_tool,
    caller=web_data_agent,
    executor=user_proxy,
    description="Bright Data의 Web Unlocker API를 사용하여 일반적인 봇 방지 기능을 우회하며 웹 페이지를 가져옵니다.",
)

각 함수에는 LLM이 그 목적을 이해하고 호출 시점을 알 수 있도록 간결한 설명이 포함되어 있음을 유의하십시오.

이러한 도구들이 등록됨에 따라, web_data_agent 는 이제 웹 검색 및 웹 페이지 접근을 계획할 수 있으며, user_proxy 가 실행을 담당합니다.

이제 AG2 다중 에이전트 파이프라인은 Bright Data의 API를 활용하여 자율적인 데이터 탐색 및 스크래핑을 완벽하게 수행할 수 있습니다. 미션 완료!

단계 #8: AG2 다중 에이전트 오케스트레이션 로직 도입

AG2는 여러 에이전트를 오케스트레이션하고 관리하는 여러 방법을 지원합니다. 이 예제에서는 그룹 채팅 패턴을 살펴보겠습니다.

AG2 그룹 채팅의 핵심은 모든 에이전트가 동일한 컨텍스트를 공유하며 단일 대화 스레드에 기여한다는 점입니다. 이 접근 방식은 본 파이프라인과 같이 여러 에이전트 간 협업이 필요한 작업에 이상적입니다.

그룹 채팅 내에서 에이전트 조정은 GroupChatManager가 담당합니다. 다음에 행동할 에이전트를 선택하는 다양한 전략을 지원합니다. 여기서는 매니저의 LLM을 활용해 다음에 발언할 에이전트를 결정하는 기본 자동 전략을 구성할 것입니다.

다중 에이전트 오케스트레이션을 위해 아래와 같이 모든 요소를 결합합니다:

from autogen import (
    GroupChat,
    GroupChatManager,)


# 다중 에이전트 그룹 채팅 정의
groupchat = GroupChat(
    agents=[user_proxy, web_data_agent, reporting_agent],
    speaker_selection_method="auto",
    messages=[],
    max_round=20
)

# 에이전트 상호작용 조정 관리자
manager = GroupChatManager(
    name="group_manager",
    groupchat=groupchat,
    llm_config=llm_config
)

참고: 워크플로는 reporting_agent가 is_termination_msg 로직을 트리거하는 메시지를 생성하거나, 에이전트 간 20회 ( max_round 인자)의 상호작용이 완료된 시점 중 먼저 도달하는 경우 종료됩니다.

시작합니다! 에이전트 정의와 오케스트레이션 로직이 완료되었습니다. 마지막 단계는 워크플로를 시작하고 결과를 내보내는 것입니다.

단계 #9: 에이전틱 워크플로 실행 및 결과 내보내기

Twitch 스트리머 인플루언서 검색 작업을 상세히 기술하고, 실행을 위해 user_proxy 에이전트에 메시지로 전달합니다:

prompt_message = """
시나리오:
---------
음식 & 음료 브랜드가 새로운 유형의 햄버거를 홍보하고자 합니다.

목표:
- TwitchMetrics에서 음식 & 음료 카테고리 페이지 검색
- 검색 결과 페이지(SERP)에서 가져온 TwitchMetrics 카테고리 페이지 콘텐츠를 가져오고 상위 5개 스트리머 선정
- 각 스트리머의 TwitchMetrics 프로필 페이지 방문 및 관련 정보 수집
- 다음을 포함한 구조화된 마크다운 보고서 생성:
  - 채널명
  - 예상 도달 범위
  - 콘텐츠 초점
  - 시청자 적합성
  - 브랜드 홍보 실행 가능성
"""

# 다중 에이전트 워크플로 시작
user_proxy.initiate_chat(recipient=manager, message=prompt_message)

워크플로 완료 후 출력물(즉, 마크다운 보고서)을 디스크에 저장:

with open("report.md", "w", encoding="utf-8") as f:
    f.write(user_proxy.last_message()["content"])

대단합니다! AG2 + Bright Data 멀티 에이전트 워크플로가 이제 완전히 가동되어 Twitch 인플루언서 데이터를 수집, 분석, 보고할 준비가 되었습니다.

10단계: 모든 것을 통합하기

agent.py 파일의 최종 코드는 다음과 같습니다:

from autogen import (
    LLMConfig,
    UserProxyAgent,
    ConversableAgent,
    register_function,
    GroupChat,
    GroupChatManager,)

from dotenv import load_dotenv
import os
from typing import Annotated
import requests
import urllib.parse

# OpenAI 구성 목록 파일에서 LLM 구성 불러오기
llm_config = LLMConfig.from_json(path="OAI_CONFIG_LIST")

# .env 파일에서 환경 변수 불러오기
load_dotenv()

# 환경 변수에서 Bright Data API 키 가져오기
BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

# Bright Data 도구 구현을 위한 함수 정의
def serp_api_tool(
    query: Annotated[str, "Google 검색어"],)
 -> str:
    payload = {
        "zone": "serp_api",  # Bright Data SERP API 존 이름으로 대체
        "url": f"https://www.google.com/search?q={urllib.parse.quote_plus(query)}&brd_json=1",
        "format": "raw",
    }

    headers = {
        "Authorization": f"Bearer {BRIGHT_DATA_API_KEY}",
        "Content-Type": "application/json",
    }

    response = requests.post(
        "https://api.brightdata.com/request",
        json=payload,
        headers=headers,
    )
    response.raise_for_status()

    return response.text


def web_unlocker_api_tool(
    url_to_fetch: Annotated[str, "가져올 대상 페이지 URL"],
    data_format: Annotated[
        str | None,
        "출력 페이지 형식 (예: 'markdown', 생 HTML은 생략)"
    ] = "markdown",)
 -> str:
    payload = {
        "zone": "web_unlocker",  # Bright Data Web Unlocker 영역 이름으로 대체
        "url": url_to_fetch,
        "format": "raw",
        "data_format": data_format,
    }

    headers = {
        "Authorization": f"Bearer {BRIGHT_DATA_API_KEY}",
        "Content-Type": "application/json",
    }

    response = requests.post(
        "https://api.brightdata.com/request",
        json=payload,
        headers=headers
    )
    response.raise_for_status()

    return response.text

# 도구 호출을 실행하고 인간 개입 없이 워크플로를 조정합니다
user_proxy = UserProxyAgent(
    name="user_proxy",
    code_execution_config=False,
    human_input_mode="NEVER",
    llm_config=llm_config,
)

# 웹 데이터 검색 및 추출 담당
web_data_agent = ConversableAgent(
    name="web_data_agent",
    code_execution_config=False,
    llm_config=llm_config,
    system_message=(
        """
        당신은 웹 데이터 추출 에이전트입니다.
        Bright Data SERP API 도구를 사용하여 웹을 검색하고
        Web Unlocker API 도구를 사용하여 페이지 콘텐츠를 검색합니다.
        """
    ),
)

# 수집된 데이터를 분석하고 구조화된 보고서를 생성합니다
reporting_agent = ConversableAgent(
    name="reporting_agent",
    code_execution_config=False,
    system_message=(
        """
        당신은 마케팅 분석가입니다.
        당신은 의사 결정권자를 위한 구조화되고 비즈니스에 바로 활용 가능한
        Markdown 보고서를 생성합니다.
        """
    ),
    llm_config=llm_config,
    # "보고서" 단어가 나타나면 대화를 자동 종료
    is_termination_msg=lambda msg: "report" in (msg.get("content", "") or "").lower()
)

# 웹 데이터 에이전트용 SERP 검색 도구 등록
register_function(
    serp_api_tool,
    caller=web_data_agent,
    executor=user_proxy,
    description="Bright Data의 SERP API를 사용하여 Google 검색을 수행하고 원시 결과를 반환합니다."
)

# 보호된 페이지 가져오기용 웹 언락커 도구 등록
register_function(
    web_unlocker_api_tool,
    caller=web_data_agent,
    executor=user_proxy,
    description="Bright Data의 웹 언락커 API를 사용하여 일반적인 봇 방지 보호 기능을 우회하고 웹 페이지를 가져옵니다.",
)

# 다중 에이전트 그룹 채팅 정의
groupchat = GroupChat(
    agents=[user_proxy, web_data_agent, reporting_agent],
    speaker_selection_method="auto",
    messages=[],
    max_round=20
)

# 에이전트 상호작용 조정 담당 관리자
manager = GroupChatManager(
    name="group_manager",
    groupchat=groupchat,
    llm_config=llm_config)


prompt_message = """
시나리오:
---------
음식 & 음료 브랜드가 새로운 유형의 햄버거를 홍보하고자 합니다.

목표:
- TwitchMetrics에서 '음식 & 음료' 카테고리 페이지 검색
- 검색 결과 페이지(SERP)에서 가져온 TwitchMetrics 카테고리 페이지 콘텐츠를 확인하고 상위 5개 스트리머 선정
- 각 스트리머의 TwitchMetrics 프로필 페이지 방문 및 관련 정보 수집
- 다음을 포함한 구조화된 마크다운 보고서 생성:
  - 채널명
  - 예상 도달 범위
  - 콘텐츠 초점
  - 시청자 적합성
  - 브랜드 홍보 실행 가능성
"""

# 다중 에이전트 워크플로 시작
user_proxy.initiate_chat(recipient=manager, message=prompt_message)

# 최종 보고서를 마크다운 파일로 저장
with open("report.md", "w", encoding="utf-8") as f:
    f.write(user_proxy.last_message()["content"])

강력한 AG2 API 덕분에, 약 170줄의 코드로 복잡하고 기업용으로 준비된 Bright Data 기반 다중 에이전트 워크플로를 구축했습니다!

11단계: 다중 에이전트 시스템 테스트

터미널에서 AG2 에이전트 애플리케이션이 정상 작동하는지 확인하세요:

python agent.py

예상 출력 결과는 다음과 같습니다:

자세한 내용은 다중 에이전트 워크플로가 단계별로 진행되는 방식을 확인하세요:

1. web_data_agent는 필요한 TwitchMetrics “Food & Drink” 카테고리 페이지를 찾기 위해 serp_api_tool을 호출해야 함을 판단합니다.
2. 사용자 프록시 에이전트를 통해 이 도구는 여러 검색 쿼리를 실행합니다.
3. 올바른 TwitchMetrics 카테고리 페이지가 확인되면, web_unlocker_api_tool을 호출하여 Markdown 형식의 콘텐츠를 스크래핑합니다.
4. 마크다운 출력에서 “음식 및 음료” 카테고리의 상위 5개 인플루언서 TwitchMetrics 프로필의 URL을 추출합니다.
5. 웹_언락커_API_툴을 다시 호출하여 각 프로필 페이지의 마크다운 형식 콘텐츠를 가져옵니다.
6. 수집된 모든 데이터는 reporting_agent로 전달되어 분석 후 최종 보고서를 생성합니다.

이 최종 보고서는 코드에 명시된 대로 report.md로 디스크에 저장됩니다:

VS Code의 마크다운 미리보기 기능을 사용하여 보고서의 상세함과 정보량을 확인해 보세요:

원본 데이터의 출처가 궁금하다면 TwitchMetrics의 ‘음식 & 음료’ 스트림 카테고리 페이지를 확인하세요:

보고서의 Twitch 스트리머 정보는 상위 5개 프로필 각각에 대한 TwitchMetrics 전용 프로필 페이지와 일치합니다:

이 모든 정보는 다중 에이전트 시스템이 자동으로 수집한 것으로, AG2의 성능과 Bright Data와의 통합을 입증합니다.

이제 다양한 입력 프롬프트로 자유롭게 실험해 보세요. Bright Data 덕분에 AG2 멀티 에이전트 워크플로우는 다양한 실제 업무를 처리할 수 있습니다.

자, 이제 Bright Data로 강화된 AG2 워크플로의 역량을 직접 확인하셨습니다.

AG2를 Bright Data Web MCP에 연결하는 단계별 가이드

Bright Data를 AG2에 통합하는 또 다른 방법은 Bright Data Web MCP 서버를 이용하는 것입니다.

Web MCP를 사용하면 Bright Data의 웹 자동화 및 데이터 수집 플랫폼을 기반으로 구축된 60개 이상의 도구를 이용할 수 있습니다. 무료 계정에서도 두 가지 강력한 도구를 사용할 수 있습니다:

도구	설명
search_engine	Google, Bing 또는 Yandex 결과를 JSON 또는 Markdown 형식으로 가져옵니다.
scrape_as_markdown	모든 웹페이지를 깨끗한 마크다운으로 스크랩하면서 봇 방지 조치를 우회합니다.

Web MCP의 Pro 모드는 기능을 한 단계 더 발전시킵니다. 이 프리미엄 옵션은 Amazon, LinkedIn, Instagram, Reddit, YouTube, TikTok, Google Maps 등 주요 플랫폼의 구조화된 데이터 추출을 가능하게 합니다. 또한 고급 브라우저 자동화를 위한 도구도 추가됩니다.

참고: 프로젝트 설정은 이전 장의 1단계를 참조하세요.

다음으로 AG2 내에서 Bright Data의 Web MCP를 사용하는 방법을 살펴보겠습니다!

필수 조건

이 튜토리얼 섹션을 따라하려면 로컬에 Node.js가 설치되어 있어야 합니다. 이는 Web MCP를 실행하는 데 필수적입니다.

또한 AG2용 MCP 패키지를 설치해야 합니다:

pip install ag2[mcp]

이를 통해 AG2가 MCP 클라이언트로 작동할 수 있습니다.

1단계: Bright Data의 Web MCP 시작하기

AG2를 Bright Data의 Web MCP에 연결하기 전에, 로컬 머신에서 MCP 서버를 실행할 수 있는지 확인하세요. 이는 Web MCP 서버에 로컬로 연결하는 방법을 보여드리기 때문에 중요합니다.

참고: 웹 MCP는 스트리밍 가능한 HTTP를 통한 원격 서버로도 제공되며, 무제한 확장성 덕분에 기업용 사용 사례에 더 적합합니다.

먼저 Bright Data 계정이 있는지 확인하세요. 이미 계정이 있다면 로그인하기만 하면 됩니다. 빠른 설정을 위해 대시보드의 “MCP” 섹션에 있는 지침을 따르세요:

추가 안내가 필요하면 아래 단계를 참조하세요.

Bright Data API 키를 생성하세요. 로컬 Web MCP 인스턴스 인증에 곧 사용할 것이므로 안전한 곳에 보관하십시오.

다음으로 @brightdata/mcp 패키지를 사용하여 컴퓨터에 Web MCP를 전역 설치하세요:

npm install -g @brightdata/mcp

다음 명령을 실행하여 MCP 서버를 시작하세요:

API_TOKEN="<YOUR_BRIGHT_DATA_API>" npx -y @brightdata/mcp

또는 PowerShell에서 동일하게 실행:

$Env:API_TOKEN="<YOUR_BRIGHT_DATA_API>"; npx -y @brightdata/mcp

<YOUR_BRIGHT_DATA_API> 를 귀하의 Bright Data API 토큰으로 대체하십시오. 이 명령어들은 필요한 API_TOKEN 환경 변수를 설정하고 로컬에서 웹 MCP 서버를 실행합니다.

성공하면 다음과 유사한 출력이 표시됩니다:

기본적으로 Web MCP는 첫 실행 시 Bright Data 계정에 두 개의 영역을 생성합니다:

• mcp_unlocker: 웹 언로커용 영역.
• mcp_browser: 브라우저 API용 영역.

이 두 영역은 Web MCP에서 제공하는 60개 이상의 도구를 구동합니다.

Bright Data 대시보드의 “프록시 및 스크래핑 인프라”를 방문하여 영역이 생성되었는지 확인할 수 있습니다:

Web MCP 무료 계층에서는 search_engine 및 scrape_as_markdown 도구(및 해당 배치 버전)만 사용할 수 있습니다.

모든 도구를 사용하려면 PRO_MODE="true" 환경 변수를 설정하여 Pro 모드를 활성화하세요:

API_TOKEN="<YOUR_BRIGHT_DATA_API>" PRO_MODE="true" npx -y @brightdata/mcp

또는 Windows에서:

$Env:API_TOKEN="<YOUR_BRIGHT_DATA_API>"; $Env:PRO_MODE="true"; npx -y @brightdata/mcp

프로 모드는 60개 이상의 모든 도구를 사용할 수 있게 하지만, 무료 계정에는 포함되지 않으며 추가 요금이 발생할 수 있습니다.

완료! 이제 Web MCP 서버가 로컬에서 실행되는 것을 확인했습니다. 다음 단계는 AG2를 구성하여 서버를 로컬에서 시작하고 연결하는 것이므로, 당분간 MCP 프로세스를 중지하세요.

단계 #2: AG2 내 웹 MCP 통합

AG2 MCP 클라이언트를 사용하여 STDIO를 통해 로컬 Web MCP 인스턴스에 연결하고 사용 가능한 도구를 가져옵니다:

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from autogen.mcp import create_toolkit

# 로컬 Web MCP 인스턴스에 연결하는 방법
server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@brightdata/mcp"],
    env={
        "API_TOKEN": BRIGHT_DATA_API_KEY,
        "PRO_MODE": "true" # 선택 사항
    },)


async with stdio_client(server_params) as (read, write), ClientSession(read, write) as session:
    # MCP 연결 세션 생성 및 도구 가져오기
    await session.initialize()
    web_mcp_toolkit = await create_toolkit(session, use_mcp_resources=False)

StdioServerParameters 객체는 이전에 실행한 npx 명령어를 반영하며, 자격 증명 및 설정을 위한 환경 변수를 포함합니다:

• API_TOKEN: 필수. Bright Data API 키로 설정하세요.
• PRO_MODE: 선택 사항. 무료 티어(search_engine 및 scrape_as_markdown 및 해당 배치 버전만 해당)를 유지하려면 제거하세요.

세션은 Web MCP에 연결하고 create_toolkit을 사용하여 AG2 MCP 툴킷을 생성하는 데 사용됩니다.

참고: GitHub 이슈에서 강조된 바와 같이, mcp.shared.exceptions.McpError: Method not found 오류를 방지하려면 use_mcp_resources=False 옵션이 필수입니다.

생성된 web_mcp_toolkit 객체에는 모든 Web MCP 도구가 포함됩니다. 다음으로 확인하세요:

for tool in web_mcp_toolkit.tools:
    print(tool.name)
    print(tool.description)
    print("---n")

출력 결과는 다음과 같습니다:

설정된 티어에 따라 60개 이상의 모든 웹 MCP 도구(Pro 모드) 또는 무료 티어 도구만 사용할 수 있습니다.

훌륭합니다! 이제 AG2에서 웹 MCP 연결이 완전히 작동합니다.

3단계: 에이전트에 Web MCP 도구 연결하기

AG2에서 Web MCP 통합을 테스트하는 가장 간단한 방법은 LLM을 사용하여 작업을 신속하게 해결하도록 설계된 ConversableAgent의 하위 클래스인 AssistantAgent를 이용하는 것입니다. 먼저 에이전트를 정의하고 Web MCP 툴킷을 등록하세요:

from autogen import AssistantAgent

# 웹 데이터 검색 및 추출이 가능한 에이전트 정의
assistant_agent = AssistantAgent(
    name="assistant",
    code_execution_config=False,
    llm_config=llm_config,
    system_message="""
    웹 MCP가 제공하는 모든 도구에 접근할 수 있습니다. 포함 항목:
    - 웹 검색
    - 웹 스크래핑 및 페이지 가져오기
    - 웹 데이터 피드
    - 브라우저 기반 사용자 시뮬레이션

    필요할 때 이 도구들을 사용하세요.
    """)

# 에이전트에 웹 MCP 도구 등록
web_mcp_toolkit.register_for_llm(assistant_agent)

등록 후 a_run() 함수를 사용하여 에이전트를 실행하고 사용할 도구를 직접 지정할 수 있습니다. 예를 들어, Amazon 웹 스크래핑 작업에서 에이전트를 테스트하는 방법은 다음과 같습니다:

prompt = """
다음 아마존 제품에서 데이터를 추출하고 주요 정보로 간략한 요약 생성:

"""

# Web MCP 확장 에이전트를 비동기적으로 실행
result = await assistant_agent.a_run(
        message=prompt,
        tools=web_mcp_toolkit.tools,
        user_input=False,)

await result.process()

중요: 이 코드는 통합을 보여주기 위한 데모일 뿐임을 유념하세요. 모든 웹 MCP 도구 덕분에 에이전트는 다양한 웹 플랫폼과 데이터 소스에서 훨씬 더 복잡한 다단계 작업을 처리할 수 있습니다.

4단계: 최종 코드 + 실행

AG2 + Bright Data Web MCP 통합을 위한 최종 코드는 다음과 같습니다:

import asyncio
from autogen import (
    LLMConfig,
    AssistantAgent,)

from dotenv import load_dotenv
import os
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from autogen.mcp import create_toolkit

# .env 파일에서 환경 변수 로드
load_dotenv()

# 환경 변수에서 Bright Data API 키 가져오기
BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

# 모든 웹 MCP 도구를 포함하는 MCP 툴킷 정의
async def launch_mcp_agent():
    # OpenAI 구성 목록 파일에서 LLM 구성 로드
    llm_config = LLMConfig.from_json(path="OAI_CONFIG_LIST")

    # 로컬 웹 MCP 인스턴스에 연결하는 명령어
    server_params = StdioServerParameters(
        command="npx",
        args=["-y", "@brightdata/mcp"],
        env={
            "API_TOKEN": BRIGHT_DATA_API_KEY,
            "PRO_MODE": "true" # 선택 사항
        },
    )

    async with stdio_client(server_params) as (read, write), ClientSession(read, write) as session:
        # MCP 연결 세션 생성 및 도구 가져오기
        await session.initialize()
        web_mcp_toolkit = await create_toolkit(session, use_mcp_resources=False)

        # 웹 데이터 검색 및 가져오기 가능한 에이전트 정의
        assistant_agent = AssistantAgent(
            name="assistant",
            code_execution_config=False,
            llm_config=llm_config,
            system_message="""
            웹 MCP에서 제공하는 모든 도구를 사용할 수 있습니다:
            - 웹 검색
            - 웹 스크래핑 및 페이지 가져오기
            - 웹 데이터 피드
            - 브라우저 기반 사용자 시뮬레이션

            필요할 때 이 도구들을 사용하세요.
            """
        )
        # 에이전트에 웹 MCP 도구 등록
        web_mcp_toolkit.register_for_llm(assistant_agent)

        # 에이전트에 전달할 프롬프트
        prompt = """
        다음 아마존 상품에서 데이터를 가져와 주요 정보로 간략한 요약문을 생성하세요:
        
        """

        # 웹 MCP 확장 에이전트를 비동기적으로 실행
        result = await assistant_agent.a_run(
                message=prompt,
                tools=web_mcp_toolkit.tools,
                user_input=False,
        )
        await result.process()

asyncio.run(launch_mcp_agent())

실행하면 결과는 다음과 같습니다:

생성된 보고서는 대상 아마존 상품 페이지의 모든 관련 데이터를 포함합니다:

파이썬으로 아마존 상품 데이터를 스크래핑해 본 적이 있다면, 그 과정이 결코 쉽지 않다는 것을 알 것입니다. 아마존은 악명 높은 아마존 CAPTCHA를 비롯해 다양한 봇 방지 조치를 사용합니다. 게다가 상품 페이지는 지속적으로 변경되며 구조도 다양합니다.

Bright Data의 Web MCP가 이 모든 문제를 해결해 줍니다. 무료 티어에서는 Web Unlocker를 통해 페이지 구조를 깔끔한 마크다운 형식으로 추출하는 scrape_as_markdown 도구를 백그라운드에서 호출합니다. 프로 모드에서는 Bright Data의 Amazon Scraper를 활용해 완전히 구조화된 제품 데이터를 수집하는 web_data_amazon_product 제품을 사용합니다.

이것이 전부입니다! 이제 Bright Data Web MCP로 AG2를 확장하는 방법을 알게 되었습니다.

결론

이 튜토리얼에서는 커스텀 함수 또는 Web MCP를 통해 Bright Data를 AG2에 통합하는 방법을 배웠습니다.

이 통합을 통해 AG2 에이전트는 웹 검색을 수행하고, 구조화된 데이터를 추출하며, 실시간 웹 피드에 접근하고, 웹 상호작용을 자동화할 수 있습니다. 이 모든 것은 Bright Data의 AI용 서비스 제품군으로 구동됩니다.

Bright Data 계정을 무료로 생성하고 AI 지원 웹 데이터 도구를 지금 바로 탐색해 보세요!