Agente

Lleve la capacidad de resolución de CapSolver a cualquier marco de LLM/agente. capsolver-agent es una capa delgada sobre el motor capsolver-core: envuelve los métodos solve / detect / solve_on_page del núcleo como herramientas que un LLM puede llamar, haciendo que el límite “el modelo decide, el núcleo ejecuta” encaje en su lugar de forma natural.

División del trabajo: el modelo maneja la navegación y la toma de decisiones, capsolver-core maneja la resolución y capsolver-agent es la capa intermedia del adaptador de herramientas; el modelo llama “resolver” de la misma manera que llama “hacer clic” o “escribir”, sin tener que hacer clic en el CAPTCHA.

1. Cómo se relaciona capsolver-agent con capsolver-core

Casi nunca escribes el código de llamada principal directamente. Cuando el LLM decide llamar a una herramienta, el ejecutor de la capa de agente llama al método central correspondiente y devuelve un resultado estructurado al modelo:

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

Cada herramienta de agente se asigna directamente a un método central, que es donde el núcleo hace el trabajo real en cada escenario:

2. Instalación

capsolver-agent está construido sobre capsolver-core (el núcleo resuelve) y depende de él en tiempo de ejecución. Ambos son de código abierto en GitHub y aún no se han publicado en PyPI, y capsolver-agent depende de capsolver-core por su nombre. Instale primero el núcleo y luego el agente:

# 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

Agregue extras según sea necesario:

# 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. Uso: Conexión de la resolución al bucle de conversación

La integración aterriza dentro del bucle “conversación-herramienta” del modelo. Una ronda completa transcurre así:

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 la práctica, el modelo decide si utilizar y qué herramienta; su trabajo es conectar el núcleo a este bucle, en tres pasos: conectar el núcleo → entregar las herramientas al modelo → ejecutar las llamadas que el modelo devuelve dentro del bucle, encadenándolas en un bucle de trabajo.

3.1 Conectar núcleo: crear un ejecutor

Lo que realmente resuelve es siempre el motor Capsolver de capsolver-core. La capa de agente solo agrega un ToolExecutor a su alrededor: internamente contiene un Capsolver, envía las llamadas a la herramienta del modelo a los métodos correspondientes del motor y envuelve el retorno en un resultado estructurado. A continuación, primero mostramos cómo se ensambla este contenedor y luego la taquigrafía de una sola línea.

Cómo carga el ejecutor el núcleo. En detalle, son dos líneas, con el núcleo creado en la primera:

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

El despacho es un mapeo fijo; cada llamada a una herramienta finalmente aterriza en un método central:

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

En cada llamada, el ejecutor reúne los argumentos de la herramienta en la forma que el núcleo espera, llama al núcleo y envuelve el resultado (o error) en un dictado que puede enviar directamente al modelo: el éxito es {"success": True, "solution": {...}}, el fracaso es {"success": False, "error": "..."}. Por lo tanto, los métodos y parámetros que aprendió en la página Core SDK se aplican aquí sin cambios.

Uso. Las dos líneas anteriores tienen un envoltorio ya preparado; en el uso diario, simplemente llámalo:

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

Cuando desee personalizar el comportamiento del núcleo, cualquier argumento de palabra clave adicional pasado a create_executor() se reenvía tal cual a Capsolver(...), por ejemplo, create_executor(api_key=..., default_timeout=180).

3.2 Entregar las herramientas al modelo

get_all_tools() le brinda todas las definiciones de herramientas: la descripción exterior de las capacidades del núcleo. Exportarlos en el formato de su marco de destino y pasarlos al modelo como su interfaz de llamada de funciones:

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 Ejecutar la llamada que devuelve el modelo, transmitiéndola al núcleo

Cuando el modelo devuelve un tool_call en algún paso, entrégueselo al ejecutor desde 3.1: execute(tool_name, args) envía la llamada al método central correspondiente ( solve / detect / solve_on_page…), devuelve un resultado estructurado y lo devuelves al modelo:

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 Encadenarlo en un bucle completo

Incorpore los tres pasos anteriores en el bucle de conversación del modelo y tendrá un agente mínimo que resuelve CAPTCHA por sí solo (usando la función OpenAI como ejemplo):

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

Cuando solo desee ejecutar una herramienta una vez en lugar de crear todo el bucle, llame a execute_tool(name, args, api_key=...) de una sola vez.

4. Por marco: el mismo bucle, un caparazón diferente

Los dos pasos anteriores son el esqueleto universal. Cuando se conecta a un marco específico, las únicas diferencias son quién impulsa el ciclo “llamar a una herramienta → retroalimentar el resultado” y qué capacidades principales utiliza: los parámetros conocidos del sitio pasan por el modo Token ( solve() ), mientras que la conducción autónoma de la página pasa por el modo Navegador ( detect() / solve_on_page() ).

De estos, El uso del navegador es el más cercano a la automatización del mundo real: el agente navega por sí solo, y cuando encuentra un CAPTCHA a mitad de la tarea, llama a la resolución como una acción: detectar, resolver y completar dentro de la misma sesión del navegador, y luego continúa el flujo original una vez que tiene el resultado, sin interrumpir el ritmo:

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

5. Ejecutando los ejemplos

Cada escenario en la tabla anterior incluye un ejemplo ejecutable, todo bajo examples/ en el repositorio del agente. Clónelo, instale las dependencias y ejecútelo.

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

Las dependencias adicionales de cada ejemplo ( capsolver-agent / capsolver-core se instalan desde GitHub; el resto son paquetes PyPI normales):

# 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