LangChain

LangChain とは

langchain-scrapeless を使って、Python の LangChain アプリケーションに Scrapeless を接続します。ツールを直接呼び出して検索やデータ抽出を行うことも、エージェントに登録してモデルにツールの選択と結果の利用を任せることもできます。

まず Google Search のクイックスタートを試し、その後エージェントに接続するか、以下の別の製品を選んでください。

利用可能なツール

この統合では、4 つの製品分野を利用できます。ツールクラスは langchain_scrapeless からインポートします。

Web Unlocker の名称について： 製品名は Web Unlocker です。langchain-scrapeless 0.1.4 では、Python クラス名は引き続き ScrapelessUniversalScrapingTool です。インポートとコードでは、この名前を正確に使用してください。

セットアップ

Python 3.10 以降と、選択した製品へのアクセス権およびクレジットを持つ Scrapeless API キーが必要です。ツールを直接呼び出す場合は、このキーだけで利用できます。任意で試せるエージェントの例には、モデルプロバイダーのキーも必要です。

このガイドは langchain-scrapeless 0.1.4 を対象としています。このバージョンでは Scrapeless Python SDK 1.3.0 がインストールされます。エージェントの例では LangChain 1.x を使用します。

パッケージのインストール

仮想環境を作成し、有効にします。

macOS / Linux:

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

Windows PowerShell:

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

続いて統合パッケージをインストールします。

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

API キーの設定

プレースホルダーを置き換え、Python を実行するターミナルで変数を設定してください。

macOS / Linux:

export SCRAPELESS_API_KEY="YOUR_SCRAPELESS_API_KEY"

Windows PowerShell:

$env:SCRAPELESS_API_KEY = "YOUR_SCRAPELESS_API_KEY"

ツールは SCRAPELESS_API_KEY を自動的に読み取ります。キーをソースファイルや共有ログに含めないでください。

クイックスタート：Google 検索

次のコードを 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", ""))

有効にした環境で実行します。

python search.py

オーガニック検索結果がある場合、スクリプトは最大 3 件のタイトル、URL、スニペットを出力します。hl は検索言語、gl は国を指定します。リストが空であることだけではリクエストの失敗とは判断できないため、レスポンス全体を確認してください。

検索スニペットは要約です。ページの本文が必要な場合は、返された URL を Crawl に渡してください。これらの例では handle_tool_error=False を指定し、LangChain のツール例外がツール出力に変換されずに伝播するようにしています。

LangChain エージェントの接続

エージェントはモデルを使ってツールを選択し、回答を作成します。検索は Scrapeless が実行します。モデルプロバイダーの使用量は、Scrapeless の使用量とは別に計算されます。

モデル統合のインストールと設定

同じ環境に以下をインストールします。

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

SCRAPELESS_API_KEY の設定を維持し、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"

モデルのプレースホルダーを、アカウントで利用可能でツール呼び出しに対応したモデル ID に置き換えてください。OPENAI_MODEL は、この例で明示的に使用する変数です。

エージェントの作成と実行

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()

python agent.py を実行します。出力されたメッセージで、scrapeless_deepserp_google_search の呼び出し、ツールのレスポンス、その結果に基づく最終回答を確認してください。レスポンスに利用可能なデータが含まれているか確認します。モデルの回答だけでは、Scrapeless が呼び出されたことを確認できません。

ツールを登録すると利用可能になりますが、すべてのリクエストで呼び出されるとは限りません。別の機能を追加するには、対応するツールのインスタンスを作成し、tools=[...] に含めてください。

その他の製品の例

これらの例はそれぞれ独立しています。各コードブロックを .py ファイルとして保存し、設定済みの環境で python filename.py を実行してください。

Crawl

既知の URL には ScrapelessCrawlerScrapeTool を使用します。urls に 1 件または複数の URL を指定してください。

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", ""))

この呼び出しはバッチタスクの完了を待ちます。タスクのステータスに加え、各ページのステータスと内容も確認してください。poll_timeout の単位は秒で、別のページパラメーター timeout の単位はミリ秒です。

リンク先のページを検出するには、ScrapelessCrawlerCrawlTool に {"url": "https://example.com", "limit": 5, "formats": ["markdown"]} を指定します。こちらも完了を待ち、status と data を含む辞書を返します。limit は上限のため、返されるページ数が少なくなる場合があります。バージョン 0.1.4 では、このツールは poll_timeout を公開していません。

Web Unlocker

JavaScript レンダリングを有効にして Markdown をリクエストします。

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")

page.md を開いて抽出された本文を確認してください。テキスト形式には markdown、html、plaintext があります。返されたテキストをそのまま使用します。Crawl の status や data フィールドはありません。入力 URL を出典としてコンテンツと一緒に保存してください。

AI Scraper

エンジン別のツールを使用するか、ScrapelessAIScraperTool でエンジンを選択します。対応するエンジン値は chatgpt、perplexity、copilot、gemini、aimode、overview、grok、alexa です。

この例では、AI Scraper の ChatGPT エンジンを使用します。

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 [])

ChatGPT ツールはデフォルトでテキストを返します。output_format="json" を指定すると、タスクのステータスと結果フィールドを含む Python 辞書を返します。統合ツールとその他のエンジン別ツールは、デフォルトでタスク全体の辞書を返します。入力と回答のフィールドはエンジンによって異なり、たとえば Copilot には mode が必要です。出典が空の場合や、Google AI Overview が概要を生成せずに完了する場合もあります。

この呼び出しに必要なのは SCRAPELESS_API_KEY のみです。AI Scraper はプラットフォームの回答を収集します。エージェントの例の ChatOpenAI モデルは別の役割を持ち、別のキーを使用します。

タスクの処理

上記の例の多くは結果を待ちます。長時間のワークフローでは、次の方法を使用してください。

• AI Scraper： エンジンの入力に wait=False と output_format="json" を設定し、task_id を保存して ScrapelessAIScraperResultTool で結果を取得します。同じ engine を指定してください。取得時には wait、poll_timeout、poll_interval を指定でき、後の 2 つの単位は秒です。

• バッチ抽出： ポーリングがタイムアウトした場合は、エラーに含まれるタスク ID を保存してください。Python SDK の client.scraping_crawl.scrape.check_batch_scrape_status(task_id) で既存のバッチを照会します。

• ウェブサイトのクロール： SDK の async_crawl_url() でタスクを送信し、check_crawl_status() で保存済みタスクを取得します。ステータス照会は、status や data などの属性を持つオブジェクトを返します。

これらはリモートタスクのワークフローであり、Python の async/await とは別のものです。ポーリングのタイムアウトはリモートタスクをキャンセルしません。再送信する前に、既存の ID を照会してください。詳細な使い方は Python SDK ガイドとパッケージの例を参照してください。

トラブルシューティング

関連リソース

• ソースリポジトリと課題トラッカー

• Google Search API

• Crawl

• Web Unlocker

• AI Scraper: ChatGPT

• LangChain エージェント