Hugging Face smolagents + Scrapeless MCP: Crie um Web Scraper de IA em Python

Resumo:

• Um agente Hugging Face obtém 21 ferramentas web ao vivo de um endpoint MCP. Apontar ToolCollection.from_mcp para https://api.scrapeless.com/mcp fornece ao CodeAgent de smolagents controle de navegador, raspagem de página e pesquisa e tendências do Google, enquanto renderização, roteamento de proxy e anti-detecção permanecem do lado do servidor.
• O caminho hospedado é Python puro. HTTP transmitível com um cabeçalho x-api-token substitui qualquer processo de servidor local — sem Node.js, apenas pip install "smolagents[mcp]".
• A interface da ferramenta funciona antes de um modelo. Uma simples chamada de função para scrape_markdown retorna uma página ao vivo como markdown limpo — 4.249 caracteres para a página de demonstração neste guia — para que você possa testar a conexão com apenas uma chave da API Scrapeless.
• Um scraper AI extrai por significado, não por seletor. O agente lê o markdown e retorna os campos que você pede, então um redesign do site que quebraria um script de seletor CSS geralmente não lhe custa nada.
• O único pré-requisito extra é uma chave de modelo. A listagem de ferramentas, chamadas diretas de ferramentas e construção de agentes funcionam sem uma; apenas a rodada de raciocínio precisa de um token Hugging Face ou outro provedor suportado.
• Gratuito para começar. Crie sua chave de API no plano gratuito em app.scrapeless.com.

O que esta integração possibilita

Um scraper baseado em seletor é uma aposta de que a página-alvo nunca mudará, e essa aposta geralmente falha. Um scraper AI adota uma posição diferente: busque a página como texto limpo, permita que um modelo de linguagem extraia os campos que você deseja e pare de se preocupar em qual div o preço está esta semana.

smolagents é a biblioteca de pequenos agentes da Hugging Face — seus agentes escrevem Python para chamar ferramentas em vez de emitir chamadas de ferramentas JSON. O que falta em sua própria cela é uma maneira de acessar a web ao vivo. Essa é a função do Modelo de Protocolo de Contexto: a especificação do Modelo de Protocolo de Contexto define como um servidor anuncia ferramentas tipadas que qualquer cliente pode listar e invocar. Se o protocolo em si é novo para você, o primer sobre o que é MCP e como funciona cobre o conceito de ponta a ponta.

Conecte os dois e você obterá um scraper AI programático em algumas dezenas de linhas de Python: smolagents fornece o loop de raciocínio, o servidor Scrapeless MCP fornece busca, renderização e pesquisa como ferramentas chamáveis. Este guia construirá esse scraper passo a passo e mostrará exatamente quais partes funcionam com nada além de uma chave Scrapeless.

Por que Scrapeless MCP

O servidor Scrapeless MCP expõe a infraestrutura de raspagem como 21 ferramentas tipadas, e o trabalho pesado acontece no servidor, não no seu processo. scrape_html, scrape_markdown e scrape_screenshot capturam páginas únicas em diferentes formatos. Dezesseis ferramentas browser_* operam sessões de navegador em nuvem no Navegador de Raspagem — um navegador em nuvem anti-deteção alimentado por Chromium desenvolvido internamente — para trabalhos onde um agente deve clicar, digitar e rolar. google_search e google_trends cobrem a descoberta.

Três propriedades são importantes para esta construção:

• Uma chave, transporte hospedado. A mesma chave da API Scrapeless que movimenta o resto da plataforma autentica o endpoint MCP. Seu processo Python nunca inicia um navegador ou um servidor Node.
• Testabilidade sem modelo. Ferramentas listam e executam sem nenhum LLM no loop, então a integração pode ser comprovada camada por camada em vez de depurada através do raciocínio de um agente.
• Um caminho de extração priorizando markdown. A captura de markdown de uma página é uma fração do tamanho de seu HTML bruto, o que significa menos tokens por extração e menos ruído para o modelo ler. scrape_markdown retorna exatamente isso.

O mesmo endpoint também se conecta ao LangChain, se essa for a sua stack — o guia LangChain + Scrapeless MCP abrange a mesma superfície do lado do adaptador.

Pré-requisitos

• Python 3.10 ou mais recente — as execuções neste guia usaram Python 3.12.
• Uma chave da API Scrapeless do painel — a documentação do desenvolvedor cobre a criação da chave e a referência do endpoint.
• Para a ida e volta final do agente apenas: um token do Hugging Face (ou credenciais para qualquer provedor de modelo que smolagents suporte). Cada passo antes disso funciona sem ele.

Instalar e configurar

Um pacote com um extra traz a biblioteca de agentes e a infraestrutura do cliente MCP. Essas versões são as que este guia foi escrito — smolagents 1.26.0, mcp 1.27.1, mcpadapt 0.1.20:

pip install "smolagents[mcp]==1.26.0"

Exporte sua chave para que os scripts possam lê-la do ambiente em vez de do código fonte:

export SCRAPELESS_API_KEY="sk_sua_chave_aqui"

Conectar via HTTP transmissível e listar as ferramentas

A conexão é um dicionário, não um arquivo de configuração. ToolCollection.from_mcp aceita os mesmos parâmetros que o cliente HTTP transmissível subjacente, então a URL do endpoint, o nome do transporte e o cabeçalho de autenticação viajam em uma única literal:

# connect_and_list.py — handshake com o servidor MCP do Scrapeless, listar as ferramentas
import os

from smolagents import ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    names = sorted(tool.name for tool in tc.tools)
    print(f"Contagem de ferramentas: {len(names)}")
    print("\n".join(names))

O gerenciador de contexto possui o ciclo de vida da conexão: ele realiza o handshake MCP na entrada e desconecta de forma limpa na saída. Um parâmetro merece uma palavra: a especificação das ferramentas MCP permite que um servidor retorne resultados como texto simples ou como conteúdo estruturado, e as ferramentas Scrapeless retornam texto — então passe structured_output=False explicitamente. smolagents 1.26 avisa sempre que o parâmetro é omitido, porque seu padrão está programado para mudar em uma futura versão.

Um handshake correto imprime Contagem de ferramentas: 21 seguido pelos nomes: dezesseis ferramentas browser_*, google_search, google_trends, scrape_html, scrape_markdown, e scrape_screenshot.

Uma rota stdio também existe, para clientes que preferem iniciar um processo de servidor local — as mesmas 21 ferramentas por trás de um ciclo de vida diferente:

{
  "mcpServers": {
    "scrapeless": {
      "command": "npx",
      "args": ["-y", "scrapeless-mcp-server"],
      "env": { "SCRAPELESS_KEY": "sk_sua_chave_aqui" }
    }
  }
}

Para uma construção apenas em Python, o HTTP transmissível é o caminho mais curto: nada para instalar além do pip, nada para manter em execução.

Obtenha sua chave da API no plano gratuito: app.scrapeless.com

Chame scrape_markdown antes de qualquer modelo ser envolvido

Cada ferramenta na coleção é um objeto Tool chamável smolagents, então a camada de scraping pode ser exercida diretamente — sem chave de agente ou modelo envolvida:

# call_tool.py — executar uma ferramenta MCP como uma chamada de função simples
import json
import os

from smolagents import ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    tools = {tool.name: tool for tool in tc.tools}
    raw = str(tools["scrape_markdown"](url="https://quotes.toscrape.com/"))
    # A ferramenta hospedada retorna a página como uma string citada em JSON após uma
    # linha "Response:" — decodifique-a para obter o markdown em si.
    body = raw.split("\n\n", 1)[1] if raw.startswith("Response:") else raw
    text = json.loads(body) if body.startswith('"') else body
    print(f"scrape_markdown retornou {len(text):,} caracteres de markdown")
    print(text[:160])

Contra o site de demonstração de citações, isso retorna 4.249 caracteres de markdown, começando com o título da página e a primeira citação — texto legível com o chrome da página já removido. Essa única chamada é toda a camada de recuperação do scraper. Tudo depois disso é interpretação.

Anexar as ferramentas a um CodeAgent

Vincular a coleção a um agente é um construtor, e funciona antes de qualquer chamada de modelo acontecer. O objeto agente indexa cada ferramenta MCP por nome ao lado de seu final_answer embutido:

# attach_agent.py — entregar a superfície da ferramenta MCP a um CodeAgent smolagents
import os

from smolagents import CodeAgent, InferenceClientModel, ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    model = InferenceClientModel(model_id="Qwen/Qwen2.5-72B-Instruct")
    agent = CodeAgent(tools=[*tc.tools], model=model, add_base_tools=False)
    print(sorted(agent.tools.keys()))

add_base_tools=False mantém a caixa de ferramentas apenas com as ferramentas MCP, além do final_answer embutido do agente. Para um scraper que deve buscar páginas e nada mais, você pode restringi-lo ainda mais — passe apenas a ferramenta que deseja, como em tools=[t for t in tc.tools if t.name == "scrape_markdown"] — e o modelo fisicamente não pode vagar por sessões de navegador ou chamadas de pesquisa que não necessita. Uma caixa de ferramentas menor também significa um prompt de sistema menor e menos desvios do modelo.

Uso orientado por prompt: a execução do scraper de IA

A etapa de extração é um prompt, não um analisador. Você informa ao agente qual página ler e quais campos devolver, e o agente decide chamar scrape_markdown, lê o resultado e monta a resposta — smolagents descreve cada ferramenta para o modelo com entradas tipadas, a mesma estrutura que a especificação JSON Schema define para restrições de campo legíveis por máquina.

Nota: Esta etapa final é a única lacuna pré-requisito neste guia — a troca de ida e volta do agente precisa de um provedor de modelo. Defina HF_TOKEN com um token do Hugging Face (ou configure outro provedor que o smolagents suporte) antes de executá-lo. Cada bloco acima roda apenas com a chave Scrapeless.

# run_scraper.py — a troca de modelo (requer HF_TOKEN ou outro provedor)
result = agent.run(
    "Chame scrape_markdown em https://quotes.toscrape.com/ e retorne um array JSON "
    "das citações na página. Cada item deve ter exatamente estas chaves: "
    "text (string), author (string), tags (array de strings). "
    "Retorne apenas o array JSON, sem comentários."
)
print(result)

A forma do prompt controla a forma da saída. Nomear as chaves e tipos exatos, exigir "apenas o array JSON" e manter uma página por execução dá a você uma saída que pode json.loads e validar a montante. Quando um campo está faltando na página, instrua o agente a usar null em vez de inventar um valor — os modelos preenchem lacunas com confiança, a menos que seja dito para não fazê-lo.

O que você recebe de volta

Da camada de busca, você recebe markdown como uma string: o título da página como um cabeçalho, texto de link preservado entre colchetes, texto do corpo na ordem de leitura. A captura de 4.249 caracteres do site de citações começa assim:

# [Citações para Scrapar](https://quotes.toscrape.com/)

[Login](https://quotes.toscrape.com/login)

“O mundo como o criamos é um processo do nosso pensamento.

Da execução do agente, você recebe qualquer contrato que seu prompt impôs — aqui, um array JSON de objetos {text, author, tags}, um por citação na página. O valor do arranjo aparece no dia em que o site-alvo muda seus nomes de classe: o markdown ainda contém as citações, o prompt ainda nomeia os campos, e o scraper ainda retorna o mesmo esquema, enquanto um script baseado em seletores não retorna nada.

Conclusão

A integração envolve três pequenos movimentos: apontar ToolCollection.from_mcp para o endpoint hospedado, provar a camada de busca com uma chamada direta scrape_markdown, e então vincular as ferramentas a um CodeAgent e deixar um prompt fazer a extração. Cada camada é testável por conta própria, apenas a última precisa de uma chave de modelo, e a parte mais suscetível a falhas em um scraper clássico — a análise — é a parte que o modelo absorve.

Pronto para Dar ao Seu Agente uma Superfície Real da Web?

O endpoint MCP autentica com a mesma chave de API que o resto da plataforma Scrapeless — planos e volumes incluídos estão na página de preços. Crie uma chave no plano gratuito em app.scrapeless.com e o script de handshake acima imprimirá suas 21 ferramentas em menos de um minuto.

Perguntas Frequentes

Q: O que é um scraper de IA?

Um scraper de IA é um scraper que usa um modelo de linguagem para a etapa de extração, em vez de regras de análise escritas à mão. Um scraper convencional junta busca e análise a uma estrutura de página específica; um scraper de IA busca a página como texto e solicita a um modelo que retorne campos nomeados, o que continua funcionando através de mudanças de layout que quebrariam seletores.

Q: Preciso de um token do Hugging Face para chamar as ferramentas Scrapeless?

Não. Listar ferramentas, chamar scrape_markdown diretamente e construir o CodeAgent, todos autenticam apenas com a chave da API Scrapeless. O token do Hugging Face (ou chave de outro provedor) é necessário para exatamente uma coisa: a troca de raciocínio agent.run().

Q: Devo me conectar via HTTP streamable ou stdio?

Use HTTP streamable para projetos em Python: não precisa de processo local e autentica com um cabeçalho. O transporte stdio (npx -y scrapeless-mcp-server, autenticado através da variável de ambiente SCRAPELESS_KEY) se adapta a clientes MCP desktop que gerenciam os processos do servidor por conta própria. Ambos os transportes expõem a mesma superfície de ferramenta.
Q: O agente pode usar apenas uma ferramenta em vez de todas as 21?

Sim. Filtre a coleção antes de construir o agente — tools=[t for t in tc.tools if t.name == "scrape_markdown"] — e o modelo só verá essa ferramenta. Para raspadores de único propósito, essa é a forma recomendada: o prompt do sistema diminui e o modelo não pode iniciar sessões de navegador que você nunca pretendia.

Q: E quanto às páginas com muito JavaScript ou páginas atrás de desafios anti-bot?

A renderização acontece no lado do servidor, então seu código Python não muda. scrape_html e scrape_markdown lidam com páginas que precisam da execução de JavaScript, e as ferramentas browser_* dirigem sessões completas de navegador na nuvem para fluxos que exigem clicar ou digitar. O roteamento por proxy e a anti-detecção fazem parte do serviço gerenciado, em vez de algo que o agente deve considerar.

Q: Quais modelos funcionam com smolagents?

Qualquer provedor suportado pela biblioteca. InferenceClientModel cobre modelos servidos através de provedores de inferência do Hugging Face, e a biblioteca também inclui OpenAIModel, AzureOpenAIModel, AmazonBedrockModel, LiteLLMModel, e backends locais como TransformersModel — veja a referência de modelos smolagents para a lista atual. O lado MCP é independente do modelo: as ferramentas parecem idênticas, não importa qual modelo raciocina sobre elas.

Q: É legal raspar com um agente de IA?

As mesmas regras se aplicam como para qualquer raspador: colete apenas páginas públicas, respeite os termos e diretrizes de robots do site-alvo, mantenha os volumes limitados e trate quaisquer dados pessoais de acordo com as leis de privacidade que se aplicam a você. Um agente muda como a extração acontece, não o que você é permitido coletar — em caso de dúvida, consulte um advogado antes de aumentar a carga de trabalho.