SDK de Agentes OpenAI + Scrapeless: Ferramentas Web para Seus Agentes via MCP

TL;DR:

• O OpenAI Agents SDK conecta-se ao Scrapeless MCP Server através de um objeto, MCPServerStreamableHttp, que transporta o endpoint e o cabeçalho x-api-token.
• await server.list_tools() retorna todas as 21 ferramentas — scrape_markdown, scrape_html, google_search, google_trends, scrape_screenshot, e um conjunto de 16 ferramentas browser_* — apenas com a chave do Scrapeless definida.
• Ao contrário de frameworks que convertem ferramentas MCP em objetos autônomos, o SDK mantém o servidor como uma conexão de primeira classe: você entrega todo o server ao agente, e ele chama list_tools e call_tool para você.
• Você pode chamar qualquer ferramenta diretamente com await server.call_tool("scrape_markdown", {"url": ...}) antes de um agente ser envolvido — nenhuma chave de modelo é necessária para carregar ou chamar ferramentas.
• Apenas Runner.run precisa de uma chave de provedor de modelo, porque é nessa etapa que o modelo decide quais ferramentas chamar.
• Comece no plano gratuito do Scrapeless e dê aos seus agentes do OpenAI Agents SDK ferramentas da web reais.

O OpenAI Agents SDK é a estrutura leve da OpenAI para construir aplicativos agentes em Python, e um agente nele é tão útil quanto as ferramentas que você lhe fornece. Nada na instalação básica acessa a web ao vivo. O Modelo Context Protocol corrige isso: aponte o SDK para um servidor MCP e toda ferramenta que esse servidor expõe se torna chamável pelo seu agente através da mesma interface que uma função ferramenta escrita à mão.

Este guia conecta o SDK ao Scrapeless MCP Server, lista suas 21 ferramentas, chama uma de verdade e, em seguida, anexa todo o servidor a um Agent — verificado contra o endpoint ao vivo. A única etapa que precisa de uma chave de provedor de modelo é a chamada de geração do agente, e este post marca exatamente onde essa linha se situa.

O que o Scrapeless MCP Server dá a um agente

O Scrapeless MCP Server expõe ferramentas de raspagem web e de navegador que um agente pode chamar diretamente, então a camada de raspagem não é algo que você constrói ou hospeda. Uma conexão serve 21 ferramentas: scrape_markdown e scrape_html para conteúdo de página, google_search e google_trends para dados de busca, scrape_screenshot para capturas, e um conjunto de 16 ferramentas browser_* que controla um navegador em nuvem através de cliques, digitação, rolagem e esperas.

As ferramentas browser_* rodam no navegador em nuvem Scrapeless, então um agente pode navegar por uma página interativa e ler o que realmente renderiza sem um navegador na sua máquina. Se você quiser o mesmo servidor integrado a um stack diferente, o guia LangChain + Scrapeless MCP cobre esse lado, e O que é MCP explica o protocolo em si.

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 SDK. O cliente MCP já vem dentro dele, então não há nada extra para adicionar.

pip install "openai-agents==0.18.3"

Defina sua chave Scrapeless no shell e mantenha o placeholder fora do seu código-fonte.

export SCRAPELESS_API_KEY="sk_your_key_here"

Conectar e carregar as ferramentas

MCPServerStreamableHttp aceita um dicionário params com o endpoint e os cabeçalhos, e é um gerenciador de contexto assíncrono, então a conexão se abre e fecha em torno de um bloco with. list_tools executa o handshake e retorna as ferramentas do servidor.

import asyncio
import os

from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        tools = await server.list_tools()
        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 se baseia na especificação JSON-RPC 2.0. O SDK também inclui MCPServerStdio para um servidor local em subprocesso; o servidor do Scrapeless é um endpoint HTTP hospedado, então a classe streamable-HTTP é a correta aqui.

Chamar uma ferramenta diretamente

Antes que um agente exista, você pode chamar qualquer ferramenta no servidor por conta própria. call_tool recebe o nome da ferramenta e um dicionário de argumentos e retorna um CallToolResult cujo content é uma lista de blocos; o texto está nos blocos de texto.

import asyncio
import os

from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        result = await server.call_tool("scrape_markdown", {"url": "https://quotes.toscrape.com/"})
        text = "".join(block.text for block in result.content if block.type == "text")
        print("caracteres markdown:", len(text))
        print("contém uma citação:", "Einstein" in text)


asyncio.run(main())

A chamada retorna a página em Markdown, e a verificação de conteúdo confirma que um texto real foi retornado.

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

Essa é a forma que um agente recebe de volta da mesma ferramenta: conteúdo da página que pode raciocinar sobre. A documentação do SDK OpenAI Agents MCP cobre list_tools, call_tool e a opção cache_tools_list que pula apertos de mão repetidos quando o conjunto de ferramentas é estável.

Entregar as ferramentas a um agente

Aqui o SDK difere das estruturas de adaptadores de ferramentas. Você não converte as ferramentas e passa uma lista; você passa o servidor inteiro ao argumento mcp_servers do agente, e o agente chama list_tools e call_tool nele durante a execução. Este é o passo que precisa de uma chave de provedor de modelo.

Nota: Runner.run 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 ida e volta do modelo é uma lacuna pré-requisito.

import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        agent = Agent(
            name="web_agent",
            instructions="Use as ferramentas do Scrapeless para buscar e ler páginas.",
            mcp_servers=[server],
        )
        result = await Runner.run(
            agent,
            "Use scrape_markdown para buscar https://quotes.toscrape.com/ e listar as três primeiras citações com autores.",
        )
        print(result.final_output)


asyncio.run(main())

Em tempo de execução, o modelo lê a tarefa, chama scrape_markdown com a URL, recebe o Markdown que a chamada direta já retornou e escreve a resposta. As ferramentas são as mesmas de qualquer maneira — o único novo ingrediente é o modelo que decide quando chamá-las.

Conclusão

O SDK OpenAI Agents mais o Servidor MCP Scrapeless é um caminho curto de um agente nu para um que lê a web ao vivo. Um objeto MCPServerStreamableHttp abre a conexão, list_tools retorna todas as 21 ferramentas, call_tool prova que uma funciona, e um único argumento mcp_servers=[server] entrega o conjunto ao agente. Apenas o passo de geração precisa de uma chave de modelo, então você pode conectar e testar toda a superfície da ferramenta primeiro. Comece a partir dos scripts acima, escopos as ferramentas para o que a tarefa precisa e deixe o modelo conduzir.

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

FAQ

Q: O SDK OpenAI Agents precisa de uma chave de modelo para carregar ferramentas MCP?

Não. MCPServerStreamableHttp executa o aperto de mão e list_tools retorna as ferramentas com apenas a chave API do Scrapeless definida, e call_tool invoca qualquer uma delas diretamente. Uma chave de provedor de modelo é necessária apenas quando você passa o servidor a um Agent e chama Runner.run, porque é quando o modelo decide quais ferramentas chamar.
Q: Como chamo uma ferramenta MCP sem construir um agente?

Abra o servidor como um gerenciador de contexto assíncrono e chame await server.call_tool(name, arguments). Isso retorna um CallToolResult cujo content é uma lista de blocos; leia o texto dos blocos de texto. Esta é a maneira mais rápida de confirmar a conexão e inspecionar a saída de uma ferramenta antes de qualquer modelo ser envolvido.

Q: Por que passar o servidor em vez de uma lista de ferramentas?

O SDK mantém o servidor MCP como uma conexão ao vivo e o consulta durante a execução, por isso você o anexa com mcp_servers=[server] em vez de converter cada ferramenta. Se o conjunto de ferramentas for estável, defina cache_tools_list=True no servidor para que ele não re-execute o handshake a cada rodada.

Q: Posso me conectar a um servidor MCP local, em vez disso?

Sim. Troque MCPServerStreamableHttp por MCPServerStdio e forneça o comando que inicia seu servidor local, depois passe-o para o agente da mesma forma. O Scrapeless MCP Server é um ponto de extremidade HTTP hospedado, então este guia usa a classe de HTTP transmitível.

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

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