
Sora Fujimoto
AI Solutions Architect

OpenAI Agents SDKは、ツールコール機能を備えたプロダクション対応のフレームワークを提供します。これらのエージェントがreCAPTCHAで保護されたウェブサイトと相互作用する際には、検証チャレンジをプログラム的にクリアする方法が必要です。CapSolverのcapsolver-agentパッケージは、@function_toolデコレーターを通じてOpenAI Agents SDKと統合され、エージェントがreCAPTCHA v2およびv3のチャレンジを自律的なワークフローの一部として解決できるようにします。
@function_toolを使用してコール可能なツールを登録します - CapSolverはこのパターンをネイティブにサポートしていますcapsolver-agentのexecute_tool()関数は、SDKと互換性のある単一の非同期呼び出しで解決をラップしますOpenAI Agents SDKは、ツールを使用してマルチステップタスクを実行するエージェントを構築する開発者を支援します。エージェントのタスクにウェブインタラクションが含まれる場合(ログイン後のデータアクセス、フォームの提出、保護されたページからの情報収集など)、reCAPTCHAチャレンジが進行を妨げます。エージェントは次のアクションを推論できますが、解決ツールがないと、進行するために必要な検証トークンを生成できません。
reCAPTCHAは、エージェントがアクセスするサイトで特に一般的です:ログインポータル、レート制限付きデータAPI、政府データベース、SaaSプラットフォーム。 GoogleのreCAPTCHAドキュメンテーションによると、世界中で500万以上のサイトがreCAPTCHAを使用しており、エージェントが遭遇する最も可能性の高い検証チャレンジです。
CapSolverのアーキテクチャは、OpenAI Agents SDKの設計と完全に一致しています:エージェントは「何をすべきか」(包括的にCAPTCHAを解決するタイミングを含む)を決定し、CapSolverはその「解決」をAIサービスを通じて処理します。この責任の分離により、エージェントのロジックはクリーンなままに保たれ、検証クリア機能が追加されます。
必要なパッケージをインストールします:
# CapSolverコアエンジン
pip install git+https://github.com/capsolver-ai/capsolver-core.git
# CapSolverエージェントツール
pip install git+https://github.com/capsolver-ai/capsolver-agent.git
# OpenAI Agents SDK
pip install openai-agents
環境変数を設定します:
export CAPSOLVER_API_KEY="your-capsolver-api-key"
export OPENAI_API_KEY="your-openai-api-key"
SDKは現在、reCAPTCHA v2、reCAPTCHA v3(エンタープライズを含む)、およびCloudflare Turnstileをサポートしています。これは、エージェントが頻繁に遭遇する検証タイプをカバーしています。
OpenAI Agents SDKは@function_toolを使用して、エージェントが呼び出せるツールを定義します。CapSolverのエクスキュータをこのパターンにラップします:
from agents import Agent, Runner, function_tool
from capsolver_agent.schema import execute_tool
@function_tool
async def solve_recaptcha(
website_url: str,
website_key: str,
captcha_type: str = "reCaptchaV2"
) -> str:
"""ウェブサイト上のreCAPTCHAチャレンジを解決し、検証トークンを返します。
ページ上のreCAPTCHA検証を通過する必要がある場合にこのツールを使用してください。
引数:
website_url: reCAPTCHAが含まれるページの完全なURL
website_key: reCAPTCHAサイトキー(data-sitekey属性にあります)
captcha_type: 'reCaptchaV2'または'reCaptchaV3'(デフォルト: reCaptchaV2)
戻り値:
提出するg-recaptcha-responseとしての解決されたreCAPTCHAトークン
"""
result = await execute_tool("solve_captcha", {
"captcha_type": captcha_type,
"website_url": website_url,
"website_key": website_key
}, api_key="YOUR_CAPSOLVER_API_KEY")
if result["success"]:
return f"reCAPTCHAが解決されました。トークン: {result['solution']['token']}"
return f"解決に失敗しました: {result['error']}"
capsolver-agentのexecute_tool()関数は、タスクの作成、結果のポーリング、構造化された出力の返却を含むフルソルブライフサイクルを処理する単一の非同期呼び出しです。これは、フルエクスキュータループを構築することなく、1回のソルブを希望するシナリオに特化しています。
OpenAI Agents SDKの@function_toolデコレーターは、モデルがツールのパラメータを理解するために必要なJSONスキーマを自動的に生成します。エージェントはツールの説明を認識し、いつ使用すべきかを理解し、SDKの組み込みの関数コールメカニズムを通じて正しい引数で呼び出します。
async defを使用し、CapSolver呼び出しではawaitを使用してください。reCAPTCHA解決ツールを含むOpenAIエージェントを構築します:
from agents import Agent, Runner
# reCAPTCHA解決機能を持つエージェントを作成
captcha_agent = Agent(
name="Web Access Agent",
instructions="""あなたはユーザーがウェブサイトと相互作用するのを支援するエージェントです。
タスクがreCAPTCHA保護されたページにアクセスする必要がある場合、solve_recaptchaツールを使用して検証トークンを取得してください。
reCAPTCHA v2の場合: captcha_type='reCaptchaV2'を使用してください
reCAPTCHA v3の場合: captcha_type='reCaptchaV3'を使用してください
ユーザーのリクエストから正確なwebsite_urlとwebsite_keyを提供してください。""",
tools=[solve_recaptcha]
)
# エージェントを実行
async def main():
result = await Runner.run(
captcha_agent,
"I need to access https://example.com/login which has a reCAPTCHA v2. "
"The site key is 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. "
"Please solve it and give me the token."
)
print(result.final_output)
import asyncio
asyncio.run(main())
エージェントはリクエストを処理し、reCAPTCHA解決が必要であることを認識し、提供されたパラメータでツールを呼び出し、ユーザーにトークンを返します。
OpenAI Agents SDKは、会話ループ、ツールディスパッチ、結果の統合を自動的に処理します。ツールを一度定義すれば、SDKのランタイムがいつどのように呼び出されるかを管理します。これは、手動で関数コールループを構築するよりも簡単です。
reCAPTCHA v3はスコアベースで非表示であり、page_actionパラメータを必要とし、関連するスコアを持つトークンを返します。専用のツールを作成します:
@function_tool
async def solve_recaptcha_v3(
website_url: str,
website_key: str,
page_action: str = "verify",
min_score: float = 0.7
) -> str:
"""reCAPTCHA v3(非表示、スコアベース)チャレンジを解決します。
サイトがreCAPTCHA v3を使用している場合にこのツールを使用してください。チェックボックスは表示されませんが、スコアベースのトークンが背景で検証されます。
引数:
website_url: ページの完全なURL
website_key: reCAPTCHA v3サイトキー
page_action: スコアリング用のアクション名(例: 'login', 'submit', 'verify')
min_score: 最低許容スコア(0.0-1.0、デフォルト 0.7)
"""
result = await execute_tool("solve_captcha", {
"captcha_type": "reCaptchaV3",
"website_url": website_url,
"website_key": website_key,
"page_action": page_action,
"min_score": min_score
}, api_key="YOUR_CAPSOLVER_API_KEY")
if result["success"]:
return f"reCAPTCHA v3が高スコアで解決されました。トークン: {result['solution']['token']}"
return f"解決に失敗しました: {result['error']}"
reCAPTCHA v3の解決ガイドでは、異なるサイトに正しいpage_actionパラメータを識別する方法が説明されています。一般的なアクションにはlogin、submit、homepage、verifyがあります。
reCAPTCHA解決を他のツールと組み合わせて、完全なウェブタスクを実行するエージェントを作成します:
from agents import Agent, Runner, function_tool
@function_tool
async def solve_recaptcha(website_url: str, website_key: str, captcha_type: str = "reCaptchaV2") -> str:
"""reCAPTCHAを解決し、トークンを返します。"""
result = await execute_tool("solve_captcha", {
"captcha_type": captcha_type,
"website_url": website_url,
"website_key": website_key
}, api_key="YOUR_CAPSOLVER_API_KEY")
if result["success"]:
return f"トークン: {result['solution']['token']}"
return f"失敗: {result['error']}"
@function_tool
async def check_solver_balance() -> str:
"""残りのCAPTCHA解決クレジットを確認します。"""
result = await execute_tool("get_balance", {}, api_key="YOUR_CAPSOLVER_API_KEY")
if result["success"]:
return f"残高: ${result['balance']:.2f}"
return "残高を確認できませんでした"
# マルチ機能エージェント
web_agent = Agent(
name="自律的ウェブエージェント",
instructions="""ユーザーがreCAPTCHAで保護されたウェブリソースにアクセスするのを支援します。
reCAPTCHA v2(表示されるチェックボックス)およびv3(非表示のスコアベース)の両方を解決できます。
ユーザーがコストについて尋ねた場合は、解決前に残高を確認してください。
reCAPTCHAを解決する際:
- v2: captcha_type='reCaptchaV2'を使用
- v3: captcha_type='reCaptchaV3'を使用し、分かっている場合はpage_actionを含めてください
ユーザーがフォームに提出できるように、トークンを明確に返してください。""",
tools=[solve_recaptcha, check_solver_balance]
)
async def run_web_agent(task: str):
result = await Runner.run(web_agent, task)
return result.final_output
このパターンは、単一のセッション内で異なるサイトで複数のreCAPTCHAバージョンを処理するエージェントに適しています。
ボーナスコードを取得してください: CapSolverダッシュボードでコードWEBSを使用すると、毎回の充電で追加の5%のボーナスを取得できます。OpenAIエージェントを構築する開発者に最適です。
reCAPTCHA解決機能を持つプロダクション用OpenAIエージェントの場合:
import os
from agents import Agent, Runner, function_tool
from capsolver_agent.schema import create_executor
# カスタム設定でプロダクションエクスキュータ
executor = create_executor(
api_key=os.environ["CAPSOLVER_API_KEY"],
default_timeout=90, # 90秒のタイムアウト
polling_interval=3 # 3秒ごとにポーリング
)
@function_tool
async def solve_recaptcha_production(
website_url: str,
website_key: str,
captcha_type: str = "reCaptchaV2"
) -> str:
"""リトライロジックを備えたプロダクショングレードのreCAPTCHAソルバー。"""
for attempt in range(3):
result = await executor.execute("solve_captcha", {
"captcha_type": captcha_type,
"website_url": website_url,
"website_key": website_key
})
if result["success"]:
return f"解決済み(試行 {attempt+1})。トークン: {result['solution']['token']}"
if attempt < 2:
await asyncio.sleep(2)
return f"3回の試行後に失敗: {result.get('error')}"
プロダクションでの考慮事項の主なポイント:
default_timeoutを設定してくださいCapSolver APIドキュメンテーションでは、プロダクション環境での解決時間を最適化するための追加の構成オプションが説明されています。ターゲットサイトでのreCAPTCHAパラメータの識別については、CapSolverブラウザ拡張機能が自動検出を提供します。
OpenAI Agents SDKにreCAPTCHA解決を統合するには、CapSolverのexecute_tool()関数をラップする@function_toolを定義し、それをエージェントに割り当てます。SDKのランタイムはツールディスパッチを自動的に処理します - エージェントはreCAPTCHA解決が必要なタイミングを自律的に決定し、適切なパラメータでツールを呼び出します。CapSolverは、reCAPTCHA v2、v3、およびエンタープライズバージョンの有効なトークンを生成するAI駆動の解決インフラを提供します。
単一のsolve_recaptchaツールから始め、既知のターゲットでエージェントでテストし、v3サポートとプロダクションリトライロジックを追加してください。OpenAI Agents SDKの非同期アーキテクチャはCapSolverの非同期APIと自然に一致し、統合はクリーンでパフォーマンスが向上しています。
はい。SDKは完全に非同期であり、CapSolverのexecute_tool()は非同期関数です。@function_toolデコレーターはasync def関数をネイティブにサポートしているため、CAPTCHA解決はエージェントのイベントループをブロックすることなく実行されます。
はい。パラメータにenterprise: trueを渡してください。reCAPTCHAエンタープライズは同じv2/v3タスクタイプを使用しますが、sトークンパラメータが必要な場合があります。CapSolverは同じAPIを通じてエンタープライズバージョンを透明に処理します。
エージェントの指示にv2とv3の識別に関するガイドラインを含めてください。または、タスクプロンプトにCAPTCHAタイプを提供してください。reCAPTCHA識別ガイドでは、v2とv3の違いが説明されています:v2は表示されるウィジェットを表示し、v3はスクリプタグを介して非表示でロードされます。
reCAPTCHA v2は1,000回の解決で約$2-3、reCAPTCHA v3は1,000回で$1-2です。エージェントがセッションあたり10回のreCAPTCHAを解決する場合、コストはセッションあたり約$0.02-0.03で、自律的なタスク完了の価値に比べて無視できるほどです。
はい。専用の「CAPTCHAソルバー」エージェントを作成し、メインエージェントが検証チャレンジに遭遇したときにハンドオフできます。ソルバーエージェントはCAPTCHAを解決し、トークンとともにメインエージェントにハンドオフします。これにより、エージェントの責任が明確に分離されます。
CapSolverを使用してCrewAIのマルチエージェントワークフローにCAPTCHAの解決を統合する完全なガイド、リカプチャおよびクラウドフレア・ターニースタイル用のコード例付き。

LangGraph Cloudflare Turnstileソルバーのワークフローを構築するには、CapSolver、Playwrightセッション処理、ポリシーゲート、リトライ、検証、およびレビューを用いてください。
