Pydantic AI를 Bright Data의 Web MCP와 통합하십시오.

이 가이드에서 배우게 될 내용:

Pydantic AI가 무엇이며, AI 에이전트 구축 프레임워크로서의 독보적인 특징은 무엇인지.
웹에 접근할 수 있는 에이전트 구축을 위해 Pydantic AI가 Bright Data의 Web MCP 서버와 잘 어울리는 이유.
실제 데이터로 구동되는 AI 에이전트를 만들기 위해 Pydantic을 Bright Data의 Web MCP와 통합하는 방법.

자, 시작해 보겠습니다!

Pydantic AI란 무엇인가요?

Pydantic AI는 Python에서 가장 널리 사용되는 데이터 검증 라이브러리인 Pydantic의 제작자가 개발한 Python 에이전트 프레임워크입니다.

다른 AI 에이전트 프레임워크와 비교하여 Pydantic AI는 유형 안전성, 구조화된 출력, 실제 데이터 및 도구와의 통합을 강조합니다. 세부적으로 주요 특징은 다음과 같습니다:

OpenAI, Anthropic, Gemini, Cohere, Mistral, Groq, HuggingFace, Deepseek, Ollama 및 기타 LLM 공급자 지원.
Pydantic 모델을 통한 구조화된 출력 검증.
Pydantic Logfire를 통한 디버깅 및 모니터링.
도구, 프롬프트, 검증기를 위한 선택적 의존성 주입.
실시간 데이터 검증을 통한 스트리밍 LLM 응답.
복잡한 워크플로우를 위한 다중 에이전트 및 그래프 지원.
MCP를 통한 도구 통합 및 HTTP 호출 포함.
표준 Python 앱과 같은 AI 에이전트 구축을 위한 친숙한 파이썬식 흐름.
단위 테스트 및 반복적 개발을 위한 내장 지원.

이 라이브러리는 오픈 소스이며 GitHub에서 이미 11,000개 이상의 스타를 받았습니다.

웹 데이터 검색을 위해 Pydantic AI와 MCP 서버를 결합해야 하는 이유

Pydantic AI로 구축된 AI 에이전트는 기반 LLM의 한계를 그대로 물려받습니다. 여기에는 실시간 정보 접근 부족이 포함되며, 이는 부정확한 응답으로 이어질 수 있습니다. 다행히도 최신 데이터와 실시간 웹 탐색 기능을 에이전트에 탑재함으로써 이 문제를 쉽게 해결할 수 있습니다.

이때 Bright Data의 Web MCP가 해결책이 됩니다. Node.js 기반으로 구축된 이 MCP 서버는 Bright Data의 AI 지원 데이터 검색 도구 모음과 통합됩니다. 이 도구들은 에이전트가 웹 콘텐츠에 접근하고, 구조화된 데이터셋을 쿼리하며, 웹을 검색하고, 웹 페이지와 실시간으로 상호작용할 수 있도록 지원합니다.

현재 서버 내 MCP 도구 에는 다음이 포함됩니다:

도구	설명
`scrape_as_markdown`	단일 웹페이지 URL에서 고급 추출 옵션으로 콘텐츠를 스크랩하여 결과를 마크다운 형식으로 반환합니다. 봇 탐지 및 CAPTCHA를 우회할 수 있습니다.
`search_engine`	Google, Bing 또는 Yandex에서 검색 결과를 추출하여 SERP 데이터(URL, 제목, 스니펫)를 마크다운 형식으로 반환합니다.
`scrape_as_html`	고급 추출 옵션으로 URL에서 웹 페이지 콘텐츠를 검색하여 전체 HTML을 반환합니다. 봇 감지 및 CAPTCHA를 우회할 수 있습니다.
`session_stats`	현재 세션 동안의 도구 사용에 대한 통계를 제공합니다.
`scraping_browser_go_back`	스크래핑 브라우저 세션에서 이전 페이지로 돌아갑니다.
`scraping_browser_go_forward`	스크래핑 브라우저 세션에서 다음 페이지로 이동합니다.
`scraping_browser_click`	선택자에 의해 특정 요소에 대한 클릭 동작을 수행합니다.
`scraping_browser_links`	텍스트 및 선택기를 포함하여 현재 페이지의 모든 링크를 검색합니다.
`scraping_browser_type`	스크래핑 브라우저 내에서 지정된 요소에 텍스트를 입력합니다.
`scraping_browser_wait_for`	특정 요소가 페이지에 표시될 때까지 기다린 후 진행합니다.
`scraping_browser_screenshot`	현재 브라우저 페이지의 스크린샷을 캡처합니다.
`scraping_browser_get_html`	브라우저에서 현재 페이지의 HTML 콘텐츠를 가져옵니다.
`scraping_browser_get_text`	현재 페이지에서 보이는 텍스트 콘텐츠를 추출합니다.

또한, 웹 스크레이퍼 API를 사용하여 다양한 웹사이트(예: Amazon, Yahoo Finance, TikTok, LinkedIn 등)에서 구조화된 데이터를 수집하는 40개 이상의 전문 도구가 있습니다. 예를 들어, web_data_amazon_product 도구는 유효한 제품 URL을 입력으로 받아 Amazon에서 상세하고 구조화된 제품 정보를 수집합니다.

이제 Pydantic AI에서 이러한 MCP 도구를 사용하는 방법을 살펴보세요!

Python에서 Pydantic AI와 Bright MCP 서버 통합 방법

이 섹션에서는 Pydantic AI를 사용하여 AI 에이전트를 구축하는 방법을 배웁니다. 이 에이전트는 웹 MCP 서버로부터 실시간 데이터 스크래핑, 검색 및 상호작용 기능을 갖추게 됩니다.

예시로, 에이전트가 아마존에서 실시간으로 제품 데이터를 검색하는 방법을 시연해 보겠습니다. 이는 수많은 사용 사례 중 하나일 뿐임을 유념하세요. AI 에이전트는 MCP 서버를 통해 제공되는 50개 이상의 도구 중 어떤 것이든 활용하여 다양한 작업을 수행할 수 있습니다.

이 가이드를 따라 Pydantic AI를 활용해 Gemini + Bright Data MCP 기반 AI 에이전트를 구축해 보세요!

필수 조건

코드 예제를 재현하려면 로컬에 다음이 설치되어 있는지 확인하세요:

Python 3.10 이상
Node.js (최신 LTS 버전 권장).

또한 다음이 필요합니다:

Bright Data 계정.
Gemini API 키 (또는 OpenAI, Anthropic, Deepseek, Ollama, Groq, Cohere, Mistral 등 지원되는 다른 LLM 공급자의 API 키).

아직 API 키 설정에 대해 걱정하지 마세요. 아래 단계에서는 적절한 시기에 Bright Data와 Gemini 자격 증명을 모두 구성하는 방법을 안내해 드립니다.

필수 사항은 아니지만, 튜토리얼을 따라가는데 도움이 될 배경 지식:

MCP 작동 방식에 대한 일반적인 이해.
AI 에이전트 작동 방식에 대한 기본적인 이해.
웹 MCP 서버 및 사용 가능한 도구에 대한 일부 지식.
Python에서의 비동기 프로그래밍에 대한 기본 지식.

1단계: Python 프로젝트 생성

터미널을 열고 프로젝트용 새 폴더 생성:

mkdir pydantic-ai-mcp-agent

pydantic-ai-mcp-agent 폴더는 Python AI 에이전트의 모든 코드를 보관할 것입니다.

새로 생성된 폴더로 이동하여 가상 환경을 설정합니다:

cd pydantic-ai-mcp-agent
python -m venv venv

이제 선호하는 Python IDE에서 프로젝트 폴더를 엽니다. Python 확장 프로그램이 설치된 Visual Studio Code 또는 PyCharm Community Edition을 권장합니다.

프로젝트 루트에 agent.py 파일을 생성하세요. 이 시점에서 폴더 구조는 다음과 같아야 합니다:

pydantic-ai-mcp-agent/
├── venv/
└── agent.py

agent.py 파일은 현재 비어 있지만, 곧 Pydantic AI를 Bright Data Web MCP 서버와 통합하는 로직이 포함될 예정입니다.

IDE의 터미널을 사용하여 가상 환경을 활성화하세요. Linux 또는 macOS에서는 다음 명령을 실행합니다:

source venv/bin/activate

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

venv/Scripts/activate

이제 준비 완료! 웹 데이터 접근이 가능한 AI 에이전트 구축을 위한 Python 환경이 마련되었습니다.

2단계: Pydantic AI 설치

활성화된 가상 환경에서 다음 명령어로 필요한 모든 Pydantic AI 패키지를 설치하세요:

pip install "pydantic-ai-slim[google,mcp]"

이 명령어는 불필요한 종속성을 끌어들이지 않는 전체 pydantic-ai 패키지의 경량 버전인 pydantic-ai-slim을 설치합니다.

이 경우 에이전트를 Bright Data Web MCP 서버와 통합할 계획이므로 mcp 확장 모듈이 필요합니다. 또한 Gemini를 LLM 제공자로 통합할 예정이므로 google 확장 모듈도 추가로 필요합니다.

참고: 다른 모델이나 공급자를 사용할 경우, 모델 문서에서 필요한 선택적 종속성을 확인하세요.

다음으로 agent.py 파일에 다음 임포트 문구를 추가하세요:

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio
from pydantic_ai.models.google import GoogleModel
from pydantic_ai.providers.google import GoogleProvider

좋아요! 이제 에이전트 구축에 Pydantic AI를 사용할 수 있습니다.

3단계: 환경 변수 설정

AI 에이전트는 Bright Data, Gemini 같은 타사 서비스와 API로 소통할 거야. API 키를 Python 코드에 하드코딩하지 말고, 보안과 유지보수를 위해 환경 변수에서 불러와야 해.

이 과정을 간소화하려면 python-dotenv 라이브러리를 활용하세요. 가상 환경을 활성화한 상태에서 다음 명령어로 설치합니다:

pip install python-dotenv

그런 다음 agent.py 파일에서 라이브러리를 임포트하고 load_dotenv()로 환경 변수를 불러옵니다:

from dotenv import load_dotenv

load_dotenv()

이렇게 하면 스크립트가 로컬 .env 파일에서 환경 변수를 읽을 수 있습니다. 프로젝트 폴더 내에 .env 파일을 생성하세요:

pydantic-ai-mcp-agent/
├── venv/
├── agent.py
└── .env     # <---------------

이제 다음과 같이 환경 변수에 접근할 수 있습니다:

env_value = os.getenv("<ENV_NAME>")

Python 표준 라이브러리에서 os 모듈을 반드시 임포트하세요:

import os

이제 .env 파일에서 API 키를 안전하게 불러올 수 있도록 설정이 완료되었습니다.

4단계: Bright Data MCP 서버 시작하기

아직 계정이 없다면 Bright Data 계정을 생성하세요. 이미 계정이 있다면 로그인하세요.

그런 다음 공식 지침에 따라 Bright Data API 키를 설정하세요. 간편함을 위해 이 섹션에서는 관리자 권한이 있는 토큰을 사용한다고 가정합니다.

npm을 통해 Bright Data의 Web MCP 를 전역으로 설치하세요:

npm install -g @brightdata/mcp

다음으로 아래 Bash 명령어로 모든 것이 정상 작동하는지 테스트하세요:

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

Windows에서는 동등한 PowerShell 명령은 다음과 같습니다:

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

위 명령어에서 <YOUR_BRIGHT_DATA_API> 자리 표시자를 앞서 획득한 실제 Bright Data API로 대체하세요. 두 명령어 모두 필수 API_TOKEN 환경 변수를 설정하고 @brightdata/mcp npm 패키지를 통해 MCP 서버를 시작합니다.

모든 것이 정상적으로 작동하면 터미널에 다음과 유사한 로그가 표시됩니다:

The Bright Data Web MCP server startup logs

MCP 서버를 처음 실행하면 Bright Data 계정에 두 개의 기본 영역이 자동 생성됩니다:

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

이 두 영역을 통해 MCP 서버는 제공하는 모든 도구를 실행할 수 있습니다.

이를 확인하려면 Bright Data 대시보드에 로그인하여 “프록시 및 스크래핑 인프라” 페이지로 이동하세요. 자동 생성된 다음 영역을 확인할 수 있습니다:

The mcp_unlocker and mcp_browser zones created by the MCP server at startup

참고: 관리자 권한이 있는 API 토큰을 사용하지 않는 경우, 영역을 수동으로 생성해야 합니다. 어쨌든 공식 문서에 설명된 대로 환경 변수(envs)에서 영역 이름을 항상 지정할 수 있습니다.

기본적으로 Web MCP는 search_engine 및 scrape_as_markdown 도구만 노출합니다. 브라우저 자동화 및 구조화된 데이터 추출과 같은 고급 기능을 사용하려면 PRO_MODE=true 환경 변수를 설정하여 Pro 모드를 활성화해야 합니다.

훌륭합니다! 웹 MCP가 완벽하게 작동합니다.

단계 #5: 웹 MCP에 연결하기

이제 컴퓨터에서 Web MCP를 실행할 수 있음을 확인했으니, 연결해 보세요!

먼저 Bright Data API 키를 .env 파일에 추가하세요:

BRIGHT_DATA_API_KEY="<YOUR_BRIGHT_DATA_API_KEY>"

<YOUR_BRIGHT_DATA_API_KEY> 자리 표시자를 앞서 받은 실제 Bright Data API 키로 대체하세요.

그런 다음 agent.py 파일에서 다음 코드로 읽어옵니다:

BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

Pydantic AI는 MCP 서버에 연결하는 세 가지 방법을 지원합니다:

스트리밍 가능한 HTTP 전송 사용.
HTTP SSE 전송 사용.
서버를 서브프로세스로 실행하고 stdio를 통해 연결하기.

처음 두 가지 방법에 익숙하지 않다면, SSE와 스트리밍 가능 HTTP의 차이점에 대한 가이드를 참고하여 자세한 설명을 확인하세요.

이 경우 서버를 서브프로세스로 실행(세 번째 방법)해야 합니다. 이를 위해 아래와 같이 MCPServerStdio 인스턴스를 초기화하세요:

server = MCPServerStdio(
    "npx",
    args=[
        "-y",
        "@brightdata/mcp",
    ],
    env={
        "API_TOKEN": BRIGHT_DATA_API_KEY,
        "PRO_MODE": "true" # 모든 Bright Data 도구 접근을 위한 Pro 모드 활성화
    },
)

이 코드 줄들은 기본적으로 이전에 실행한 것과 동일한 npx 명령어를 사용하여 웹 MCP를 실행합니다. 인증을 위해 Bright Data API 키를 사용하여 API_TOKEN 환경 변수를 설정합니다. 또한 PRO_MODE를 활성화하여 고급 도구를 포함한 모든 사용 가능한 도구에 접근할 수 있도록 합니다.

훌륭합니다! 이제 코드를 통해 로컬 Web MCP 연결 설정을 성공적으로 완료했습니다.

6단계: LLM 구성

참고: 이 섹션은 튜토리얼에 선택된 LLM인 Gemini를 기준으로 합니다. 그러나 공식 문서를 따라 OpenAI 또는 기타 지원되는 LLM으로 쉽게 적용할 수 있습니다.

먼저 Gemini API 키를 가져와 다음과 같이 .env 파일에 추가하세요:

GOOGLE_API_KEY="<YOUR_GOOGLE_API_KEY>"

<YOUR_GOOGLE_API_KEY> 자리 표시자를 실제 API 키로 대체하세요.

다음으로 Gemini 통합에 필요한 Pydantic AI 라이브러리를 임포트하세요:

from pydantic_ai.models.google import GoogleModel
from pydantic_ai.providers.google import GoogleProvider

이 임포트를 통해 Google API에 연결하고 Gemini 모델을 구성할 수 있습니다. .env 파일에서 GOOGLE_API_KEY를 수동으로 읽을 필요가 없다는 점에 유의하세요. 그 이유는 GoogleProvider가 내부적으로 google-genai를 사용하며, 이 라이브러리가 GOOGLE_API_KEY 환경 변수에서 API 키를 자동으로 읽어오기 때문입니다.

이제 제공자 및 모델 인스턴스를 초기화합니다:

provider = GoogleProvider()
model = GoogleModel("gemini-2.5-flash", provider=provider)

놀랍습니다! 이렇게 하면 Pydantic AI 에이전트가 Google API를 통해 gemini-2.5-flash 모델에 연결할 수 있으며, 이 API는 무료로 사용 가능합니다.

7단계: Pydantic AI 에이전트 정의

사전 구성된 LLM을 사용하고 Web MCP 서버에 연결하는 Pydantic AI 에이전트를 정의합니다:

agent = Agent(model, toolsets=[server])

완벽합니다! 단 한 줄의 코드로 에이전트 객체를 생성했습니다. 이 객체는 웹 MCP 서버가 제공하는 도구를 활용하여 작업을 처리할 수 있는 AI 에이전트를 나타냅니다.

8단계: 에이전트 실행

AI 에이전트를 테스트하려면 웹 데이터 추출(상호작용 시) 작업을 포함하는 프롬프트를 작성해야 합니다. 이를 통해 에이전트가 Bright Data 도구를 예상대로 사용하는지 확인할 수 있습니다.

좋은 시작점은 아마존 페이지에서 제품 데이터를 가져오도록 요청하는 것입니다. 예를 들어:

“https://www.amazon.com/AmazonBasics-Pound-Neoprene-Dumbbells-Weights/dp/B01LR5S6HK/에서 제품 데이터를 가져와 줘”

일반적으로 이와 같은 요청을 Gemini에 직접 전송하면 두 가지 중 하나의 결과가 발생합니다:

아마존의 봇 방지 시스템(예: 아마존 CAPTCHA)으로 인해 요청이 실패합니다. 이로 인해 Gemini가 페이지 콘텐츠에 접근할 수 없게 됩니다.
실제 페이지에 접근할 수 없기 때문에 허위 또는 조작된 제품 정보를 반환할 수 있습니다.

Gemini에서 직접 프롬프트를 실행해 보세요. 아마존 페이지에 접근할 수 없다는 메시지와 함께 아래와 같은 허위 제품 정보가 반환될 것입니다:

The unsuccessful response produced by Gemini

웹 MCP 서버와의 연동 덕분에 여러분의 설정에서는 이런 현상이 발생하지 않아야 합니다. 에이전트는 실패하거나 추측하는 대신 web_data_amazon_product 도구를 사용하여 아마존 페이지에서 실시간 구조화된 제품 데이터를 가져온 후 깔끔하고 읽기 쉬운 형식으로 반환해야 합니다.

Pydantic AI 에이전트에 대한 질의 방법이 비동기이므로, 실행 로직을 다음과 같이 async 함수로 감싸야 합니다:

async def main():
    async with agent:
       result = await agent.run("Give me product data from https://www.amazon.com/AmazonBasics-Pound-Neoprene-Dumbbells-Weights/dp/B01LR5S6HK/")

    output = result.output
    print(output)

if __name__ == "__main__":
    asyncio.run(main())

Python 표준 라이브러리에서 asyncio를 반드시 임포트하세요:

import asyncio

미션 완료! 이제 전체 코드를 실행하고 에이전트가 기대에 부응하는지 확인하기만 하면 됩니다.

9단계: 모든 것을 합치기

다음은 agent.py의 최종 코드입니다:

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio
from pydantic_ai.models.google import GoogleModel
from pydantic_ai.providers.google import GoogleProvider
from dotenv import load_dotenv
import os
import asyncio

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

# Bright Data Web MCP 서버 연동을 위해 환경 변수에서 API 키 읽기
BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

# Bright Data Web MCP 서버에 연결
server = MCPServerStdio(
    "npx",
    args=[
        "-y",
        "@brightdata/mcp",
    ],
    env={
        "API_TOKEN": BRIGHT_DATA_API_KEY,
        "PRO_MODE": "true" # 모든 Bright Data 도구 접근을 위한 Pro Mode 활성화
    },
)

# Google LLM 모델 구성
provider = GoogleProvider()
model = GoogleModel("gemini-2.5-flash", provider=provider)

# Gemini 및 Bright Data 웹 MCP 서버 통합으로 AI 에이전트 초기화
agent = Agent(model, toolsets=[server])

async def main():
    async with agent:
       # AI 에이전트에게 스크래핑 작업 수행 요청
       result = await agent.run("https://www.amazon.com/AmazonBasics-Pound-Neoprene-Dumbbells-Weights/dp/B01LR5S6HK/에서 제품 데이터를 제공해 주세요")
    # 에이전트가 생성한 결과물 가져와 출력
    output = result.output
    print(output)

if __name__ == "__main__":
    asyncio.run(main())

와우! Pydantic AI와 Bright Data 덕분에 약 50줄의 코드로 강력한 MCP 기반 AI 에이전트를 구축했습니다.

AI 에이전트 실행 방법: