이 블로그 글에서 여러분은 다음을 배우게 됩니다:

스몰에이전트(smolagents)가 무엇이며 왜 인기를 얻고 있는지.
에이전트가 도구 실행에 의존하는 방식과 Bright Data의 Web MCP를 통해 도구를 검색하는 방법.
Web MCP 도구를 smolagents에 통합하여 AI 코드 에이전트를 구축하는 방법.

자, 시작해 보겠습니다!

smolagents란 무엇인가요?

smolagents는 최소한의 코드로 강력한 AI 에이전트를 구축할 수 있게 해주는 경량 Python 라이브러리입니다. 이 라이브러리의 독특한 점은 CodeAgent로, 프롬프트 실행에 필요한 동작을 실행 가능한 Python 코드 스니펫으로 작성합니다(단순히 텍스트 응답을 반환하는 것이 아닙니다).

이러한 접근 방식은 효율성을 높이고 LLM 호출을 줄이며, 에이전트가 샌드박스화된 실행을 통해 도구 및 환경과 안전하게 직접 상호작용할 수 있게 합니다. 커뮤니티는 이 새로운 AI 에이전트 구축 방식을 적극 수용했으며, 이는 단 몇 달 만에 GitHub에서 23,000개의 스타를 획득한 것으로 입증됩니다:

smolagents의 특징은 다음과 같습니다:

모델 독립적이며, OpenAI, Anthropic, 로컬 트랜스포머 또는 Hugging Face Hub의 모든 LLM을 지원합니다.
모달리티 독립적: 텍스트, 비전, 오디오, 비디오를 지원합니다.
도구 독립적: MCP 서버, LangChain, Hub Spaces의 도구를 지원합니다.

이 라이브러리의 철학에 대한 자세한 내용은 Hugging Face 블로그의 발표 글을 참고하세요.

smolagents가 도구 사용을 권장하는 이유

LLM은 훈련된 데이터에 의해 제한됩니다 . 해당 지식 기반으로 응답, 콘텐츠, 코드 또는 멀티미디어를 생성할 수 있습니다. 이는 강력한 장점이지만, 동시에 현재 AI의 가장 큰 한계점 중 하나이기도 합니다.

smolagents는 도구를 중심으로 구축된 에이전트를 제공함으로써 이 문제를 해결합니다. 이는 매우 핵심적인 요소로, 라이브러리의 모든 에이전트 클래스는 필수 인수로 도구 목록을 받아들입니다. 도구 호출 덕분에 AI 모델은 환경과 상호작용하고 콘텐츠 생성 이상의 작업을 수행할 수 있습니다.

특히 smolagents는 MCP 서버, LangChain, 심지어 Hub Space의 도구에도 연결할 수 있다는 점을 기억하세요. 표준 JSON/텍스트 기반 도구 호출도 지원합니다.

그렇다면 오늘날 일반적인 AI에 부족한 것은 무엇일까요? 정확하고 최신 데이터, 그리고 인간처럼 웹 페이지와 상호작용하는 능력입니다. 바로 이것이 Bright Data의 Web MCP 도구가 제공하는 것입니다!

웹 MCP는 60개 이상의 AI 지원 도구를 제공하는 오픈소스 서버로, 웹 상호작용 및 데이터 수집을 위한 Bright Data 인프라를 기반으로 합니다. 무료 계정에서도 두 가지 혁신적인 도구를 이용할 수 있습니다:

도구	설명
`search_engine`	Google, Bing 또는 Yandex에서 JSON 또는 Markdown 형식의 검색 결과를 가져옵니다.
`scrape_as_markdown`	봇 탐지 및 CAPTCHA를 우회하여 모든 웹 페이지를 깔끔한 마크다운 형식으로 스크랩합니다.

이 외에도 Web MCP는 클라우드 브라우저에서 상호 작용을 위한 도구와 YouTube, Amazon, LinkedIn, TikTok, Yahoo Finance 등 다양한 플랫폼에서 구조화된 데이터를 수집하기 위한 수십 가지의 전문 도구를 제공합니다. 공식 GitHub 페이지에서 더 자세한 정보를 확인하세요.

smolagents로 Web MCP의 실제 작동 모습을 확인하세요!

Web MCP 도구로 smolagents AI 코드 에이전트 확장하기

이 튜토리얼 섹션에서는 Bright Data Web MCP와 통합되는 smolagents AI 에이전트를 구축하는 방법을 배웁니다. 구체적으로, 에이전트는 MCP 서버가 제공하는 도구를 사용하여 웹 데이터를 실시간으로 가져오고 감성 분석을 수행합니다.

참고: 이는 예시일 뿐이며, 입력 프롬프트를 변경하여 다른 사용 사례에 쉽게 적용할 수 있습니다.

아래 지침을 따르세요!

필수 조건

이 튜토리얼을 따라하려면 다음이 설치되어 있어야 합니다:

로컬에 설치된Python 3.10 이상
웹 MCP 실행을 위해 컴퓨터에 Node.js 설치 ( 최신 LTS 버전 권장).
Gemini API 키 (또는 지원되는 다른 모델의 API 키).

또한 API 키가 있는 Bright Data 계정이 필요합니다. 곧 안내해 드리니 걱정하지 마세요. MCP의 작동 방식과 웹 MCP가 제공하는 도구에 대한 기본적인 이해도 도움이 될 것입니다.

1단계: 프로젝트 설정

터미널을 열고 smolagents 프로젝트용 새 폴더를 생성하세요:

mkdir smolagents-mcp-agent

smolagents-mcp-agent/ 폴더에는 Web MCP 도구를 통해 확장된 AI 에이전트의 Python 코드가 포함됩니다.

그런 다음 프로젝트 디렉터리로 이동하여 가상 환경을 초기화합니다:

cd smolagents-mcp-agent
python -m venv .venv

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

smolagents-mcp-agent/
├── .venv/
└── agent.py

agent.py는 메인 Python 파일로 AI 에이전트 정의를 포함합니다.

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

앞서 생성한 가상 환경을 활성화할 차례입니다. Linux 또는 macOS에서는 다음 명령을 실행하세요:

source .venv/bin/activate

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

.venv/Scripts/activate

가상 환경이 활성화된 상태에서 필요한 PyPI 라이브러리를 설치하세요:

pip install "smolagents[mcp,openai]" python-dotenv

의존성은 다음과 같습니다:

"smolagents[mcp,openai]": MCP 통합 및 OpenAI와 유사한 API를 제공하는 모든 공급자에 연결하기 위한 섹션이 확장된 smolagent 패키지입니다.
python-dotenv: 로컬 .env 파일에서 환경 변수를 읽기 위한 도구입니다.

완료! 이제 smolagents를 활용한 AI 에이전트 개발용 Python 환경이 구축되었습니다.

2단계: 환경 변수 읽기 설정

에이전트는 Gemini, Bright Data 같은 타사 서비스에 연결됩니다. 연결 인증을 위해 API 키를 설정해야 합니다. agent.py 파일에 키를 하드코딩하는 것은 보안 문제를 유발할 수 있는 코드 스멜입니다. 따라서 스크립트가 환경 변수에서 비밀 정보를 읽도록 구성하세요.

바로 이 목적으로 python-dotenv 패키지를 설치했습니다. agent.py 파일에서 라이브러리를 임포트하고 load_dotenv() 를 호출하여 환경 변수를 로드하세요:

from dotenv import load_dotenv

load_dotenv()

이제 스크립트가 로컬 .env 파일에서 환경 변수를 참조할 수 있습니다.

프로젝트 디렉터리에 .env 파일을 추가하세요:

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

그런 다음 코드에서 환경 변수를 다음과 같이 사용할 수 있습니다:

import os

os.getenv("ENV_NAME")

훌륭합니다! 이제 스크립트가 환경 변수에서 타사 통합 비밀 정보를 안전하게 불러옵니다.

3단계: Bright Data의 Web MCP 로컬 테스트

Bright Data 웹 MCP 연결을 구성하기 전에, 해당 서버를 실행할 수 있는지 확인하세요. 이는 로컬에서 웹 MCP를 시작하도록 smolagents에 지시할 것이기 때문에 필요합니다. 에이전트는 이후 STDIO를 통해 여기에 연결됩니다.

Bright Data 계정이 없다면 새로 생성하세요. 계정이 있다면 로그인하세요. 빠른 설정을 위해 계정의 “MCP” 섹션에 있는 지침을 따르세요:

The “MCP” section in your Bright Data account

더 자세한 안내가 필요하면 아래 지침을 따르세요.

먼저 Bright Data API 키를 생성하세요. 곧 필요할 수 있으니 안전한 곳에 보관하십시오. 여기서는 Web MCP 통합 과정을 단순화하기 위해 API 키에 관리자 권한이 부여된 것으로 가정합니다.

@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 환경 변수를 설정하고 npm 패키지를 실행하여 로컬에서 웹 MCP를 시작합니다.

성공 시 다음과 같은 로그가 표시됩니다:

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

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

60개 이상의 도구를 구동하기 위해 Web MCP는 이 두 Bright Data 제품에 의존합니다.

존이 생성되었는지 확인하려면 Bright Data 대시보드에 로그인하세요. “프록시 및 스크래핑 인프라”페이지로 이동하면 테이블에서 두 존을 확인할 수 있습니다:

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

참고: API 토큰에 관리자 권한이 없는 경우 두 영역이 생성되지 않습니다. 이 경우 GitHub에 설명된 대로 환경 변수를 통해 영역 이름을 수동으로 설정하고 구성해야 합니다.

기본적으로 MCP 서버는 search_engine 및 scrape_as_markdown 도구(및 해당 배치 버전)만 노출합니다. 이 도구들은 Web MCP 무료 계층에 포함되어 있으므로 비용 없이 사용할 수 있습니다.

브라우저 자동화 및 구조화된 데이터 피드와 같은 고급 도구를 사용하려면 Pro 모드를 활성화해야 합니다. 이를 위해 Web MCP 시작 전에 PRO_MODE="true" 환경 변수를 설정하세요:

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개 이상의 모든 도구를 사용할 수 있게 하지만, 무료 요금제에 포함되지 않으며 추가 요금이 부과됩니다.

훌륭합니다! 방금 웹 MCP 서버가 시스템에서 실행되는지 확인했습니다. 스크립트를 구성하여 서버를 실행하고 연결할 예정이므로 MCP 프로세스를 종료하세요.

4단계: 웹 MCP에 연결하기

Python 스크립트가 STDIO를 통해 웹 MCP 서버에 연결하도록 지시하세요.

먼저 이전에 획득한 Bright Data API 키를 .env 파일에 추가하세요:

BRIGHT_DATA_API_KEY="<YOUR_BRIGHT_DATA_API_KEY>"

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

agent.py에서 API 키를 다음과 같이 로드하세요:

BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

그런 다음 STDIO 연결을 구성하기 위해 StdioServerParameters 객체를 정의하세요:

from mcp import StdioServerParameters

server_parameters = StdioServerParameters(
    command="npx",
    args=["-y", "@brightdata/mcp"],
    env={
      "API_TOKEN": BRIGHT_DATA_API_KEY,
      "PRO_MODE": "true", # 선택 사항
    },
)

이 설정은 API 토큰에 환경 변수를 사용하는 이전의 npx 명령어를 반영합니다. API_TOKEN은 필수인 반면 PRO_MODE는 선택 사항입니다.

MCPClient 인스턴스를 사용하여 이러한 연결 설정을 적용하고 서버에서 노출된 도구 목록을 가져옵니다:

from smolagents import MCPClient

with MCPClient(server_parameters, structured_output=True) as tools:

이제 agent.py 스크립트가 Web MCP 프로세스를 실행하고 STDIO를 통해 연결합니다. 결과는 모든 smolagents AI 에이전트에 전달할 수 있는 도구 배열입니다.

사용 가능한 도구를 출력하여 연결을 확인하세요:

for bright_data_tool in bright_data_tools:
    print(f"TOOL: {bright_data_tool.name} - {bright_data_tool.description}n")

Pro 모드가 비활성화된 상태로 스크립트를 실행하면 제한된 도구 세트가 표시됩니다:

The list of tools with Pro mode disabled

프로 모드를 활성화하면 60개 이상의 모든 도구가 표시됩니다:

훌륭합니다! 이는 웹 MCP 통합이 정상적으로 작동함을 확인해 줍니다.

단계 #5: LLM 통합 정의

이제 스크립트가 도구에 접근할 수 있지만, 에이전트에는 ‘두뇌’도 필요합니다. 즉, LLM 서비스 연결을 구성할 때입니다.

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

GEMINI_API_KEY="<YOUR_GEMINI_API_KEY>"

그런 다음 agent.py 파일에서 이를 불러옵니다:

GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

다음으로 Gemini API에 연결할 OpenAIServerModel 인스턴스를 정의합니다:

from smolagents import OpenAIServerModel

model = OpenAIServerModel(
    model_id="gemini-2.5-flash",
    # Google Gemini OpenAI 호환 API 기본 URL
    api_base="https://generativelanguage.googleapis.com/v1beta/openai/",
    api_key=GEMINI_API_KEY,
)

OpenAI용 모델 클래스를 사용 중이더라도 이 방법은 작동합니다. 이는 설정한 특정 api_base 덕분에 가능하며, 이를 통해 Gemini 통합을 위한 OpenAI 호환 엔드포인트에 접근할 수 있습니다. 멋지네요!

6단계: 웹 MCP 도구로 AI 에이전트 생성하기

이제 smolagents 코드 AI 에이전트를 생성할 모든 구성 요소를 갖추셨습니다. 웹 MCP 도구와 LLM 엔진을 사용하여 에이전트를 정의하세요:

from smolagents import CodeAgent

agent = CodeAgent(
  model=model,
  tools=tools,
  stream_outputs=True,
)

CodeAgent는 smolagents의 주요 AI 에이전트 유형입니다. 이 에이전트는 작업을 수행하고 과제를 해결하기 위한 Python 코드 스니펫을 생성합니다. 이 접근법의 장단점은 다음과 같습니다:

장점:

표현력 우수: 복잡한 논리, 제어 흐름 처리 및 여러 도구 결합이 가능합니다. 또한 루프, 변환, 추론 등을 지원합니다.
유연성: 모든 작업을 사전 정의할 필요가 없으며, 새로운 작업과 도구를 동적으로 생성할 수 있습니다.
자발적 추론: 다단계 문제나 동적 의사 결정에 적합합니다.

단점:

오류 발생 위험: 처리해야 할 Python 구문 오류나 예외가 발생할 수 있음.
예측 불가능성: 결과가 예상치 못하거나 안전하지 않을 수 있음.
안전한 환경 필요: 안전한 실행 환경에서 실행되어야 합니다.

이제 에이전트를 실행하고 작업을 수행하도록 하면 됩니다!

7단계: 에이전트에서 작업 실행하기

에이전트의 웹 데이터 검색 기능을 테스트하려면 적절한 프롬프트를 작성해야 합니다. 예를 들어, YouTube 동영상 댓글의 감정을 분석하고 싶다고 가정해 보겠습니다.

웹 MCP 도구가 댓글을 가져오고, CodeAgent가 생성한 Python 스크립트가 감정 분석을 수행합니다. 마지막으로 코드가 실행됩니다. 생성된 Python 코드를 보유하는 것은 프로세스를 이해하고 향후 확장을 용이하게 하는 데에도 유용합니다.

에이전트에서 다음과 같은 프롬프트를 실행하여 이를 달성하세요:

prompt = """
다음 YouTube 동영상에서 상위 10개 댓글을 검색하세요:

실제 댓글 발췌문과 함께 감정 분석을 포함한 간결한 보고서를 제공하세요
"""

# 에이전트에서 프롬프트 실행
agent.run(prompt)

입력 동영상은 커뮤니티에서 호평받지 못한 비디오 게임 ‘블랙 옵스 7’의 예고편 발표 영상입니다.

대부분의 댓글이 상당히 편향되어 있으므로, 감정 분석 결과는 주로 부정적인 반응을 강조할 것으로 예상됩니다.

단계 #8: 모든 것을 통합하기

현재 agent.py 파일에는 다음 내용이 포함되어야 합니다:

# pip install "smolagents[mcp,openai]" python-dotenv
from dotenv import load_dotenv
import os
from smolagents import OpenAIServerModel, MCPClient, CodeAgent, ToolCallingAgent
from mcp import StdioServerParameters

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

# 환경 변수에서 API 키 읽기
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

server_parameters = StdioServerParameters(
    command="npx",
    args=["-y", "@brightdata/mcp"],
    env={
      "API_TOKEN": BRIGHT_DATA_API_KEY,
      "PRO_MODE": "true", # 선택 사항
    },
)

# Gemini 연결 초기화
model = OpenAIServerModel(
    model_id="gemini-2.5-flash",
    # Google Gemini OpenAI 호환 API 기본 URL
    api_base="https://generativelanguage.googleapis.com/v1beta/openai/",
    api_key=GEMINI_API_KEY,
)

# MCP 클라이언트 초기화 및 도구 가져오기
with MCPClient(server_parameters, structured_output=True) as tools:
  # MCP 도구로 확장된 AI 에이전트 정의
  agent = CodeAgent(
    model=model,
    tools=tools,
    stream_outputs=True,
  )

  prompt = """
  다음 YouTube 동영상에서 상위 10개 댓글을 가져옵니다:
  
  실제 댓글 발췌문과 함께 감정 분석을 포함한 간결한 보고서를 제공하세요
  """

  # 에이전트에서 프롬프트 실행
  agent.run(prompt)

약속대로 smolagents는 기대에 부응하며, 50줄 미만의 코드로 MCP 통합이 가능한 완전한 AI 에이전트를 구축할 수 있게 합니다.

다음 명령어로 테스트하세요:

python agent.py

웹 MCP에 대해 Pro 모드가 활성화된 상태로 실행한다고 가정합니다. 결과는 다음과 같은 다단계 출력으로 나타납니다:

The Step 1 produced by the smolagents AI agent

프롬프트에 기반하여 에이전트가 web_data_youtube_comments 웹 MCP 도구를 성공적으로 선택했음을 확인하세요. 목표 달성을 위해 올바른 인수로 호출했습니다. 해당 도구는 “구조화된 유튜브 댓글 데이터를 빠르게 읽습니다. 유효한 유튜브 동영상 URL이 필요합니다. 캐시 조회 방식이므로 스크래핑보다 안정적일 수 있습니다”라고 설명됩니다. 따라서 올바른 결정을 내렸습니다!

도구가 댓글 데이터를 반환한 후, 보고서 생성을 위한 2단계가 시작됩니다:

이 단계에서는 최종 감정 분석 보고서를 생성합니다. 특히 CodeAgent는 보고서 생성을 위한 모든 Python 코드를 생성하고, web_data_youtube_comments가 가져온 데이터에 대해 이를 실행합니다.

이러한 접근 방식은 AI가 출력을 생성하는 데 사용한 프로세스를 명확히 이해할 수 있게 하여, LLM의 일반적인 “블랙박스” 효과를 상당 부분 제거합니다.

결과는 다음과 같을 것입니다:

예상대로 감정 분석 결과는 대체로 부정적입니다.

보고서에 언급된 댓글은 해당 동영상 YouTube 페이지에서 볼 수 있는 내용과 정확히 일치합니다:

YouTube 스크래핑을 시도해 본 적이 있다면, 봇 방지 보호 장치와 필수 사용자 상호작용으로 인해 얼마나 어려운지 잘 알 것입니다. 이는 일반적인 LLM이 처리할 수 없는 부분으로, Bright Data의 Web MCP를 smolagents AI 에이전트에 통합하는 것의 강력함과 효과성을 보여줍니다.

다양한 입력 프롬프트로 자유롭게 실험해 보세요. Bright Data 웹 MCP의 광범위한 도구들을 활용하면 다양한 실제 사용 사례를 해결할 수 있습니다.

자, 이제 보셨죠! Bright Data의 Web MCP와 Python 기반 smolagents 코드 AI 에이전트를 결합한 강력한 성능을 확인하셨습니다.

결론

이 블로그 포스트에서는 smolagents를 사용해 코드 기반 AI 에이전트를 구축하는 방법을 배웠습니다. 무료 티어도 제공하는 Bright Data의 Web MCP 도구로 이를 강화하는 방법도 확인했습니다.

이러한 통합을 통해 에이전트에 웹 검색, 구조화된 데이터 추출, 실시간 웹 데이터 피드 접근, 자동화된 웹 상호작용 등의 기능을 부여할 수 있습니다. 더욱 정교한 AI 에이전트를 생성하려면 Bright Data 생태계 내에서 제공되는 다양한 AI 지원 제품 및 서비스를 살펴보세요.

지금 바로 Bright Data 계정을 생성하고 웹 데이터 도구로 실험을 시작해 보세요!

문의하기 무료 체험 시작하기

Bright Data의 Web MCP를 smolagents에 통합하십시오.