AIエージェントがソルバーを呼び出す前にCAPTCHAを検出する方法

TL;DR

• AIエージェントによるCAPTCHA検出は、解決ツールが呼び出される前にサポートされているチャレンジ証拠を識別する必要があります。
• CapSolverのCore SDKは、チャレンジの検出、パラメータの読み取り、解決のリクエストを分離しています。
• 空の検出結果は、SDKが検査したページ状態にサポートされているチャレンジが見つからなかったことを意味し、ページが準備完了していることを証明するものではありません。
• 以下の例は、Googleの公開reCAPTCHAデモページに対して公式の検出メソッドを実行し、解決や送信は行いません。
• 次のステップで同じブラウザページを使用し、通常のページエラーとCAPTCHAを区別し、元のタスクを後で検証してください。

エージェントがページを開くが、その後に進まない場合があります。これは、CAPTCHAに到達した、ページロードが未完了、レートリミット、または通常のフォームエラーのいずれかです。解決ツールをすぐに呼び出すと、単純なブラウザの問題が混乱を招く繰り返しリクエストのシーケンスになる可能性があります。

CapSolverは、解決前にサポートされているCAPTCHAタイプを識別するドキュメント化されたブラウザ検出メソッドを提供しています。役立つ手順は、現在のページを検査し、検出されたものを分類し、関連するツールを選択し、最終結果を確認することです。このガイドでは、これらのステップを分離し、小さな実行可能な例を使用します。所有されたQA環境、承認されたブラウザワークフロー、および公開デモページに焦点を当て、チャレンジの検出とアプリケーションタスクの完了の間には明確な境界を設けています。

ドキュメント化された検出メソッドを使用する

アプリケーションが互換性のあるブラウザページをすでに制御している場合、Core SDKの検出メソッドを使用してください。

Core SDKリファレンスには、4つの関連する操作がドキュメント化されています: detect(page)は検出されたCAPTCHAタイプを返します; get_captcha_info(page)は構造化されたパラメータを読み取ります; solve(info)は解決をリクエストします; そして solve_on_page(page)はブラウザベースの検出、解決、およびフィルバックを組み合わせます。

検出チェックを行うには、検出メソッドを呼び出してください。ページにチャレンジが含まれているかどうかを確認するために、単に解決メソッドをフルに使用しないでください。この選択を明示的に保つことで、解決サービスの資格情報が必要なステップと、ブラウザ状態を検査するステップを区別しやすくなります。

SDKは、アプリケーションが独自のステータスメッセージで使用する可能性のある任意のラベルではなく、CAPTCHAタイプの列挙型値を返します。文字列表現からマッピングを発明する代わりに、ドキュメント化された値を読み取ってください。

CapSolver for AI Agentsの概要では、検出とパラメータの準備はあなたの側で行われ、実際の認識はサービスを使用します。この区別は、ログを読むときに重要です: ローカルでの成功した検出は、解決リクエストが送信された証拠ではありません。

小さな検出例を最初に実行する

ビジネスワークフローに影響を与えないで、公式のデモページでブラウザアクセスと検出メソッドのチェックを行うために、最初にそれを使いましょう。

以下の例は、公式Core SDKのcreate_capsolverとdetectの使用法を変更したものです。追加のコードは、Playwrightブラウザを開閉し、デモウィジェットのフレームを待機し、返された列挙型値を出力します。

テスト環境ではPython 3.12、capsolver-core==0.1.1、playwright==1.63.0を使用しました。これらのパッケージを隔離された環境にインストールし、対応するChromiumブラウザをインストールしてください:

python -m pip install "capsolver-core[playwright]==0.1.1" "playwright==1.63.0"
python -m playwright install chromium --only-shell

PlaywrightのPythonインストールガイドは、別個のパッケージとブラウザのインストール手順を説明しています。Pythonパッケージをインストールするだけでは、対応するブラウザ実行ファイルが存在する保証はありません。

これをdetect_demo.pyとして保存してください:

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright


async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        try:
            page = await browser.new_page()
            await page.goto(
                "https://www.google.com/recaptcha/api2/demo",
                wait_until="domcontentloaded",
            )
            await page.wait_for_selector('iframe[title="reCAPTCHA"]')
            async with create_capsolver(api_key="YOUR_API_KEY") as cap:
                types = await cap.detect(page)
                print([item.value for item in types])
        finally:
            await browser.close()


asyncio.run(main())

python detect_demo.pyで実行してください。検証実行では、実際の出力結果は['reCaptchaV2']でした。

プレースホルダーのキーは検出のみを行うため十分であり、解決APIの呼び出し、チャレンジのクリック、デモフォームの送信、トークンの検証は行いません。実際の解決操作には、適切なサービス資格情報とタスク入力が必要です。

この実行は、テスト時のそのページでの検出パスを確認します。これは、普遍的な検出カバレッジや解決成功確率を確立するものではありません。

次の行動を決定する前に現在のページを読み取る

検出を、特定の瞬間のページの観測として扱ってください。

ページは、ウィジェットやアプリケーションコントロールが表示される前に初期ナビゲーションを終えることがあります。例では、domcontentloadedの後に、既知のデモフレームを待つ処理を行っています。別のページでは、実際のインターフェースに応じた準備状態の条件を選択してください。

Playwright Page APIは、ページナビゲーションと要素待ちの動作を説明しています。準備状態のチェックは、検査されている状態を確立するのではなく、長時間の無条件のスリープを導入しないようにする必要があります。

検出器がタイプを返すと、その結果を中断されたタスクに関連付けるために十分なコンテキストを記録してください: 承認されたページ、時間、および保留中の操作の短い説明。大きな状態マシンフレームワークは必要ありません。

検出器が空のリストを返すと、継続する前にページを検査してください。コンテンツは通常のもの、まだ読み込み中、この検出器でサポートされていない、または他の問題の影響を受けている可能性があります。"検出されなかった"と"タスクに成功"は別々のステートメントです。

CAPTCHA風のクラスを持つ単純なHTML要素も、初期化されたウィジェットと同じであるとは限りません。特にサイトが検証コントロールをどのようにレンダリングするかの変更後は、実際のページ動作をテストしてください。

CAPTCHAと隣接するエラーを分離する

証拠がその分類をサポートしている場合にのみ、ページをCAPTCHA処理のパスに送ってください。

CAPTCHAは、1つの可能性のある中断です。有効期限切れのセッション、無効なフォームフィールド、必要な権限がない、またはネットワークエラーは別の応答が必要です。ページに複数のメッセージが表示されている場合、意図された操作を妨げるものを検査してください。

例えば、HTTP 429はリクエストレートリミットを示し、リトライ遅延を含む可能性があります。これは、単独でCAPTCHAが存在している証拠ではありません。検出器とアプリケーションの応答は、決定の異なる部分を通知する必要があります。

次のアクションを単純に保ってください:

• 予期された通常のページが準備できていれば、承認されたタスクを続行してください。
• サポートされているチャレンジが検出された場合、そのパラメータと設定されたハンドラを確認してください。
• ページが関係ないエラーを表示している場合、そのエラーのトラブルシューティングパスに従ってください。
• 状態が不明確な場合、解決ツールを繰り返し呼び出す代わりに、停止して検査してください。

これは、AIエージェントのタスクがCAPTCHAで詰まる理由に関する関連記事で説明されている実用的な境界です。検出は次の決定を明確にするものであり、すべての失敗したページの周りに別のループを作成してはなりません。

CapSolverのボーナスコードを取得する

自動化予算を即座に増やす！
CapSolverアカウントにチャージする際にボーナスコード CAP26 を使用すると、毎回のチャージで 5%のボーナス を受け取れます — 何の制限もありません。
CapSolverダッシュボードで今すぐ取得してください

次のステップに適切なCapSolverレイヤーを選択する

タスクを制御しているアプリケーションに適合する統合レイヤーを選択してください。

PythonブラウザスクリプトはCore SDKを直接使用できます。LLM駆動のアプリケーションは、エージェントツールアダプターを通じてサポートされる操作を公開できます。MCPクライアントは、構成されたMCPサービスとそのサービスが実際に提供する機能へのアクセスが必要です。

エージェントツールのドキュメントは、アダプターとコアエンジンの関係を説明しています。プロンプトにツールの説明を追加しても、それがブラウザに自動的に接続されるわけではありません。実行者には必要な実行環境が必要です。

初期実装では、検出と承認された次のアクションを近くに保つようにしてください。検出後にブラウザがナビゲートした場合、古いパラメータを検査せずに新しいページ状態を確認してください。

存在するすべてのメソッドをエージェントに追加しないでください。タスクに必要な操作を公開し、アプリケーションが停止すべきタイミングを定義してください。ツール選択を小さく保つことで、トラブルシューティングが容易になります。

検出と解決後の動作を検証する

各段階をそれぞれの期待される結果に対して検証してください。

検出はSDKが見つけたものを報告する必要があります。パラメータの読み取りは、選択されたタスクに必要なフィールドを生成する必要があります。解決呼び出しは、ドキュメント化された結果またはエラーを返す必要があります。ブラウザワークフローは、その後、独自の期待されるページ、データ、または確認に到達する必要があります。

承認されたカタログ読み取りでは、成功は要求されたアイテムのデータを取得することです。テストフォームでは、成功はアプリケーションの確認を観察することです。検出器がタイプを返しても、どちらの条件も満たされません。

統合の検証時に小さなチェックセットを使用してください:

1. 通常のページは不要な解決をトリガーしない。
2. サポートされている初期化されたウィジェットは認識できる。
3. 関係ないページエラーはその独自の分岐に従う。
4. 変更されたページは以前の観測からの仮定を無効にする。
5. 失敗した試行は有用な理由を報告し、選択した制限内で停止する。

これらのチェックは、すべての現実世界のチャレンジがサポートされていることを保証するのではなく、アプリケーションの決定をテストします。実際の検出器出力をデバッグ用に保持し、一般的な「CAPTCHAが修正されました」というメッセージで置き換えないでください。

複雑なシステムを構築せずに繰り返しチェックを制御する

各タスクに明確な終了ポイントを提供し、より多くの作業を試行する前に繰り返しの中断を検査してください。

同じチャレンジが再び表示される場合、ページが変更されたか、ハンドラが完了したか、アプリケーションが結果を受け入れたかを検査してください。繰り返しの検出は、別の有料の解決タスクを作成することとは異なります。これらのアクションを別々に追跡し、無害な観測が静かに繰り返し送信になることを防いでください。

短い診断記録で十分です: ページの識別、検出されたタイプ、ハンドラの結果、アプリケーションの結果。OWASPログガイドは、運用ログでの機密情報の保護を推奨しています。APIキー、セッションクッキー、ローソリューショントークン、不要なページコンテンツを除外してください。

単一のテストからスケジュールされた作業に移行する際には、同じ明確なチェックを保持してください。範囲を段階的に拡大し、失敗を原因別にレビューし、承認されたタスクまたはアクセス条件が変更された場合は停止してください。複雑さは示されたニーズに従ってください。

検出をタスク完了から分離する

信頼性の高い検出は、エージェントが次のアクションに必要な証拠を提供します。これは解決、ブラウザ状態のチェック、またはアプリケーションからの確認を置き換えるものではありません。

小さな例から始め、承認されたページに合わせて準備状態のチェックを調整し、必要なときにCapSolverを使用してサポートされているチャレンジステップを実行してください。単純なシーケンスを維持してください: 観測、分類、処理、検証。

FAQ

Q: AIエージェントはCAPTCHAを検出できますか？

アプリケーションは、サポートされている検出メソッドを使用してライブブラウザページを検査し、その証拠をエージェントに返すことができます。CapSolverのCore SDKは、認識されたCAPTCHAタイプを返すdetectメソッドをドキュメント化しています。

Q: 検出には有料の解決リクエストが必要ですか？

示された検出のみの呼び出しは、解決サービスを呼び出さずにブラウザページを検査しました。解決は、適切な資格情報とタスク入力が必要な別の操作です。

Q: 空の検出結果とは何を意味していますか？

検査されたページ状態にサポートされているタイプが見つからなかったことを意味します。その結果を進むための許可として扱う前に、準備状態、ページエラー、および検出器のカバレッジを確認してください。

Q: そのサンプルはすべてのサイトのすべてのCAPTCHAを検出できますか？

いいえ。このサンプルは、1つの公式reCAPTCHAデモページで検証されました。他のチャレンジタイプ、レンダリングパターン、およびブラウザコンテキストには、それぞれのチェックが必要です。

Q: エージェントはいつ停止すべきですか？

ページ状態が不明確で、ワークフローが承認された範囲を逸脱した、または繰り返しの処理が確認された進展をもたらさない場合に停止してください。無限ループを続けるのではなく、観測された理由を報告してください。