Captchas lösen mit
OpenAI Agents SDK-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 agents import Agent, function_tool
@function_tool
def solve_captcha(kind: str, sitekey: str, url: str) -> str:
"""Return a token for a captcha blocking the current page."""
return solve({"type": kind, "sitekey": sitekey, "url": url})["token"]
agent = Agent(name="browser", tools=[solve_captcha])Warum 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 OpenAI Agents SDK ein
Das OpenAI Agents SDK macht mit function_tool aus einer typisierten Python-Funktion ein Tool. Der Solver wird zu einem der Tools des Agenten.
- 01Funktion dekorieren
Kapseln Sie den API-Aufruf mit @function_tool und typisierten Argumenten.
- 02Dem Agenten hinzufügen
Übergeben Sie es in der Tool-Liste des Agenten.
- 03Agenten anweisen
Weisen Sie ihn an, das Tool mit Sitekey und URL aufzurufen, wenn eine Seite ein Captcha zeigt.
- 04Nachverfolgen
Das Tracing des SDK zeigt jeden Tool-Aufruf und jedes Ergebnis, einschließlich der Kosten, die wir zurückgeben.
So kommt das Token in die Seite
Der Agent erhält das Token und übergibt es an sein Browser- oder HTTP-Tool.
Woran Integrationen meistens scheitern
Typisieren Sie jedes Argument, damit das erzeugte Schema präzise ist und das Modell es korrekt ausfüllt.
Setzen Sie das HTTP-Timeout höher als den wait-Wert, damit das Tool nicht scheitert, während die Lösung noch läuft.
FAQ zu Captchas mit OpenAI Agents SDK
Funktioniert es auch mit anderen Modellen als denen von OpenAI?
Das SDK unterstützt über seine Modellschnittstelle auch andere Anbieter, und das Tool selbst ist reines HTTP – also ja.
Kann ich es mit Handoffs nutzen?
Ja. Geben Sie das Tool dem Agenten, der den Browser steuert; andere Agenten können an ihn übergeben.
Wo sollte der API-Schlüssel liegen?
In einer Umgebungsvariablen, die innerhalb der Tool-Funktion gelesen wird, nie in den Anweisungen des Agenten.
Wie begrenze ich die Ausgaben?
Erfassen Sie das Feld cost jedes Ergebnisses im Laufkontext und lehnen Sie weitere Lösungen ab, sobald ein Budget überschritten ist.
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.