Spicrawl ahora funciona con OpenAI Agents SDK, LangChain, Codex, Claude Code y más.Ver integraciones
Saltar al contenido

Web scraping con el OpenAI Agents SDK

Conecta un agente del OpenAI Agents SDK al servidor MCP de Spicrawl. Así el agente puede leer páginas web como Markdown.

Configúralo

  1. Instala openai-agents.

  2. Configura SPICRAWL_API_KEY y OPENAI_API_KEY.

  3. Abre MCPServerStreamableHttp con la URL y el encabezado Authorization en params.

  4. Usa create_static_tool_filter para limitar qué herramientas ve el modelo y pasa el servidor a tu Agent.

Ejemplo: lee una página de precios

openai_agents_example.py
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())

El servidor no tiene OAuth, así que envía siempre la clave en headers. Si recibes un 401, comprueba que SPICRAWL_API_KEY esté configurada en el proceso que ejecuta el agente.

Mantén corta la lista de herramientas

Los 25 esquemas de herramientas se envían en cada llamada al modelo. Conserva spicrawl_scrape y, para muchas URL, añade spicrawl_batch_submit, spicrawl_batch_status y spicrawl_batch_results.

Si tu código ya sabe qué URL obtener, una función simple que llame a POST /v1/scrape es más sencilla. No gasta tokens de esquema de herramientas y es más fácil de probar.

Qué puede hacer

El servidor ofrece al agente 25 herramientas de spicrawl_*. Cada llamada se ejecuta con tu clave de API, con los mismos límites y créditos que una llamada directa a la API.

  • Lee una página: spicrawl_scrape devuelve Markdown (predeterminado), texto, HTML, JSON o PDF.
  • Lee muchas páginas: spicrawl_batch_submit pone en cola hasta 10.000 URL. Continúa con spicrawl_batch_status y spicrawl_batch_results.
  • Páginas con login: spicrawl_session_create conserva las cookies y el almacenamiento entre llamadas.
  • Depura un fallo: spicrawl_requests_list y spicrawl_request_get.
  • Revisa el uso: spicrawl_usage_summary y las demás herramientas de uso. Requieren una clave con el alcance read.
  • Busca cosas: spicrawl_docs_search y spicrawl_docs_read buscan y leen la documentación de Spicrawl.

Una herramienta, spicrawl_browser_connect_url, aparece en la lista pero llegará pronto. En spicrawl_scrape, el argumento de renderizado es render, no el js_render de la API.

Conviene saber

  • No rastrea. Spicrawl no sigue enlaces ni encuentra páginas. Dale las URL al agente.
  • Créditos por solicitud. Una obtención simple cuesta 1 crédito. El renderizado de JavaScript, 3. El renderizado con navegador completo, 8.
  • Los fallos son gratis. Una solicitud fallida cuesta 0 créditos.
  • La caché ahorra tiempo, no créditos. Un acierto de caché cuesta lo mismo que la obtención que lo guardó.
  • Limita cada llamada. Configura max_cost y una solicitud que podría costar más se rechaza antes de ejecutarse.
  • Próximamente: proxies gestionados, modo sigiloso, un navegador remoto y extracción con IA a partir de un prompt en lenguaje natural. Hoy puedes usar tu propio proxy.

Preguntas frecuentes

¿Qué paquete necesito?

openai-agents. Configura SPICRAWL_API_KEY y OPENAI_API_KEY antes de ejecutar el ejemplo.

¿Cómo limito las herramientas que ve el modelo?

Pass tool_filter=create_static_tool_filter(allowed_tool_names=[...]). The example keeps spicrawl_scrape and spicrawl_batch_submit.

¿Por qué recibo un 401 cuando el agente se conecta?

Falta el encabezado o la clave es incorrecta. Construye el encabezado en código a partir de SPICRAWL_API_KEY y comprueba que la variable esté definida en el proceso que ejecuta el agente.

¿Qué pasa cuando falla una llamada a una herramienta?

El error llega al modelo como un error de herramienta MCP con el código de la API. Las llamadas fallidas cuestan 0 créditos.

¿Cuánto cuesta cada página?

Una solicitud simple cuesta 1 crédito, el renderizado con JavaScript 3 y el renderizado con navegador completo 8. Las solicitudes fallidas cuestan 0. Un acierto de caché cuesta lo mismo que la solicitud que lo guardó. Pide al agente que configure max_cost en cada solicitud para que nunca gaste más de lo que esperas.