Agent

Intégrez la capacité de résolution de CapSolver dans n’importe quel cadre LLM/agent. capsolver-agent est une fine couche sur le moteur capsolver-core: elle enveloppe les méthodes solve / detect / solve_on_page du noyau en tant qu’outils qu’un LLM peut appeler, ce qui permet à la limite « le modèle décide, le noyau exécute » de se mettre naturellement en place.

Division du travail: le modèle gère la navigation et la prise de décision, capsolver-core gère la résolution et capsolver-agent est la couche d’adaptateur d’outils entre les deux — le modèle appelle « résoudre » de la même manière qu’il appelle « cliquer » ou « taper », sans avoir à cliquer sur le CAPTCHA lui-même.

1. Comment capsolver-agent est lié à capsolver-core

Vous n’écrivez presque jamais directement le code d’appel principal. Lorsque le LLM décide d’appeler un outil, l’exécuteur de la couche agent appelle pour vous la méthode principale correspondante et renvoie un résultat structuré au modèle:

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

Chaque outil d’agent correspond directement à une méthode principale - c’est là que le noyau effectue le vrai travail dans chaque scénario:

2.Installation

capsolver-agent est construit sur capsolver-core (le noyau effectue la résolution) et en dépend au moment de l’exécution. Les deux sont open source sur GitHub et ne sont pas encore publiés sur PyPI, et capsolver-agent dépend de capsolver-core par son nom. Installez d’abord le noyau, puis l’agent:

# 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

Ajoutez des extras si nécessaire:

# 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. Utilisation: câblage de la résolution dans la boucle de conversation

L’intégration atterrit à l’intérieur de la boucle «conversation-outil» du modèle. Un tour complet se déroule comme ceci:

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

En pratique, le modèle décide si et quel outil utiliser ; votre travail consiste à câbler le noyau dans cette boucle, en trois étapes: connecter le noyau → transmettre les outils au modèle → exécuter les appels que le modèle renvoie à l’intérieur de la boucle, en les enchaînant dans une boucle de travail.

3.1 Connect core: créer un exécuteur

La chose qui résout réellement est toujours le moteur Capsolver de capsolver-core. La couche agent ajoute uniquement un ToolExecutor autour d’elle: en interne, elle contient un Capsolver , distribue les appels d’outils du modèle aux méthodes correspondantes du moteur et enveloppe le retour dans un résultat structuré. Ci-dessous, nous montrons d’abord comment ce wrapper est assemblé, puis le raccourci sur une ligne.

Comment l’exécuteur charge le noyau. En clair, il s’agit de deux lignes, avec le noyau créé sur la première:

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

La répartition est une cartographie fixe; chaque appel d’outil atterrit finalement sur une méthode principale:

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

À chaque appel, l’exécuteur rassemble les arguments de l’outil sous la forme attendue par core, appelle core et enveloppe le résultat (ou l’erreur) dans un dict que vous pouvez renvoyer directement au modèle - le succès est {"success": True, "solution": {...}} , l’échec est {"success": False, "error": "..."} . Ainsi, les méthodes et paramètres que vous avez appris sur la page Core SDK s’appliquent ici sans changement.

Utilisation. Les deux lignes ci-dessus ont un wrapper prêt à l’emploi; au quotidien, appelez-le simplement:

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

Lorsque vous souhaitez personnaliser le comportement du noyau, tous les arguments de mots clés supplémentaires transmis à create_executor() sont transmis tels quels à Capsolver(...) — par exemple, create_executor(api_key=..., default_timeout=180) .

3.2 Remettre les outils au modèle

get_all_tools() vous donne toutes les définitions des outils – la description extérieure des capacités du cœur. Exportez-les au format de votre framework cible et transmettez-les au modèle comme interface d’appel de fonction:

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 Exécuter l’appel renvoyé par le modèle, en le relayant vers le noyau

Lorsque le modèle renvoie un tool_call à une étape donnée, remettez-le à l’exécuteur de 3.1 — execute(tool_name, args) envoie l’appel à la méthode principale correspondante ( solve / detect / solve_on_page …), renvoie un résultat structuré et vous le renvoyez au modèle:

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 Enchaînez-le dans une boucle complète

Intégrez les trois étapes ci-dessus dans la boucle de conversation du modèle et vous disposez d’un agent minimal qui résout les CAPTCHA par lui-même (en utilisant l’appel de fonction OpenAI comme exemple):

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

Lorsque vous souhaitez exécuter un outil une seule fois plutôt que de créer la boucle entière, appelez execute_tool(name, args, api_key=...) d’un seul coup.

4. Par Framework: la même boucle, un shell différent

Les deux étapes ci-dessus constituent le squelette universel. Lorsque vous vous connectez à un framework spécifique, les seules différences sont qui pilote la boucle « appeler un outil → renvoyer le résultat » et quelles fonctionnalités de base vous utilisez: les paramètres de site connus passent par le mode Token ( solve() ), tandis que la conduite autonome de la page passe par le mode Navigateur ( detect() / solve_on_page() ).

Parmi ceux-ci, l’utilisation du navigateur est la plus proche de l’automatisation du monde réel: l’agent navigue tout seul, et lorsqu’il atteint un CAPTCHA en cours de tâche, il appelle la résolution comme une action: détecter, résoudre et remplir au cours de la même session de navigateur, puis poursuivre le flux d’origine une fois le résultat obtenu, sans interrompre le pas:

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

5. Exécuter les exemples

Chaque scénario du tableau ci-dessus est livré avec un exemple exécutable, le tout sous examples/ dans le référentiel de l’agent. Clonez-le, installez les dépendances et exécutez.

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

Les dépendances supplémentaires de chaque exemple (installation capsolver-agent / capsolver-core à partir de GitHub; le reste sont des packages PyPI standards):

# 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