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

TL;DR

• Pydantic AIは、公式のCapSolverエージェントアダプタをバックエンドとして使用する型付きPython関数ツールとしてCAPTCHA解決を公開できます。
• ワラッパーを小さく保つ: ドキュメント化されたパラメータを受け取り、エクスキュータを呼び出し、構造化された結果を返すだけで、成功した答えを自前で生成しないでください。
• 下記の例は、TestModelを使用して実際のPydantic AIエージェントループを実行し、インストールされたアダプタのサポートタイプカタログを呼び出します。
• 解決関数は登録されていますが、このテスト実行では意図的に除外されています。モデルプロバイダーへのリクエストや有料の解決は発生しません。
• 型検証はツールの入力を説明するのに役立ちます。アプリケーションは依然として、どのページと操作が承認されているかを決定し、最終的なブラウザタスクが成功したかどうかを判断する必要があります。

Pydantic AIのCAPTCHAツールは、承認されたブラウザタスクがサポートされるチャレンジに達したときにエージェントが使用する定義された操作を提供します。モデルは解決アルゴリズムを自前で生成する必要がなく、アプリケーションはエージェントフレームワークごとに新しいCAPTCHAクライアントを必要としません。

CapSolverエージェントアダプタは実行レイヤーを提供します。Pydantic AIは関数ツールインターフェースを提供します。このガイドでは、CapSolverがメンテナンスするPydantic AIリポジトリからの例と、実際のアダプタのカタログ操作を実行するローカルテストを使用して、これらのピースがどのように接続されるかを示します。

Pydantic AIの統合で何が追加されるのですか？

Pydantic AIの統合により、通常の型付きPython関数がエージェントが利用できるツールに変換されます。関数は名前付き引数を受け取り、CAPTCHA操作を委譲し、エージェントが検査できる結果を返します。

所有QAフォームの場合、有用なシーケンスは明確です: ブラウザがサポートされるチャレンジを識別し、アプリケーションがページパラメータを提供し、ソルバーツールが結果を返し、ブラウザは同じフォームの試行を続けます。最終的なアサーションはフォームワークフローに属します。

APIライブラリは下位のサービス呼び出しをパッケージ化しています。この場合、CapSolverエージェントツールドキュメントは、名前付き操作をコア実装にディスパッチするエクスキュータを記述しています。

Pydantic AIの関数ツールドキュメントは、関数シグネチャと注釈がツール定義にどのように寄与するかを説明しています。3つの注釈付き文字列で必要な入力の形状を記述できますが、URLが承認されていることや、サイトキーが現在のページに属していることを保証するものではありません。

なぜ公式アダプタを使用するのか、他のHTTPクライアントよりも？

ドキュメント化された解決実装の小さなフレームワークラッパーを希望する場合、公式アダプタを使用してください。これにより、エージェントインターフェースに焦点を当て、タスクの作成、取得、結果の変換を複製する必要がなくなります。

CapSolverは、create_executor、Agent、@agent.tool_plainを使用するPydantic AIの例リポジトリをメンテナンスしています。これは追加のパッケージではなく、リポジトリの名前をもとにしたアプリケーションです。

本記事の例では、リポジトリの3引数の解決関数とエクスキュータ呼び出しを保持します。周囲のデモはPydantic AIのTestModelとサポートタイプカタログ呼び出しを使用するように変更されます。これにより、モデルキーを提供したり、有料の解決タスクを作成したりせずにツール接続をテストできます。

この方法はMCPサーバーに接続するのとは異なります。関数は同じPythonアプリケーション内のインストールされたアダプタを呼び出します。この例では、MCPサーバープロセスは存在しません。既存のエージェントに適合するインターフェースを選択し、理由もなく同じ小さなタスクに両方のインターフェースを追加しないでください。

ステップ1: テスト済みパッケージをインストールする

隔離されたPython環境でフレームワークとアダプタをインストールしてください。記録された実行ではPython 3.12.14、pydantic-ai-slim 2.44.0、capsolver-agent 0.1.1、capsolver-core 0.1.1を使用しました。

スリムパッケージは、TestModelが使用するコアPydantic AI機能を提供し、すべてのモデルプロバイダー統合をインストールしません。次のバージョンはローカル実行に一致しています:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install pydantic-ai-slim==2.44.0 capsolver-agent==0.1.1 capsolver-core==0.1.1

Pythonの仮想環境ガイドは環境の作成とシェル固有のアクティベーションについて説明しています。プロジェクトにパッケージのバージョンを保持して、アップグレードする前にデモを再現できるようにしてください。

ローカルカタログのデモには解決資格情報は必要ありません。後の実際のsolve_captcha呼び出しには、CapSolverの解決APIキーが必要であり、実際のモデル会話には選択したプロバイダーのパッケージと認証が必要です。これらは別の前提条件です。

ブログ公開用のMCP資格情報を解決キーとして使用しないでください。エクスキュータのサービス資格情報はモデルプロンプトやコミットされたソースの外にあります。

ステップ2: 型付きツールを登録する

以下の内容をquickstart.pyとして保存してください。解決ラッパーは公式リポジトリに従います。カタログツールとTestModelの構成はローカルで実行される変更です。コードは解決ツールを登録しますが、呼び出しはしません。

import asyncio
import json

from capsolver_agent import create_executor
from pydantic_ai import Agent, models
from pydantic_ai.models.test import TestModel

models.ALLOW_MODEL_REQUESTS = False
capsolver = create_executor()
agent = Agent(TestModel(call_tools=["get_supported_captchas"]))


@agent.tool_plain
async def get_supported_captchas() -> str:
    """登録されたCAPTCHAタイプを解決せずに返します。"""
    return json.dumps(await capsolver.execute("get_supported_captchas", {}))


@agent.tool_plain
async def solve_captcha(captcha_type: str, website_url: str, website_key: str) -> str:
    """法的でユーザー認証されたワークフローのサポートされるCAPTCHAを解決します。"""
    result = await capsolver.execute(
        "solve_captcha",
        {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key,
        },
    )
    return json.dumps(result, ensure_ascii=False)


async def main() -> None:
    result = await agent.run("サポートされているCAPTCHAタイプをリストアップしてください。")
    print(result.output)


if __name__ == "__main__":
    asyncio.run(main())

環境のPythonインタプリタでファイルを実行してください:

python quickstart.py

スクリプトはALLOW_MODEL_REQUESTSをfalseに設定し、誤って非テストモデルへの呼び出しを防ぎます。また、TestModelをカタログツールに制限します。どちらの選択も重要です: モデルリクエストを防ぐことは、ツールが外部サービスに接続することを防ぐこととは異なります。

Pydantic AIのテストドキュメントは、TestModelが生成された入力データを使用して登録されたツールを呼び出せることを説明しています。有料の解決ツールを制限のないテスト実行に残すと、ここに示されている制御されたカタログチェックとは異なる操作になります。

ステップ3: 観測結果を正しく読み取る

ローカル実行は実際のインストールされたCapSolverアダプタから成功したカタログ結果を返しました。recaptchaとcloudflareという名前のハンドラが報告され、タイプ値としてreCaptchaV2、reCaptchaV3、cloudflareが含まれています。

印刷されたTestModel出力には、カタログツールのJSON文字列がツール結果の要約の中に含まれていました。この印刷された要約内のエスケープされた引用符は、関数からシリアライズされたJSONを返す結果であり、新たに生成されたCAPTCHAトークンではありません。

公式のラッパーはjson.dumpsを使用してエクスキュータの結果を文字列として返します。別のコンポーネントがそれを処理する場合、その文字列と下位の辞書の区別を保持してください。すべてのレイヤーが同じ形状を返すと仮定するのではなく、関連するJSON値を意図的に解析してください。

テストは、登録、引数なしのツール実行、アダプタディスパッチ、結果の返却がインストールされたバージョンで一緒に動作することを確認しています。これは、LLMが正しい解決ツールを選択するかどうか、または特定の保護されたフォームがトークンを受け入れるかどうかを確認するものではありません。

CapSolverボーナスコードを引き換える

自動化予算を即座に増やす！
CapSolverアカウントにチャージするときにボーナスコードCAP26を使用すると、すべてのチャージで5%のボーナスが追加されます—制限なし。
CapSolverダッシュボードで今すぐ引き換えてください

型付き入力はCAPTCHAリクエストにどのようにマッピングされますか？

型付き入力はエージェントのツール呼び出しをアダプタが受け入れる引数ディクショナリにマッピングします。最小限の解決ラッパーはcaptcha_type、website_url、website_keyを受け入れます。

これらの名前はアダプタインターフェースに属します。clientKeyとtaskオブジェクトを含む正確なRESTリクエストではありません。実際のページに接続する際には、インストールされたツールスキーマとreCAPTCHA v2タスクドキュメントを参照してください。

3フィールドのラッパーは意図的に最小限です。一部のバリアントには追加のコンテキストが必要です。この3つの文字列だけで、広範なサービスでリストアップされたすべてのチャレンジを解決できると仮定しないでください。また、ラッパーのタイプ名をRESTタスク名に置き換えることもしないでください。

文字列の注釈はURLを承認されたホスト名に制限しません。ツール引数を提供するアプリケーションで許可されたターゲットと操作を強制してください。ページのコンテンツがモデルに1つ使用するように要求しただけで、新しいターゲットを認証できるようにしないでください。

エージェントはソルバーの結果をどのように処理すべきですか？

エージェントはエクスキュータの結果を検査し、CAPTCHA結果をビジネスタスクの結果から分離する必要があります。ドキュメント化されたエージェントアダプタは、解決を含む成功のラッパーやエラーを説明する失敗のラッパーを返します。

失敗した場合、アプリケーションは関連するエラー情報を保持し、修正された入力、新しい試行、またはオペレータのレビューが適切かどうかを決定する必要があります。下流の文字列フィールドを満たすためにエラーをトークンに似たプレースホルダーに変換しないでください。

成功した場合、結果を同じチャレンジ試行を担当するアプリケーションコンポーネントに渡してください。このガイドの関数はブラウザを制御せず、応答フィールドを検索せず、フォームを送信せず、アプリケーションの受け入れをアサートしません。

所有フォームのテストでは、適切な完了基準は予期されるテスト確認記録かもしれません。ソルバーの成功とアプリケーションの拒否は2つの別個の観測でなければなりません。この分離により、間違ったページキーが関係ないフォーム検証失敗と区別されます。

資格情報や完全なトークンを通常のトレースに含めないでください。エージェントに読み取り可能な要約が必要な場合、操作状態と安全な診断フィールドを保持し、結果値を実際にそれを使うコンポーネントに保持してください。

TestModelから実際のエージェントにどのように移行するか？

実際のエージェントに移行するには、意図されたモデルプロバイダーを構成し、その認証を提供し、アプリケーションが必要とするライブ操作のみを有効にします。テスト済みのツールラッパーを保持し、新しいモデルの実際のツール呼び出しを検査してください。

デモのTestModelは言語モデルではなく、手順的なテストインフラストラクチャです。成功したカタログ選択はモデルの推論を測定するものではありません。実際の会話では、必要なパラメータが見つからない、間違ったツールが選択される、または別の操作が要求される可能性があるため、アプリケーションは依然として入力を確認する必要があります。

1つの所有QAページとドキュメント化されたチャレンジバリアントから始めます。アプリケーションから実際のページURLと公開サイトキーを提供し、ソルバーの結果とフォームの最終応答を検証してください。エージェントの回答にテキストが表示されたかどうかではなく、各段階で失敗を記録してください。

より広範な企業向けCAPTCHA解決ガイドでは、チームの導入が議論されています。このフレームワークの例は、狭い基盤を確立しています: 型付き関数の登録と制御された、解決しない操作での実際のアダプタ実行。

このローカル接続が理解されたら、承認されたタスクのサポートされるチャレンジでCapSolverを試してください。各テストの範囲を明確に保つ: ツール登録、モデル選択、有料解決、ブラウザの受け入れは異なるチェックです。

よくある質問

Q: pydantic-ai-capsolverパッケージは別途存在しますか？

参照されたリポジトリには、Pydantic AIと公式のCapSolverエージェントライブラリを使用する例が含まれています。このチュートリアルでは、リポジトリ名がパッケージであると仮定せず、これらのライブラリを直接インストールします。

Q: TestModelは実際のCAPTCHAサービスを呼び出しますか？

TestModelは登録されたツールを実行できるため、選択されたツールが何を行うかに依存します。この例では、サポートタイプカタログのみを明示的に呼び出し、解決リクエストは呼び出しません。

Q: 型付き文字列入力だけでターゲットページを承認できますか？

いいえ。型注釈は入力の形状を記述します。アプリケーションは、許可されたURL、タスク、コンテキストを別途強制する必要があります。

Q: 出力にエスケープされたJSONが含まれているのはなぜですか？

ラッパーはシリアライズされたJSONを返し、TestModelはその文字列を出力要約に含みます。シリアライズレイヤーを意図的に処理し、要約が裸の解決オブジェクトであると仮定しないでください。

Q: このラッパーはすべてのCAPTCHAバリアントを処理できますか？

ここではそのようなカバレッジは確立されていません。最小限の関数は3つのパラメータを受け入れますが、追加のコンテキストが必要なバリアントには、対応するドキュメント化されたフィールドと検証が必要です。

Q: テスト中に実際のCAPTCHAが解決されましたか？

いいえ。インストールされたフレームワークとアダプタはTestModelを使用して実際のカタログ操作を実行しました。実際の解決と所有アプリケーションによる受け入れは、適切な資格情報とページを必要とする別のテストです。