AutoGen + Scrapeless: Dê aos seus agentes ferramentas web ao vivo via MCP

TL;DR:

• O AutoGen carrega as ferramentas do Scrapeless MCP Server com mcp_server_tools e entrega todas as 21 a um agente, desde scrape_markdown até um conjunto completo de navegador.
• A conexão é um objeto, StreamableHttpServerParams, que carrega o endpoint e o cabeçalho x-api-token; nenhum cliente de modelo é necessário para carregar ou chamar as ferramentas.
• Cada ferramenta chega como um StreamableHttpMcpToolAdapter, então você pode chamar uma diretamente com run_json({...}, CancellationToken()) antes de conectar ao agente.
• Apenas AssistantAgent.run precisa de uma chave de provedor de modelo; carregar as ferramentas e chamar scrape_markdown não precisam.
• Uma chamada de scrape_markdown retorna a página alvo como Markdown, pronta para o agente raciocinar.
• Comece com o plano gratuito do Scrapeless e dê aos seus agentes AutoGen ferramentas reais da web.

AutoGen é a estrutura da Microsoft para aplicações multi-agente, e seus agentes são tão capacitados quanto as ferramentas que possuem. De fábrica, nenhuma dessas ferramentas alcança a web ao vivo. O Protocolo de Contexto de Modelo fecha essa lacuna: aponte o AutoGen para um servidor MCP e cada ferramenta que ele expõe se torna uma ferramenta AutoGen que seu agente pode chamar, com a mesma interface que qualquer ferramenta de função.

Este guia conecta o AutoGen ao Scrapeless MCP Server, carrega suas 21 ferramentas, chama uma de verdade e anexa o conjunto a um AssistantAgent — tudo verificado contra o servidor ao vivo. O único passo que precisa de uma chave de provedor de modelo é a chamada de geração do agente, e este post é explícito sobre onde essa linha cai.

Por que Scrapeless MCP

O Scrapeless MCP Server expõe ferramentas de web scraping e navegador que um agente pode chamar diretamente, então você não precisa construir ou hospedar a camada de scraping por conta própria. 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 controla um navegador em nuvem. O AutoGen transforma cada uma delas em uma ferramenta nativa através de mcp_server_tools, sem código de adaptador para escrever.

As ferramentas browser_* controlam o navegador em nuvem do Scrapeless, então um agente pode navegar em uma página interativa e ler o que é renderizado, tudo na infraestrutura do Scrapeless. Para o mesmo servidor conectado a uma estrutura diferente, o post LangChain + Scrapeless MCP cobre o lado do LangChain.

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 AutoGen com o extra MCP e o pacote de agente.

pip install "autogen-ext[mcp]" autogen-agentchat

Defina sua chave Scrapeless no shell. Use a chave real em tempo de execução e mantenha o marcador fora de sua origem.

export SCRAPELESS_API_KEY="sk_your_key_here"

Carregar as Ferramentas

StreamableHttpServerParams nomeia o endpoint e carrega a chave da API no cabeçalho x-api-token. mcp_server_tools executa o handshake e retorna as ferramentas do servidor como ferramentas AutoGen.

import asyncio
import os

from autogen_ext.tools.mcp import StreamableHttpServerParams, mcp_server_tools

async def main() -> None:
    params = StreamableHttpServerParams(
        url="https://api.scrapeless.com/mcp",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    )
    tools = await mcp_server_tools(params)
    names = sorted(tool.name for tool in tools)
    print("contagem 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.

contagem 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

A camada de transporte e mensagem segue a especificação do Protocolo de Contexto de Modelo, que é baseada em a especificação JSON-RPC 2.0. Para um servidor local, o AutoGen também fornece StdioServerParams; o servidor Scrapeless é um endpoint HTTP hospedado, então este guia usa os parâmetros HTTP transmitíveis.

Chamar uma Ferramenta

Cada ferramenta carregada é um StreamableHttpMcpToolAdapter, e você pode chamar uma diretamente antes de entregá-la a um agente. run_json aceita os argumentos e um token de cancelamento e retorna o resultado da ferramenta.

import asyncio
import os

from autogen_core import CancellationToken
from autogen_ext.tools.mcp import StreamableHttpServerParams, mcp_server_tools


async def main() -> None:
    params = StreamableHttpServerParams(
        url="https://api.scrapeless.com/mcp",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    )
    tools = await mcp_server_tools(params)
    scrape_markdown = next(tool for tool in tools if tool.name == "scrape_markdown")
    result = await scrape_markdown.run_json({"url": "https://quotes.toscrape.com/"}, CancellationToken())
    text = result if isinstance(result, str) else str(result)
    print("caracteres 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 de conteúdo confirma que uma citação real está presente.

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

Esta é a forma que o agente recebe: conteúdo da página sobre o qual pode raciocinar. A referência de ferramentas AutoGen MCP documenta os parâmetros e adaptadores na íntegra.

Anexar as Ferramentas a um Agente

Passe as ferramentas para um AssistantAgent junto com um cliente de modelo, e o agente as chama quando a tarefa precisa delas. Este é o passo que requer uma chave de provedor de modelo.

Nota: AssistantAgent.run precisa de uma chave de provedor de modelo, como OPENAI_API_KEY, que não está configurada aqui. Carregar as 21 ferramentas e a chamada direta scrape_markdown acima funcionam sem isso. Este bloco é mostrado com sua forma exata; apenas a etapa de ida e volta do modelo é um requisito prévio.

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient


async def run_agent(tools) -> None:
    model_client = OpenAIChatCompletionClient(model="gpt-4o")
    agent = AssistantAgent("web_agent", model_client=model_client, tools=tools)
    result = await agent.run(
        task="Use scrape_markdown para buscar https://quotes.toscrape.com/ e listar as três primeiras citações com autores."
    )
    print(result.messages[-1].content)

Em tempo de execução, o modelo lê a tarefa, chama scrape_markdown com a URL, recebe o Markdown que a chamada direta já demonstrou e escreve a resposta. As ferramentas são os mesmos objetos, seja o modelo as chamando ou você as chamando.

Conclusão

AutoGen mais o Servidor MCP Scrapeless é um caminho curto de um agente básico para um que lê a web ao vivo. mcp_server_tools carrega as 21 ferramentas, run_json prova uma que funciona, e um argumento tools no AssistantAgent as conecta todas. Apenas a etapa de geração do agente precisa de uma chave do modelo, então você pode carregar e testar toda a superfície da ferramenta primeiro. Comece a partir dos scripts acima, limite as ferramentas ao que o agente precisa e deixe o modelo conduzir.

Criar uma conta gratuita Scrapeless para obter uma chave API e confira preços do Scrapeless quando planejar um agente recorrente.

FAQ

P: O AutoGen precisa de um cliente de modelo para carregar ferramentas MCP?

Não. mcp_server_tools executa o handshake e retorna as ferramentas com apenas a chave da API Scrapeless configurada, e cada ferramenta pode ser chamada diretamente com run_json. Um cliente de modelo é necessário apenas quando você anexa as ferramentas a um AssistantAgent e chama run, porque é nesse momento que o modelo decide quais ferramentas chamar.

P: Como chamarei uma ferramenta MCP sem um agente?

Cada ferramenta de mcp_server_tools é um StreamableHttpMcpToolAdapter com um método run_json. Passe um dicionário de argumentos e um CancellationToken, e ele retorna o resultado da ferramenta. Esta é a maneira mais rápida de confirmar a conexão e inspecionar a saída de uma ferramenta antes de conectá-la a um agente.

P: Como me conectar a um servidor stdio MCP em vez de HTTP?

Troque os parâmetros. Use StdioServerParams com o comando do servidor em vez de StreamableHttpServerParams com uma URL, e depois passe-o à mesma chamada de mcp_server_tools. O Servidor MCP Scrapeless é um endpoint HTTP hospedado, então este guia utiliza os parâmetros de HTTP transmissível.

P: Como dou a um agente apenas algumas das ferramentas?

mcp_server_tools retorna uma lista, então filtre-a antes de passá-la ao AssistantAgent. Entregar a um agente 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 busca.

P: Quais ferramentas o servidor Scrapeless fornece?

Vinte e uma: scrape_markdown, scrape_html, scrape_screenshot, google_search, google_trends, e um conjunto de 16 ferramentas browser_* para navegação, clique, digitação, rolagem e espera em um navegador em nuvem. Juntas, elas cobrem extração de conteúdo, busca e interação completa com o navegador.

P: A extração através das ferramentas está sujeita às regras do alvo?

Sim. As ferramentas buscam páginas públicas, e você continua responsável por respeitar os termos de cada alvo e suas diretrizes do Protocolo de Exclusão de Robôs. Mantenha o volume controlado e os dados públicos, e limite o agente às ferramentas que a tarefa realmente necessita.