이 블로그 글에서는 다음을 확인하실 수 있습니다:
- Claude Agent SDK의 정의와 차별화된 특징
- 더 강력한 AI 에이전트를 위해 Bright Data의 Web MCP를 통한 확장이 이상적인 접근 방식인 이유.
- Claude Agent SDK로 구축한 AI 에이전트를 Web MCP를 통해 Bright Data 웹 도구와 연결하는 방법.
자, 시작해 보겠습니다!
Claude Agent SDK란 무엇인가요?
Claude Agent SDK는 Anthropic에서 제공하는 오픈소스 프레임워크로, Claude Code 기반의 자율적 AI 에이전트를 구축할 수 있게 합니다. 특히 에이전트가 사용자 정의 오케스트레이션 로직 없이도 파일 읽기, 명령 실행, 웹 검색, 코드 편집, 도구와의 상호작용을 가능하게 합니다.
이 SDK는 컨텍스트 수집, 작업 수행, 결과 검증까지 가능한 강력한 에이전트 루프를 제공합니다. 이를 통해 에이전트가 복잡한 워크플로를 안정적으로 수행할 수 있습니다. SDK는 다음과 같은 형태로 제공됩니다:
- Python: GitHub에서 4,500개 이상의 스타를 보유한 라이브러리
- TypeScript: GitHub에서 720개 이상의 스타를 보유한 라이브러리.
Claude 에이전트 SDK는 내장 도구, 서브 에이전트, 외부 서비스를 위한 MCP(모델 컨텍스트 프로토콜)와의 네이티브 통합을 지원합니다. 최종 목표는 AI 에이전트 개발을 단순화하여 Claude의 추론 및 도구 실행 기능을 활용하는 전문 어시스턴트, 연구 에이전트, 자동화 봇을 구축할 수 있는 간편한 API를 제공하는 것입니다.
Bright Data의 웹 데이터 기능으로 Claude 에이전트 SDK를 확장해야 하는 이유
Claude 에이전트의 한계와 해결 방안을 살펴보세요!
Claude 에이전트 SDK 도구에 대한 배경 설명
가장 뛰어난 Claude AI 모델조차도 모든 대규모 언어 모델(LLM)에 내재된 한계가 있습니다. 이러한 한계는 AI 모델이 과거의 순간을 포착한 데이터로 훈련된다는 사실에서 비롯됩니다.
결과적으로 LLM은 훈련된 데이터에 기반한 답변만 생성할 수 있습니다. 알지 못하는 사항(또는 최근 사건)에 대해 질문받으면 완전히 실패하거나, 더 나쁘게는 허위 정보를 생성할 수 있습니다. 또한 스스로 외부 세계와 상호작용할 수 없습니다.
AI 에이전트는 LLM으로 구동되므로 이러한 모든 한계를 그대로 물려받습니다. 동시에 에이전트에는 중요한 장점이 하나 있습니다: 도구를 사용할 수 있다는 점입니다! 도구를 통해 에이전트는 외부 서비스와 시스템을 호출할 수 있어, LLM만으로 제한된 능력을 확장할 수 있습니다.
Claude 에이전트 SDK는 파일 작업, 명령 실행, 웹 검색, 코드 편집 등을 위한 기본 내장 도구 세트를 에이전트에 제공합니다.
또한 맞춤형 도구 정의에 대한 독특한 접근 방식을 도입합니다. Claude 에이전트 SDK에서 맞춤형 도구는 인프로세스 MCP 서버로 구현됩니다. Claude의 개발사인 Anthropic이 MCP를 정의했다는 점을 고려하면 이는 당연한 일입니다.
기본 Claude Agent SDK 도구는 유용하지만, 생산 환경 수준의 사용 사례에는 항상 충분하지 않습니다. 실제로는 오래된 지식이나 실시간 웹과의 제한된 상호작용과 같은 일반적인 LLM 한계를 해결하도록 설계된 전문적인 타사 공급자를 통합하는 것이 더 좋습니다.
바로 여기에 Bright Data 웹 MCP가 등장합니다!
Bright Data 웹 MCP 소개
Claude Agent SDK의 커스텀 도구는 백그라운드에서 MCP를 기반으로 실행됩니다. 따라서 이미 풍부한 생산 환경용 도구를 제공하는 MCP로 에이전트 빌드를 확장하는 것이 합리적입니다.
Bright Data의 Web MCP는 자동화된 웹 데이터 수집, 구조화된 데이터 추출, 브라우저 수준 상호작용을 위한 60개 이상의 AI 지원 도구를 제공합니다. 2,000개 이상의 GitHub 스타를 보유한 공개 저장소를 기반으로 원격 서비스 및 로컬 서버 형태로 이용 가능합니다.
무료 티어에서도 MCP 서버는 특히 유용한 두 가지 도구(및 해당 배치 변형)를 제공합니다:
| 도구 | 설명 |
|---|---|
search_engine |
Google, Bing 또는 Yandex 결과를 JSON 또는 마크다운 형식으로 가져옵니다. |
scrape_as_markdown |
모든 웹페이지를 깨끗한 마크다운으로 스크랩하며, 봇 방지 조치를 우회합니다. |
Web MCP가 진정으로 빛을 발하는 부분은 프로 모드입니다. 이 모드는 Amazon, LinkedIn, Yahoo Finance, YouTube, TikTok, Zillow, Google Maps 등 다양한 플랫폼에서 구조화된 데이터를 추출할 수 있는 프리미엄 도구를 제공합니다. 또한, 모든 AI 에이전트에게 웹을 탐색하고 인간 사용자와 같은 방식으로 웹 페이지와 상호작용할 수 있는 능력을 부여합니다.
이제 Bright Data Web MCP를 Claude 에이전트 SDK에 통합하는 방법을 살펴보겠습니다!
Web MCP를 통해 Claude Agent SDK를 Bright Data 도구와 연결하는 방법
이 단계별 가이드에서는 MCP를 통해 Claude Agent SDK로 구축된 AI 에이전트에 Bright Data 서비스를 통합하는 방법을 배웁니다. 구체적으로 Bright Data의 Web MCP를 Claude Agent SDK AI 에이전트에 연결하여 사용 가능한 모든 웹 데이터 도구에 대한 접근 권한을 부여합니다.
참고: Claude Agent SDK는 TypeScript로도 제공됩니다. 공식 문서를 참고하면 아래 섹션을 Python에서 JavaScript 또는 TypeScript로 쉽게 변환할 수 있습니다.
아래 지침을 따르세요!
필수 조건
이 튜토리얼을 따라하려면 다음 요구 사항을 충족해야 합니다:
- 로컬에 설치된Python 3.10 이상
- Claude Code가 컴퓨터에 설치되어 있어야 합니다.
- 사용 가능한 크레딧이 있는 Claude API 키.
- API 키가 있는 Bright Data 계정.
참고: Bright Data 계정 설정 과정은 튜토리얼 후반부에 Web MCP 사용을 위한 별도 섹션에서 안내됩니다.
Claude Agent SDK는 Claude Code를 런타임으로 사용하므로 Claude Code를 로컬에 설치해야 합니다. 단계별 지침은 Claude Code + Bright Data Web MCP 통합 가이드를 참조하십시오.
마지막으로, MCP 프로토콜과 웹 MCP가 제공하는 도구에 대한 기본적인 이해가 도움이 될 것입니다.
1단계: Python에서 Claude Agent SDK 프로젝트 설정
먼저, Claude Code가 컴퓨터에 설치되어 있는지 확인하세요. 다음 명령어를 실행하세요:
claude --version다음과 유사한 출력이 표시되어야 합니다:
2.1.29 (Claude Code)확인되면 훌륭합니다! 이는 Claude Agent SDK 사용의 주요 전제 조건이 충족되었음을 의미합니다.
다음으로 프로젝트 디렉터리를 생성하세요. 그런 다음 터미널에서 해당 디렉터리로 이동합니다:
mkdir claude-agent-sdk-bright-data-ai-agent
cd claude-agent-sdk-bright-data-ai-agent이제 프로젝트 내에서 가상 환경을 초기화하세요:
python -m venv .venv프로젝트 루트에 agent.py라는 새 파일을 생성하세요. 이제 디렉터리 구조는 다음과 같아야 합니다:
claude-agent-sdk-bright-data-ai-agent/
├── .venv/
└── agent.pyagent.py 파일에는 Claude Agent SDK로 구축되고 Bright Data Web MCP와 상호작용하는 AI 에이전트의 로직이 포함됩니다.
선호하는 Python IDE에서 프로젝트 폴더를 엽니다. 예를 들어 PyCharm Community Edition이나 Python 확장 프로그램이 설치된 Visual Studio Code에서 로드하세요.
이제 이전에 생성한 가상 환경을 활성화하세요. Linux 또는 macOS에서는 다음 명령을 실행합니다:
source .venv/bin/activateWindows에서는 다음과 같이 실행하세요:
.venv/Scripts/activate가상 환경이 활성화된 상태에서 필요한 종속성을 설치하세요:
pip install claude-agent-sdk python-dotenv이 애플리케이션의 종속성은 다음과 같습니다:
claude-agent-sdk: Claude Agent SDK를 통해 Python으로 AI 에이전트를 구축하기 위함입니다.python-dotenv: 로컬 .env 파일에서 비밀 정보(예: Claude API 키 및 Bright Data API 키)를 불러오기 위해 사용됩니다.
모든 준비 완료! 이제 Python 환경에서 Claude Agent SDK로 AI 에이전트를 구축할 수 있습니다.
2단계: 환경 변수 로딩 준비
AI 에이전트는 Bright Data 및 (당연히) Claude와 같은 타사 서비스에 연결됩니다. 이를 위해서는 해당 서비스 계정과 연결된 API 키를 사용해야 합니다. 모범 사례로, 소스 코드에 자격 증명을 직접 하드코딩해서는 안 됩니다.
대신 필요한 API 키를 .env 파일에서 불러와야 합니다. 바로 이 때문에 이전 단계에서 python-dotenv를 설치한 것입니다. 먼저 agent.py 파일에서 라이브러리를 임포트하세요:
from dotenv import load_dotenv그런 다음 프로젝트 루트에 .env 파일을 생성하세요:
claude-agent-sdk-bright-data-ai-agent/
├─── .venv/
├─── agent.py
└─── .env # <-----.env 파일에는 이 프로젝트에 필요한 두 가지 비밀 정보인 Claude API 키와 Bright Data API 키가 저장됩니다.
이제 agent.py에서 다음 함수를 호출하여 .env 파일의 환경 변수를 로드하세요:
load_dotenv()좋습니다! 이제 스크립트가 환경 변수에서 민감한 자격 증명을 안전하게 읽을 수 있으며, 이를 코드베이스 외부로 분리할 수 있습니다.
3단계: Claude Agent SDK 시작하기
agent.py에 다음 코드를 추가하여 Claude Agent SDK를 사용한 간단한 AI 에이전트를 구축하세요:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.types import StreamEvent
async def main():
# Claude 에이전트 구성
options = ClaudeAgentOptions(
model="claude-haiku-4-5", # 원하는 Claude 모델로 교체
include_partial_messages=True # 스트리밍 응답 활성화
)
# 에이전트에 전송할 프롬프트
prompt = "안녕! 요즘 어떻게 지내?"
# 에이전트 루프: Claude Agent SDK가 반환하는 이벤트 스트리밍
async for message in query(prompt=prompt, options=options):
# 스트리밍 이벤트만 가로채기
if isinstance(message, StreamEvent):
event = message.event
event_type = event.get("type")
# 증분 텍스트 출력 처리
if event_type == "content_block_delta":
delta = event.get("delta", {})
if delta.get("type") == "text_delta":
# 스트리밍 텍스트가 도착하는 대로 출력
print(delta.get("text", ""), end="", flush=True)
asyncio.run(main())이 스크립트는 세 가지 주요 구성 요소로 이루어져 있습니다:
옵션: 에이전트를 구성합니다. 이 예시에서 에이전트는 Claude Haiku 4.5 모델을 사용하고 스트리밍 응답을 활성화하여 출력을 점진적으로 출력할 수 있도록 합니다.prompt: Claude AI 에이전트가 수행할 작업을 정의합니다. Claude는 이 입력에 기반하여 작업 처리 방식을 자동으로 결정합니다.query: 에이전트 루프를 시작하는 주요 진입점입니다. 비동기 반복자를 반환하므로, Claude가 추론하고 도구를 호출하며 결과를 관찰하고 출력을 생성하는 동안 메시지를 스트리밍하기 위해async for를사용합니다.
비동기 for 루프는 Claude가 “생각하는” 동안 계속 실행됩니다. 각 반복은 추론 단계, 도구 호출, 도구 결과 또는 최종 답변과 같은 다양한 메시지 유형을 반환할 수 있습니다. 이 예제에서는 최종 텍스트 출력만 터미널로 스트리밍합니다.
Claude Agent SDK가 정상적으로 실행되려면 Claude API에 대한 접근 권한이 필요합니다. 기본적으로 ANTHROPIC_API_KEY 환경 변수에서 API 키를 읽습니다. 따라서 .env 파일에 다음과 같이 추가하세요:
ANTHROPIC_API_KEY="<YOUR_ANTHROPIC_API_KEY>" <YOUR_ANTHROPIC_API_KEY>를 실제 Anthropic Claude API 키로 대체하십시오.
참고: Claude Agent SDK 에이전트가 API 키에 접근할 수 없는 경우 다음 오류로 실패합니다:
귀하의 조직은 Claude에 대한 접근 권한이 없습니다. 다시 로그인하거나 관리자에게 문의하십시오.이전 단계의 코드를 모두 고려하여 다음 명령어로 에이전트를 시작하세요:
python agent.py터미널에서 다음과 유사한 스트리밍 응답을 확인할 수 있습니다:
훌륭합니다! 응답이 입력 프롬프트와 일치한다는 것은 Claude Agent SDK 기반 AI 에이전트가 완벽하게 작동하고 있음을 의미합니다.
4단계: Bright Data의 웹 MCP로 시작하기
Claude Agent SDK의 커스텀 툴은 인프로세스 MCP 서버를 통해 구현된다는 점을 기억하세요. 따라서 AI 에이전트를 Bright Data 웹 MCP 서버 인스턴스에 직접 연결하는 것이 합리적입니다.
결국 Bright Data 서비스와 직접 통합하여 커스텀 도구를 정의한 후 MCP를 통해 노출하는 것은 큰 의미가 없습니다. 이미 공식(그리고 널리 사용되는!) MCP 서버가 존재하기 때문입니다.
이 섹션에서는 로컬 인스턴스 연결 방법을 보여드립니다. 동시에 확장성이 뛰어나고 기업 환경에 적합한 설정을 위해 원격 웹 MCP 서버에 연결할 수도 있습니다.
Claude Agent SDK를 Bright Data의 Web MCP에 연결하기 전에, MCP 서버가 여러분의 머신에서 실행 가능한지 확인하세요!
먼저 Bright Data 계정을 생성하세요. 이미 계정이 있다면 로그인만 하면 됩니다. 빠른 설정을 위해 대시보드의 “MCP” 섹션에 있는 마법사를 따라가세요:
추가 안내가 필요하면 아래 지침을 참조하세요.
Bright Data API 키 생성을 시작하세요. 이 API 키는 곧 로컬 Web MCP 인스턴스를 Bright Data 계정으로 인증하는 데 사용됩니다. 코드에서 이 키에 접근해야 하므로 .env 파일에 다음을 추가하세요:
BRIGHT_DATA_API_KEY="<YOUR_BRIGHT_DATA_API_KEY>"그런 다음 agent.py 파일에 로드하세요:
import os
BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")@brightdata/mcp 패키지를 통해 Web MCP를 전역으로 설치하세요:
npm install -g @brightdata/mcpLinux/macOS에서는 다음 명령어로 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 계정에 자동으로 두 개의 영역을 설정합니다:
이 두 영역은 Web MCP에서 사용 가능한 60개 이상의 도구를 구동합니다. 문서에 설명된 대로 두 영역의 기본 이름을 재정의할 수도 있습니다.
생성 여부를 확인하려면 Bright Data 대시보드의 “프록시 및 스크래핑 인프라” 페이지로 이동하세요. “내 영역” 테이블에 두 영역이 모두 표시되어야 합니다:
참고: Web MCP 무료 계층 에서는 search_engine 및 scrape_as_markdown 도구(및 해당 배치 버전)만 이용할 수 있습니다.
60개 이상의 모든 도구를 사용하려면 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중요: 프로 모드는 무료 이용권에 포함되지 않으며 추가 요금이 부과됩니다.
훌륭합니다! 이제 웹 MCP 서버가 여러분의 머신에서 실행 중임을 확인하셨습니다. 다음으로 Claude Agent SDK를 구성하여 서버를 자동으로 시작하고 연결하도록 설정할 것입니다.
단계 #5: Claude Agent SDK를 Web MCP에 연결하기
Claude Agent SDK는 ClaudeAgentOptions 클래스의 mcp_servers 옵션을 통해 MCP 연결을 지원합니다. 이를 통해 에이전트가 Bright Data의 웹 MCP와 직접 통신할 수 있습니다.
웹 MCP에 연결하려면 옵션 변수를 다음과 같이 업데이트하세요:
options = ClaudeAgentOptions(
# Bright Data의 Web MCP에 연결
mcp_servers={
"bright_data": {
"command": "npx",
"args": ["-y", "@brightdata/mcp"],
"env": {
"API_TOKEN": BRIGHT_DATA_API_KEY,
"PRO_MODE": "true" # Pro 모드 활성화
}
}
},
allowed_tools=["mcp__bright_data__*"], # 모든 Bright Data 웹 MCP 도구 활성화
model="claude-haiku-4-5", # 원하는 Claude 모델로 교체
include_partial_messages=True, # 스트리밍 응답 활성화
)이 설정은 환경 변수를 통해 자격 증명과 구성을 전달하는, 앞서 테스트한 npx 명령어를 반영합니다:
API_TOKEN: 인증에 필요합니다. Bright Data API 키로 설정하세요.PRO_MODE: 프로 모드 활성화에 필수입니다.
중요: allowed_tools 필드는 와일드카드를 사용하여 구성된 bright_data 서버의 모든 도구를 허용합니다. 이 설정이 없으면 Claude 기반 에이전트가 도구를 볼 수는 있지만 사용할 수 없습니다.
코드에서 mcp_servers 옵션을 명시하지 않으려면, 프로젝트 루트에 다음과 같은 구조의 .mcp.json 파일을 생성할 수도 있습니다:
{
"mcpServers": {
"bright_data": {
"command": "npx",
"args": ["-y", "@brightdata/mcp"],
"env": {
"API_TOKEN": "<YOUR_BRIGHT_DATA_API_KEY>",
"PRO_MODE": "true"
}
}
}
}웹 MCP 연결을 확인하려면 간단한 프롬프트로 에이전트를 테스트하세요:
prompt = "어떤 Bright Data MCP 도구에 접근 권한이 있나요?"프로 모드(PRO_MODE="true")에서는 다음과 같이 사용 가능한 60개 이상의 모든 도구가 응답에 나열되어야 합니다:
이제 에이전트가 웹 MCP 서버에서 제공하는 모든 고급 도구를 확인하고 사용할 수 있습니다. 미션 완료! Claude Agent SDK로 구축한 AI 에이전트가 웹 MCP 도구를 통해 Bright Data의 웹 데이터 기능으로 확장되었습니다.
6단계: 에이전트 실행
Bright Data 웹 MCP와 통합된 AI 에이전트의 효과를 보여주기 위해서는 적절한 프롬프트가 필요합니다. 특히 웹 데이터 검색 및/또는 웹 상호작용을 포함해야 합니다.
예를 들어, 경쟁사 웹사이트를 모니터링하여 자동으로 스크린샷을 찍고 페이지 텍스트를 추출하는 AI 에이전트를 구축한다고 가정해 보세요. 이는 적절한 도구 없이는 표준 AI 에이전트가 단독으로 수행할 수 없는 작업입니다.
경쟁사가 Nike라고 가정해 보겠습니다. 다음과 같은 프롬프트를 작성할 수 있습니다:
prompt = """
스크래핑 브라우저 세션을 열고 다음 웹 페이지로 이동하세요:
"https://www.nike.com/"
페이지가 완전히 로드될 때까지 기다린 후 전체 페이지 스크린샷을 캡처하세요. 또한 페이지 전체 텍스트를 추출하세요. 스크린샷은 로컬 `screenshot.png` 파일로, 페이지 텍스트는 로컬 `text.txt` 파일로 저장하세요.
"""프리미엄 Bright Data Web MCP 도구의 브라우징 기능 덕분에 AI 에이전트는 이제 다음과 같은 작업을 수행할 수 있습니다:
- 브라우저 API를 통해 클라우드에서 원격 브라우저 세션을 열고, 일반적인 봇 방지 기능을 우회하며 사실상 모든 웹 페이지에 접근할 수 있습니다.
- 페이지가 완전히 로드될 때까지 대기합니다.
- 전체 페이지 스크린샷을 캡처하고 가시 영역의 모든 텍스트를 추출합니다.
마지막으로 에이전트는 Claude Agent SDK가 제공하는 내장 도구를 사용하여 요청된 대로 생성된 출력을 디스크에 저장합니다.
이미지 처리 및 디스크 쓰기 기능을 활성화하려면 다음 두 가지 추가 옵션이 필요합니다:
options = ClaudeAgentOptions(
# ...
permission_mode="acceptEdits", # 에이전트가 디스크에 파일 쓰기 가능하도록 설정
max_buffer_size=10 * 1024 * 1024, # 이미지 처리를 위해 10MB로 증가
)에이전트 실행 시 도구 사용이 포함되므로, 도구 호출 관련 이벤트도 가로채도록 스트리밍 로직을 업데이트하는 것이 합리적입니다. 비동기 for 루프를 다음과 같이 수정하세요:
# 현재 도구를 추적하고 입력 JSON을 누적
current_tool = None
tool_input = ""
# 에이전트 루프: Claude Agent SDK가 반환한 이벤트 스트리밍
async for message in query(prompt=prompt, options=options):
# 스트리밍 이벤트만 가로채기
if isinstance(message, StreamEvent):
event = message.event
event_type = event.get("type")
if event_type == "content_block_start":
# 새 도구 호출 시작
content_block = event.get("content_block", {})
if content_block.get("type") == "tool_use":
current_tool = content_block.get("name")
tool_input = ""
print(f"nStarting tool: {current_tool}")
# 증분 텍스트 출력 처리
elif event_type == "content_block_delta":
delta = event.get("delta", {})
if delta.get("type") == "text_delta":
# 스트리밍되는 텍스트가 도착하는 대로 출력
print(delta.get("text", ""), end="", flush=True)
elif delta.get("type") == "input_json_delta":
# 스트리밍되는 JSON 입력 축적
chunk = delta.get("partial_json", "")
tool_input += chunk
elif event_type == "content_block_stop":
# 도구 호출 완료 (최종 입력 표시)
if current_tool:
print(f"도구 {current_tool} 호출됨: {tool_input}")
current_tool = None이 로직은 에이전트가 호출한 도구와 각 도구의 입력을 더 잘 이해하는 데 도움이 될 것입니다. 대단하네요! 이제 남은 것은 에이전트를 테스트하는 것뿐입니다.
7단계: AI 에이전트 테스트
최종 agent.py 파일은 다음과 같이 구성됩니다:
from dotenv import load_dotenv
import os
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.types import StreamEvent
# .env 파일에서 환경 변수 로드
load_dotenv()
# Bright Data API 키 환경 변수 접근
BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")
async def main():
options = ClaudeAgentOptions(
# Bright Data의 Web MCP에 연결
mcp_servers={
"bright_data": {
"command": "npx",
"args": ["-y", "@brightdata/mcp"],
"env": {
"API_TOKEN": BRIGHT_DATA_API_KEY,
"PRO_MODE": "true" # Pro 모드 활성화
}
}
},
allowed_tools=["mcp__bright_data__*"], # 모든 Bright Data 웹 MCP 도구 활성화
model="claude-haiku-4-5", # 원하는 Claude 모델로 교체
include_partial_messages=True, # 스트리밍 응답 활성화
permission_mode="acceptEdits", # 에이전트가 디스크에 파일 쓰기 허용
max_buffer_size=10 * 1024 * 1024, # 이미지 처리를 위해 10MB로 증가
)
# 에이전트에게 전송되는 프롬프트
prompt = """
스크래핑 브라우저 세션을 열고 다음 웹 페이지로 이동하세요:
"https://www.nike.com/"
페이지가 완전히 로드될 때까지 기다린 후 전체 페이지 스크린샷을 캡처하세요. 또한 페이지 전체 텍스트를 추출하세요. 스크린샷은 로컬 `screenshot.png` 파일로, 페이지 텍스트는 로컬 `text.txt` 파일로 저장하세요.
"""
# 현재 도구를 추적하고 입력 JSON을 누적
current_tool = None
tool_input = ""
# 에이전트 루프: Claude Agent SDK가 반환하는 이벤트 스트리밍
async for message in query(prompt=prompt, options=options):
# 스트리밍 이벤트만 가로채기
if isinstance(message, StreamEvent):
event = message.event
event_type = event.get("type")
if event_type == "content_block_start":
# 새 도구 호출 시작
content_block = event.get("content_block", {})
if content_block.get("type") == "tool_use":
current_tool = content_block.get("name")
tool_input = ""
print(f"nStarting tool: {current_tool}")
# 증분 텍스트 출력 처리
elif event_type == "content_block_delta":
delta = event.get("delta", {})
if delta.get("type") == "text_delta":
# 스트리밍되는 텍스트가 도착하는 대로 출력
print(delta.get("text", ""), end="", flush=True)
elif delta.get("type") == "input_json_delta":
# 스트리밍되는 JSON 입력값을 누적
chunk = delta.get("partial_json", "")
tool_input += chunk
elif event_type == "content_block_stop":
# 도구 호출 완료 (최종 입력 표시)
if current_tool:
print(f"도구 {current_tool} 호출됨: {tool_input}")
current_tool = None
asyncio.run(main())다음 명령어로 실행:
python agent.py에이전트를 실행하면 다음과 같은 출력이 표시됩니다:
보시다시피 에이전트는 Web MCP에 연결하여 다음 도구를 사용합니다:
mcp__bright_data__scraping_browser_screenshot: 전체 페이지 스크린샷 캡처mcp__bright_data__scraping_browser_get_text: 웹 페이지의 모든 텍스트 추출
그런 다음 “Write” 도구를 사용하여 요청된 파일에 출력을 저장합니다. 실행 후 프로젝트 루트 폴더에 screenshot.png와 text.txt 파일이 생성됩니다:
screenshot.png를 열어 대상 Nike 홈페이지의 전체 화면 스크린샷을 확인하세요:
text.txt를 열어 위 페이지에서 추출된 텍스트를 확인하세요:
자, 이제 Claude Agent SDK로 오케스트레이션되고 Bright Data Web MCP로 확장된 AI 에이전트가 웹 브라우징을 비롯한 다양한 작업을 처리할 수 있습니다!
결론
이 튜토리얼에서는 Claude Agent SDK의 MCP 통합을 통해 맞춤형 툴링을 활용하여 확장된 AI 에이전트를 구축하는 방법을 배웠습니다. 특히 Claude Agent Python SDK로 구동되는 AI 에이전트를 Bright Data의 Web MCP에 연결하여 강화하는 이유와 방법을 확인했습니다.
이 통합을 통해 Claude 기반 AI 에이전트는 웹 검색, 구조화된 데이터 추출, 실시간 웹 데이터 수집, 자동화된 웹 상호작용과 같은 강력한 기능을 갖추게 되어 다양한 에이전트 활용 사례를 가능하게 합니다.
지금 바로 Bright Data 계정을 무료로 가입하고 AI 활용이 가능한 웹 데이터 도구를 직접 체험해 보세요!
