Pydantic AI + Scrapeless: Dê ao Seu Agente Ferramentas Web Ao Vivo através do MCP

Resumo:

• Pydantic AI se conecta ao Scrapeless MCP Server via HTTP transmitível e fornece a um agente 21 ferramentas web ao vivo, de scrape_markdown a um conjunto completo de automação de navegador.
• A conexão utiliza três classes de pydantic_ai.mcp: um StreamableHttpTransport, um FastMCPClient e um MCPToolset que você anexa a um Agent.
• O handshake, a lista de ferramentas e uma chamada real de scrape_markdown são executados sem chave de provedor de modelo; apenas a geração final de agent.run precisa de uma.
• defer_model_check=True permite que o Agent seja construído antes que uma chave de modelo exista, para que você possa conectar e inspecionar o conjunto de ferramentas primeiro.
• Uma chamada de scrape_markdown retorna a página alvo como Markdown limpo, pronto para ser entregue ao modelo como contexto.
• Comece no plano gratuito do Scrapeless e conecte o seu primeiro agente.

Pydantic AI fornece uma estrutura ao agente: saídas tipadas, argumentos de ferramenta validados e uma maneira limpa de compor ferramentas. O que não fornece ao agente é uma forma de acessar a web ao vivo. Essa lacuna é exatamente o que o Protocolo de Contexto do Modelo preenche. Aponte o Pydantic AI para um servidor MCP e cada ferramenta que esse servidor expõe se torna uma ferramenta que seu agente pode chamar, com os esquemas de argumentos validados da mesma forma que o resto do seu código Pydantic AI.

Este guia conecta o Pydantic AI ao Scrapeless MCP Server, lista as ferramentas que ele oferece, chama uma de verdade e anexa todo o conjunto a um Agent — tudo verificado contra o servidor ao vivo. O único passo que precisa de uma chave de provedor de modelo é a chamada de geração no final, e este post é explícito sobre onde essa linha cai.

Por Que Scrapeless MCP

O Scrapeless MCP Server expõe ferramentas de scraping da web e navegador que um agente pode chamar diretamente, para que você não construa ou hospede a camada de scraping você mesmo. Uma única conexão serve 21 ferramentas: scrape_markdown e scrape_html para conteúdo de página, google_search e google_trends para dados de pesquisa, scrape_screenshot para capturas, e um conjunto completo de browser_* que aciona um navegador na nuvem para clicar, digitar, rolar e navegar. O post sobre o Scrapeless MCP Server cobre o servidor em si; este guia é sobre conectá-lo ao Pydantic AI.

Como as ferramentas funcionam na infraestrutura do Scrapeless, o agente obtém páginas renderizadas e resultados de busca sem um navegador local ou pool de proxy. As ferramentas browser_* acionam o navegador na nuvem Scrapeless, para que um agente possa navegar em uma página interativa e ler o que é renderizado.

Pré-requisitos

• Python 3.10 ou posterior.
• Uma chave de API do Scrapeless do painel, exportada como SCRAPELESS_API_KEY.
• Uma chave de provedor de modelo (como OPENAI_API_KEY) apenas para o passo final de geração. O handshake, a lista de ferramentas e as chamadas de ferramentas não precisam de uma.

Instalação

Instale o Pydantic AI com o extra MCP, que puxa as classes do cliente MCP.

pip install "pydantic-ai-slim[mcp]"

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

export SCRAPELESS_API_KEY="sk_your_key_here"

Conectar e Listar as Ferramentas

A conexão é composta por três objetos. Um StreamableHttpTransport nomeia o endpoint e carrega a chave da API no cabeçalho x-api-token, um FastMCPClient fala o protocolo sobre esse transporte, e um MCPToolset envolve o cliente para que o Pydantic AI possa usá-lo. Entrar no contexto assíncrono do conjunto de ferramentas executa o handshake; list_tools retorna o que o servidor oferece.

import asyncio
import os

from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

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


async def main() -> None:
    async with scrapeless:
        tools = await scrapeless.list_tools()
        names = sorted(t.name for t in tools)
        print("contagem de ferramentas:", len(names))
        print("ferramentas:", ", ".join(names))


asyncio.run(main())

O servidor ao vivo retorna 21 ferramentas, e nenhuma chave de provedor de modelo foi definida para chegar aqui.

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

Os nomes das ferramentas são simples, sem prefixo de servidor, então scrape_markdown pode ser endereçado exatamente por esse nome. A camada de transporte e a camada de mensagem seguem a especificação do Protocolo de Contexto de Modelo, que por sua vez se baseia em a especificação JSON-RPC 2.0.

Chame uma Ferramenta Diretamente

Antes de entregar as ferramentas a um agente, chame uma você mesmo para ver o que ela retorna. direct_call_tool invoca uma ferramenta pelo nome com seus argumentos, que é a maneira mais rápida de confirmar que uma ferramenta funciona e inspecionar sua saída.

import asyncio
import os

from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

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


async def main() -> None:
    async with scrapeless:
        result = await scrapeless.direct_call_tool("scrape_markdown", {"url": "https://quotes.toscrape.com/"})
        markdown = result if isinstance(result, str) else str(result)
        print(" caracteres markdown:", len(markdown))
        print(" contém uma citação:", "O mundo como o criamos" in markdown)


asyncio.run(main())

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

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

Esta é a forma como seu agente recebe: Markdown limpo sobre o qual pode raciocinar, em vez de HTML bruto que precisa ser limpo. A documentação do cliente Pydantic AI MCP cobre todos os métodos do conjunto de ferramentas.

Anexar as Ferramentas a um Agente

Anexar é um argumento: passe o conjunto de ferramentas para o Agent em toolsets. Como a construção normal de um Agent valida o modelo imediatamente, defer_model_check=True permite que ele construa antes que uma chave de modelo seja definida, para que você possa conectar e inspecionar o conjunto de ferramentas primeiro.

import asyncio
import os

from pydantic_ai import Agent
from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

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

# defer_model_check permite que o agente seja construído antes que a chave do modelo seja definida,
# para que o conjunto de ferramentas possa ser conectado e inspecionado primeiro.
agent = Agent("openai:gpt-4o", toolsets=[scrapeless], defer_model_check=True)


async def main() -> None:
    async with scrapeless:
        names = sorted(t.name for t in await scrapeless.list_tools())
    web = [n for n in names if n.startswith(("scrape_", "google_"))]
    print("agente conectado com", len(names), "ferramentas Scrapeless")
    print("ferramentas web:", web)


asyncio.run(main())

O agente agora possui todas as ferramentas Scrapeless, e o subconjunto de raspagem da web é a parte que a maioria dos tutoriais procura primeiro.

agente conectado com 21 ferramentas Scrapeless
ferramentas web: ['google_search', 'google_trends', 'scrape_html', 'scrape_markdown', 'scrape_screenshot']

Para entregar ao agente apenas algumas ferramentas em vez de todas as 21, MCPToolset expõe filtered e renamed, para que você possa limitar um agente a scrape_markdown e google_search apenas, em vez de todo o conjunto de ferramentas do navegador.

Executar um Prompt

Com o conjunto de ferramentas anexado, o agente decide quando chamar uma ferramenta. Este é o único passo que precisa de uma chave de provedor de modelo.

Nota: agent.run precisa de uma chave de provedor de modelo, como OPENAI_API_KEY. Tudo acima — o handshake, a lista de 21 ferramentas, a chamada scrape_markdown, e a anexação — funciona sem ela. Apenas essa chamada de geração é uma lacuna pré-requisito; ela é mostrada aqui com a forma exata que assume, não como um resultado capturado.

async def run_prompt() -> None:
    async with agent:
        result = await agent.run(
            "Use scrape_markdown para buscar https://quotes.toscrape.com/ "
            "e listar as três primeiras citações com seus autores."
        )
    print(result.output)


asyncio.run(run_prompt())

No tempo de execução, o modelo lê o prompt, chama scrape_markdown com a URL, recebe o Markdown que a chamada anterior já demonstrou, e escreve a resposta. A camada de ferramenta é idêntica, independentemente de você chamá-la diretamente ou deixar o modelo chamá-la.

Conclusão

Pydantic AI mais o Servidor MCP Scrapeless é um caminho curto de um agente simples para um que lê a web ao vivo. Três classes fazem a conexão, list_tools mostra as 21 ferramentas, direct_call_tool prova que uma funciona, e um argumento toolsets anexa todas elas. Apenas o passo de geração precisa de uma chave de modelo, o que mantém toda a integração explorável antes de você se comprometer com um provedor. Comece a partir dos scripts acima, limite o conjunto de ferramentas às ferramentas que seu agente precisa, e deixe que o modelo faça o resto.
Crie uma conta gratuita no Scrapeless para obter uma chave de API e consulte os preços do Scrapeless quando planejar um agente recorrente.

FAQ

Q: O Pydantic AI precisa de uma chave de modelo para listar as ferramentas MCP?

Não. O handshake, list_tools e direct_call_tool funcionam apenas com a chave de API do Scrapeless. Uma chave de provedor de modelo é necessária somente para o agent.run, quando o próprio modelo decide quais ferramentas chamar, assim você pode explorar e testar toda a superfície de ferramentas antes de comprometer-se com um provedor.

Q: Qual é a diferença entre FastMCPClient e MCPToolset?

O FastMCPClient fala o protocolo MCP por meio de um transporte e expõe operações de baixo nível, como list_tools. O MCPToolset envolve esse cliente para que o Pydantic AI possa tratar as ferramentas do servidor como ferramentas de agente, e adiciona recursos de conjunto de ferramentas, como filtered e renamed. Você anexa o MCPToolset, não o cliente, a um Agente.

Q: Como me conecto a um servidor MCP stdio em vez de HTTP?

Troque o transporte. Use StdioTransport com o comando do servidor em vez de StreamableHttpTransport com uma URL, em seguida, envolva-o no mesmo FastMCPClient e MCPToolset. O Servidor MCP do Scrapeless é um endpoint HTTP hospedado, então este guia utiliza StreamableHttpTransport.

Q: Por que usar defer_model_check ao construir o Agente?

Construir um Agente normalmente valida o provedor de modelo imediatamente, o que falha se nenhuma chave estiver definida. defer_model_check=True adia essa verificação para o tempo de execução, assim você pode construir o agente, conectar o conjunto de ferramentas e inspecionar as ferramentas disponíveis sem uma chave de modelo presente.

Q: Como posso dar a um agente apenas algumas das ferramentas?

Use MCPToolset.filtered para expor um subconjunto, ou renamed para alterar como as ferramentas aparecem para o modelo. Limitar um agente a scrape_markdown e google_search é mais seguro do que fornecer todas as 21 ferramentas quando a tarefa só precisa de conteúdo e pesquisa.

Q: O que scrape_markdown retorna?

Ele retorna a página alvo renderizada como Markdown, que na chamada verificada tinha 4.308 caracteres para a página de citações e continha o texto real da página. Markdown é mais fácil para um modelo raciocinar do que HTML bruto, portanto, é um bom padrão para alimentar o conteúdo da página de volta em um prompt.

Q: O scraping através das ferramentas está vinculado às regras do alvo?

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