Résolution de captcha pour
agents OpenAI Agents SDK
Un agent qui rencontre un défi n'a rien dans sa boîte à outils pour y répondre : il se bloque ou hallucine un contournement. Donnez-lui un solveur sous forme d'outil et le blocage devient un appel de plus.
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])Pourquoi les agents en ont particulièrement besoin
Un scraper qui tombe sur un défi échoue bruyamment, et vous le corrigez. Un agent échoue en silence : il raisonne sur la page bloquée, invente une étape suivante plausible et signale des progrès qu'il n'a jamais faits. L'échec est pire parce qu'il est silencieux. Un outil de résolution typé transforme une impasse ambiguë en un résultat déterministe sur lequel l'agent peut s'appuyer.
Ce que renvoie l'outil
- Un token ou un cookie, selon le type de défi. Les systèmes évalués sur la session renvoient un cookie ainsi que l'ensemble des en-têtes utilisés pour l'obtenir.
- Le user agent utilisé, pour que l'agent puisse le réutiliser lors de la soumission.
- Le coût de la résolution, pour qu'un agent soumis à un budget puisse le comptabiliser au lieu de dépenser à l'aveugle.
Garder la boucle bornée
Donnez à l'agent un budget de résolutions par exécution. Chaque réponse indique son coût : un superviseur peut donc couper la boucle quand les dépenses dépassent un seuil, plutôt que de le découvrir sur la facture. À $0.00598 par résolution, une exécution d'agent typique coûte quelques centimes ou moins, mais une boucle de nouvelles tentatives sans limite reste une boucle sans limite.
Gardez l'appel d'outil bloquant
Les exemples appellent ?wait=60, pour que l'outil renvoie un token finalisé en une seule étape. C'est plus important pour les agents que pour les scripts : un outil qui renvoie "résolution en cours" oblige le modèle à raisonner sur le polling, ce qu'il fait mal. Si vous avez besoin d'un délai plus long, augmentez wait jusqu'à 120 secondes. Les formats de requête de chaque type de défi figurent dans la référence de l'API.
Comment la résolution s'intègre à OpenAI Agents SDK
L'OpenAI Agents SDK transforme une fonction Python typée en outil grâce à function_tool. Le solveur devient l'un des outils de l'agent.
- 01Décorer une fonction
Encapsulez l'appel à l'API avec @function_tool et des arguments typés.
- 02L'ajouter à l'agent
Passez-le dans la liste des outils de l'agent.
- 03Donner des instructions à l'agent
Demandez-lui d'appeler l'outil, avec la sitekey et l'URL, lorsqu'une page affiche un captcha.
- 04Le tracer
Le tracing du SDK affiche chaque appel d'outil et son résultat, y compris le coût que nous renvoyons.
Injecter le token dans la page
L'agent reçoit le token et le transmet à son outil navigateur ou HTTP.
Là où les intégrations échouent le plus souvent
Typez chaque argument pour que le schéma généré soit précis et que le modèle le remplisse correctement.
Réglez le timeout HTTP au-dessus de la valeur de wait pour que l'outil n'échoue pas pendant que la résolution est encore en cours.
FAQ captcha OpenAI Agents SDK
Cela fonctionne-t-il avec d'autres modèles que ceux d'OpenAI ?
Le SDK prend en charge d'autres fournisseurs via son interface de modèle, et l'outil lui-même repose sur du HTTP standard : la réponse est donc oui.
Puis-je l'utiliser avec des handoffs ?
Oui. Confiez l'outil à l'agent qui pilote le navigateur ; les autres peuvent lui passer la main.
Où stocker la clé API ?
Dans une variable d'environnement lue à l'intérieur de la fonction de l'outil, jamais dans les instructions de l'agent.
Comment plafonner les dépenses ?
Suivez le champ cost de chaque résultat dans le contexte d'exécution et refusez toute nouvelle résolution au-delà d'un budget.
Guides utiles
Prêt à développer ?
Commencez par un essai gratuit de 3 jours, puis payez par résolution réussie à mesure que votre trafic augmente. Aucune carte requise pour l'essai.