🎉新着AI エージェント向け CapSolver-MCP、エージェントツール、SDK 統合
Sora Fujimoto
AI Solutions Architect
発行済み Oct 22, 2026
更新されました Oct 22, 2026 · 最小読み取り
ブラウザベースのエージェントは、作業中に CAPTCHA によって中断されたとき、有用な情報を必要とします。ページタイトルやスクリーンショットだけでは、どの CAPTCHA ファミリーが存在するのか、次のステップにどんなパラメータが必要なのか、エージェントに分からない場合があります。小さな構造化結果を返すことで、アプリケーションは解決を要求する前に明確な判断ポイントを得られます。
Haystack は、AI アプリケーション、検索パイプライン、エージェントを構築するための Python フレームワークです。Haystack のネイティブツールは、そのアプリケーションで利用される関数をラップできます。本ガイドでは、Haystack のツールを CapSolver に接続し、「現在のブラウザページを検査して 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 を、実行許可のあるワークフロー内のサポートされた CAPTCHA ステップに利用してください。ブラウザ、ソルバー結果、アプリケーション結果を別々のチェックとして保持し、ツール呼び出しの成功がタスク失敗を覆い隠さないようにします。
Q: この統合には MCP が必要ですか？
いいえ。この例では、同一アプリケーション内でネイティブな Haystack Tool と Python Core SDK を使用します。MCP サーバーは起動しません。
Q: スクリプトを実行するのに LLM の API キーは必要ですか？
いいえ。スクリプトはツールを直接呼び出します。モデルプロバイダの資格情報は、このツールの周囲に LLM 駆動のエージェントを追加したときに初めて必要になります。
Q: この例はテスト CAPTCHA を解決しますか？
いいえ。ウィジェットを読み込み、公開パラメータを読み取るだけです。ソルバートークンの要求やフォーム送信は行いません。
Q: 同じアプローチで既存の Playwright ページを検査できますか？
はい。既存の認可済みページにツールをバインドし、その呼び出し中はページを生かしておきます。サポートされるディスクリプタフィールドは、そのページで SDK が検出できる内容に依存します。
Q：なぜ引数なしのツールを使うのですか？
その関数は、すでに現在の承認済みページを把握しています。空の入力スキーマにしておくことで、ナビゲーションとページ選択をアプリケーション側の制御下に保てます。
Q：結果が空であれば、そのページは通常コンテンツとして安全に処理できるという意味ですか？
いいえ。先へ進む前にページの状態を確認してください。検出結果が空であることは、タイミングの問題や未対応のメカニズム、不完全なウィジェット初期化などを反映している可能性もあります。
Sora Fujimoto
AI Solutions Architect
Connecting agents, browsers, and APIs into one workflow.
著者について
ローカル MCP 拡張機能を使用して、CAPTCHA ソルバー ツールを Goose に追加します。Python を設定し、ツールの検出状況を確認し、解決タスクを実行する前にセットアップのトラブルシューティングを行います。
MCPClient を使用して Mastra を CAPTCHA ソルバーに接続し、名前空間付きツールを確認し、ケイパビリティチェックを実行して、認可されたエージェントワークフローの次のステップを定義します。