CAPSOLVER
ブログ
OpenAI Agents SDKでreCAPTCHAを解決する方法

reCAPTCHA の解決方法: OpenAI エージェント SDK における

Logo of CapSolver

Sora Fujimoto

AI Solutions Architect

28-Jul-2026

OpenAI Agents SDKは、ツールコール機能を備えたプロダクション対応のフレームワークを提供します。これらのエージェントがreCAPTCHAで保護されたウェブサイトと相互作用する際には、検証チャレンジをプログラム的にクリアする方法が必要です。CapSolverのcapsolver-agentパッケージは、@function_toolデコレーターを通じてOpenAI Agents SDKと統合され、エージェントがreCAPTCHA v2およびv3のチャレンジを自律的なワークフローの一部として解決できるようにします。

TL;DR

  • OpenAI Agents SDKは@function_toolを使用してコール可能なツールを登録します - CapSolverはこのパターンをネイティブにサポートしています
  • capsolver-agentexecute_tool()関数は、SDKと互換性のある単一の非同期呼び出しで解決をラップします
  • reCAPTCHA v2(チェックボックスおよび非表示)、reCAPTCHA v3(スコアベース)、およびエンタープライズバージョンをサポートしています
  • トークンモードではブラウザが不要です - サイトキーとURLのみが必要です
  • エージェントはタスクのコンテキストに基づいて、CAPTCHA解決をいつ呼び出すかを自律的に決定します

OpenAI AgentsがreCAPTCHA解決を必要とする理由

OpenAI Agents SDKは、ツールを使用してマルチステップタスクを実行するエージェントを構築する開発者を支援します。エージェントのタスクにウェブインタラクションが含まれる場合(ログイン後のデータアクセス、フォームの提出、保護されたページからの情報収集など)、reCAPTCHAチャレンジが進行を妨げます。エージェントは次のアクションを推論できますが、解決ツールがないと、進行するために必要な検証トークンを生成できません。

reCAPTCHAは、エージェントがアクセスするサイトで特に一般的です:ログインポータル、レート制限付きデータAPI、政府データベース、SaaSプラットフォーム。 GoogleのreCAPTCHAドキュメンテーションによると、世界中で500万以上のサイトがreCAPTCHAを使用しており、エージェントが遭遇する最も可能性の高い検証チャレンジです。

CapSolverのアーキテクチャは、OpenAI Agents SDKの設計と完全に一致しています:エージェントは「何をすべきか」(包括的にCAPTCHAを解決するタイミングを含む)を決定し、CapSolverはその「解決」をAIサービスを通じて処理します。この責任の分離により、エージェントのロジックはクリーンなままに保たれ、検証クリア機能が追加されます。

開始前に必要なもの

必要なパッケージをインストールします:

bash Copy
# 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

環境変数を設定します:

bash Copy
export CAPSOLVER_API_KEY="your-capsolver-api-key"
export OPENAI_API_KEY="your-openai-api-key"

SDKは現在、reCAPTCHA v2、reCAPTCHA v3(エンタープライズを含む)、およびCloudflare Turnstileをサポートしています。これは、エージェントが頻繁に遭遇する検証タイプをカバーしています。

ステップ1 — CAPTCHA解決を関数ツールとして登録する

何をするか

OpenAI Agents SDKは@function_toolを使用して、エージェントが呼び出せるツールを定義します。CapSolverのエクスキュータをこのパターンにラップします:

python Copy
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-agentexecute_tool()関数は、タスクの作成、結果のポーリング、構造化された出力の返却を含むフルソルブライフサイクルを処理する単一の非同期呼び出しです。これは、フルエクスキュータループを構築することなく、1回のソルブを希望するシナリオに特化しています。

なぜ重要なのか

OpenAI Agents SDKの@function_toolデコレーターは、モデルがツールのパラメータを理解するために必要なJSONスキーマを自動的に生成します。エージェントはツールの説明を認識し、いつ使用すべきかを理解し、SDKの組み込みの関数コールメカニズムを通じて正しい引数で呼び出します。

避けなければならない一般的なミス

  • 同期実行: OpenAI Agents SDKは非同期です。ツール関数では常にasync defを使用し、CapSolver呼び出しではawaitを使用してください。
  • 型ヒントの欠如: SDKは型ヒントからスキーマを生成します。すべてのパラメータに適切な型注釈を含めてください。

ステップ2 — reCAPTCHA解決機能を持つエージェントを作成する

何をするか

reCAPTCHA解決ツールを含むOpenAIエージェントを構築します:

python Copy
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のランタイムがいつどのように呼び出されるかを管理します。これは、手動で関数コールループを構築するよりも簡単です。

ステップ3 — スコア要件を持つreCAPTCHA v3を処理する

何をするか

reCAPTCHA v3はスコアベースで非表示であり、page_actionパラメータを必要とし、関連するスコアを持つトークンを返します。専用のツールを作成します:

python Copy
@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パラメータを識別する方法が説明されています。一般的なアクションにはloginsubmithomepageverifyがあります。

ステップ4 — 完全なウェブワークフロー用のマルチツールエージェントを構築する

何をするか

reCAPTCHA解決を他のツールと組み合わせて、完全なウェブタスクを実行するエージェントを作成します:

python Copy
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エージェントを構築する開発者に最適です。

ステップ5 — プロダクションデプロイメントの考慮事項

reCAPTCHA解決機能を持つプロダクション用OpenAIエージェントの場合:

python Copy
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と自然に一致し、統合はクリーンでパフォーマンスが向上しています。

FAQ

OpenAI Agents SDKは非同期のCAPTCHA解決をサポートしていますか?

はい。SDKは完全に非同期であり、CapSolverのexecute_tool()は非同期関数です。@function_toolデコレーターはasync def関数をネイティブにサポートしているため、CAPTCHA解決はエージェントのイベントループをブロックすることなく実行されます。

この統合でreCAPTCHAエンタープライズをエージェントが解決できますか?

はい。パラメータにenterprise: trueを渡してください。reCAPTCHAエンタープライズは同じv2/v3タスクタイプを使用しますが、sトークンパラメータが必要な場合があります。CapSolverは同じAPIを通じてエンタープライズバージョンを透明に処理します。

エージェントはサイトがどのreCAPTCHAバージョンを使用しているかをどうやって知っていますか?

エージェントの指示にv2とv3の識別に関するガイドラインを含めてください。または、タスクプロンプトにCAPTCHAタイプを提供してください。reCAPTCHA識別ガイドでは、v2とv3の違いが説明されています:v2は表示されるウィジェットを表示し、v3はスクリプタグを介して非表示でロードされます。

reCAPTCHA解決のコストはどのくらいですか?

reCAPTCHA v2は1,000回の解決で約2-3、reCAPTCHA v3は1,000回で1-2です。エージェントがセッションあたり10回のreCAPTCHAを解決する場合、コストはセッションあたり約$0.02-0.03で、自律的なタスク完了の価値に比べて無視できるほどです。

OpenAI Agents SDKのハンドオフ機能とこの統合を併用できますか?

はい。専用の「CAPTCHAソルバー」エージェントを作成し、メインエージェントが検証チャレンジに遭遇したときにハンドオフできます。ソルバーエージェントはCAPTCHAを解決し、トークンとともにメインエージェントにハンドオフします。これにより、エージェントの責任が明確に分離されます。

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

もっと見る

TinyFish AgentQでキャプチャを解く
TinyFish AgentQLを使ってCAPTCHAを解決する方法 – CapSolverを使用したステップバイステップガイド

CapSolverをTinyFish AgentQLに統合する方法を学び、reCAPTCHAやCloudflare TurnstileなどのCAPTCHAを自動的に解決する方法を学びましょう。PythonとJavaScript SDKの例を含むステップバイステップのチュートリアルで、シームレスなAI駆動のウェブ自動化を実現します。

ai
Logo of CapSolver

Sora Fujimoto

05-Aug-2026

ラマインデックスのエージェントでキャプチャをどうやって解決するか
LlamaIndexエージェントにおけるCAPTCHAの解決方法

CAPTCHAの解決をLlamaIndexエージェントにFunctionToolとCapSolverを使用してウェブデータのインジェストパイプラインに統合する。

ai
Logo of CapSolver

Sora Fujimoto

31-Jul-2026

CAPTCHAをMCP CapSolverサービスで解決する方法
MCPを使用したCAPTCHAの解き方: キャプソルバー モデル コンテキスト プロトコル サービス

Claude Desktop、Cursor、および任意のMCPクライアントでゼロコードでCAPTCHAを解くためのCapSolver MCPサービスを設定してください。

ai
Logo of CapSolver

Sora Fujimoto

31-Jul-2026

OpenAI Agents SDKにおけるreCAPTCHA v3の解き方
reCAPTCHA v3をOpenAIエージェントSDKで解く方法

OpenAI Agents SDKで、CapSolverのfunction_toolを使用して、高スコアのreCAPTCHA v3トークンを生成します。

ai
Logo of CapSolver

Sora Fujimoto

30-Jul-2026

クラウドフレアトゥルニスティールを解決する方法 クリューAIエージェントで
Cloudflare Turnstile の解決方法: CrewAI エージェントでの

CrewAIのマルチエージェントワークフローにCloudflare Turnstileの解決を統合し、CapSolverを用いて行います。

ai
Logo of CapSolver

Sora Fujimoto

30-Jul-2026

CAPTCHAを解く方法: AutoGen AIエージェントでCapSolverを使う
CAPTCHAを解決する方法: AutoGenエージェント

Microsoft AutoGenのマルチエージェント会話にCAPTCHAの解決を統合する完全なガイド – register_functionとグループチャットのパターンを使用してCapSolverで

ai
Logo of CapSolver

Sora Fujimoto

29-Jul-2026