Integre el MCP Web de Bright Data en smolagents

En esta entrada del blog, aprenderá:

• Qué es smolagents y por qué está ganando tanta popularidad.
• Cómo se basan sus agentes en la ejecución de herramientas y cómo recuperar herramientas a través de Web MCP de Bright Data.
• Cómo integrar herramientas Web MCP en smolagents para construir un agente de código IA.

¡Vamos a sumergirnos!

¿Qué es smolagents?

smolagents es una librería Python ligera que permite construir potentes agentes de IA con un código mínimo. Lo que la hace única es su CodeAgent, que escribe las acciones necesarias para ejecutar una petición como fragmentos ejecutables de código Python (en lugar de devolver sólo una respuesta textual).

Este enfoque mejora la eficiencia, reduce las llamadas LLM y permite a los agentes interactuar directamente con herramientas y entornos de forma segura a través de la ejecución sandboxed. La comunidad ha adoptado este nuevo enfoque para crear agentes de IA, como demuestran las 23.000 estrellas que ha recibido la biblioteca en GitHub en tan solo unos meses:

Tenga en cuenta que smolagents es:

1. Modelo agnóstico, compatible con OpenAI, Anthropic, transformadores locales, o cualquier LLM en el Hugging Face Hub.
2. Modalidad agnóstica, compatible con texto, visión, audio y vídeo.
3. Herramienta agnóstica, compatible con herramientas de servidores MCP, LangChain o Hub Spaces.

Más información sobre la filosofía de esta biblioteca en el anuncio publicado en el blog de Hugging Face.

Por qué smolagents impulsa el uso de herramientas

Los LLM están limitados por los datos con los que fueron entrenados. Pueden generar respuestas, contenido, código o multimedia basándose en ese conocimiento. Esto las hace potentes, sin duda, pero también representa una de las mayores limitaciones de la IA actual.

smolagents lo soluciona proporcionando agentes construidos en torno a herramientas. Esto es tan importante que cada clase de agente de la biblioteca acepta una lista de herramientas como argumento obligatorio. Gracias a la llamada a herramientas, su modelo de IA puede interactuar con el entorno y realizar tareas más allá de la generación de contenidos.

En particular, recuerde que smolagents puede conectarse a herramientas de servidores MCP, LangChain o incluso un Hub Space. También admite llamadas a herramientas estándar basadas en JSON/texto.

Ahora bien, ¿qué le falta a la IA típica de hoy en día? Datos precisos y recientes y la capacidad de interactuar con páginas web como los humanos. Eso es precisamente lo que ofrecen las herramientas Web MCP de Bright Data.

El Web MCP es un servidor de código abierto que ofrece más de 60 herramientas preparadas para la IA, todas ellas impulsadas por la infraestructura de Bright Data para la interacción web y la recopilación de datos. Incluso en la versión gratuita, tendrá acceso a dos herramientas revolucionarias:

Además de éstas, Web MCP expone herramientas para la interacción en un navegador en la nube y docenas de herramientas especializadas para la recopilación de datos estructurados a través de plataformas como YouTube, Amazon, LinkedIn, TikTok, Yahoo Finance, y más. Descubra más en la página oficial de GitHub.

¡Vea Web MCP en acción con smolagents!

Cómo ampliar un agente de código IA smolagents con herramientas Web MCP

En esta sección del tutorial, aprenderá a crear un agente de IA smolagents que se integre con Bright Data Web MCP. En concreto, el agente utilizará las herramientas expuestas por el servidor MCP para recuperar datos web sobre la marcha y realizar análisis de sentimiento sobre ellos.

Nota: Esto es sólo un ejemplo, y puede adaptarlo fácilmente a otros casos de uso cambiando la solicitud de entrada.

Siga las instrucciones a continuación.

Requisitos previos

Para seguir este tutorial, asegúrate de tener

• Python 3.10+ instalado localmente.
• Node.js instalado en tu máquina (recomendamos la última versión LTS) para la ejecución de Web MCP.
• Una clave API Gemini (o una clave API de cualquiera de los otros modelos soportados).

También necesitará una cuenta de Bright Data con una clave API. No se preocupe, ya que le guiaremos al respecto en breve. También será útil tener un conocimiento básico del funcionamiento de MCP y de las herramientas proporcionadas por Web MCP.

Paso #1: Configuración del Proyecto

Abre el terminal y crea una nueva carpeta para tu proyecto smolagents:

mkdir smolagents-mcp-agent

smolagents-mcp-agent/ contendrá el código Python para su agente IA extendido a través de las herramientas Web MCP.

A continuación, entre en el directorio del proyecto e inicialice un entorno virtual dentro de él:

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

Añade un nuevo archivo llamado agent.py. La estructura de archivos de tu proyecto debería ser ahora

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

agent. py representará tu archivo Python principal y contendrá la definición del agente IA.

Cargue la carpeta del proyecto en su IDE de Python favorito. Recomendamos Visual Studio Code con la extensión Python o PyCharm Community Edition.

Es hora de activar el entorno virtual que creaste anteriormente. En Linux o macOS, dispara:

source .venv/bin/activate

Equivalentemente, en Windows, ejecuta

.venv/Scripts/activate

Con el entorno virtual activado, instala las librerías PyPI necesarias:

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

Las dependencias son:

• "smolagents[mcp,openai]": El paquete smolagent, ampliado con secciones para la integración con MCP y la conexión con cualquier proveedor que ofrezca APIs similares a OpenAI.
• python-dotenv: Para leer variables de entorno desde un fichero .env local.

¡Listo! Ya dispone de un entorno Python para el desarrollo de agentes de IA con smolagents.

Paso #2: Configurar la lectura de variables de entorno

Su agente se conectará a servicios de terceros como Gemini y Bright Data. Para autenticar esas conexiones, necesitas establecer algunas claves API. Codificarlas en el archivo agent.py es un problema de código, ya que puede crear problemas de seguridad. Por lo tanto, configure su script para leer los secretos de las variables de entorno.

Esta es exactamente la razón por la que instalamos el paquete python-dotenv. En tu archivo agent.py, importa la librería y llama a load_dotenv() para cargar tus variables de entorno:

from dotenv import load_dotenv

cargar_dotenv()

Ahora tu script puede acceder a las variables de entorno desde un archivo .env local.

Añada un archivo .env al directorio de su proyecto:

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

A continuación, puede acceder a las variables de entorno en su código utilizando:

import os

os.getenv("NOMBRE_ENTORNO")

¡Genial! Ahora su script carga de forma segura secretos de integración de terceros a partir de variables de entorno.

Paso 3: Pruebe el MCP web de Bright Data localmente

Antes de configurar la conexión al MCP Web de Bright Data, asegúrese de que su máquina puede ejecutar el servidor. Esto es necesario porque indicará a smolagents que inicie el MCP web localmente. Su agente se conectará a él a través de STDIO.

Si no tiene una cuenta Bright Data, cree una nueva. Si ya la tiene, inicie sesión. Para una configuración rápida, siga las instrucciones de la sección “MCP” de su cuenta:

De lo contrario, para obtener más orientación, siga las instrucciones siguientes.

En primer lugar, genere una clave API de Bright Data. Guárdela en un lugar seguro, ya que la necesitará en breve. En este caso, asumimos que su clave API tiene permisos de administrador, ya que esto simplifica el proceso de integración de Web MCP.

Proceda instalando Web MCP globalmente en su máquina mediante el paquete @brightdata/mcp:

npm install -g @brightdata/mcp

A continuación, comprueba que el servidor MCP local funciona lanzándolo:

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

O, de forma equivalente, en PowerShell

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

Sustituya el marcador de posición <YOUR_BRIGHT_DATA_API> por su token de API de Bright Data. Estos comandos establecen la variable de entorno API_TOKEN necesaria e inician el Web MCP localmente ejecutando su paquete npm.

Si tiene éxito, debería ver registros como éste:

En el primer inicio, Web MCP crea automáticamente dos zonas predeterminadas en su cuenta de Bright Data:

• mcp_unlocker: Una zona para Web Unlocker.
• mcp_browser: Una zona para Browser API.

Para alimentar sus más de 60 herramientas, Web MCP se basa en estos dos productos de Bright Data.

Si desea comprobar que se han creado las zonas, acceda a su panel de Bright Data. Vaya a la página “Proxies & Infraestructura de scraping” y debería ver las dos zonas en la tabla:

Nota: Si su token de API no tiene permisos de administrador, no se crearán las dos zonas. En este caso, deberá crearlas manualmente y configurar sus nombres mediante variables de entorno , tal y como se explica en GitHub.

Por defecto, el servidor MCP sólo expone las herramientas search_engine y scrape_as_markdown (y sus versiones por lotes). Estas herramientas están incluidas en el nivel gratuito de Web MCP, por lo que puedes utilizarlas sin coste alguno.

Para desbloquear las herramientas avanzadas, como las herramientas para la automatización del navegador y los feeds de datos estructurados, debes activar el modo Pro. Para ello, establezca la variable de entorno PRO_MODE="true" antes de iniciar Web MCP:

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

O, en Windows

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

El modo Pro desbloquea las más de 60 herramientas, pero no está incluido en el nivel gratuito e incurrirá en cargos adicionales.

Maravilloso. Acaba de verificar que el servidor Web MCP se ejecuta en su sistema. Cierre el proceso de MCP, ya que está a punto de configurar su script para que se inicie y se conecte a él.

Paso #4: Conectarse a Web MCP

Indique a su script Python que se conecte al servidor Web MCP a través de STDIO.

Comience agregando la clave API de Bright Data que obtuvo anteriormente a su archivo .env:

BRIGHT_DATA_API_KEY="<SU_CLAVE_API_DE_BRIGHT_DATA>"

Sustituya el marcador de posición <YOUR_BRIGHT_DATA_API_KEY> por su clave real.

En agent.py, carga la clave API con:

BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

A continuación, define un objeto StdioServerParameters para configurar la conexión STDIO:

from mcp import StdioServerParameters

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

Esta configuración refleja el comando npx anterior, utilizando la variable de entorno para el token de API. Tenga en cuenta que API_TOKEN es obligatorio, mientras que PRO_MODE es opcional.

Utilice una instancia de MCPClient para aplicar estos ajustes de conexión y recuperar la lista de herramientas expuestas por el servidor:

from smolagents import MCPClient

con MCPClient(server_parameters, structured_output=True) como tools:

Tu script agent. py lanzará ahora un proceso Web MCP y se conectará vía STDIO. El resultado es un array de herramientas que puede pasar a cualquier agente smolagents IA.

Verifique la conexión imprimiendo las herramientas disponibles:

for herramienta_datos_brillantes in herramientas_datos_brillantes:
    print(f "HERRAMIENTA: {brillante_datos_herramienta.nombre} - {brillante_datos_herramienta.descripción}")

Si ejecuta el script con el modo Pro desactivado, debería ver un conjunto limitado de herramientas:

Con el modo Pro activado, se mostrarán las más de 60 herramientas:

¡Fantástico! Esto confirma que su integración Web MCP está funcionando correctamente.

Paso #5: Definir la Integración LLM

Tu script ahora tiene acceso a las herramientas, pero tu agente también necesita un cerebro. Esto significa que es hora de configurar una conexión a un servicio LLM.

Comienza añadiendo tu clave API Gemini al archivo .env:

GEMINI_API_KEY="<TU_CLAVE_API_GEMINI>"

A continuación, cárgala en tu archivo agent.py:

GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

A continuación, define una instancia de OpenAIServerModel para conectar con las APIs de Gemini:

from smolagents import OpenAIServerModel

model = OpenAIServerModel(
    model_id="gemini-2.5-flash",
    # URL base de la API de Google Gemini compatible con OpenAI
    api_base="https://generativelanguage.googleapis.com/v1beta/openai/",
    api_key=GEMINI_API_KEY,
)

Incluso si estás utilizando una clase modelo para OpenAI, esto funcionará. Esto es gracias a la api_base específica que has establecido, que te da acceso a los puntos finales compatibles con OpenAI para la integración de Gemini. ¡Genial!

Paso 6: Crear el Agente IA con las Herramientas Web MCP

Ya tiene todos los elementos necesarios para crear un agente de IA con código smolagents. Utilice las herramientas Web MCP y el motor LLM para definir uno:

from smolagents import CodeAgent

agente = CodeAgent(
  model=modelo,
  herramientas=herramientas,
  stream_outputs=True,
)

CodeAgent es el principal tipo de agente de IA de smolagents. Genera fragmentos de código Python para realizar acciones y resolver tareas. Los pros y contras de este enfoque son:

Pros:

• Altamente expresivo: Puede manejar lógica compleja, flujo de control y combinar múltiples herramientas. Además, soporta bucles, transformaciones, razonamientos, etc.
• Flexible: No es necesario predefinir cada acción, ya que puede generar dinámicamente nuevas acciones y herramientas.
• Razonamiento emergente: Muy adecuado para problemas de múltiples pasos o toma de decisiones dinámicas.

Contras:

• Riesgo de errores: Puede producir errores de sintaxis de Python o excepciones que necesiten ser manejadas.
• Menos predecible: Las salidas pueden ser inesperadas o inseguras.
• Requiere un entorno seguro: Debe ejecutarse en un contexto de ejecución seguro.

Todo lo que queda es ejecutar el agente y dejar que ejecute las tareas.

Paso 7: Ejecutar una tarea en el agente

Para probar las capacidades de recuperación de datos web de su agente, necesita escribir un prompt apropiado. Por ejemplo, supongamos que quiere analizar el sentimiento de los comentarios en un vídeo de YouTube.

Una herramienta Web MCP recuperará los comentarios, y un script Python generado por el CodeAgent realizará el análisis de sentimiento. Por último, se ejecutará el código. Disponer del código Python generado también es útil para comprender el proceso y facilitar futuras ampliaciones.

Consiga esto ejecutando un prompt como el siguiente en su agente:

prompt = """
Recuperar los 10 comentarios principales del siguiente vídeo de YouTube:

Proporcionar un informe conciso que incluya el análisis de sentimiento, junto con extractos de los comentarios reales
"""

# Ejecutar el prompt en el agente
agent.run(prompt)

El vídeo de entrada es un tráiler de anuncio de Black Ops 7, un videojuego que no ha sido bien recibido por la comunidad.

Dado que la mayoría de los comentarios son bastante parciales, se espera que el análisis de sentimiento produzca resultados que destaquen principalmente las reacciones negativas.

Paso #8: Ponerlo todo junto

En este momento, su archivo agent.py debe contener:

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

# Cargar variables de entorno desde el archivo .env
load_dotenv()

# Leer las claves API de los envs
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", # Opcional
    },
)

# Inicializar la conexión con Gemini
model = OpenAIServerModel(
    model_id="gemini-2.5-flash",
    # URL base de la API de Google Gemini compatible con OpenAI
    api_base="https://generativelanguage.googleapis.com/v1beta/openai/",
    api_key=GEMINI_API_KEY,
)

# Inicializar el cliente MCP y recuperar las herramientas
with MCPClient(server_parameters, structured_output=True) as tools:
  # Definir el agente IA, extendido con las herramientas MCP
  agente = CodeAgent(
    model=modelo,
    tools=herramientas,
    stream_outputs=True,
  )

  prompt = """
  Recuperar los 10 comentarios principales del siguiente vídeo de YouTube:
  
  Proporciona un informe conciso que incluya un análisis de sentimiento, junto con extractos de los comentarios reales
  """

  # Ejecutar el prompt en el agente
  agent.run(prompt)

Tal y como prometía, smolagents cumple las expectativas y permite construir un agente de IA completo con integración MCP en menos de 50 líneas de código.

Pruébalo ejecutando

python agente.py

Supongamos que lo ejecutas con el modo Pro activado para el Web MCP. El resultado será una salida multipaso como esta:

Observa que, basándose en el prompt, el agente ha seleccionado correctamente la herramienta Web MCP web_data_youtube_comments. La llamó con los argumentos correctos para alcanzar el objetivo. Esa herramienta se describe como: “Leer rápidamente datos estructurados de comentarios de youtube. Requiere una URL de vídeo de youtube válida. Puede ser una búsqueda en caché, por lo que puede ser más fiable que el scraping”. Así que, ¡tomó una buena decisión!

Después de que la herramienta devolviera los datos de los comentarios, comienza el paso 2 para la generación de informes:

Este paso genera el informe final del análisis de sentimiento. En concreto, CodeAgent produce todo el código Python para generar el informe y lo ejecuta sobre los datos recuperados por web_data_youtube_comments.

Este enfoque permite entender claramente el proceso que ha seguido la IA para producir el resultado, eliminando gran parte del efecto de “caja negra” habitual de los LLM.

El resultado será algo así

Como era de esperar, el análisis del sentimiento es mayoritariamente negativo.

Observa que los comentarios a los que se hace referencia en el informe coinciden exactamente con lo que puedes ver en la página de YouTube del vídeo:

Ahora bien, si alguna vez has intentado hacer scraping en YouTube, sabes lo difícil que puede ser debido a las protecciones anti-bot y a las interacciones necesarias con el usuario. Esto es algo que los LLMs vainilla no pueden manejar, lo que demuestra el poder y la efectividad de integrar el MCP Web de Bright Data en un agente de IA smolagents.

No dude en experimentar con diferentes solicitudes de entrada. Con la amplia gama de herramientas Web MCP de Bright Data, puede abordar una gran variedad de casos de uso del mundo real.

¡Et voilà! Acaba de ver la potencia de combinar el MCP Web de Bright Data con un agente de IA de código smolagents en Python.

Conclusión

En esta entrada de blog, ha aprendido a crear un agente de IA basado en código utilizando smolagents. Ha visto cómo mejorarlo con herramientas del MCP Web de Bright Data, que incluso ofrece un nivel gratuito.

Esta integración dota a su agente de búsqueda web, extracción de datos estructurados, acceso a fuentes de datos web en directo, interacciones web automatizadas y mucho más. Para crear agentes de IA aún más sofisticados, explore la amplia gama de productos y servicios preparados para IA disponibles en el ecosistema de Bright Data.

Cree una cuenta de Bright Data hoy mismo y empiece a experimentar con nuestras herramientas de datos web.