Agent

Bringen Sie die Lösungsfähigkeit von CapSolver in jedes LLM-/Agent-Framework ein. capsolver-agent ist eine dünne Schicht über der capsolver-core-Engine: Sie umhüllt die Methoden solve / detect / solve_on_page des Kerns als Tools, die ein LLM aufrufen kann, sodass die Grenze „Modell entscheidet, Kern führt aus“ auf natürliche Weise entsteht.

Arbeitsteilung: Das Modell kümmert sich um die Navigation und Entscheidungsfindung, capsolver-core kümmert sich um das Lösen und capsolver-agent ist die Tool-Adapter-Schicht dazwischen – das Modell ruft „solve“ auf die gleiche Weise auf, wie es „click“ oder „type“ nennt, ohne dass auf das CAPTCHA selbst geklickt werden muss.

1. Wie sich capsolver-agent auf capsolver-core bezieht

Sie schreiben Kernaufrufcode fast nie direkt. Wenn das LLM beschließt, ein Tool aufzurufen, ruft der Executor der Agentenschicht die entsprechende Kernmethode für Sie auf und gibt ein strukturiertes Ergebnis an das Modell zurück:

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

Jedes Agententool ist direkt einer Kernmethode zugeordnet – wobei der Kern in jedem Szenario die eigentliche Arbeit erledigt:

2. Installation

capsolver-agent baut auf capsolver-core auf (der Kern übernimmt die Lösung) und ist zur Laufzeit davon abhängig. Beide sind Open Source auf GitHub und noch nicht auf PyPI veröffentlicht, und capsolver-agent hängt namentlich von capsolver-core ab. Zuerst den Kern installieren, dann den Agenten:

# 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

Fügen Sie nach Bedarf Extras hinzu:

# 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. Verwendung: Verkabelungslösung in die Gesprächsschleife integrieren

Die Integration landet innerhalb der „Konversations-Tool“-Schleife des Modells. Eine komplette Runde läuft so ab:

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

In der Praxis entscheidet das Modell, ob und welches Tool eingesetzt wird; Ihre Aufgabe besteht darin, den Kern in drei Schritten mit dieser Schleife zu verbinden: Kern verbinden → Werkzeuge an das Modell übergeben → die Aufrufe ausführen, die das Modell innerhalb der Schleife zurückgibt, und sie in eine Arbeitsschleife einbinden.

3.1 Kern verbinden: Einen Executor erstellen

Das, was tatsächlich löst, ist immer die Capsolver-Engine von capsolver-core. Die Agentenschicht fügt lediglich ein ToolExecutor um sich herum hinzu: Intern enthält sie ein Capsolver , leitet die Toolaufrufe des Modells an die entsprechenden Methoden der Engine weiter und verpackt die Rückgabe in ein strukturiertes Ergebnis. Im Folgenden zeigen wir zunächst, wie dieser Wrapper zusammengesetzt wird, dann die einzeilige Abkürzung.

Wie der Executor den Kern lädt. Ausgeschrieben sind es zwei Zeilen, wobei der Kern in der ersten erstellt wird:

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

Der Versand ist eine feste Zuordnung; Jeder Tool-Aufruf landet letztendlich auf einer Kernmethode:

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

Bei jedem Aufruf fügt der Executor die Toolargumente in der vom Kern erwarteten Form zusammen, ruft den Kern auf und verpackt das Ergebnis (oder den Fehler) in ein Diktat, das Sie direkt an das Modell zurückgeben können – Erfolg ist {"success": True, "solution": {...}} , Fehler ist {"success": False, "error": "..."} . Daher gelten hier unverändert die Methoden und Parameter, die Sie auf der Seite Core SDK gelernt haben.

Verwendung. Die beiden Zeilen oben haben einen vorgefertigten Wrapper; im alltäglichen Gebrauch nennen Sie es einfach:

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

Wenn Sie das Verhalten des Kerns anpassen möchten, werden alle zusätzlichen Schlüsselwortargumente, die an create_executor() übergeben werden, unverändert an Capsolver(...) weitergeleitet – zum Beispiel create_executor(api_key=..., default_timeout=180) .

3.2 Geben Sie dem Modell die Werkzeuge

get_all_tools() bietet Ihnen alle Werkzeugdefinitionen – die nach außen gerichtete Beschreibung der Kernfunktionen. Exportieren Sie sie im Format Ihres Ziel-Frameworks und übergeben Sie sie als Funktionsaufrufschnittstelle an das Modell:

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 Führen Sie den Aufruf aus, den das Modell zurückgibt, und leiten Sie ihn an den Kern weiter

Wenn das Modell irgendwann einen tool_call zurückgibt, übergeben Sie ihn an den Executor aus 3.1 – execute(tool_name, args) leitet den Aufruf an die entsprechende Kernmethode ( solve / detect / solve_on_page …) weiter, gibt ein strukturiertes Ergebnis zurück und Sie geben es an das Modell zurück:

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 Fädeln Sie es in eine vollständige Schleife ein

Betten Sie die drei oben genannten Schritte in die Konversationsschleife des Modells ein, und Sie haben einen minimalen Agenten, der CAPTCHAs selbst löst (am Beispiel des OpenAI-Funktionsaufrufs):

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

Wenn Sie ein Tool nur einmal ausführen möchten, anstatt die gesamte Schleife zu erstellen, rufen Sie execute_tool(name, args, api_key=...) in einem einzigen Schritt auf.

4. Pro Framework: die gleiche Schleife, eine andere Shell

Die beiden oben genannten Schritte bilden das universelle Grundgerüst. Wenn Sie eine Verbindung zu einem bestimmten Framework herstellen, bestehen die einzigen Unterschiede darin, wer die Schleife „Ein Tool aufrufen → Ergebnis zurückgeben“ steuert und welche Kernfunktionen Sie nutzen – bekannte Site-Parameter durchlaufen den Token-Modus ( solve() ), während die autonome Steuerung der Seite den Browser-Modus ( detect() / solve_on_page() ) durchläuft.

Von diesen kommt die Verwendung des Browsers der realen Automatisierung am nächsten: Der Agent durchsucht selbstständig, und wenn er mitten in der Aufgabe auf ein CAPTCHA trifft, ruft er die Lösung als Aktion auf – Erkennen, Lösen und Wiederauffüllen innerhalb der gleichen Browsersitzung, und setzt dann den ursprünglichen Ablauf fort, sobald er das Ergebnis hat, ohne den Schritt zu unterbrechen:

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

5. Ausführen der Beispiele

Zu jedem Szenario in der Tabelle oben gehört ein ausführbares Beispiel, alles unter examples/ im Agent-Repository. Klonen Sie es, installieren Sie die Abhängigkeiten und führen Sie es aus.

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

Die zusätzlichen Abhängigkeiten jedes Beispiels ( capsolver-agent / capsolver-core Installation von GitHub; der Rest sind reguläre PyPI-Pakete):

# 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