Đại lý

Đưa khả năng giải quyết của CapSolver vào bất kỳ khung LLM/đại lý nào. capsolver-agent là một lớp mỏng trên công cụ capsolver-core: nó bao bọc các phương thức solve / detect / solve_on_page của lõi như các công cụ mà LLM có thể gọi, làm cho ranh giới “mô hình quyết định, lõi thực thi” rơi vào đúng vị trí một cách tự nhiên.

Phân công lao động: mô hình xử lý việc điều hướng và ra quyết định, capsolver-core xử lý việc giải quyết và capsolver-agent là lớp bộ chuyển đổi công cụ ở giữa — mô hình gọi “giải quyết” giống như cách nó gọi “nhấp chuột” hoặc “gõ” mà không cần phải nhấp vào chính CAPTCHA.

1. capsolver-agent Liên hệ với capsolver-core như thế nào

Bạn gần như không bao giờ viết mã cuộc gọi cốt lõi một cách trực tiếp. Khi LLM quyết định gọi một công cụ, người thực thi của lớp tác nhân sẽ gọi phương thức cốt lõi tương ứng cho bạn và trả về kết quả có cấu trúc cho mô hình:

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

Mỗi công cụ tác nhân ánh xạ trực tiếp tới một phương thức cốt lõi — đây là nơi cốt lõi thực hiện công việc thực sự trong mọi tình huống:

2. Cài đặt

capsolver-agent được xây dựng dựa trên capsolver-core (lõi thực hiện việc giải quyết) và phụ thuộc vào nó trong thời gian chạy. Cả hai đều là nguồn mở trên GitHub và chưa được xuất bản lên PyPI và capsolver-agent phụ thuộc vào capsolver-core theo tên. Cài đặt lõi trước, sau đó cài đặt tác nhân:

# 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

Thêm các tính năng bổ sung khi cần thiết:

# 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. Cách sử dụng: Nối dây vào vòng hội thoại

Sự tích hợp diễn ra bên trong vòng lặp “công cụ hội thoại” của mô hình. Một vòng đầy đủ chạy như thế này:

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

Trong thực tế, mô hình quyết định có sử dụng công cụ nào hay không và sử dụng công cụ nào; công việc của bạn là nối lõi vào vòng lặp này, theo ba bước: kết nối lõi → đưa công cụ vào mô hình → thực hiện các lệnh gọi mà mô hình trả về bên trong vòng lặp, xâu chuỗi chúng thành một vòng lặp hoạt động.

3.1 Connect core: tạo bộ thực thi

Điều thực sự giải quyết được luôn là động cơ Capsolver của capsolver-core. Lớp tác nhân chỉ thêm ToolExecutor xung quanh nó: bên trong nó chứa Capsolver , gửi các lệnh gọi công cụ của mô hình đến các phương thức tương ứng của động cơ và gói kết quả trả về thành một kết quả có cấu trúc. Dưới đây, trước tiên chúng tôi trình bày cách lắp ráp trình bao bọc này, sau đó là tốc ký một dòng.

Cách người thực thi tải lõi. Nói ra, đó là hai dòng, với lõi được tạo ở dòng đầu tiên:

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

Công văn là một bản đồ cố định; mọi lệnh gọi công cụ cuối cùng đều hướng đến một phương thức cốt lõi:

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

Trên mỗi lệnh gọi, người thực thi sẽ tập hợp các đối số của công cụ thành mong đợi cốt lõi của biểu mẫu, gọi lõi và gói kết quả (hoặc lỗi) thành một lệnh mà bạn có thể cung cấp thẳng cho mô hình - thành công là {"success": True, "solution": {...}} , thất bại là {"success": False, "error": "..."} . Vì vậy, các phương thức và tham số bạn đã tìm hiểu trên trang Core SDK sẽ không thay đổi ở đây.

Cách sử dụng. Hai dòng trên có một trình bao bọc làm sẵn; trong sử dụng hàng ngày, chỉ cần gọi nó:

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

Khi bạn muốn tùy chỉnh hành vi của lõi, mọi đối số từ khóa bổ sung được chuyển đến create_executor() đều được chuyển tiếp nguyên trạng tới Capsolver(...) — ví dụ: create_executor(api_key=..., default_timeout=180) .

3.2 Đưa dụng cụ vào mẫu

get_all_tools() cung cấp cho bạn tất cả các định nghĩa về công cụ - mô tả bên ngoài về khả năng của lõi. Xuất chúng theo định dạng của khung mục tiêu của bạn và chuyển chúng sang mô hình dưới dạng giao diện gọi hàm của nó:

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 Thực hiện lệnh gọi model trả về, chuyển tiếp về lõi

Khi mô hình trả về tool_call ở một bước nào đó, hãy giao nó cho người thực thi từ 3.1 — execute(tool_name, args) gửi lệnh gọi đến phương thức cốt lõi tương ứng ( solve / detect / solve_on_page …), trả về kết quả có cấu trúc và bạn đưa kết quả đó trở lại mô hình:

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 Xâu chuỗi thành một vòng lặp hoàn chỉnh

Nhúng ba bước trên vào vòng hội thoại của mô hình và bạn sẽ có một tác nhân tối thiểu có thể tự giải quyết CAPTCHA (sử dụng lệnh gọi hàm OpenAI làm ví dụ):

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..."))

Khi bạn chỉ muốn chạy một công cụ một lần thay vì xây dựng toàn bộ vòng lặp, hãy gọi execute_tool(name, args, api_key=...) chỉ trong một lần.

4. Mỗi Framework: Cùng một vòng lặp, một Shell khác nhau

Hai bước trên là bộ xương phổ quát. Khi bạn kết nối với một khung cụ thể, điểm khác biệt duy nhất là người điều khiển vòng lặp “gọi công cụ → phản hồi kết quả” và khả năng cốt lõi nào bạn sử dụng — các tham số trang web đã biết sẽ chuyển qua chế độ Mã thông báo ( solve() ), trong khi tự động điều khiển trang đi qua chế độ Trình duyệt ( detect() / solve_on_page() ).

Trong số này, Sử dụng trình duyệt gần nhất với tự động hóa trong thế giới thực: tác nhân tự duyệt và khi chạm vào một tác vụ CAPTCHA giữa chừng, nó gọi việc giải quyết như một hành động — phát hiện, giải quyết và điền lại trong cùng một phiên trình duyệt, sau đó tiếp tục quy trình ban đầu khi có kết quả mà không bị gián đoạn:

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

5. Chạy các ví dụ

Mọi kịch bản trong bảng trên đều có một ví dụ có thể chạy được, tất cả đều nằm dưới examples/ trong kho lưu trữ tác nhân. Sao chép nó, cài đặt các phần phụ thuộc và chạy.

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

Các phần phụ thuộc bổ sung của mỗi ví dụ ( capsolver-agent / capsolver-core cài đặt từ GitHub; phần còn lại là các gói PyPI thông thường):

# 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