LangGraphエージェントでreCAPTCHAを解決する方法

TL;DR

• LangChainのエクストラを使用してcapsolver-agentをインストールし、get_langchain_tools()で準備されたツールを読み込みます。
• これらのツールをチャットモデルにバインドし、LangGraphのToolNode内で実行します。
• reCAPTCHA v2トークンモードの場合、正確な認可済みページのURLとサイトキーを提供します。返されるトークンはAPIレベルでのgRecaptchaResponseです。
• ツールノードの周りに許可リスト、再試行制限、シークレットの隔離、人間レビューのルーティングを設定します。
• ダイナミックページが必要な場合、同じセッション内で検出とトークンの挿入を行うブラウザモードの復元を使用します。

イントロダクション

LangGraphエージェントでreCAPTCHAを解決する最も保守性の高い方法は、チャレンジの復元をタイプ付きのツールノードとして扱い、モデルのプロンプトにネットワークロジックを埋め込まないことです。CapSolverのエージェントSDKはLangChain互換のツールを提供し、LangGraphは明示的な状態、ルーティング、エラー処理、再開性を提供します。モデルは、サポートされているチャレンジが次の認可されたステップをブロックすることを決定できますが、決定的なツールはページパラメータを検証し、ソルバーを呼び出し、構造化された結果を返します。このアーキテクチャにより、APIキーがメッセージに含まれなくなり、再試行が観測可能になり、関係のないターゲットが送信されなくなります。このチュートリアルでは、最小限のグラフの構築方法を示し、ツール呼び出しのルーティング方法、reCAPTCHA v2パラメータの説明、ブラウザ自動化、QA、RPA、承認されたパブリックデータワークフローのための本番用のセーフガードを追加します。

CapSolverがLangGraphステートマシンに適合する場所

LangGraphは、ノードが限られた作業を行い、エッジが次の動作を制御する状態付きワークフローに設計されています。CapSolverは専用のツールノードに自然に適合します：

ユーザー主導のタスク
      ↓
推論ノードがサポートされているチャレンジを識別
      ↓
ツールノードがCapSolverツールを実行
      ↓
構造化された解決策または正規化されたエラー
      ↓
ブラウザが再開、再試行、または人間レビューを要求

モデルはいつ復元が必要かを決定すべきです。シークレットが保存される場所、許可されたホスト、許可された再試行回数を決定すべきではありません。これらの決定は決定的なアプリケーションコードに属します。

CapSolver AIブログにはエージェント統合パターンが記載されており、CapSolver AIと自動化のFAQでは、復元レイヤーが既存のエージェントスタックを補完する方法が説明されています。

エージェントツールとLangGraphのインストール

ユーザー提供のCapSolverエージェントドキュメントでは、capsolver-agentがcapsolver-coreに依存していると指定されています。まずコアをインストールし、その後LangChain統合付きのエージェントパッケージをインストールします。

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"
pip install langchain-openai langgraph

実行時環境を通じて資格情報を構成します：

export CAPSOLVER_API_KEY="CAP-xxxxxxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

公式のCapSolverエージェントリポジトリはこのインポートパスをドキュメント化しています：

from capsolver_agent.langchain_tools import get_langchain_tools

tools = get_langchain_tools(api_key="YOUR_API_KEY")

返されるオブジェクトはLangChain互換のBaseToolインスタンスです。公式LangChainツールガイドでは、ツールがモデルに定義された入力と出力を公開し、型情報と説明がモデルが正しいアクションを選択するのを助けます。

reCAPTCHA v2タスクパラメータを理解する

標準的なプロキシなしのreCAPTCHA v2タスクの場合、必要な入力はページURLとサイトキーです。CapSolverの公式reCAPTCHA v2ドキュメントでは、ビルトインプロキシパス用のReCaptchaV2TaskProxyLessと、ページがreCAPTCHA Enterpriseを使用する場合の別途のエンタープライズタスクタイプがリストされています。

RESTタスクレベルでは、解決トークンがsolution.gRecaptchaResponseとして返されます。エージェントSDKはコア結果を構造化された辞書にラップし、グラフが成功または失敗でルーティングできるようにします。任意のプロセスを解析することなく。

パラメータの発見については、CapSolverブラウザ拡張ガイドとreCAPTCHA v2実装ガイドを参照してください。

CapSolverツールでLangGraphを構築する

以下の例では、公式のCapSolverツールを読み込み、それらをチャットモデルにバインドし、ToolNodeに配置します。ツールの各応答の後にグラフは推論ノードに戻ります。

import os
from typing import Literal

from capsolver_agent.langchain_tools import get_langchain_tools
from langchain_openai import ChatOpenAI
from langgraph.graph import START, StateGraph
from langgraph.graph.message import MessagesState
from langgraph.prebuilt import ToolNode, tools_condition

capsolver_tools = get_langchain_tools(
    api_key=os.environ["CAPSOLVER_API_KEY"]
)

model = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
).bind_tools(capsolver_tools)


def agent_node(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}


def safe_tool_error(error: Exception) -> str:
    return (
        "チャレンジツールが失敗しました。自動的に再試行しないでください。"
        "ワークフローをオペレータレビューに戻してください。"
    )

builder = StateGraph(MessagesState)
builder.add_node("agent", agent_node)
builder.add_node(
    "tools",
    ToolNode(
        capsolver_tools,
        handle_tool_errors=safe_tool_error,
    ),
)
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")

graph = builder.compile()

LangGraph ToolNodeリファレンスでは、ToolNodeがBaseToolインスタンスを受け入れ、ツール呼び出しを実行し、構成可能なエラー処理をサポートすることをドキュメント化しています。これは観測可能で予測可能な復元ブランチに適しています。

エージェントに狭い指示を与える

モデルは正しいツールを呼び出すために十分な文脈が必要ですが、制限のない権限を受けてはなりません。検証されたアプリケーションデータからメッセージを構築します：

request = {
    "website_url": "https://staging.example.com/approved-form",
    "website_key": "6LcXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
}

messages = [
    (
        "system",
        "あなたは承認されたワークフローのみを操作します。サポートされているreCAPTCHAが次のステップをブロックする場合、"
        "アプリケーションから提供された正確なURLとサイトキーでCapSolverのsolve_captchaツールを一度だけ呼び出してください。"
        "ターゲットを発明したり、資格情報を要求したりしないでください。解決に失敗した場合は、停止してオペレータレビューを要求してください。",
    ),
    (
        "user",
        "承認されたステージングタスクを続行してください。ブラウザは"
        f"{request['website_url']}でreCAPTCHA v2を報告し、サイトキー"
        f"{request['website_key']}を表示しました。",
    ),
]

result = graph.invoke(
    {"messages": messages},
    config={"recursion_limit": 6},
)

再帰制限は制御不能なグラフループを防ぎます。本番環境では、メッセージを構築する前に許可されたホスト名を制限し、トレースに解決トークンを保存しないでください。

グラフの前にホスト許可リストを追加する

CapSolverツールは要求されたことを解決しますが、アプリケーションがどのジョブが承認されているかを決定する必要があります。モデルの外でページURLを検証します：

from urllib.parse import urlparse

ALLOWED_HOSTS = {
    "staging.example.com",
    "qa.example.com",
}


def validate_target(url: str) -> str:
    parsed = urlparse(url)
    if parsed.scheme != "https":
        raise ValueError("HTTPSターゲットのみが許可されています")
    if parsed.hostname not in ALLOWED_HOSTS:
        raise PermissionError("ターゲットホストは承認されていません")
    return url

複数の顧客が同じプラットフォームを共有する場合、テナント固有の許可リストまたは署名付きワークフローマニフェストを使用してください。自然言語の指示でこのポリシーを変更しないでください。

成功、失敗、人間レビューのルーティング

有用な復元グラフには「解決」や「クラッシュ」だけでなく、3つの結果が必要です。ツール出力をワークフローデシジョンに正規化します：

from typing import TypedDict

class RecoveryDecision(TypedDict):
    status: Literal["continue", "retry", "review"]
    reason: str


def classify_recovery(result: dict, attempt: int) -> RecoveryDecision:
    if result.get("success"):
        return {"status": "continue", "reason": "解決が返されました"}

    error = str(result.get("error", "不明なエラー"))
    if attempt == 0 and "timeout" in error.lower():
        return {"status": "retry", "reason": "1回の制限付き再試行が許可されています"}

    return {"status": "review", "reason": error}

ブラウザが直接トークンを消費できる場合、モデルメッセージに元のトークンを露出しないでください。理想的な境界は：ツール結果 → 信頼できるブラウザコントローラー → 提出結果 → グラフに戻る際のマスキングされたステータスです。

CapSolverエラーとトラブルシューティングFAQは一般的な診断経路を提供し、CapSolverレスポンスAPIガイドは結果の処理方法を説明しています。

トークンモード vs ブラウザモード

トークンモードは通常、既知のreCAPTCHAパラメータに対して単純です。認可されたPlaywrightフローでdetect()とsolve_on_page()を同じセッションで必要とする場合、ブラウザモードは役立ちます。CapSolverエージェントドキュメントではsolve_captchaがコアトークン解決にマッピングされ、solve_on_pageがブラウザ復元にマッピングされています。

シークレットを漏洩させずに観測性を確保する

グラフの遷移と運用メトリクスを記録し、機密値を記録しないでください。役立つフィールドには次のものがあります：

safe_event = {
    "workflow_id": "wf_01J...",
    "node": "tools",
    "tool": "solve_captcha",
    "target_host": "staging.example.com",
    "challenge_type": "recaptcha_v2",
    "attempt": 1,
    "duration_ms": 6420,
    "outcome": "success",
}

CapSolver APIキー、完全な解決トークン、認証済みクッキー、フォームデータをログに記録しないでください。外部の観測システムにイベントを送信する前にトレースのマスキングを適用してください。

ボーナスコード: CapSolverダッシュボードでコード WEBS を使用すると、毎回のチャージで追加の5%のボーナスを取得できます。

本番用チェックリスト

本番用のLangGraph reCAPTCHAソルバーには、ホスト名許可リスト、固定タスクポリシー、短いトークン有効期間の処理、制限付き再試行、トレースマスキング、明示的な停止条件、オペレータレビューノードが必要です。未監視の自動化に接続する前に、承認されたステージングページでテストしてください。

CapSolver CAPTCHAソルビングFAQはタスクの動作をカバーし、CapSolver Pythonスクレイピングガイドはブラウザ自動化の実践を提供します。

責任ある使用

このワークフローは、所有するシステム、テストするシステム、または自動化に明示的な許可を与えたシステムでのみ使用してください。チャレンジの解決はアクセス権を提供しません。サイトの利用規約、レートリミット、プライバシー義務、目的制限を尊重してください。グラフがフォームを送信する、アカウントデータを変更する、または高影響力のアクションを実行する前に、人間の確認を要求してください。

結論

LangGraph reCAPTCHAソルバーは、明示的なツールノードで厳密なルーティングを行うことで最も信頼性が高くなります。CapSolverの準備済みLangChainツールを読み込み、モデルにバインドし、ToolNodeを通じて実行し、認証、シークレット、再試行、トークンの消費を決定的なアプリケーションコードに保持してください。これにより、エージェントに制限のないコントロールを与えることなく、復元機能を提供できます。

CapSolverから始めて、承認されたステージングワークフローでグラフを検証し、スケーリングする前にトレースマスキングと人間レビューを追加してください。

FAQ

LangGraphで使用するCapSolverのインポートはどれですか？

from capsolver_agent.langchain_tools import get_langchain_toolsを使用し、get_langchain_tools(api_key=...)を呼び出して、ToolNodeに渡すことができるLangChain互換ツールを取得してください。

reCAPTCHA v2トークンモードに必要な入力は何ですか？

ページURLとreCAPTCHAサイトキーが必要です。エンタープライズ、非表示、アクション、またはセッションフィールドは、認可されたページが実際にそれらを使用する場合にのみ含めます。

LangGraphモデルに解決トークンを渡すべきですか？

信頼できるツールレイヤーからブラウザコントローラーにトークンを直接送る方が好ましいです。可能な限り、マスキングされた成功または失敗イベントのみを推論グラフに戻してください。

グラフが許可する自動再試行はどのくらいですか？

通常、一時的なタイムアウトに対して1回の制限付き再試行で十分です。繰り返し拒否された場合は、URL、キー、セッション、またはページ構成が誤っている可能性があるため、人間レビューにルーティングしてください。

このパターンは動的なブラウザチャレンジを処理できますか？

はい。ワークフローが同じPlaywrightセッション内で検出とページレベルの復元が必要な場合、制御されたツールを通じてブラウザ対応のCapSolverコアメソッドを使用できます。