Web scraping com o OpenAI Agents SDK
Conecte um agente do OpenAI Agents SDK ao servidor MCP do Spicrawl. O agente passa a ler páginas web como Markdown.
Configure
Instale
openai-agents.Defina
SPICRAWL_API_KEYeOPENAI_API_KEY.Abra
MCPServerStreamableHttpcom a URL e o cabeçalhoAuthorizationemparams.Use
create_static_tool_filterpara limitar quais ferramentas o modelo enxerga e passe o servidor para o seuAgent.
Exemplo: ler uma página de preços
import asyncio
import os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp, create_static_tool_filter
async def main() -> None:
async with MCPServerStreamableHttp(
name="spicrawl",
params={
"url": "https://mcp.spicrawl.com/mcp",
"headers": {"Authorization": f"Bearer {os.environ['SPICRAWL_API_KEY']}"},
},
cache_tools_list=True,
tool_filter=create_static_tool_filter(
allowed_tool_names=["spicrawl_scrape", "spicrawl_batch_submit"]
),
) as server:
agent = Agent(
name="Page reader",
instructions="Use the Spicrawl tools to read web pages.",
mcp_servers=[server],
)
result = await Runner.run(
agent,
"Read https://example.com/pricing as markdown and list the plans.",
)
print(result.final_output)
asyncio.run(main())O servidor não tem OAuth, então sempre envie a chave em headers. Se você receber um 401, confira se SPICRAWL_API_KEY está definido no processo que roda o agente.
Mantenha a lista de ferramentas curta
Os schemas das 25 ferramentas são enviados a cada chamada ao modelo. Mantenha spicrawl_scrape e, para muitas URLs, adicione spicrawl_batch_submit, spicrawl_batch_status e spicrawl_batch_results.
Se o seu código já sabe qual URL buscar, uma função simples que chama POST /v1/scrape é mais simples. Ela não gasta tokens de schema de ferramentas e é mais fácil de testar.
O que ele pode fazer
O servidor dá ao agente 25 ferramentas spicrawl_*. Cada chamada roda sob a sua chave de API, com os mesmos limites e créditos de uma chamada direta à API.
- Ler uma página:
spicrawl_scraperetorna Markdown (o padrão), texto, HTML, JSON ou PDF. - Ler várias páginas:
spicrawl_batch_submitenfileira até 10.000 URLs. Acompanhe comspicrawl_batch_statusespicrawl_batch_results. - Páginas atrás de um login:
spicrawl_session_createmantém cookies e armazenamento entre as chamadas. - Depure uma falha:
spicrawl_requests_listespicrawl_request_get. - Verifique o uso:
spicrawl_usage_summarye as outras ferramentas de uso. Elas exigem uma chave com o escoporead. - Pesquise coisas:
spicrawl_docs_searchespicrawl_docs_readpesquisam e leem a documentação do Spicrawl.
Uma ferramenta, spicrawl_browser_connect_url, está listada mas chega em breve. Em spicrawl_scrape, o argumento de renderização é render, não o js_render da API.
Bom saber
- Sem crawl. O Spicrawl não segue links nem encontra páginas. Dê as URLs ao agente.
- Créditos por requisição. Um fetch simples custa 1 crédito. A renderização JavaScript custa 3. A renderização em navegador completo custa 8.
- Falhas são grátis. Uma requisição que falha custa 0 crédito.
- O cache economiza tempo, não créditos. Um acerto de cache custa o mesmo que a busca que o guardou.
- Limite cada chamada. Defina
max_coste uma requisição que poderia custar mais é recusada antes de rodar. - Em breve: proxies gerenciados, modo stealth, um navegador remoto e extração com IA a partir de um prompt em linguagem natural. Hoje você pode usar seu próprio proxy.
Perguntas frequentes
De qual pacote eu preciso?
openai-agents. Defina SPICRAWL_API_KEY e OPENAI_API_KEY antes de rodar o exemplo.
Como limito quais ferramentas o modelo enxerga?
Pass tool_filter=create_static_tool_filter(allowed_tool_names=[...]). The example keeps spicrawl_scrape and spicrawl_batch_submit.
Por que recebo um 401 quando o agente se conecta?
O cabeçalho está ausente ou a chave está errada. Monte o cabeçalho no código a partir de SPICRAWL_API_KEY e confira se a variável está definida no processo que roda o agente.
O que acontece quando uma chamada de ferramenta falha?
O erro chega ao modelo como um erro de ferramenta MCP com o código da API. Chamadas com falha custam 0 crédito.
Quanto custa cada página?
Um fetch simples custa 1 crédito, a renderização JavaScript 3 e a renderização em navegador completo 8. Requisições com falha custam 0. Um acerto de cache custa o mesmo que o fetch que o armazenou. Peça ao agente para definir max_cost em cada requisição, para que ele nunca gaste mais do que você espera.