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.
| Produto | Quando usar | Classes de ferramentas |
|---|---|---|
| Scraping API — Google Search | Encontrar resultados de pesquisa e URLs de páginas | ScrapelessDeepSerpGoogleSearchTool |
| Crawl | Extrair conteúdo de URLs conhecidas ou descobrir páginas de um site | ScrapelessCrawlerScrapeTool, ScrapelessCrawlerCrawlTool |
| Web Unlocker | Extrair uma página com opções como renderização de JavaScript | ScrapelessUniversalScrapingTool |
| AI Scraper | Coletar respostas de plataformas de IA e fontes disponíveis | ScrapelessAIScraperTool, 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/activateWindows PowerShell:
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1Em seguida, instale a integração:
python -m pip install "langchain-scrapeless==0.1.4"
python -m pip checkConfigurar 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.pyQuando 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 checkMantenha 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=Falseeoutput_format="json"na entrada do mecanismo, salvetask_ide recupere o resultado comScrapelessAIScraperResultTool. Passe o mesmoengine. A consulta oferece suporte await,poll_timeoutepoll_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 echeck_crawl_status()para recuperar a tarefa salva. A consulta de status retorna um objeto com atributos comostatusedata.
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
| Problema | O que verificar |
|---|---|
| Erro de importação ou dependência | Use 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ção | Defina 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âmetros | Verifique 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 excedido | Preserve o ID da tarefa e siga as orientações de consulta acima. Reenviar pode criar outra tarefa. |
| Saída vazia ou inesperada | Examine 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 pesquisa | Primeiro 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. |