Agent Tools| Capsolver

＃代理人

将 CapSolver 的求解能力引入任何 LLM/代理框架。 capsolver-agent 是 capsolver-core 引擎上的一个薄层：它将核心的 solve / detect / solve_on_page 方法包装为 LLM 可以调用的工具，使“模型决定，核心执行”边界自然就位。

**分工：**模型处理导航和决策，capsolver-core 处理求解，capsolver-agent 是中间的工具适配器层 - 模型调用“求解”的方式与调用“单击”或“类型”的方式相同，而无需单击验证码本身。

1. `capsolver-agent` 与 `capsolver-core` 有何关系

您几乎从不直接编写核心调用代码。当LLM决定调用某个工具时，代理层的执行器会为您调用相应的核心方法，并向模型返回结构化结果：

LLM (decides)
   │  emits a tool call, e.g. solve_captcha(...)
   ▼
capsolver-agent (schema + executor)   ← tool-adapter layer
   │  executor.execute(...) internally relays to ↓
   ▼
capsolver-core (solve / detect / solve_on_page)
   │
   ▼
CapSolver API

每个代理工具都直接映射到一个核心方法 - 这是核心在每种场景中执行实际工作的地方：

代理工具	底层 `capsolver-core` 方法	浏览器？
`solve_captcha`	`cap.solve(info)`	没有
`detect_captchas`	`cap.detect(page)`	是的
`solve_on_page`	`cap.solve_on_page(page)`	是的
`get_balance`	`cap.get_balance()`	没有
`get_supported_captchas`	`cap.get_supported_captchas()`	没有

2.安装

capsolver-agent 构建在 capsolver-core 之上（核心进行求解）并在运行时依赖于它。两者都是 GitHub 上的开源代码，尚未发布到 PyPI，并且 capsolver-agent 的名称依赖于 capsolver-core。先安装core，再安装agent：

# 1) Install the core engine first (agent depends on it)
pip install git+https://github.com/capsolver-ai/capsolver-core.git
 
# 2) Then install agent itself
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

根据需要添加额外内容：

# With LangChain support
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"
# With Playwright (detect / solve_on_page)
pip install "capsolver-agent[browser] @ git+https://github.com/capsolver-ai/capsolver-agent.git"

export CAPSOLVER_API_KEY="your-capsolver-api-key"

3. 用法：将求解连接到对话循环中

集成落在模型的“对话-工具”循环中。一轮完整的运行如下：

1. Hand the tools to the model ───────────────────┐
2. The model answers and decides: do I need a tool here?
   ├─ No  → return the final answer, done         │
   └─ Yes → return a tool_call                    │
3. You execute the call → relay to core → get a result
4. Feed the result back to the model ─────────────┘  back to step 2, next round

在实践中，模型决定是否使用以及使用哪种工具；你的工作是将核心连接到这个循环中，分三个步骤：连接核心→将工具交给模型→执行模型在循环内返回的调用，将它们串入工作循环。

3.1 连接核心：创建执行器

真正解决的始终是 capsolver-core 的 Capsolver 引擎。代理层仅在其周围添加一个 ToolExecutor ：在内部它保存一个 Capsolver ，将模型的工具调用分派给引擎的相应方法，并将返回结果包装为结构化结果。下面我们首先展示这个包装器是如何组装的，然后是单行简写。

执行器如何加载核心。 拼写出来，它是两行，第一行创建了核心：

from capsolver_core import Capsolver               # capsolver-core engine
from capsolver_agent.schema import ToolExecutor
 
cap = Capsolver(api_key="YOUR_CAPSOLVER_KEY")       # the same Capsolver from the "Core SDK" page
executor = ToolExecutor(cap)                        # wrap a "tool call → core method" dispatcher around it

调度是一个固定的映射；每个工具调用最终都会落在一个核心方法上：

executor.execute("solve_captcha",  {...})   # → cap.solve(CaptchaInfo(...))
executor.execute("detect_captchas", {...})  # → cap.detect(page)
executor.execute("get_balance",    {})      # → cap.get_balance()

在每次调用时，执行器都会将工具参数组装成核心期望的形式，调用核心，并将结果（或错误）包装到一个字典中，您可以直接反馈给模型 - 成功是 {"success": True, "solution": {...}} ，失败是 {"success": False, "error": "..."} 。所以你在Core SDK页面学到的方法和参数在这里不变。

用法。 上面两行有一个现成的包装纸；日常使用时，直接调用：

from capsolver_agent.schema import create_executor
 
executor = create_executor(api_key="YOUR_CAPSOLVER_KEY")   # == Capsolver(...) + ToolExecutor(...)

当您想要自定义核心的行为时，传递给 create_executor() 的任何额外关键字参数都会按原样转发到 Capsolver(...) — 例如， create_executor(api_key=..., default_timeout=180) 。

3.2 将工具交给模型

get_all_tools() 为您提供所有工具定义——核心功能的外向描述。以目标框架的格式导出它们并将它们作为其函数调用接口传递给模型：

from capsolver_agent.schema import get_all_tools
 
tools = [t.to_openai_function() for t in get_all_tools()]
# to_openai_function() → {"type": "function", "function": {...}}, the format OpenAI's tools= expects
# you can also use t.to_json_schema() → an MCP-style tool description (name + inputSchema)

3.3 执行模型返回的调用，中继到核心

当模型在某个步骤返回 tool_call 时，将其交给 3.1 中的执行器 — execute(tool_name, args) 分派对相应核心方法的调用（solve / detect / solve_on_page …），返回结构化结果，然后将其反馈给模型：

result = await executor.execute("solve_captcha", {
    "captcha_type": "reCaptchaV2",
    "website_url": "https://example.com",
    "website_key": "6Le-wvkSAAAAAPBMRT...",
})
# result → {"success": True, "solution": {"token": "03AF...", ...}}

3.4 将其串成一个完整的循环

将上述三个步骤嵌入到模型的对话循环中，您就拥有了一个可以自行解决验证码的最小代理（以 OpenAI 函数调用为例）：

import asyncio, json
from openai import OpenAI
from capsolver_agent.schema import get_all_tools, create_executor
 
client = OpenAI()                                       # your LLM client
executor = create_executor(api_key="YOUR_CAPSOLVER_KEY") # 3.1 connect core
tools = [t.to_openai_function() for t in get_all_tools()] # 3.2 hand tools to the model
 
async def run(prompt: str) -> str:
    messages = [{"role": "user", "content": prompt}]
    while True:
        resp = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
        msg = resp.choices[0].message
        messages.append(msg)
 
        if not msg.tool_calls:                          # model no longer calls a tool
            return msg.content                          # → final answer, exit the loop
 
        for call in msg.tool_calls:                     # model wants to call a tool
            result = await executor.execute(            # 3.3 execute → relay to core
                call.function.name,
                json.loads(call.function.arguments),
            )
            messages.append({                           # feed the result back, next round
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result),
            })
 
asyncio.run(run("Solve the reCAPTCHA v2 on https://example.com for me; the sitekey is 6Lc..."))

当您只想运行一个工具一次而不是构建整个循环时，请一次性调用 execute_tool(name, args, api_key=...) 。

4. 每个框架：相同的循环，不同的 Shell

上面两步就是通用骨架。当您连接到特定框架时，唯一的区别是谁驱动“调用工具→反馈结果”循环，以及您使用哪些核心功能 - 已知站点参数通过令牌模式（ solve() ），而自主驱动页面则通过浏览器模式（ detect() / solve_on_page() ）。

场景/框架	使用的核心能力	如何整合	示例文件
OpenAI函数调用	`solve()`（令牌模式）	您驱动循环：将架构提供给模型 + 执行器运行它	`openai_function_calling.py`
OpenAI 代理 SDK	`solve()` 等	运行时驱动循环：`@function_tool` 包装 `execute_tool`	`openai_agents.py`
浪链反应	`solve()` 等	将 `get_langchain_tools()` 用于现成的 `BaseTool`	`langchain_agent.py`
浏览器使用	`detect()` / `solve_on_page()`	`@tools.action` 将求解注册为一个动作	`browser_use_agent.py`
剧作家（非法学硕士）	`detect()` / `solve_on_page()`	直接使用`capsolver-core`，绕过代理层	`playwright_sdk.py`

其中，浏览器使用最接近现实世界的自动化：代理自行浏览，当它遇到验证码中间任务时，它会调用解决作为一个操作 - 在同一浏览器会话中进行检测、解决和填充，然后在获得结果后继续原始流程，而不会中断步伐：

Agent browses the page → hits a CAPTCHA → calls the solve action (core: solve_on_page) → gets a token → continues the task

5. 运行示例

上表中的每个场景都附带一个可运行的示例，全部位于代理存储库中的 examples/ 下。克隆它，安装依赖项，然后运行。

git clone https://github.com/capsolver-ai/capsolver-agent.git
cd capsolver-agent
uv sync
 
export CAPSOLVER_API_KEY=CAP-XXXXXX
export OPENAI_API_KEY=sk-XXXXXX      # required by the LLM-based examples

每个示例的额外依赖项（ capsolver-agent / capsolver-core 从 GitHub 安装；其余的是常规 PyPI 包）：

# OpenAI Function Calling
pip install openai
# OpenAI Agents SDK
pip install openai-agents
# LangChain
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git" langchain-openai langgraph
# Browser Use
pip install browser-use langchain-openai playwright && playwright install chromium
# Playwright (no LLM)
pip install git+https://github.com/capsolver-ai/capsolver-core.git playwright && playwright install chromium

核心 SDK MCP 服务

1. capsolver-agent 与 capsolver-core 有何关系