Como integrar o Bright Data Web MCP com smolagents

Nesta publicação do blog, você aprenderá:

O que é smolagents e por que ele está ganhando tanta popularidade.
Como seus agentes dependem da execução de ferramentas e como recuperar ferramentas por meio do Web MCP da Bright Data.
Como integrar as ferramentas do Web MCP ao smolagents para criar um agente de código IA.

Vamos nos aprofundar!

O que é o smolagents?

O smolagents é uma biblioteca Python leve que permite criar agentes de IA avançados com o mínimo de código. O que a torna única é seu CodeAgent, que grava as ações necessárias para executar um prompt como trechos de código Python executáveis (em vez de apenas retornar uma resposta textual).

Essa abordagem aumenta a eficiência, reduz as chamadas LLM e permite que os agentes interajam diretamente com ferramentas e ambientes com segurança por meio da execução em sandbox. A comunidade adotou essa nova abordagem para a criação de agentes de IA, como evidenciado pelas 23 mil estrelas que a biblioteca recebeu no GitHub em apenas alguns meses:

Tenha em mente que a smolagents é:

Agnóstico em relaçãoao modelo, compatível com OpenAI, Anthropic, transformadores locais ou qualquer LLM no Hugging Face Hub.
Modalidade agnóstica, compatível com texto, visão, áudio e vídeo.
Independente de ferramenta, compatível com ferramentas de servidores MCP, LangChain ou Hub Spaces.

Saiba mais sobre a filosofia por trás dessa biblioteca na postagem de anúncio no blog da Hugging Face.

Por que a smolagents incentiva o uso de ferramentas

Os LLMs são limitados pelos dados em que foram treinados. Eles podem gerar respostas, conteúdo, código ou multimídia com base nesse conhecimento. Isso os torna poderosos, com certeza, mas também representa uma das maiores limitações da IA atual.

A smolagents resolve esse problema fornecendo agentes criados com base em ferramentas. Isso é tão importante que todas as classes de agentes da biblioteca aceitam uma lista de ferramentas como argumento obrigatório. Graças às chamadas de pedágio, seu modelo de IA pode interagir com o ambiente e realizar tarefas que vão além da geração de conteúdo.

Em particular, lembre-se de que os smolagents podem se conectar a ferramentas de servidores MCP, LangChain ou até mesmo de um Hub Space. Ele também é compatível com a chamada de ferramenta padrão baseada em texto/JSON.

Agora, o que está faltando na IA típica atual? Dados precisos e recentes e a capacidade de interagir com páginas da Web como os humanos. É exatamente isso que as ferramentas do Web MCP da Bright Data oferecem!

O Web MCP é um servidor de código aberto que oferece mais de 60 ferramentas prontas para IA, todas alimentadas pela infraestrutura da Bright Data para interação com a Web e coleta de dados. Mesmo no nível gratuito, você tem acesso a duas ferramentas revolucionárias:

Ferramenta	Descrição da ferramenta
`search_engine`	Recupere resultados de pesquisa do Google, Bing ou Yandex em JSON ou Markdown.
`scrape_as_markdown`	Extraia qualquer página da Web em um formato Markdown limpo, ignorando a detecção de bots e o CAPTCHA.

Além disso, o Web MCP expõe ferramentas para interação em um navegador em nuvem e dezenas de ferramentas especializadas para coleta de dados estruturados em plataformas como YouTube, Amazon, LinkedIn, TikTok, Yahoo Finance e muito mais. Saiba mais na página oficial do GitHub.

Veja o Web MCP em ação com smolagents!

Como estender um agente de código IA da smolagents com ferramentas do Web MCP

Nesta seção do tutorial, você aprenderá a criar um agente de IA do smolagents que se integra ao Bright Data Web MCP. Especificamente, o agente usará ferramentas expostas pelo servidor MCP para recuperar dados da Web em tempo real e realizar análise de sentimentos sobre eles.

Observação: esse é apenas um exemplo, e você pode adaptá-lo facilmente a outros casos de uso alterando o prompt de entrada.

Siga as instruções abaixo!

Pré-requisitos

Para seguir este tutorial, certifique-se de que você tenha:

Python 3.10+ instalado localmente.
O Node.js instalado em seu computador (recomendamos a versão mais recente do LTS) para a execução do Web MCP.
Uma chave de API Gemini (ou uma chave de API de qualquer um dos outros modelos suportados).

Você também precisará de uma conta da Bright Data com uma chave de API. Não se preocupe, pois vamos orientá-lo sobre isso em breve. Também será útil ter um conhecimento básico de como o MCP funciona e das ferramentas fornecidas pelo Web MCP.

Etapa 1: Configuração do projeto

Abra o terminal e crie uma nova pasta para seu projeto smolagents:

mkdir smolagents-mcp-agent

smolagents-mcp-agent/ conterá o código Python para seu agente IA estendido por meio de ferramentas Web MCP.

Em seguida, entre no diretório do projeto e inicialize um ambiente virtual dentro dele:

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

Adicione um novo arquivo chamado agent.py. A estrutura de arquivos em seu projeto agora deve ser:

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

O agent.py representará seu arquivo Python principal e conterá a definição do agente IA.

Carregue a pasta do projeto em seu IDE Python favorito. Recomendamos o Visual Studio Code com a extensão Python ou o PyCharm Community Edition.

É hora de ativar o ambiente virtual que você criou anteriormente. No Linux ou no macOS, dispare:

source .venv/bin/activate

De forma equivalente, no Windows, execute:

.venv/Scripts/activate

Com o ambiente virtual ativado, instale as bibliotecas PyPI necessárias:

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

As dependências são:

"smolagents[mcp,openai]": O pacote smolagent, estendido com seções para integração com MCP e conexão com qualquer provedor que ofereça APIs semelhantes à OpenAI.
python-dotenv: para ler variáveis de ambiente de um arquivo .env local.

Pronto! Agora você tem um ambiente Python para o desenvolvimento de agentes de IA com smolagents.

Etapa 2: configurar a leitura de variáveis de ambiente

Seu agente se conectará a serviços de terceiros, como Gemini e Bright Data. Para autenticar essas conexões, você precisa definir algumas chaves de API. Codificá-las em seu arquivo agent.py é um problema de código, pois isso pode criar problemas de segurança. Portanto, configure seu script para ler segredos de variáveis de ambiente.

É exatamente por isso que instalamos o pacote python-dotenv. Em seu arquivo agent.py, importe a biblioteca e chame load_dotenv() para carregar suas variáveis de ambiente:

from dotenv import load_dotenv

load_dotenv()

Seu script agora pode acessar as variáveis de ambiente de um arquivo .env local.

Adicione um arquivo .env ao diretório do seu projeto:

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

Em seguida, você pode acessar as variáveis de ambiente em seu código usando:

import os

os.getenv("ENV_NAME")

Ótimo! Seu script agora carrega com segurança segredos de integração de terceiros a partir de variáveis de ambiente.

Etapa 3: Teste o Web MCP da Bright Data localmente

Antes de configurar a conexão com o Web MCP da Bright Data, certifique-se de que sua máquina possa executar o servidor. Isso é necessário, pois você instruirá os smolagents a iniciar o Web MCP localmente. Em seguida, seu agente se conectará a ele via STDIO.

Se você não tiver uma conta da Bright Data, crie uma nova. Se tiver, basta fazer login. Para uma configuração rápida, siga as instruções na seção “MCP” da sua conta:

The “MCP” section in your Bright Data account

Caso contrário, para obter mais orientações, siga as instruções abaixo.

Primeiro, gere uma chave API da Bright Data. Guarde-a em um local seguro, pois você precisará dela em breve. Aqui, assumimos que sua chave de API tem permissões de administrador porque isso simplifica o processo de integração do Web MCP.

Prossiga instalando o Web MCP globalmente em sua máquina por meio do pacote @brightdata/mcp:

npm install -g @brightdata/mcp

Em seguida, verifique se o servidor MCP local funciona, iniciando-o:

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

Ou, de forma equivalente, no PowerShell:

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

Substitua o espaço reservado <YOUR_BRIGHT_DATA_API> pelo seu token da API da Bright Data. Esses comandos definem a variável de ambiente API_TOKEN necessária e iniciam o Web MCP localmente executando seu pacote npm.

Se for bem-sucedido, você verá registros como este:

Na primeira inicialização, o Web MCP cria automaticamente duas Zonas padrão em sua conta Bright Data:

mcp_unlocker: Uma zona para o Web Unlocker.
mcp_browser: Uma zona para a API do navegador.

Para alimentar suas mais de 60 ferramentas, o Web MCP depende desses dois produtos da Bright Data.

Se quiser verificar se as zonas foram criadas, faça login no painel de controle da Bright Data. Acesse a página “Proxies & Scraping Infrastructure” e você verá as duas zonas na tabela:

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

Observação: se seu token de API não tiver permissões de administrador, as duas zonas não serão criadas. Nesse caso, você deverá defini-las manualmente e configurar seus nomes por meio de variáveis de ambiente , conforme explicado no GitHub.

Por padrão, o servidor MCP expõe apenas as ferramentas search_engine e scrape_as_markdown (e suas versões em lote). Essas ferramentas estão incluídas na camada gratuita do Web MCP, portanto, você pode usá-las sem nenhum custo.

Para desbloquear ferramentas avançadas, como ferramentas para automação do navegador e feeds de dados estruturados, você deve ativar o modo Pro. Para fazer isso, defina a variável de ambiente PRO_MODE="true" antes de iniciar o Web MCP:

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

Ou, no Windows:

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

O modo Pro desbloqueia todas as mais de 60 ferramentas, mas não está incluído na camada gratuita e incorrerá em cobranças adicionais.

Maravilhoso! Você acabou de verificar que o servidor Web MCP é executado em seu sistema. Encerre o processo do MCP, pois você está prestes a configurar seu script para iniciar e se conectar a ele.

Etapa 4: conectar-se ao Web MCP

Instrua o script Python a se conectar ao servidor Web MCP via STDIO.

Comece adicionando a chave da API da Bright Data que você obteve anteriormente ao arquivo .env:

BRIGHT_DATA_API_KEY="<YOUR_BRIGHT_DATA_API_KEY>"

Substitua o espaço reservado <YOUR_BRIGHT_DATA_API_KEY> pela sua chave real.

Em agent.py, carregue a chave da API com:

BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

Em seguida, defina um objeto StdioServerParameters para configurar a conexão 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
    },
)

Essa configuração reflete o comando npx de antes, usando a variável de ambiente para o token da API. Observe que API_TOKEN é obrigatório, enquanto PRO_MODE é opcional.

Use uma instância do MCPClient para aplicar essas configurações de conexão e recuperar a lista de ferramentas expostas pelo servidor:

from smolagents import MCPClient

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

Seu script agent.py agora iniciará um processo Web MCP e se conectará via STDIO. O resultado é uma matriz de ferramentas que você pode passar para qualquer agente de IA da smolagents.

Verifique a conexão imprimindo as ferramentas disponíveis:

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

Se você executar o script com o modo Pro desativado, verá um conjunto limitado de ferramentas:

The list of tools with Pro mode disabled

Com o modo Pro ativado, todas as mais de 60 ferramentas serão exibidas:

Excelente! Isso confirma que a integração do Web MCP está funcionando corretamente.

Etapa 5: Definir a integração com o LLM

Seu script agora tem acesso às ferramentas, mas seu agente também precisa de um cérebro. Isso significa que é hora de configurar uma conexão com um serviço LLM.

Comece adicionando sua chave da API do Gemini ao arquivo .env:

GEMINI_API_KEY="<YOUR_GEMINI_API_KEY>"

Em seguida, carregue-a em seu arquivo agent.py:

GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

Em seguida, defina uma instância do OpenAIServerModel para se conectar às APIs do Gemini:

from smolagents import OpenAIServerModel

model = OpenAIServerModel(
    model_id="gemini-2.5-flash",
    # URL da base da API compatível com a OpenAI do Google Gemini
    api_base="https://generativelanguage.googleapis.com/v1beta/openai/",
    api_key=GEMINI_API_KEY,
)

Mesmo que você esteja usando uma classe de modelo para OpenAI, isso funcionará. Isso se deve ao api_base específico que você definiu, que lhe dá acesso a pontos de extremidade compatíveis com OpenAI para integração com o Gemini. Legal!

Etapa 6: criar o IA Agent com as ferramentas Web MCP

Agora você tem todos os blocos de construção para criar um agente de IA com código smolagents. Use as ferramentas Web MCP e o mecanismo LLM para definir um:

de smolagents import CodeAgent

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

O CodeAgent é o principal tipo de agente de IA da smolagents. Ele gera trechos de código Python para executar ações e resolver tarefas. Os prós e contras dessa abordagem são:

Prós:

Altamente expressivo: Pode lidar com lógica complexa, fluxo de controle e combinar várias ferramentas. Além disso, suporta loops, transformações, raciocínio etc.
Flexível: Não há necessidade de predefinir cada ação, pois pode gerar dinamicamente novas ações e ferramentas.
Raciocínio emergente: Adequado para problemas de várias etapas ou tomada de decisão dinâmica.

Contras:

Risco de erros: Pode produzir erros de sintaxe do Python ou exceções que precisam ser tratadas.
Menos previsível: Os resultados podem ser inesperados ou inseguros.
Requer ambiente seguro: Deve ser executado em um contexto de execução seguro.

Tudo o que resta é executar seu agente e deixá-lo executar as tarefas!

Etapa nº 7: executar uma tarefa no agente

Para testar os recursos de recuperação de dados da Web do seu agente, você precisa escrever um prompt adequado. Por exemplo, suponha que você queira analisar o sentimento dos comentários em um vídeo do YouTube.

Uma ferramenta Web MCP recuperará os comentários, e um script Python gerado pelo CodeAgent executará a análise de sentimento. Por fim, o código será executado. Ter o código Python gerado também é útil para compreender o processo e facilitar futuras extensões.

Para isso, execute um prompt como o seguinte em seu agente:

prompt = """
Recupere os 10 principais comentários do seguinte vídeo do YouTube:

Forneça um relatório conciso que inclua análise de sentimento, juntamente com trechos dos comentários reais
"""

# Executar o prompt no agente
agent.run(prompt)

O vídeo de entrada é um trailer de anúncio do Black Ops 7, um videogame que não foi bem recebido pela comunidade.

Como a maioria dos comentários é bastante tendenciosa, espera-se que a análise de sentimentos produza resultados que destaquem principalmente as reações negativas.

Etapa 8: Juntar tudo

Neste momento, seu arquivo agent.py deve conter:

# 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

# Carregar variáveis de ambiente do arquivo .env
load_dotenv()

# Ler as chaves de API dos 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 a conexão com o Gemini
model = OpenAIServerModel(
    model_id="gemini-2.5-flash",
    # URL da base da API compatível com o Google Gemini OpenAI
    api_base="https://generativelanguage.googleapis.com/v1beta/openai/",
    api_key=GEMINI_API_KEY,
)

# Inicializar o cliente MCP e recuperar as ferramentas
with MCPClient(server_parameters, structured_output=True) as tools:
  # Defina o agente de IA, estendido com as ferramentas do MCP
  agente = CodeAgent(
    model=model,
    tools=tools,
    stream_outputs=True,
  )

  prompt = """
  Recupere os 10 principais comentários do seguinte vídeo do YouTube:
  
  Forneça um relatório conciso que inclua análise de sentimento, juntamente com trechos dos comentários reais
  """

  # Executar o prompt no agente
  agent.run(prompt)

Como prometido, o smolagents atende às expectativas e permite que você crie um agente de IA completo com integração de MCP em menos de 50 linhas de código.

Teste-o executando:

python agent.py

Suponha que você esteja executando-o com o modo Pro ativado para o Web MCP. O resultado será uma saída de várias etapas como esta:

The Step 1 produced by the smolagents AI agent

Observe que, com base no prompt, o agente selecionou com êxito a ferramenta Web MCP web_data_youtube_comments. Ele a chamou com os argumentos corretos para atingir a meta. Essa ferramenta é descrita como: “Ler rapidamente dados estruturados de comentários do YouTube. Requer um URL de vídeo válido do YouTube. Isso pode ser uma pesquisa de cache, portanto, pode ser mais confiável do que a raspagem.” Portanto, foi uma boa decisão!

Depois que a ferramenta retornou os dados dos comentários, começou a Etapa 2 para a geração de relatórios:

Essa etapa gera o relatório final da análise de sentimentos. Em particular, o CodeAgent produz todo o código Python para gerar o relatório e o executa nos dados recuperados por web_data_youtube_comments.

Essa abordagem permite que você entenda claramente o processo que a IA usou para produzir o resultado, removendo grande parte do efeito de “caixa preta” usual dos LLMs.

O resultado será algo como:

Como esperado, a análise de sentimento é amplamente negativa.

Observe que os comentários mencionados no relatório correspondem exatamente ao que você pode ver na página do vídeo no YouTube:

Agora, se você já tentou fazer scraping do YouTube, sabe como isso pode ser difícil devido às proteções antibot e às interações necessárias com o usuário. Isso é algo com que os LLMs comuns não conseguem lidar, o que demonstra o poder e a eficácia da integração do Web MCP da Bright Data em um agente de IA smolagents.

Sinta-se à vontade para experimentar diferentes solicitações de entrada. Com a ampla gama de ferramentas do Web MCP da Bright Data, você pode abordar uma variedade de casos de uso do mundo real.

E pronto! Você acabou de ver o poder de combinar o Web MCP da Bright Data com um agente de IA de código smolagents em Python.

Conclusão

Nesta postagem do blog, você aprendeu a criar um agente de IA baseado em código usando smolagents. Você viu como aprimorá-lo com ferramentas do Web MCP da Bright Data, que oferece até mesmo um nível gratuito.

Essa integração capacita seu agente com pesquisa na Web, extração de dados estruturados, acesso a feeds de dados da Web ao vivo, interações automatizadas na Web e muito mais. Para criar agentes de IA ainda mais sofisticados, explore a gama mais ampla de produtos e serviços prontos para IA disponíveis no ecossistema da Bright Data.

Crie uma conta na Bright Data hoje mesmo e comece a fazer experiências com nossas ferramentas de dados da Web!

Contate-nos Teste grátis