Agen

Menghadirkan kemampuan penyelesaian CapSolver ke dalam kerangka kerja LLM/agen apa pun. capsolver-agent adalah lapisan tipis di atas mesin capsolver-core: lapisan ini membungkus metode inti solve / detect / solve_on_page sebagai alat yang dapat dipanggil oleh LLM, membuat batas “model memutuskan, inti mengeksekusi” berada pada tempatnya secara alami.

Pembagian kerja: model menangani navigasi dan pengambilan keputusan, capsolver-core menangani penyelesaian, dan capsolver-agent adalah lapisan adaptor alat di antaranya — model memanggil “pecahkan” dengan cara yang sama seperti memanggil “klik” atau “ketik”, tanpa harus mengklik CAPTCHA itu sendiri.

1. Bagaimana capsolver-agent Berhubungan dengan capsolver-core

Anda hampir tidak pernah menulis kode panggilan inti secara langsung. Ketika LLM memutuskan untuk memanggil alat, pelaksana lapisan agen memanggil metode inti yang sesuai untuk Anda dan mengembalikan hasil terstruktur ke model:

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

Setiap alat agen memetakan langsung ke satu metode inti — di situlah inti melakukan pekerjaan nyata dalam setiap skenario:

2. Instalasi

capsolver-agent dibangun di atas capsolver-core (inti melakukan penyelesaian) dan bergantung padanya saat runtime. Keduanya open source di GitHub dan belum dipublikasikan ke PyPI, dan capsolver-agent bergantung pada capsolver-core berdasarkan namanya. Instal inti terlebih dahulu, lalu agen:

# 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

Tambahkan tambahan sesuai kebutuhan:

# 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. Penggunaan: Pemecahan Kabel ke dalam Lingkaran Percakapan

Integrasi masuk ke dalam lingkaran “alat-percakapan” model. Satu putaran penuh berjalan seperti ini:

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

Dalam praktiknya, model menentukan apakah dan alat mana yang akan digunakan; tugas Anda adalah memasukkan inti ke dalam loop ini, dalam tiga langkah: sambungkan inti → serahkan alat ke model → jalankan panggilan yang dikembalikan model di dalam loop, merangkainya menjadi loop yang berfungsi.

3.1 Hubungkan inti: buat eksekutor

Hal yang benar-benar menyelesaikannya adalah selalu mesin capsolver-core Capsolver. Lapisan agen hanya menambahkan ToolExecutor di sekitarnya: secara internal ia menyimpan Capsolver , mengirimkan panggilan alat model ke metode mesin yang sesuai, dan menggabungkan pengembalian ke dalam hasil terstruktur. Di bawah ini pertama-tama kami tunjukkan bagaimana pembungkus ini dirakit, kemudian tulisan singkat satu baris.

Bagaimana eksekutor memuat inti. Dijelaskan, ada dua baris, dengan inti dibuat pada baris pertama:

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

Pengirimannya adalah pemetaan tetap; setiap panggilan alat pada akhirnya mengarah pada metode inti:

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

Pada setiap panggilan, pelaksana menyusun argumen alat ke dalam bentuk yang diharapkan inti, memanggil inti, dan menggabungkan hasil (atau kesalahan) ke dalam dict yang dapat Anda masukkan langsung kembali ke model - kesuksesan adalah {"success": True, "solution": {...}} , kegagalan adalah {"success": False, "error": "..."} . Jadi metode dan parameter yang Anda pelajari di halaman Core SDK berlaku di sini tanpa perubahan.

Penggunaan. Kedua baris di atas memiliki pembungkus yang sudah jadi; dalam penggunaan sehari-hari, sebut saja:

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

Saat Anda ingin menyesuaikan perilaku inti, argumen kata kunci tambahan apa pun yang diteruskan ke create_executor() akan diteruskan apa adanya ke Capsolver(...) — misalnya, create_executor(api_key=..., default_timeout=180) .

3.2 Serahkan alat kepada model

get_all_tools() memberi Anda semua definisi alat — deskripsi kemampuan inti secara langsung. Ekspor mereka dalam format kerangka target Anda dan teruskan ke model sebagai antarmuka pemanggil fungsinya:

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 Jalankan panggilan yang dikembalikan model, diteruskan ke inti

Saat model mengembalikan tool_call pada langkah tertentu, serahkan ke pelaksana dari 3.1 — execute(tool_name, args) mengirimkan panggilan ke metode inti yang sesuai ( solve / detect / solve_on_page …), mengembalikan hasil terstruktur, dan Anda memasukkannya kembali ke model:

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 Merangkainya menjadi satu lingkaran penuh

Sematkan tiga langkah di atas ke dalam loop percakapan model, dan Anda akan memiliki agen minimal yang menyelesaikan CAPTCHA sendiri (menggunakan pemanggilan fungsi OpenAI sebagai contoh):

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

Jika Anda hanya ingin menjalankan suatu alat satu kali daripada membuat keseluruhan loop, panggil execute_tool(name, args, api_key=...) dalam satu kesempatan.

4. Per Kerangka: Loop yang Sama, Shell Berbeda

Dua langkah di atas merupakan kerangka universal. Saat Anda terhubung ke kerangka kerja tertentu, satu-satunya perbedaan adalah siapa yang menggerakkan loop “panggil alat → memberi umpan balik”, dan kemampuan inti mana yang Anda gunakan — parameter situs yang diketahui melewati mode Token ( solve() ), sementara mengarahkan laman secara mandiri melalui mode Browser ( detect() / solve_on_page() ).

Dari semua ini, Penggunaan Browser paling mirip dengan otomatisasi di dunia nyata: agen melakukan penelusuran sendiri, dan ketika mencapai pertengahan tugas CAPTCHA, agen memanggil penyelesaian sebagai tindakan — mendeteksi, menyelesaikan, dan mengisi kembali dalam sesi browser yang sama, lalu melanjutkan alur awal setelah mendapatkan hasilnya, tanpa menghentikan langkah:

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

5. Menjalankan Contoh

Setiap skenario dalam tabel di atas dikirimkan dengan contoh yang dapat dijalankan, semuanya di bawah examples/ di repositori agen. Kloning, instal dependensinya, dan jalankan.

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

Dependensi tambahan setiap contoh ( capsolver-agent / capsolver-core instal dari GitHub; sisanya adalah paket PyPI reguler):

# 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