HaystackエージェントにCAPTCHA検出ツールを追加する方法

要約

• Haystack のツールから公式の CapSolver Core SDK を呼び出し、既存のブラウザページ上の CAPTCHA パラメータを検査できます。
• エージェントが検査ツール経由で任意の URL に移動するのではなく、アプリケーションがすでに制御しているページにツールをバインドします。
• 動作例では、Google の reCAPTCHA v2 テストウィジェットを使用するローカルページから、CAPTCHA の種類、ページ URL、および公開サイトキーを取得します。
• これはネイティブな Python 統合であり、MCP サーバーやトランスポートは不要です。
• 検出はソルバータスクを作成せず、トークンを返さず、アプリケーションが検証を受け付けたことの証明にもなりません。

ブラウザベースのエージェントは、作業中に CAPTCHA によって中断されたとき、有用な情報を必要とします。ページタイトルやスクリーンショットだけでは、どの CAPTCHA ファミリーが存在するのか、次のステップにどんなパラメータが必要なのか、エージェントに分からない場合があります。小さな構造化結果を返すことで、アプリケーションは解決を要求する前に明確な判断ポイントを得られます。

Haystack は、AI アプリケーション、検索パイプライン、エージェントを構築するための Python フレームワークです。Haystack のネイティブツールは、そのアプリケーションで利用される関数をラップできます。本ガイドでは、Haystack のツールを CapSolver に接続し、「現在のブラウザページを検査して CAPTCHA パラメータを返す」という特定のタスクを実行します。例では開発用ページを使用し、有料の解決リクエストは行いません。これは、別途認可された解決ステップの前に配置できる、実動する検査コンポーネントを提供します。

Haystack ワークフローにおける CAPTCHA ツールの位置付け

CAPTCHA 検査ツールは、「ブラウザが検証チェックポイントに到達するアクション」と「そのチェックポイントへの対応方法を決めるコード」の間に位置します。ナビゲーションと現在のページは依然としてブラウザが管理します。Haystack はツールインターフェイスを提供し、Core SDK がサポートされている CAPTCHA 情報を読み取ります。

例えば、自分たちのフォームをテストしているチームは、ブラウザでフォームまで遷移させ、検査ツールを呼び出して、返ってきた CAPTCHA タイプとサイトキーを確認できます。テストハーネスは、その後、承認されたテストキー経由のパスを選ぶか、別途設定されたソルバーチェックを選択できます。CAPTCHA ウィジェット自体をフォームの業務コンテンツとして扱うべきではありません。

これは、Haystack がドキュメント化している Tool 抽象化 を用いた開発者向け統合であり、専用 Haystack プラグインを謳うものではありません。このツールの目的は限定的であり、実行に LLM を必要としません。モデル駆動のツール選択を追加する前に、ツールを直接呼び出して使うことにも価値があります。

動作例を実行する前に必要なもの

Python、Haystack パッケージ、Playwright への依存を含む CapSolver Core SDK、そして Playwright 用にインストールされた Chromium が必要です。以下の例は Python 3.12、haystack-ai 3.4.0、capsolver-core 0.1.1、Playwright 1.64.0 で実行されています。これらはテスト済みのバージョンであり、最新リリースであることを意味するものではありません。

ブラウザは Google の公開 reCAPTCHA スクリプトを読み込めなければなりません。ローカルページは、Google がドキュメント化している開発用サイトキーを使用します。これは本番用キーではなく、本番用としてデプロイしてはなりません。Google の reCAPTCHA テストに関するガイダンスで、テストキーと本番検証の違いが説明されています。

この検査のみの例では、CapSolver の API キーやモデルプロバイダのキーは不要です。後で解決操作を行う場合には、有効な CapSolver アカウントキーが必要になります。後で LLM 駆動の Haystack Agent を使う場合には、別途モデルプロバイダの設定も必要です。これらは別々の前提条件であり、CAPTCHA パラメータを変更することで、モデル資格情報の不足をトラブルシュートすべきではありません。

テスト済みパッケージのインストール

仮想環境を作成し、その環境内にパッケージをインストールします。Playwright と同じ Python インタープリタで Chromium のインストールを実行し、ブラウザ依存関係を Playwright に合わせます。

python3 -m venv .venv
.venv/bin/python -m pip install "haystack-ai==3.4.0" "capsolver-core[playwright]==0.1.1" "playwright==1.64.0"
.venv/bin/python -m playwright install chromium

上記のコマンドは POSIX 形式の環境パスを使用しています。OS が異なる仮想環境レイアウトを用いる場合は、その環境の Python 実行ファイルを使用してください。Playwright Python インストールガイドにブラウザインストール要件が記載されています。

現在のページを検査するツールを作成する

ツールは 公式 Core SDK の get_captcha_info(page) をラップします。ページは関数内で取得されるため、ツールにはナビゲーション用の引数はありません。JSON パラメータスキーマは入力フィールドを一切受け付けません。

以下を haystack_captcha_inspection.py として保存してください。ローカル HTML レスポンスは Playwright のルーティングで提供されます。これは開発用フィクスチャであり、リモートホストされたアプリケーションではありません。reCAPTCHA スクリプト自体は Google から読み込まれます。このプログラムは、ウィジェットをクリックしたりフォームを送信したりせずにパラメータを読み取ります。

import asyncio
import json

from capsolver_core import create_capsolver
from haystack.tools import Tool
from playwright.async_api import async_playwright

TEST_PAGE = """<!doctype html><html><body>
<div id="captcha" class="g-recaptcha"
     data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</body></html>"""


async def main():
    async with async_playwright() as pw:
        browser = await pw.chromium.launch()
        try:
            page = await browser.new_page()
            await page.route("http://127.0.0.1:8765/", lambda route: route.fulfill(
                status=200, content_type="text/html", body=TEST_PAGE))
            await page.goto("http://127.0.0.1:8765/")
            await page.wait_for_function(
                "() => window.___grecaptcha_cfg && "
                "Object.keys(window.___grecaptcha_cfg.clients || {}).length > 0")
            async with create_capsolver() as cap:
                async def inspect_captcha():
                    infos = await cap.get_captcha_info(page)
                    return {"captchas": [
                        {"type": info.type.value,
                         "website_url": info.website_url,
                         "website_key": info.website_key}
                        for info in infos
                    ]}

                captcha_tool = Tool(
                    name="inspect_current_page_captcha",
                    description="Read CAPTCHA types and public parameters from the current approved page; does not solve or submit.",
                    parameters={"type": "object", "properties": {},
                                "additionalProperties": False},
                    async_function=inspect_captcha,
                )
                result = await captcha_tool.invoke_async()
                print(json.dumps(result, indent=2))
        finally:
            await browser.close()


if __name__ == "__main__":
    asyncio.run(main())

SDK と Playwright の操作は非同期であるため、async_function 引数が重要です。Haystack の Tool API リファレンスでは、このパス向けに invoke_async() がドキュメント化されています。コルーチンを同期専用の呼び出しパスに入れると、CAPTCHA 検査が行われる前に失敗することがあります。

コンテキストマネージャと finally ブロックは、SDK とブラウザのリソースをクローズします。この例を長時間動作するアプリケーションに適用する際も、このクリーンアップ処理は維持してください。そうしないと、ページ読み込みが失敗したときにブラウザプロセスが残り続けることがあります。

CapSolver ボーナスコードを利用する

自動化予算を即座に増やしましょう！
CapSolver アカウントのチャージ時にボーナスコード CAP26 を使用すると、チャージごとに 5% のボーナス が無制限で付与されます。
今すぐ CapSolver ダッシュボード で利用できます。

検査を実行し、結果を理解する

スクリプトを実行すると、Haystack ツールが直接呼び出され、その戻り値の辞書が表示されます。この例では、その辞書は reCAPTCHA v2 のエントリを 1 つ含む captchas リストを持ちます。

.venv/bin/python haystack_captcha_inspection.py

ローカル実行では、type は reCaptchaV2、website_url は http://127.0.0.1:8765/、HTML に設定されている公開テストサイトキーが返ってきました。これらのフィールドは、モックされたツールレスポンスに埋め込まれたものではなく、実際の SDK とブラウザ経由で読み取られたものです。

結果は意図的に小さくしています。SDK の完全なディスクリプタには追加フィールドが含まれることがありますが、エージェントは次の判断に必要なものだけを受け取るべきです。サイトキーは公開されたウィジェット識別子であり、CapSolver アカウントキーやサイトの秘密の検証キーではありません。

この実行によって、Haystack が非同期関数を呼び出せること、ブラウザが開発用ウィジェットを読み込めること、Core SDK がそのパラメータを読み取れることが確認できます。ただし、モデルによるツール選択、本番サイトの CAPTCHA 検出、トークン生成の成功、ウェブサイトのバックエンドによる受理といった点は確認されません。それらは実際のアプリケーションに対して別途検証が必要です。

既存のエージェントに検査済みページを接続する

Haystack Agent にこの機能を追加する際は、同じ Tool オブジェクトとページバインディングを保持します。Haystack の Agent は、ドキュメント化された tools 設定を通じてツールを受け取ります。このオブジェクトを、アプリケーションがすでに使用しているツールと並べて登録し、呼び出し中はブラウザページを生かしておきます。

既存のブラウザワークフローでは、ローカルフィクスチャのセットアップを、アプリケーションがすでに開いていて検査の権限を持つページに置き換えます。ブラウザのナビゲーションはツールの外に保ちます。そうすることで、ページ選択が明示的になり、モデルが生成した URL によって検査対象が暗黙に変更されるのを防ぎます。

ツールには正確な名前と説明を付けてください。例では「CAPTCHA 情報を読み取り、解決や送信は行わない」と説明しています。「検証を完了する」といった説明は、関数が行う以上のことを約束してしまい、エージェントに早期の成功報告を促してしまう可能性があります。

有用なアプリケーション側の判断としては、結果に必要なパラメータを備えた既知のウィジェットが含まれていれば適切な次のステップを提示し、空または不完全であれば、さらなる情報収集か人間による確認を要求するといったものが挙げられます。同じ不完全なページを何度も検査し続ける無条件ループを追加しないでください。

検出と解決を別ステップとして分離する

検査結果はソルバー判断の入力であり、CAPTCHA の解決そのものではありません。Core SDK には、トークン解決用の solve(info)、より広いブラウザワークフロー用の solve_on_page(page) がドキュメント化されています。これらは get_captcha_info(page) とは異なる効果を持ち、別途設定と認可が必要です。

本ガイドでは、検査ツールは目的上読み取り専用のままにしてください。後に解決用ツールを追加する場合は、アプリケーション側で検出されたタイプと現在のページを検証し、アカウント資格情報はモデルから見えない引数の外側で渡し、そのワークフローにふさわしい予算と承認ルールを適用してください。また、トークンと完了したアプリケーションアクションを明確に区別する結果を返してください。

返されたトークンには、依然としてアプリケーション側での処理が必要です。サイト自身の検証とフォーム結果が、意図した操作が成功したかどうかを決定します。captchas リストが空でないことや Haystack ツールの呼び出しが成功したことは、アプリケーションが CAPTCHA 応答を受け付けた証拠にはなりません。

当てずっぽうにならない接続トラブルシューティング

トラブルシューティングでは、「どのレイヤーが失敗したのか」を特定する必要があります。パッケージインストール、ブラウザ起動、ウィジェット読み込み、SDK による検査、ツール呼び出しのどこかです。複数コンポーネントを一度に置き換えるのではなく、エラーから示唆されるレイヤーだけを変更してください。

ブラウザ実行ファイルが見つからない

アクティブな仮想環境から Playwright のコマンドで Chromium をインストールしてください。pip install が成功しても、それだけでは対応するブラウザバイナリが利用可能であることの証明にはなりません。

ウィジェットの待機がタイムアウトする

ブラウザが Google スクリプトを読み込めているか、テストページがウィジェットを作成しているかを確認してください。この例の待機は、初期化されたウィジェットクライアントの存在を確認しています。ネットワーク障害は SDK による検査対象が現れる前に発生し得ます。その場合、ソルバーを再試行しても問題は解決しません。

ツールが空のリストを返す

空の結果は、「そのページのその時点で、この検査がサポートされたディスクリプタを何も見つけなかった」ことを意味します。ページに検証メカニズムが存在しない証明ではありません。ページタイミング、渡したページオブジェクト、実際のウィジェットを確認してください。CAPTCHA パラメータ検査ガイド は、ブラウザ状態を検査する補完的な方法を提供します。

ツールが直接呼び出しでは動き、エージェントでは動かない

同じ Tool オブジェクトが登録されているか、エージェントのモデルが意図したツールワークフローをサポートしているか、ブラウザセッションがまだ開いているかを確認してください。直接呼び出しが成功するチェックポイントを別途保持し、モデル設定の問題が CAPTCHA API の失敗として誤解されないようにします。

検査結果を有用なものにする

小さな CAPTCHA 検査ツールは、Haystack アプリケーションに解決前の具体的なチェックポイントを提供します。まずはテスト済みの開発用ページから始め、非同期呼び出しとクリーンアップを維持したまま、既存ワークフローが制御するページにツールを接続してください。各追加操作ごとに、明確な入力、検証済みの挙動、観察可能な結果が得られるようになってから、責務を拡張します。

CapSolver で信頼性の高い自動化ワークフローを構築する

CapSolver を、実行許可のあるワークフロー内のサポートされた CAPTCHA ステップに利用してください。ブラウザ、ソルバー結果、アプリケーション結果を別々のチェックとして保持し、ツール呼び出しの成功がタスク失敗を覆い隠さないようにします。

FAQ

Q: この統合には MCP が必要ですか？

いいえ。この例では、同一アプリケーション内でネイティブな Haystack Tool と Python Core SDK を使用します。MCP サーバーは起動しません。

Q: スクリプトを実行するのに LLM の API キーは必要ですか？

いいえ。スクリプトはツールを直接呼び出します。モデルプロバイダの資格情報は、このツールの周囲に LLM 駆動のエージェントを追加したときに初めて必要になります。

Q: この例はテスト CAPTCHA を解決しますか？

いいえ。ウィジェットを読み込み、公開パラメータを読み取るだけです。ソルバートークンの要求やフォーム送信は行いません。

Q: 同じアプローチで既存の Playwright ページを検査できますか？

はい。既存の認可済みページにツールをバインドし、その呼び出し中はページを生かしておきます。サポートされるディスクリプタフィールドは、そのページで SDK が検出できる内容に依存します。
Q：なぜ引数なしのツールを使うのですか？

その関数は、すでに現在の承認済みページを把握しています。空の入力スキーマにしておくことで、ナビゲーションとページ選択をアプリケーション側の制御下に保てます。

Q：結果が空であれば、そのページは通常コンテンツとして安全に処理できるという意味ですか？

いいえ。先へ進む前にページの状態を確認してください。検出結果が空であることは、タイミングの問題や未対応のメカニズム、不完全なウィジェット初期化などを反映している可能性もあります。