LangGraph + Scrapeless: Conecte Ferramentas da Web ao Vivo ao Seu Grafo de Agentes

TL;DR:

• O LangGraph carrega as ferramentas do Servidor MCP Scrapeless através dos langchain-mcp-adapters e entrega todas as 21 a um grafo de agente, de scrape_markdown a um conjunto completo de navegador.
• MultiServerMCPClient.get_tools executa o handshake e retorna as ferramentas; nenhuma chave de provedor de modelo é necessária para carregá-las ou para chamar uma diretamente.
• langchain-mcp-adapters retorna cada resultado da ferramenta como uma lista de blocos de conteúdo, então você lê result[0]["text"] em vez de converter a lista para string.
• O agente em si é construído com from langchain.agents import create_agent, a substituição atual do obsoleto create_react_agent.
• Apenas o grafo create_agent e sua execução ainvoke precisam de uma chave de modelo; carregar e chamar as ferramentas não precisam.
• Comece no plano gratuito do Scrapeless e dê ao seu grafo ferramentas reais da web.

O LangGraph constrói um agente como um grafo: uma máquina de estado que faz loop entre o modelo e suas ferramentas até que a tarefa esteja concluída. Esse design é tão útil quanto as ferramentas no grafo, e um agente LangGraph básico não tem nenhuma que acesse a web ao vivo. O Protocolo de Contexto do Modelo preenche essa lacuna. Aponte o adaptador MCP do LangGraph para um servidor e cada ferramenta que ele expõe se torna uma ferramenta LangChain que seu grafo pode chamar.

Este guia conecta o LangGraph ao Servidor MCP Scrapeless, carrega suas 21 ferramentas, chama uma de verdade e mostra exatamente onde uma chave de provedor de modelo se torna necessária. O carregamento da ferramenta e a chamada direta são verificadas contra o servidor ao vivo; a etapa de geração é marcada como o único pré-requisito que precisa.

Por que Scrapeless MCP

O Servidor MCP Scrapeless expõe ferramentas de web scraping e de navegador que um agente pode chamar diretamente, então a camada de scraping não é algo que você constrói ou hospeda. Uma conexão serve 21 ferramentas: scrape_markdown e scrape_html para conteúdo, google_search e google_trends para dados de busca, scrape_screenshot para capturas, e um conjunto completo browser_* que aciona um navegador em nuvem. O LangGraph já tem uma forte história de MCP através dos langchain-mcp-adapters, que transforma essas ferramentas em ferramentas LangChain padrão sem código de cola.

As ferramentas browser_* acionam o navegador em nuvem Scrapeless, então um agente pode navegar por uma página interativa e ler o que é renderizado, tudo na infraestrutura Scrapeless em vez de um pool de navegador local. Se você estiver usando apenas LangChain em vez de LangGraph, o post LangChain + Scrapeless MCP cobre o mesmo servidor desse lado.

Pré-requisitos

• Python 3.10 ou posterior.
• Uma chave de API Scrapeless do painel, exportada como SCRAPELESS_API_KEY.
• Uma chave de provedor de modelo (como OPENAI_API_KEY) apenas para a execução do agente. Carregar e chamar as ferramentas não precisa de uma.

Instalação

Instale o LangGraph, LangChain e o adaptador MCP.

pip install langgraph langchain langchain-mcp-adapters

Defina sua chave Scrapeless no shell. Use a chave real em tempo de execução e mantenha o espaço reservado fora do seu código-fonte.

export SCRAPELESS_API_KEY="sk_sua_chave_aqui"

Carregar as Ferramentas

MultiServerMCPClient aceita um mapeamento de nomes de servidores para configurações de conexão. Cada configuração nomeia o transporte, a URL e os cabeçalhos; a chave Scrapeless vai no cabeçalho x-api-token. get_tools executa o handshake e retorna as ferramentas como ferramentas LangChain.

import asyncio
import os

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
    {
        "scrapeless": {
            "url": "https://api.scrapeless.com/mcp",
            "transport": "streamable_http",
            "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
        }
    }
)


async def main() -> None:
    tools = await client.get_tools()
    names = sorted(t.name for t in tools)
    print("contador de ferramentas:", len(names))
    print("ferramentas:", ", ".join(names))


asyncio.run(main())

O servidor ao vivo retorna 21 ferramentas, carregadas apenas com a chave Scrapeless definida.

contador de ferramentas: 21
ferramentas: browser_click, browser_close, browser_create, browser_get_html, browser_get_text, browser_go_back, browser_go_forward, browser_goto, browser_press_key, browser_screenshot, browser_scroll, browser_scroll_to, browser_snapshot, browser_type, browser_wait, browser_wait_for, google_search, google_trends, scrape_html, scrape_markdown, scrape_screenshot

O cliente se chama MultiServerMCPClient porque federativiza vários servidores MCP ao mesmo tempo; aqui ele possui um servidor, e adicionar outro é outra entrada no mapeamento, não uma mudança no agente. A camada de transporte e mensagem segue a especificação do Protocolo de Contexto de Modelo, que se baseia na especificação JSON-RPC 2.0.

Chame uma Ferramenta

Chame uma ferramenta manualmente antes de conectá-la a um gráfico. Cada ferramenta carregada é uma ferramenta LangChain com um método ainvoke, então você passa os argumentos e lê o resultado. Um detalhe é importante: o adaptador retorna uma lista de blocos de conteúdo, não uma string simples, então pegue o texto do primeiro bloco.

import asyncio
import os

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
    {
        "scrapeless": {
            "url": "https://api.scrapeless.com/mcp",
            "transport": "streamable_http",
            "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
        }
    }
)


async def main() -> None:
    tools = await client.get_tools()
    scrape_markdown = next(t for t in tools if t.name == "scrape_markdown")
    result = await scrape_markdown.ainvoke({"url": "https://quotes.toscrape.com/"})
    # langchain-mcp-adapters retorna uma lista de blocos de conteúdo; pegue o bloco de texto
    text = result[0]["text"] if isinstance(result, list) and result else str(result)
    print("caracteres em markdown:", len(text))
    print("contém uma citação:", "O mundo como o criamos" in text)


asyncio.run(main())

A chamada retorna a página como Markdown, e a verificação do conteúdo confirma que uma citação real está presente.

caracteres em markdown: 4308
contém uma citação: True

Ler result[0]["text"] é a parte que o código ingênuo erra: transformar toda a lista em string dá a você um repr Python com sequências de escape, não o Markdown limpo. O guia do adaptador LangChain MCP documenta o cliente e a forma do resultado em detalhes.

Construa o Gráfico do Agente

Com as ferramentas carregadas, o agente é uma única chamada. create_agent constrói um gráfico no estilo ReAct que faz loop entre o modelo e as ferramentas, e é a atual substituição para o obsoleto create_react_agent. Este é o passo que necessita de uma chave de provedor de modelo: o gráfico executa o modelo, e o modelo decide quando chamar scrape_markdown ou qualquer outra ferramenta.

Nota: construir e executar o gráfico precisa de uma chave de provedor de modelo, como OPENAI_API_KEY, que não está definida aqui. Carregar as 21 ferramentas e a chamada direta scrape_markdown acima funcionam sem isso. Este bloco é mostrado com sua forma exata; apenas a troca de ida e volta do modelo é uma lacuna pré-requisito.

from langchain.agents import create_agent


async def run_graph(tools) -> None:
    agent = create_agent("openai:gpt-4o", tools)
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "Busque https://quotes.toscrape.com/ com scrape_markdown e liste as três primeiras citações com autores."}]}
    )
    print(result["messages"][-1].content)

No tempo de execução, o gráfico passa o prompt para o modelo, o modelo chama scrape_markdown com a URL, a ferramenta retorna o Markdown que a chamada direta já demonstrou, e o modelo escreve a resposta. As ferramentas são os mesmos objetos, quer o modelo as chame ou você as chame.

Conclusão

LangGraph mais o Servidor Scrapeless MCP é um caminho curto de um gráfico simples para um que lê a web ao vivo. MultiServerMCPClient carrega as 21 ferramentas, ainvoke prova que uma funciona e mostra como ler seus blocos de conteúdo, e create_agent transforma as ferramentas em um gráfico em execução. Apenas esse último passo precisa de uma chave de modelo, então você pode carregar e testar toda a superfície da ferramenta primeiro. Comece com os scripts acima, limite as ferramentas ao que o gráfico precisa e deixe o modelo conduzir.

Crie uma conta gratuita no Scrapeless para obter uma chave de API, e confira os preços do Scrapeless ao planejar um agente recorrente.

FAQ

Q: O LangGraph precisa de uma chave de modelo para carregar ferramentas MCP?

Não. MultiServerMCPClient.get_tools executa o handshake e retorna as ferramentas apenas com a chave da API Scrapeless definida, e cada ferramenta pode ser chamada diretamente com ainvoke. Uma chave de provedor de modelo é necessária apenas quando você constrói e executa o gráfico do agente com create_agent, porque é quando o próprio modelo decide quais ferramentas chamar.

Q: Por que o resultado da ferramenta volta como uma lista em vez de uma string?
langchain-mcp-adapters retorna cada resultado da ferramenta MCP como uma lista de blocos de conteúdo, que é como o MCP representa a saída da ferramenta. Leia o texto do primeiro bloco com result[0]["text"]; transformar toda a lista em string fornece um repr com sequências de escape, em vez do conteúdo limpo.

Q: Devo usar create_react_agent ou create_agent?

Use create_agent de langchain.agents. create_react_agent foi removido de langgraph.prebuilt na LangGraph 1.0 e agora emite um aviso de depreciação, então o caminho atual, sem avisos, é from langchain.agents import create_agent com os mesmos argumentos de modelo e ferramentas.

Q: Para que serve o MultiServerMCPClient se eu só tenho um servidor?

O cliente foi projetado para federar vários servidores MCP ao mesmo tempo, mas funciona com um único servidor como um mapeamento de uma entrada. Usá-lo agora significa que adicionar um segundo servidor mais tarde é apenas uma entrada a mais na configuração, sem alteração na forma como o agente consome as ferramentas.

Q: Como faço para dar ao gráfico apenas algumas das ferramentas?

get_tools retorna uma lista, então filtre-a antes de passá-la para create_agent. Passar ao gráfico apenas scrape_markdown e google_search é mais seguro do que o conjunto completo de 21 ferramentas quando a tarefa precisa apenas de conteúdo e pesquisa.

Q: A raspagem através das ferramentas está sujeita às regras do destino?

Sim. As ferramentas acessam páginas públicas, e você continua responsável por respeitar os termos de cada destino e suas diretivas do Protocolo de Exclusão de Robots. Mantenha o volume controlado e os dados públicos, e limite o gráfico às ferramentas que a tarefa realmente necessita.