Pydantic AI 验证码工具：输入类型和求解结果

概要

• Pydantic AI 可以通过官方 CapSolver 代理适配器，将验证码解决作为类型化的 Python 函数工具暴露出来。
• 保持包装器小巧：接收文档参数，调用执行器，并返回其结构化结果，不要自己编造成功答案。
• 下面的示例运行了一个带有 TestModel 的真实 Pydantic AI 代理循环，并调用了已安装适配器支持的类型目录。
• 解决函数已注册，但故意排除在测试运行之外；不会发生模型-提供者请求或付费解决。
• 类型验证有助于描述工具输入。您的应用程序仍需决定哪些页面和操作是被批准的，并且是否最终的浏览器任务成功。

Pydantic AI 验证码工具为代理提供了一个定义好的操作，当被批准的浏览器任务遇到支持的挑战时使用。模型不需要发明解决算法，应用程序也不需要为每个代理框架添加新的验证码客户端。

CapSolver 代理适配器提供执行层。Pydantic AI 提供函数工具接口。本指南展示了这些组件如何连接，使用来自 CapSolver 维护的 Pydantic AI 仓库的示例和执行真实适配器目录操作的本地测试。

Pydantic AI 集成增加了什么？

Pydantic AI 集成将普通的类型化 Python 函数转换为代理可用的工具。该函数接收命名参数，委托验证码操作，并返回代理可以检查的结果。

对于自有 QA 表单，有用的流程是具体的：浏览器识别支持的挑战，应用程序提供页面参数，求解工具返回其结果，浏览器继续同一表单尝试。最终断言属于表单工作流。

API 库 打包了底层服务调用。在这种情况下，CapSolver 代理工具文档 描述了一个将命名操作分发到核心实现的执行器。

Pydantic AI 的 函数工具文档 解释了函数签名和注解如何贡献于工具定义。三个带注解的字符串可以描述所需的输入形状，但它们不会建立 URL 是否被批准或站点密钥是否属于当前页面。

为什么使用官方适配器而不是其他 HTTP 客户端？

当您希望在文档化的求解实现周围使用小型框架包装器时，请使用官方适配器。这使包装器专注于代理接口，而不是复制任务创建、检索和结果转换。

CapSolver 维护着 Pydantic AI 示例仓库，使用 create_executor、Agent 和 @agent.tool_plain。这是一个示例应用程序，而不是以仓库命名的额外包。

本文中的示例保留了仓库的三参数求解函数和执行器调用。它将周围的演示改为使用 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 的 虚拟环境指南 描述了环境创建和 shell 特定的激活。将包版本与您的项目保持一致，以便在升级前可以重现演示。

本地目录演示不需要求解凭证。稍后的 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:
    """返回已注册的验证码类型，而不解决挑战。"""
    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:
    """为合法、用户授权的工作流解决支持的验证码。"""
    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("列出支持的验证码类型。")
    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 的结果；它们不是新生成的验证码令牌。

官方包装器使用 json.dumps 将执行器结果作为字符串返回。如果其他组件使用它，请保留该字符串与底层字典的区别。有意识地解析相关 JSON 值，而不是假设每一层都返回相同的结构。

测试证明了注册、无参数工具执行、适配器分发和结果返回在安装版本中协同工作。它并未证明 LLM 会选择正确的求解工具或特定受保护表单会接受令牌。

领取您的 CapSolver 奖励代码

立即提升您的自动化预算！
在充值 CapSolver 账户时使用奖励代码 CAP26，每次充值可获得额外 5% 奖励——无限制。
现在在您的 CapSolver 仪表板 中领取

类型输入如何映射到验证码请求？

类型输入将代理的工具调用映射到适配器接受的参数字典。最小的求解包装器接受 captcha_type、website_url 和 website_key。

这些名称属于适配器接口。它们不是包含 clientKey 和 task 对象的原样 REST 请求。连接实际页面时，请查阅已安装的工具模式和 reCAPTCHA v2 任务文档。

三字段包装器是故意最小的。一些变体需要额外的上下文。不要假设更广泛服务列出的每个挑战都可以仅用这三个字符串解决，或包装器类型名称可以替换为 REST 任务名称。

字符串注解不会限制 URL 到批准的主机名。在提供工具参数的应用程序中强制执行允许的目标和操作。页面内容不应能通过要求模型使用一个来授权新目标。

代理应如何处理求解器结果？

代理应检查执行器的结果，并将验证码结果与业务任务结果分开。记录的代理适配器返回一个成功封装，包含解决方案，或一个失败封装描述错误。

失败时，应用程序应保留相关错误信息，并决定是否需要纠正的输入、新的尝试或操作员审查。不要将错误转换为看起来像令牌的占位符，只是为了满足下游字符串字段。

成功时，将结果传递给负责相同挑战尝试的应用程序组件。本指南中的函数不控制浏览器、定位响应字段、提交表单或断言应用程序接受。

对于自有表单测试，适当的完成标准可能是预期的测试确认记录。求解成功和应用程序拒绝应保持为两个独立的观察。这种分离使错误的页面密钥与无关的表单验证失败区分开来。

避免将凭证或完整令牌放入常规跟踪中。如果代理需要可读摘要，请保留操作状态和安全诊断字段，同时将结果值保留在实际使用它的组件中。

如何从 TestModel 过渡到真实代理？

通过配置预期的模型提供者，提供其认证，并仅启用应用程序需要的实时操作来过渡到真实代理。保留经过测试的工具包装器，并检查新模型的实际工具调用。

演示中的 TestModel 是过程测试基础设施，而不是语言模型。其成功的目录选择不衡量模型推理。真实对话可能会产生缺失参数、选择错误的工具或请求其他操作，因此应用程序仍需检查其输入。

从一个自有 QA 页面和文档化的挑战变体开始。从应用程序中提供实际页面 URL 和公钥，然后验证求解器结果和表单的最终响应。按阶段记录失败，而不是将整个实验简化为代理答案中是否出现文本。

更广泛的 企业验证码解决指南 讨论了团队采用。此框架示例建立了更窄的基础：类型函数注册和使用受控、非求解操作的真实适配器执行。

尝试 CapSolver 在理解本地连接后，为您的批准任务中的支持挑战。保持每个测试的范围明确：工具注册、模型选择、付费求解和浏览器接受是不同的检查。

常见问题

Q: 是否有单独的 pydantic-ai-capsolver 包？

引用的仓库包含使用 Pydantic AI 和官方 CapSolver 代理库的示例。本教程直接安装这些库，而不是假设仓库名称是一个包。

Q: TestModel 调用真实的验证码服务吗？

TestModel 可以执行已注册的工具，因此所选工具决定了会发生什么。此示例仅显式调用支持类型目录，不调用求解请求。

Q: 类型字符串输入是否足以批准目标页面？

不。类型注解描述输入形状。应用程序必须单独强制执行允许的 URL、任务和上下文。

Q: 为什么打印结果包含转义的 JSON？

包装器返回序列化的 JSON，而 TestModel 在其输出摘要中包含该字符串。有意识地处理每个序列化层，而不是假设摘要是一个原始解决方案对象。

Q: 这个包装器能处理所有验证码变体吗？

此处未建立此类覆盖。最小函数接受三个参数；需要额外上下文的变体需要相应的文档字段和验证。

Q: 测试期间是否解决了实时验证码？

没有。安装的框架和适配器使用 TestModel 执行了真实的目录操作。实时求解和由自有应用程序接受是需要适当凭证和页面的独立测试。