Captchas lösen mit
LangChain-Agenten
Ein Agent, der auf eine Challenge trifft, hat nichts in seinem Toolset, das sie lösen kann – also bleibt er hängen oder halluziniert sich daran vorbei. Geben Sie ihm einen Solver als Tool, und die Blockade wird zu einem weiteren Aufruf.
import time
import requests
CAPTCHANO_KEY = "cn-YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {CAPTCHANO_KEY}"}
def solve(task: dict) -> dict:
"""Block until solved; returns e.g. {"token": "...", "userAgent": "..."}."""
r = requests.post(
"https://api.captchano.com/v1/solve",
params={"wait": 60},
json=task,
headers=HEADERS,
timeout=75,
)
data = r.json()
# A solve can outlast the 60 s wait: poll the task until it finishes.
while data.get("status") in ("queued", "solving"):
time.sleep(5)
data = requests.get(
f"https://api.captchano.com/v1/task/{data['id']}",
headers=HEADERS,
timeout=30,
).json()
if data.get("status") != "ready":
raise RuntimeError(data.get("error") or data)
return data["solution"]
from langchain_core.tools import tool
@tool
def solve_captcha(kind: str, sitekey: str, url: str) -> str:
"""Call when a captcha blocks the task. kind is recaptcha_v2, recaptcha_v3
or turnstile. Returns the token to submit with the form."""
return solve({"type": kind, "sitekey": sitekey, "url": url})["token"]
# add solve_captcha to your agent's tools listWarum gerade Agenten das brauchen
Ein Scraper, der auf eine Challenge trifft, scheitert laut, und Sie beheben das Problem. Ein Agent scheitert leise: Er denkt über die blockierte Seite nach, erfindet einen plausiblen nächsten Schritt und meldet Fortschritt, den es nie gab. Der Fehler ist schlimmer, weil er unbemerkt bleibt. Ein typisiertes Solver-Tool macht aus einer unklaren Sackgasse ein deterministisches Ergebnis, auf das der Agent reagieren kann.
Was das Tool zurückgibt
- Ein Token oder Cookie – je nach Challenge-Typ. Sitzungsbasiert bewertende Systeme liefern ein Cookie sowie die Header, mit denen es erhalten wurde.
- Den verwendeten User-Agent, damit der Agent ihn beim Absenden übernehmen kann.
- Die Kosten der Lösung, damit ein Agent mit Budget sie verbuchen kann, statt blind auszugeben.
Die Schleife begrenzt halten
Geben Sie dem Agenten ein Lösungsbudget pro Lauf. Jede Response meldet ihre Kosten, sodass ein Supervisor die Schleife abbrechen kann, wenn die Ausgaben einen Schwellenwert überschreiten – statt es erst auf der Rechnung zu bemerken. Bei $0.00598 pro Lösung kostet ein typischer Agent-Lauf wenige Cent oder weniger, aber eine unbegrenzte Retry-Schleife bleibt eine unbegrenzte Retry-Schleife.
Den Tool-Aufruf blockierend halten
Die Beispiele rufen ?wait=60 auf, sodass das Tool in einem einzigen Schritt ein fertiges Token zurückgibt. Für Agenten ist das wichtiger als für Skripte: Ein Tool, das „wird noch gelöst“ zurückgibt, zwingt das Modell, über Polling nachzudenken – und das kann es schlecht. Brauchen Sie eine höhere Obergrenze, erhöhen Sie wait auf bis zu 120 Sekunden. Die Request-Formate für jeden Challenge-Typ finden Sie in der API-Referenz.
So fügt sich die Lösung in LangChain ein
In LangChain ist der Solver ein Tool mit typisiertem Schema. Der Agent ruft es auf, wenn sein Browser-Tool eine Challenge meldet.
- 01Tool definieren
Kapseln Sie den API-Aufruf mit dem Decorator @tool und einem klaren Docstring.
- 02An den Agenten binden
Fügen Sie es der Tool-Liste neben Ihren Browser-Tools hinzu.
- 03Beschreiben, wann es zu nutzen ist
Der Docstring weist das Modell an, es nur aufzurufen, wenn ein Captcha vorhanden ist.
- 04Klares Ergebnis zurückgeben
Geben Sie das Token oder eine kurze Fehlermeldung zurück, auf die das Modell reagieren kann.
So kommt das Token in die Seite
Das Tool gibt das Token als String zurück, den der Agent an sein Browser- oder HTTP-Tool übergibt.
Woran Integrationen meistens scheitern
Das Modell entscheidet anhand der Beschreibung, wann es ein Tool aufruft. Geben Sie genau an, welche Eingaben es braucht und was es zurückgibt.
Begrenzen Sie Lösungen pro Lauf, damit ein verwirrter Agent nicht endlos auf einer Seite kreist, die immer wieder eine Challenge zeigt.
FAQ zu Captchas mit LangChain
Funktioniert es mit LangGraph?
Ja. Ein LangChain-Tool ist auch in LangGraph eine von Nodes aufrufbare Funktion, dieselbe Definition funktioniert also in beiden.
Welches Modell funktioniert am besten mit dem Tool?
Jedes Modell, das Tool Calling unterstützt. Die Eingaben des Tools sind einfache Strings, auch kleinere Modelle kommen damit gut zurecht.
Woher weiß der Agent, dass ein Captcha vorhanden ist?
Sein Browser- oder Scraping-Tool sollte es melden, etwa indem es den Sitekey zurückgibt, wenn es einen findet. Machen Sie das zum Teil der Tool-Ausgabe.
Kann ich es in einem asynchronen Agenten nutzen?
Ja. Verwenden Sie im Tool einen asynchronen HTTP-Client und definieren Sie es mit async def.
Hilfreiche Anleitungen
Bereit zum Loslegen?
Starten Sie mit einer kostenlosen 3-tägigen Testphase und zahlen Sie danach pro erfolgreicher Lösung, wenn Ihr Traffic wächst. Für die Testphase ist keine Karte nötig.