IntegraçõesLangChain

LangChain

O que é LangChain

Conecte o Scrapeless à sua aplicação Python do LangChain com langchain-scrapeless. Chame ferramentas diretamente para pesquisar ou extrair dados, ou registre-as em um agente para que um modelo possa selecionar ferramentas e usar seus resultados.

Comece pelo guia rápido do Google Search e, depois, conecte-o a um agente ou escolha outro produto abaixo.

Ferramentas disponíveis

A integração oferece quatro áreas de produtos. Importe as classes de ferramentas de langchain_scrapeless.

ProdutoQuando usarClasses de ferramentas
Scraping API — Google SearchEncontrar resultados de pesquisa e URLs de páginasScrapelessDeepSerpGoogleSearchTool
CrawlExtrair conteúdo de URLs conhecidas ou descobrir páginas de um siteScrapelessCrawlerScrapeTool, ScrapelessCrawlerCrawlTool
Web UnlockerExtrair uma página com opções como renderização de JavaScriptScrapelessUniversalScrapingTool
AI ScraperColetar respostas de plataformas de IA e fontes disponíveisScrapelessAIScraperTool, ferramentas específicas de mecanismo, como ScrapelessChatGPTScraperTool, e ScrapelessAIScraperResultTool

Nome do Web Unlocker: O produto se chama Web Unlocker. No langchain-scrapeless 0.1.4, sua classe Python ainda se chama ScrapelessUniversalScrapingTool; use esse nome exato nas importações e no código.

Configuração

Você precisa do Python 3.10 ou posterior e de uma chave de API do Scrapeless com acesso e créditos para o produto escolhido. Chamadas diretas às ferramentas exigem apenas essa chave. O exemplo opcional de agente também exige uma chave do provedor do modelo.

Este guia se aplica ao langchain-scrapeless 0.1.4, que instala o SDK Python do Scrapeless 1.3.0. O exemplo de agente usa o LangChain 1.x.

Instalar o pacote

Crie e ative um ambiente virtual.

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate

Windows PowerShell:

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1

Em seguida, instale a integração:

python -m pip install "langchain-scrapeless==0.1.4"
python -m pip check

Configurar sua chave de API

Substitua o valor de exemplo e defina a variável no terminal em que você executará o Python.

macOS / Linux:

export SCRAPELESS_API_KEY="YOUR_SCRAPELESS_API_KEY"

Windows PowerShell:

$env:SCRAPELESS_API_KEY = "YOUR_SCRAPELESS_API_KEY"

As ferramentas leem SCRAPELESS_API_KEY automaticamente. Não inclua sua chave em arquivos de código-fonte nem em logs compartilhados.

Início rápido: pesquisar no Google

Salve o código a seguir como search.py:

from langchain_scrapeless import ScrapelessDeepSerpGoogleSearchTool

tool = ScrapelessDeepSerpGoogleSearchTool(handle_tool_error=False)
result = tool.invoke({
    "q": "Scrapeless documentation",
    "hl": "en",
    "gl": "us",
})

items = result.get("organic_results") or []
if not items:
    print("No organic results returned. Inspect the response:", result)
for item in items[:3]:
    print(item.get("title"), item.get("link"))
    print(item.get("snippet", ""))

Execute no ambiente ativado:

python search.py

Quando há resultados orgânicos disponíveis, o script imprime até três títulos, URLs e trechos. hl seleciona o idioma da pesquisa e gl seleciona o país. Uma lista vazia, por si só, não indica que a solicitação falhou; examine a resposta completa.

Os trechos de pesquisa são resumos. Passe as URLs retornadas para o Crawl quando precisar do conteúdo das páginas. Os exemplos usam handle_tool_error=False para que as exceções das ferramentas do LangChain sejam propagadas em vez de se tornarem saídas da ferramenta.

Conectar um agente do LangChain

O agente usa um modelo para selecionar ferramentas e elaborar respostas. O Scrapeless executa a pesquisa. O uso do provedor do modelo é contabilizado separadamente do uso do Scrapeless.

Instalar e configurar a integração do modelo

No mesmo ambiente, instale:

python -m pip install "langchain>=1,<2" "langchain-openai>=1,<2"
python -m pip check

Mantenha SCRAPELESS_API_KEY definida e adicione suas credenciais da OpenAI.

macOS / Linux:

export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
export OPENAI_MODEL="YOUR_TOOL_CALLING_MODEL"

Windows PowerShell:

$env:OPENAI_API_KEY = "YOUR_OPENAI_API_KEY"
$env:OPENAI_MODEL = "YOUR_TOOL_CALLING_MODEL"

Substitua o valor de exemplo do modelo por um ID de modelo disponível na sua conta que ofereça suporte a chamadas de ferramentas. OPENAI_MODEL é uma variável usada explicitamente por este exemplo.

Criar e executar o agente

Salve como agent.py:

import os

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_scrapeless import ScrapelessDeepSerpGoogleSearchTool

model = ChatOpenAI(model=os.environ["OPENAI_MODEL"])
search_tool = ScrapelessDeepSerpGoogleSearchTool(handle_tool_error=False)
agent = create_agent(model=model, tools=[search_tool])

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": (
            "Search the web for Scrapeless documentation and return three "
            "relevant documentation links with a short description of each."
        ),
    }],
})

# Show the model's tool calls, tool responses, and final answer.
for message in result["messages"]:
    message.pretty_print()

Execute python agent.py. Nas mensagens impressas, procure uma chamada a scrapeless_deepserp_google_search, a resposta da ferramenta e uma resposta final baseada nesses resultados. Examine a resposta para verificar se há dados utilizáveis; uma resposta do modelo, por si só, não confirma que o Scrapeless foi chamado.

Registrar uma ferramenta a torna disponível, mas não força uma chamada a cada solicitação. Para adicionar outra capacidade, crie a instância da ferramenta correspondente e inclua-a em tools=[...].

Mais exemplos de produtos

Estes exemplos são independentes. Salve cada bloco como um arquivo .py e execute python filename.py no ambiente configurado.

Crawl

Use ScrapelessCrawlerScrapeTool para URLs conhecidas. Forneça uma URL ou um lote em urls:

from langchain_scrapeless import ScrapelessCrawlerScrapeTool

tool = ScrapelessCrawlerScrapeTool(handle_tool_error=False)
result = tool.invoke({
    "urls": ["https://example.com"],
    "formats": ["markdown"],
    "only_main_content": True,
    "poll_timeout": 180,
})

if result.get("status") != "completed":
    raise RuntimeError(f"Scrape did not complete: {result.get('status')}")

pages = result.get("data") or []
print("Returned pages:", len(pages))
for page in pages:
    metadata = page.get("metadata") or {}
    print(metadata.get("sourceURL"), metadata.get("statusCode"))
    print(page.get("markdown", ""))

A chamada aguarda a tarefa em lote. Verifique o status e o conteúdo de cada página, além do status da tarefa. poll_timeout é medido em segundos; o parâmetro separado timeout da página é medido em milissegundos.

Para descobrir páginas vinculadas, use ScrapelessCrawlerCrawlTool com {"url": "https://example.com", "limit": 5, "formats": ["markdown"]}. Ele também aguarda a conclusão e retorna um dicionário com status e data. limit é um máximo, portanto menos páginas podem ser retornadas. Essa ferramenta não expõe poll_timeout na versão 0.1.4.

Web Unlocker

Solicite Markdown com a renderização de JavaScript ativada:

from pathlib import Path

from langchain_scrapeless import ScrapelessUniversalScrapingTool

tool = ScrapelessUniversalScrapingTool(handle_tool_error=False)
content = tool.invoke({
    "url": "https://example.com",
    "js_render": True,
    "response_type": "markdown",
})

if not isinstance(content, str) or not content.strip():
    raise RuntimeError("Expected non-empty Markdown text; inspect the response")

Path("page.md").write_text(content, encoding="utf-8")
print("Saved page.md")

Abra page.md para verificar o corpo extraído. Os formatos de texto incluem markdown, html e plaintext. Use o texto retornado diretamente; ele não contém os campos status e data do Crawl. Guarde a URL de entrada junto com o conteúdo como sua fonte.

AI Scraper

Use uma ferramenta específica de mecanismo ou selecione um mecanismo por meio de ScrapelessAIScraperTool. Os valores de mecanismo compatíveis são chatgpt, perplexity, copilot, gemini, aimode, overview, grok e alexa.

Este exemplo usa o mecanismo ChatGPT do AI Scraper:

from langchain_scrapeless import ScrapelessChatGPTScraperTool

tool = ScrapelessChatGPTScraperTool(handle_tool_error=False)
task = tool.invoke({
    "prompt": "Explain HTTP caching and include sources where available.",
    "country": "US",
    "web_search": True,
    "shopping": False,
    "output_format": "json",
})

if task.get("status") != "success":
    raise RuntimeError(f"Task did not complete: {task.get('task_id')}")

answer = task["task_result"]
print(answer.get("result_text", ""))
print("Links:", answer.get("links") or [])
print("Content references:", answer.get("content_references") or [])

A ferramenta ChatGPT retorna texto por padrão; output_format="json" retorna um dicionário Python com o status da tarefa e os campos de resultado. A ferramenta unificada e as demais ferramentas específicas de mecanismo retornam por padrão um dicionário completo da tarefa. Os campos de entrada e resposta variam conforme o mecanismo; por exemplo, o Copilot exige mode. As fontes podem estar vazias, e o Google AI Overview pode concluir sem gerar uma visão geral.

Esta chamada exige apenas SCRAPELESS_API_KEY. O AI Scraper coleta respostas de plataformas; o modelo ChatOpenAI do exemplo de agente tem uma função e uma chave separadas.

Gerenciamento de tarefas

A maioria dos exemplos acima aguarda os resultados. Para fluxos de trabalho mais longos:

  • AI Scraper: defina wait=False e output_format="json" na entrada do mecanismo, salve task_id e recupere o resultado com ScrapelessAIScraperResultTool. Passe o mesmo engine. A consulta oferece suporte a wait, poll_timeout e poll_interval; os dois últimos usam segundos.

  • Extração em lote: se a consulta periódica exceder o tempo limite, guarde o ID da tarefa informado no erro. Use client.scraping_crawl.scrape.check_batch_scrape_status(task_id) por meio do SDK Python para consultar o lote existente.

  • Rastreamento de sites: use async_crawl_url() do SDK para enviar a tarefa e check_crawl_status() para recuperar a tarefa salva. A consulta de status retorna um objeto com atributos como status e data.

Esses são fluxos de tarefas remotas, separados de async/await do Python. Um tempo limite de consulta não cancela a tarefa remota. Consulte o ID existente antes de enviar novamente. Veja o guia do SDK Python e os exemplos do pacote para instruções detalhadas.

Solução de problemas

ProblemaO que verificar
Erro de importação ou dependênciaUse Python 3.10+ e o mesmo ambiente virtual para instalar e executar. Execute python -m pip check e python -m pip show langchain-scrapeless scrapeless langchain-core.
Chave ausente ou falha de autenticaçãoDefina a chave no processo que executa o Python. Verifique a validade, o acesso ao produto e os créditos. A chave do provedor do modelo do agente é separada.
Erro de validação de parâmetrosVerifique o esquema da ferramenta e do mecanismo selecionados. Na ferramenta unificada AI Scraper, coloque os campos específicos do mecanismo dentro de input. Os nomes dos parâmetros do SDK, REST e ferramentas podem diferir.
Tempo limite excedidoPreserve o ID da tarefa e siga as orientações de consulta acima. Reenviar pode criar outra tarefa.
Saída vazia ou inesperadaExamine a resposta completa, o estado da tarefa e os campos de conteúdo solicitados. Ao relatar erros de decodificação de texto do Web Unlocker, inclua a versão do SDK e o traceback sem dados sensíveis.
O agente não pesquisaPrimeiro verifique o exemplo de início rápido com chamada direta. Confira o registro das ferramentas e o suporte do modelo a chamadas de ferramentas; depois examine as mensagens de execução com uma solicitação explícita de pesquisa.

Recursos relacionados