
Sora Fujimoto
AI Solutions Architect

solve_turnstile Python関数を登録し、エージェントが任意の解決コードを書くのを防ぐ。AntiTurnstileTaskProxyLessタスクを使用し、websiteURLとwebsiteKeyを指定する。actionとcdataが存在する場合のみ、オプショナルなTurnstileのactionとcdataを含める。AutoGenでCloudflare Turnstileを安全に解決する最も良い方法は、CapSolverを型付きで範囲が狭い関数ツールとして登録することです。AutoGenはワークフローにTurnstile解決が必要なタイミングを決定できますが、決定論的なPythonコードがターゲットURLとサイトキーを検証し、ドキュメントされたAntiTurnstileTaskProxyLessを作成し、結果のトークンのみを返す必要があります。ブラウザレイヤーはそのトークンを同じ認可されたワークフローに適用し、続けます。このアーキテクチャは、CapSolver AIエージェントのドキュメントにある「モデルが決定し、コアが実行する」境界とAutoGenの公式ツール登録モデルに従います。このガイドでは、ソルバ関数を作成し、コールャーとエクスキューターのエージェントに登録し、オプショナルなウィジェットメタデータを処理し、制限付きリトライを追加し、モデルに資格情報や制限のないターゲットが届かないようにする生産性の制御を設計します。
AutoGenのツールは事前に定義された関数で、エージェントが呼び出すことができます。公式AutoGenツール使用ガイドでは、ツールがエージェントが実行可能なことをより効果的に制限する方法を説明しています。型ヒントと簡潔な説明を使用してツールスキーマを自動的に作成します。
この境界は特にチャレンジ処理において重要です。エージェントはあなたのCapSolver APIキーを受信してはならず、任意のサイトを選択したり、ブラウザコンテキストを直接制御してはなりません。エージェントは、自動化ワークフローによってすでに承認されたページの解決を要求するだけです。
CapSolver AIブログではエージェント指向のパターンがカバーされており、CapSolver AIと自動化のFAQでは解決ツールが制御された自動化にどのように適合するかが説明されています。
CapSolverの公式Turnstileドキュメントでは、プロキシレスタスクタイプAntiTurnstileTaskProxyLessが指定されています。必須パラメータはwebsiteURLとwebsiteKeyです。オプショナルなメタデータにはウィジェットのactionとcdata値が含まれる場合があります。
| パラメータ | 必須 | ソース | 目的 |
|---|---|---|---|
type |
はい | 固定値 | AntiTurnstileTaskProxyLessでなければなりません |
websiteURL |
はい | 現在の認可されたページ | トークンをターゲットページに関連付けます |
websiteKey |
はい | Turnstileウィジェット | サイトのTurnstile構成を識別します |
metadata.action |
いいえ | data-action属性 |
ウィジェットで使用されるアクション値を保持します |
metadata.cdata |
いいえ | data-cdata属性 |
ウィジェットに添付されたカスタマーデータを保持します |
Cloudflareは管理された、非対話型、および非表示のウィジェットモードをドキュメントしています。Cloudflare Turnstileの概要では、ウィジェットがブラウザシグナルを評価し、サーバーサイド検証用のトークンを発行する方法が説明されています。CapSolverはサポートされているサブタイプを自動的に処理するため、タスクにはサブタイプフィールドは必要ありません。
pip install pyautogen capsolver
環境変数に資格情報を保存します:
export CAPSOLVER_API_KEY="CAP-xxxxxxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
提供されたドキュメントで説明されている新しいCapSolverエージェントアーキテクチャの場合、チームはコアとアダプタパッケージもインストールできます:
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 しやすくなります。
モデルには非機密入力のみを提供する必要があります。CapSolverキーは関数の実行環境内に残ります。
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のクラシックAgentChat APIは、ツール呼び出しを提案するエージェントとそれを実行するエクスキューターを分離しています。公式ドキュメントでは、同じ関数を両エージェントに登録するためのregister_function()が用意されています。
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製品ページを参照してください。
ブラウザまたはオーケストレーションレイヤーはウィジェットを検出し、正確なパラメータを提供する必要があります。モデルはシークレットを検査したり、任意のページをスクレイピングしてターゲットを発見したりしてはなりません。
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トークンは通常、元のフォームまたはサーバー要求で消費されます。正確な統合は承認されたアプリケーションに依存します。ブラウザワークフローの場合、返されたトークンをウィジェットと送信パスを知っている決定論的なコードに渡します。
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では無効または拒否されたトークンの診断に役立ちます。
エージェントが無限にリトライしないようにしてください。試行回数を制限し、失敗を分類して自動化が安全に停止できるようにします。
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キーにアクセス可能 |
| ツールスキーマ | 簡潔な説明を持つ型付きパラメータ |
| オプションメタデータ | ウィジェットが使用する場合にのみactionとcdataを送信 |
| リトライポリシー | 最大2回の試行、その後オペレーターのレビュー |
| トークン処理 | ログに完全なトークンを保存または公開しない |
| ブラウザ統合 | トークンを同じ承認されたワークフローに適用 |
| コンプライアンス | 利用規約、レートリミット、プライバシー、目的の制限を尊重 |
CapSolver CAPTCHA解決FAQでは一般的なタスク動作が説明されており、CapSolverウェブスクレイピングFAQでは自動収集の運用制御がカバーされています。
このワークフローは、あなたが所有する、テストする、または自動化するための明示的な許可を持つアプリケーションでのみ使用してください。ソルバトークンは、プライベートデータへのアクセス、トランザクションの送信、アカウントの作成、またはサイトの利用規約を無視する権限を提供しません。レートリミットを適用し、監査記録を保持し、データの変更やユーザーに影響を与えるアクションには確認を求めてください。
AutoGenでCloudflare Turnstileを信頼性高く解決するには、CapSolverを制限されたツールとして、オープンエンドのエージェントロジックではなくします。AutoGenのアシスタントがツールが適切なタイミングを決定し、エクスキューターが検証されたAntiTurnstileTaskProxyLessを実行し、ブラウザレイヤーが同じ承認されたワークフロー内で結果のトークンを消費します。この分離により、統合はテスト、監査、セキュリティがより簡単になります。
CapSolverから始めて、制御できるステージングページでフローを検証し、本番デプロイ前にホスト許可リスト、制限付きリトライ、トークンセーフなログを追加してください。
ドキュメントされたタスクタイプはAntiTurnstileTaskProxyLessなので、タスクにプロキシを提供する必要はありません。あなたのより広範なブラウザワークフローには独自のネットワーク構成があるかもしれません。
websiteURLとwebsiteKeyが必須です。metadata.actionとmetadata.cdataはオプションで、ウィジェットがそれらを使用する場合にのみ提供する必要があります。
より安全な設計は、決定論的なブラウザまたはアプリケーションレイヤーがサイトキーを抽出し、検証し、ツールに提供することです。モデルが値を発明したり推測したりしないようにしてください。
コールャーはツール呼び出しを提案し、エクスキューターはLLMなしで制御されたPythonコードを実行します。これにより、シークレットとランタイム権限が推論エージェントから遠ざけられます。
ページのURL、サイトキー、オプションのアクションまたはCDATA、トークンの新鮮さ、および提出パスを確認してください。最大で1回または2回リトライし、ループする代わりにオペレーターによるレビューを待つために一時停止してください。