CAPTCHAソルバーをLangGraphに統合する方法

TL;DR

• LangGraph CAPTCHAソルバーは、エージェントの一般的なブラウジングプロンプトに隠されているのではなく、限られたツールノードとしてモデル化する必要があります。
• グラフは、認証されたブラウザワークフローがサポートされているreCAPTCHAまたはCloudflare Turnstileチェックポイントを検出した場合にのみ一時停止する必要があります。
• ページURL、サイトキー、チャレンジタイプ、およびオプションのアクションメタデータを構造化された状態として渡す; グラフメッセージにCapSolver APIキーを配置しないでください。
• ready、failed、timeoutの結果を明示的なエッジを通じてルーティングし、エージェントが無限に再試行できないようにします。
• 戻り値のトークンを同じブラウザセッションで検証し、ターゲットアプリケーションが拒否した場合に停止します。

LangGraph統合が可能にする機能

LangGraph CAPTCHAソルバーは、認証されたブラウザタスクがサポートされている検証チェックポイントに遭遇したときに、AIワークフローに制御された復元パスを提供します。LangGraphはオーケストレーションを担当し、CapSolverはAPIまたはエージェントツールを通じて専門的なCAPTCHAタスクを処理します。

有用なデザインは小さな状態機械です：ブラウズ、検出、解決のリクエスト、トークンの適用、ページ結果の検証、そして継続または停止。これはCAPTCHA処理を観測可能にし、モデルがパラメータを即興で処理したり、制限なしに呼び出しを繰り返すのを防ぎます。

前提条件

このパターンは、自動化が許可されているサイトおよびテスト環境でのみ使用してください。LangGraphアプリケーション、ブラウザ制御レイヤー、CapSolverアカウント、およびCAPSOLVER_API_KEYのサーバーサイドシークレットストアが必要です。ブラウザステップは、CapSolverによって文書化されたパラメータを識別および収集できる必要があります。

CapSolverのAIエージェントガイドは、サポートされているエージェントワークフローを説明しています。Core SDKドキュメンテーションは、プログラマティックインターフェースをカバーし、Agent Toolsリファレンスはツール指向の使用法を文書化しています。

CAPTCHA状態契約を定義する

グラフ状態はルーティングおよび検証に必要な値のみを保持する必要があります：

from typing import Literal, TypedDict

class AgentState(TypedDict, total=False):
    page_url: str
    captcha_type: Literal["recaptcha_v2", "recaptcha_v3", "turnstile"]
    website_key: str
    action: str
    task_id: str
    token: str
    captcha_status: Literal["not_found", "pending", "ready", "failed", "timeout"]
    attempts: int

APIキーはこのオブジェクトの外に保持してください。グラフ状態はログに記録またはチェックポイントに保存される可能性があるため、資格情報は環境変数または承認されたシークレットマネージャーに格納する必要があります。

ソルバーノードを作成する

ソルバーノードは既知の状態を1つのサポートされているCapSolverタスクに変換する必要があります。以下のコードは説明用の境界です; ご使用のサービスで使用されている現在の公式SDKまたはRESTスキーマに接続してください。

MAX_ATTEMPTS = 2

def solve_captcha(state: AgentState) -> AgentState:
    attempts = state.get("attempts", 0)
    if attempts >= MAX_ATTEMPTS:
        return {**state, "captcha_status": "timeout"}

    required = ("page_url", "website_key", "captcha_type")
    if any(not state.get(key) for key in required):
        return {**state, "captcha_status": "failed"}

    result = capsolver_client.solve({
        "type": state["captcha_type"],
        "websiteURL": state["page_url"],
        "websiteKey": state["website_key"],
        "action": state.get("action"),
    })
    return {
        **state,
        "attempts": attempts + 1,
        "token": result.get("token", ""),
        "captcha_status": "ready" if result.get("token") else "failed",
    }

言語モデルにwebsiteKey、チャレンジタイプ、またはアクションを発明させないでください。アクティブなページまたはアプリケーション構成からこれらの値を抽出し、ツールコールの前に検証してください。

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

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

条件付きグラフエッジを追加する

LangGraphは、自由形式のモデルテキストではなく、観測された状態に基づいてルーティングする必要があります：

def route_after_detection(state: AgentState) -> str:
    if state.get("captcha_status") == "pending":
        return "solve_captcha"
    return "continue_browser"

def route_after_solve(state: AgentState) -> str:
    if state.get("captcha_status") == "ready":
        return "apply_token"
    return "stop_with_diagnostic"

apply_tokenノードは、チャレンジを検出した同じブラウザセッションで動作する必要があります。適用後、別の検証ノードがアプリケーションの応答、予期されるナビゲーション、またはサーバーサイドの確認を検査する必要があります。トークンのみではワークフローが成功した証拠とはなりません。

リトライループなしで失敗を処理する

失敗を分類してから、何をすべきかを決定してください。パラメータが欠如している場合は構成の問題です。拒否されたトークンは、有効期限切れのトークン、不一致のページURL、サイトキー、アクション、またはブラウザコンテキストを示している可能性があります。サービスのタイムアウトは運用上の問題であり、1回の制限付きリトライを正当化する可能性があります。

task_id、チャレンジタイプ、経過時間、およびサニタイズされたエラーコードを記録してください。一般のエージェントトレースにトークン、クッキー、資格情報、または機密ページコンテンツを保存しないでください。ページが自動化されてはならないアクションを要求した場合は、人間へのエスカレーションを行ってください。

プロダクションチェックリスト

• 許可されたドメインとチャレンジタイプを許可リストに追加する。
• 硬質タイムアウトと最大試行回数を設定する。
• 資格情報をプロンプトやチェックポイントに保持しない。
• 元のブラウザコンテキストでトークンを適用および検証する。
• ログイン、送信、支払い、アカウント変更の周辺に人間の承認を追加する。
• ツールコールの成功だけでなく、理由に基づいて完了率と失敗を追跡する。

結論

信頼性の高いLangGraph CAPTCHA統合は、明確な入力と停止条件を持つ狭い観測可能な分岐です。ブラウザオーケストレーションをLangGraphに保持し、CAPTCHAパラメータを構造化し、トークンの適用後にビジネス上の結果を検証してください。CapSolverは、エージェント全体を透過的な復元ループにしないで専門的なCAPTCHA機能を提供できます。

FAQ

Q: LangGraphは自分でCAPTCHAを解くことができますか？

いいえ。LangGraphはノードと状態をオーケストラします。専門的な作業は、別途認証されたブラウザとCAPTCHAサービスが行います。

Q: グラフがサポートすべきCAPTCHAタイプはどれですか？

現在のCapSolverエージェント表面で文書化されているタイプ、例えばreCAPTCHA v2、reCAPTCHA v3、Cloudflare Turnstileのみを開始してください。

Q: APIキーはLangGraph状態に保存すべきですか？

いいえ。グラフ状態は永続化またはログに記録される可能性があるため、APIキーはサーバーサイドの環境変数またはシークレットマネージャーに保存してください。

Q: ノードはどのくらいの回数リトライすべきですか？

1〜2回の制限付き試行を行い、繰り返しの拒否、パラメータの欠如、または認証の不確実性で停止してください。