CAPSOLVER
ブログ
AutoGenエージェントでクラウドフレアトゥルンスタイールを解決する方法

Cloudflare TurnstileをAutoGenエージェントで解決する方法

Logo of CapSolver

Sora Fujimoto

How to use CapSolver

25-Aug-2026

TL;DR

  • AutoGenに狭いsolve_turnstile Python関数を登録し、エージェントが任意の解決コードを書くのを防ぐ。
  • CapSolverのドキュメントされたAntiTurnstileTaskProxyLessタスクを使用し、websiteURLwebsiteKeyを指定する。
  • 認可されたページにactioncdataが存在する場合のみ、オプショナルなTurnstileのactioncdataを含める。
  • 解決トークンを決定論的なブラウザレイヤーに返し、そのレイヤーがトークンを挿入し、元のワークフローを送信する。
  • APIキー、ブラウザセッション、ターゲットの権限を言語モデルのプロンプトから外す。

イントロダクション

AutoGenでCloudflare Turnstileを安全に解決する最も良い方法は、CapSolverを型付きで範囲が狭い関数ツールとして登録することです。AutoGenはワークフローにTurnstile解決が必要なタイミングを決定できますが、決定論的なPythonコードがターゲットURLとサイトキーを検証し、ドキュメントされたAntiTurnstileTaskProxyLessを作成し、結果のトークンのみを返す必要があります。ブラウザレイヤーはそのトークンを同じ認可されたワークフローに適用し、続けます。このアーキテクチャは、CapSolver AIエージェントのドキュメントにある「モデルが決定し、コアが実行する」境界とAutoGenの公式ツール登録モデルに従います。このガイドでは、ソルバ関数を作成し、コールャーとエクスキューターのエージェントに登録し、オプショナルなウィジェットメタデータを処理し、制限付きリトライを追加し、モデルに資格情報や制限のないターゲットが届かないようにする生産性の制御を設計します。

エージェント生成コードではなくツールを使用する理由?

AutoGenのツールは事前に定義された関数で、エージェントが呼び出すことができます。公式AutoGenツール使用ガイドでは、ツールがエージェントが実行可能なことをより効果的に制限する方法を説明しています。型ヒントと簡潔な説明を使用してツールスキーマを自動的に作成します。

この境界は特にチャレンジ処理において重要です。エージェントはあなたのCapSolver APIキーを受信してはならず、任意のサイトを選択したり、ブラウザコンテキストを直接制御してはなりません。エージェントは、自動化ワークフローによってすでに承認されたページの解決を要求するだけです。

CapSolver AIブログではエージェント指向のパターンがカバーされており、CapSolver AIと自動化のFAQでは解決ツールが制御された自動化にどのように適合するかが説明されています。

Cloudflare Turnstileに必要なパラメータ

CapSolverの公式Turnstileドキュメントでは、プロキシレスタスクタイプAntiTurnstileTaskProxyLessが指定されています。必須パラメータはwebsiteURLwebsiteKeyです。オプショナルなメタデータにはウィジェットのactioncdata値が含まれる場合があります。

パラメータ 必須 ソース 目的
type はい 固定値 AntiTurnstileTaskProxyLessでなければなりません
websiteURL はい 現在の認可されたページ トークンをターゲットページに関連付けます
websiteKey はい Turnstileウィジェット サイトのTurnstile構成を識別します
metadata.action いいえ data-action属性 ウィジェットで使用されるアクション値を保持します
metadata.cdata いいえ data-cdata属性 ウィジェットに添付されたカスタマーデータを保持します

Cloudflareは管理された、非対話型、および非表示のウィジェットモードをドキュメントしています。Cloudflare Turnstileの概要では、ウィジェットがブラウザシグナルを評価し、サーバーサイド検証用のトークンを発行する方法が説明されています。CapSolverはサポートされているサブタイプを自動的に処理するため、タスクにはサブタイプフィールドは必要ありません。

AutoGenとCapSolverのインストール

bash Copy
pip install pyautogen capsolver

環境変数に資格情報を保存します:

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

提供されたドキュメントで説明されている新しいCapSolverエージェントアーキテクチャの場合、チームはコアとアダプタパッケージもインストールできます:

bash Copy
pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

以下の直接的なcapsolver.solve()関数は、公式のTurnstileタスクフィールドを使用し、AutoGenツールとしてラップされています。これにより、フレームワークの統合が簡単になり、タスクペイロードが audits しやすくなります。

型付きTurnstileソルバ関数の作成

モデルには非機密入力のみを提供する必要があります。CapSolverキーは関数の実行環境内に残ります。

python Copy
import os
from typing import Annotated
from urllib.parse import urlparse

import capsolver

capsolver.api_key = os.environ["CAPSOLVER_API_KEY"]

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


def solve_turnstile(
    website_url: Annotated[str, "Turnstileを含む承認済みページURL"],
    website_key: Annotated[str, "ウィジェットからのTurnstileサイトキー"],
    action: Annotated[str, "オプションのdata-action値"] = "",
    cdata: Annotated[str, "オプションのdata-cdata値"] = "",
) -> dict:
    """承認されたページのTurnstileを解決し、トークンを返します。"""
    parsed = urlparse(website_url)
    if parsed.scheme != "https" or parsed.hostname not in ALLOWED_HOSTS:
        return {
            "success": False,
            "error": "ターゲットは承認されたホストの許可リストにありません",
        }

    if not website_key.startswith("0x4"):
        return {
            "success": False,
            "error": "予期せぬTurnstileサイトキーの形式",
        }

    task = {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": website_url,
        "websiteKey": website_key,
    }

    metadata = {}
    if action:
        metadata["action"] = action
    if cdata:
        metadata["cdata"] = cdata
    if metadata:
        task["metadata"] = metadata

    try:
        solution = capsolver.solve(task)
        token = solution.get("token")
        if not token:
            return {"success": False, "error": "Turnstileトークンが返されませんでした"}
        return {
            "success": True,
            "token": token,
            "solution_type": solution.get("type", "turnstile"),
        }
    except Exception as exc:
        return {"success": False, "error": str(exc)}

許可リストは意図的です。これがないと、プロンプトがエージェントに無関係なターゲットを送信する可能性があります。本番システムでは、許可リストをテナントの構成、ジョブの権限、または署名されたワークフローマニフェストから構築できます。

AutoGenに関数を登録する

AutoGenのクラシックAgentChat APIは、ツール呼び出しを提案するエージェントとそれを実行するエクスキューターを分離しています。公式ドキュメントでは、同じ関数を両エージェントに登録するためのregister_function()が用意されています。

python Copy
import os
from autogen import ConversableAgent, register_function

assistant = ConversableAgent(
    name="TurnstileCoordinator",
    system_message=(
        "承認された自動化ワークフローのみを続行してください。"
        "アプリケーションがTurnstileウィジェットを報告し、正確なページURLとサイトキーを提供した場合にのみsolve_turnstileを呼び出してください。"
        "決してターゲットを発明したり、資格情報を要求したりしないでください。"
        "ツールが2回失敗した場合、停止してオペレーターのレビューを求めてください。"
    ),
    llm_config={
        "config_list": [{
            "model": "gpt-4o-mini",
            "api_key": os.environ["OPENAI_API_KEY"],
        }]
    },
)

executor = ConversableAgent(
    name="TurnstileToolExecutor",
    llm_config=False,
    human_input_mode="NEVER",
)

register_function(
    solve_turnstile,
    caller=assistant,
    executor=executor,
    name="solve_turnstile",
    description=(
        "承認されたHTTPSページのCloudflare Turnstileを、正確なサイトキーとオプションのaction/cdata値を使用して解決します。"
    ),
)

AutoGenは関数シグネチャと型アノテーションからツールスキーマを生成します。説明は運用的で具体的に保つことで、モデルがツールが適切なタイミングを理解できるようにします。

他のフレームワークパターンについては、CapSolver自動化チュートリアルCapSolver製品ページを参照してください。

ツール呼び出しの会話を開始する

ブラウザまたはオーケストレーションレイヤーはウィジェットを検出し、正確なパラメータを提供する必要があります。モデルはシークレットを検査したり、任意のページをスクレイピングしてターゲットを発見したりしてはなりません。

python Copy
chat_result = executor.initiate_chat(
    assistant,
    message=(
        "承認されたステージングワークフローがCloudflare Turnstileに遭遇しました。\n"
        "website_url=https://staging.example.com/account-check\n"
        "website_key=0x4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n"
        "action=account_check\n"
        "cdata=\n"
        "登録されたツールを1回呼び出し、構造化された結果を返してください。"
    ),
    max_turns=4,
)

本番設計では、構造化されたアプリケーションコードが検証されたランタイムデータからこのメッセージを構築する必要があります。信頼できない自然言語入力からサイトキーまたはターゲットURLを直接受け取らないでください。

ブラウザレイヤーでトークンを適用する

Turnstileトークンは通常、元のフォームまたはサーバー要求で消費されます。正確な統合は承認されたアプリケーションに依存します。ブラウザワークフローの場合、返されたトークンをウィジェットと送信パスを知っている決定論的なコードに渡します。

python Copy
async def apply_turnstile_token(page, token: str):
    await page.evaluate(
        """
        (token) => {
          const response = document.querySelector(
            'input[name="cf-turnstile-response"]'
          );
          if (!response) {
            throw new Error('Turnstile response field not found');
          }
          response.value = token;
          response.dispatchEvent(new Event('input', { bubbles: true }));
          response.dispatchEvent(new Event('change', { bubbles: true }));
        }
        """,
        token,
    )

一部のアプリケーションではコールバックベースのレンダリングやサーバー管理の送信が使用されます。自前のステージングアプリケーションでテストし、サポートされている統合に従ってください。Cloudflareのサーバーサイド検証ドキュメントでは、サイト所有者がSiteverifyでトークンを検証する必要があることが説明されています。

CapSolver Turnstileガイドではさらに実装の文脈が提供され、CapSolverトラブルシューティングFAQでは無効または拒否されたトークンの診断に役立ちます。

制限付きリトライと構造化されたエラーを追加する

エージェントが無限にリトライしないようにしてください。試行回数を制限し、失敗を分類して自動化が安全に停止できるようにします。

python Copy
import asyncio

MAX_ATTEMPTS = 2

async def solve_with_policy(params: dict) -> dict:
    last_error = "unknown error"

    for attempt in range(1, MAX_ATTEMPTS + 1):
        result = solve_turnstile(**params)
        if result.get("success"):
            return {
                **result,
                "attempt": attempt,
            }

        last_error = result.get("error", last_error)
        if "allowlist" in last_error or "site-key" in last_error:
            break
        await asyncio.sleep(2 * attempt)

    return {
        "success": False,
        "error": last_error,
        "requires_operator_review": True,
    }

安全なメタデータのみをログに記録してください: ターゲットホスト名、タスクタイプ、期間、結果、正規化されたエラー、試行回数。完全な解決トークン、APIキー、セッションクッキー、フォームの内容はログに記録しないでください。

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

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

コントロール 推奨される実装
ターゲット認証 HTTPSホスト許可リストまたは署名されたジョブマニフェスト
シークレットの分離 エクスキュータープロセスのみがCapSolverキーにアクセス可能
ツールスキーマ 簡潔な説明を持つ型付きパラメータ
オプションメタデータ ウィジェットが使用する場合にのみactioncdataを送信
リトライポリシー 最大2回の試行、その後オペレーターのレビュー
トークン処理 ログに完全なトークンを保存または公開しない
ブラウザ統合 トークンを同じ承認されたワークフローに適用
コンプライアンス 利用規約、レートリミット、プライバシー、目的の制限を尊重

CapSolver CAPTCHA解決FAQでは一般的なタスク動作が説明されており、CapSolverウェブスクレイピングFAQでは自動収集の運用制御がカバーされています。

責任ある使用

このワークフローは、あなたが所有する、テストする、または自動化するための明示的な許可を持つアプリケーションでのみ使用してください。ソルバトークンは、プライベートデータへのアクセス、トランザクションの送信、アカウントの作成、またはサイトの利用規約を無視する権限を提供しません。レートリミットを適用し、監査記録を保持し、データの変更やユーザーに影響を与えるアクションには確認を求めてください。

結論

AutoGenでCloudflare Turnstileを信頼性高く解決するには、CapSolverを制限されたツールとして、オープンエンドのエージェントロジックではなくします。AutoGenのアシスタントがツールが適切なタイミングを決定し、エクスキューターが検証されたAntiTurnstileTaskProxyLessを実行し、ブラウザレイヤーが同じ承認されたワークフロー内で結果のトークンを消費します。この分離により、統合はテスト、監査、セキュリティがより簡単になります。

CapSolverから始めて、制御できるステージングページでフローを検証し、本番デプロイ前にホスト許可リスト、制限付きリトライ、トークンセーフなログを追加してください。

FAQ

CapSolverのTurnstileタスクにはプロキシが必要ですか?

ドキュメントされたタスクタイプはAntiTurnstileTaskProxyLessなので、タスクにプロキシを提供する必要はありません。あなたのより広範なブラウザワークフローには独自のネットワーク構成があるかもしれません。

タスクに必要なフィールドはどれですか?

websiteURLwebsiteKeyが必須です。metadata.actionmetadata.cdataはオプションで、ウィジェットがそれらを使用する場合にのみ提供する必要があります。

AutoGenはサイトキーを自動的に発見できますか?

より安全な設計は、決定論的なブラウザまたはアプリケーションレイヤーがサイトキーを抽出し、検証し、ツールに提供することです。モデルが値を発明したり推測したりしないようにしてください。

なぜコールャーとエクスキューターのエージェントを別々に使用するのですか?

コールャーはツール呼び出しを提案し、エクスキューターはLLMなしで制御されたPythonコードを実行します。これにより、シークレットとランタイム権限が推論エージェントから遠ざけられます。

返されたトークンが拒否された場合、何が起こりますか?

ページのURL、サイトキー、オプションのアクションまたはCDATA、トークンの新鮮さ、および提出パスを確認してください。最大で1回または2回リトライし、ループする代わりにオペレーターによるレビューを待つために一時停止してください。

コンプライアンス免責事項: このブログで提供される情報は、情報提供のみを目的としています。CapSolverは、すべての適用される法律および規制の遵守に努めています。CapSolverネットワークの不法、詐欺、または悪用の目的での使用は厳格に禁止され、調査されます。私たちのキャプチャ解決ソリューションは、公共データのクローリング中にキャプチャの問題を解決する際に100%のコンプライアンスを確保しながら、ユーザーエクスペリエンスを向上させます。私たちは、サービスの責任ある使用を奨励します。詳細については、サービス利用規約およびプライバシーポリシーをご覧ください。

もっと見る

CapSolver MCP 公式登録 チュートリアルでは、登録記録、uvx コマンド、APIキー変数、およびアクティブな stdio 状態を表示します。
CapSolver MCPの公式MCPレジストリからのインストール方法

オフィシャル MCP レジストリで CapSolver MCP を検索し、uvx または pip を使用してバージョン 0.1.3 をインストールし、ローカルクライアントを設定し、stdio ツールを確認してください。

ai
Logo of CapSolver

Sora Fujimoto

18-Sep-2026

Pydantic AI CAPTCHA ツール: タイプ入力とソルバーの結果
Pydantic AI CAPTCHA ツール: タイプ入力とソルバーの結果

Pydantic AIに公式のCapSolverアダプタを使用してCAPTCHAツールを追加し、ローカルでツールの実行をテストし、タイプされた入力と構造化されたソルバーの結果を処理します。

ai
Logo of CapSolver

Sora Fujimoto

18-Sep-2026

MCPとCLIインターフェースが一つのAIエージェントツールサービスに接続されている
MCP 対 CLI における AIエージェントの コンテキストコストとフェールヤー処理

AIエージェントのMCPとCLIインターフェースを、ツール発見、コンテキストコスト、セキュリティ、デバッグ、フェールチャーアイド、およびハイブリッドアーキテクチャについて比較してください。

ai
Logo of CapSolver

Sora Fujimoto

18-Sep-2026

AIブラウザエージェントは、目的のフォームを選択し、そのCAPTCHAウィジェットをマッチングし、提出結果を確認します。
AIブラウザエージェントにおける複数のCAPTCHAウィジェットの取り扱い方法

1ページに複数のCAPTCHAウィジェットを処理するには、明示的なフォーム所有権、ソルバーのパラメータ、結果のルーティング、および意図されたAIエージェントのアクションの確認を備える。

ai
Logo of CapSolver

Lucas Mitchell

15-Sep-2026

AIエージェント対スクリプト:ウェブオートメーションにおける選択の仕方と主要な意思決定の図付き
AIエージェント対スクリプト:ウェブオートメーションにおける選択の仕方

タスクの不確実性、テスト可能性、コスト、信頼性のある実行に必要な制御を基に、AIエージェント、スクリプト、ハイブリッドWeb自動化のいずれかを選択してください。

ai
Logo of CapSolver

Lucas Mitchell

11-Sep-2026

CapSolver MCP ServerはAIエージェントを5つの自動化ツールに接続します
CapSolver MCP サーバーは現在、AIエージェント向けに利用可能になりました

PyPIからCapSolver MCP Serverをインストールしてください。そして、互換性のあるAIエージェントに、Model Context Protocolを通じて認可されたCAPTCHAの処理のための5つのツールを提供してください。

ai
Logo of CapSolver

Sora Fujimoto

10-Sep-2026