Agente

Leve a capacidade de resolução do CapSolver para qualquer estrutura LLM/agente. capsolver-agent é uma camada fina sobre o mecanismo capsolver-core: ele envolve os métodos solve / detect / solve_on_page do núcleo como ferramentas que um LLM pode chamar, fazendo com que o limite “o modelo decide, o núcleo executa” se encaixe naturalmente.

Divisão de trabalho: o modelo cuida da navegação e da tomada de decisões, capsolver-core cuida da resolução e capsolver-agent é a camada intermediária do adaptador de ferramenta — o modelo chama “resolver” da mesma forma que chama “clicar” ou “digitar”, sem precisar clicar no próprio CAPTCHA.

1. Como capsolver-agent se relaciona com capsolver-core

Você quase nunca escreve o código de chamada principal diretamente. Quando o LLM decide chamar uma ferramenta, o executor da camada de agente chama o método principal correspondente para você e retorna um resultado estruturado ao 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 ferramenta de agente é mapeada diretamente para um método principal — que é onde o núcleo faz o trabalho real em cada cenário:

2. Instalação

capsolver-agent é construído sobre capsolver-core (o núcleo faz a solução) e depende dele em tempo de execução. Ambos são de código aberto no GitHub e ainda não publicados no PyPI, e capsolver-agent depende de capsolver-core pelo nome. Instale primeiro o núcleo e depois o 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

Adicione extras conforme necessário:

# 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: Conectando a solução ao loop de conversa

A integração cai dentro do ciclo de “ferramenta de conversação” do modelo. Uma rodada completa é assim:

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

Na prática, o modelo decide se e qual ferramenta utilizar; seu trabalho é conectar o núcleo a esse loop, em três etapas: conectar o núcleo → entregar as ferramentas ao modelo → executar as chamadas que o modelo retorna dentro do loop, amarrando-as em um loop de trabalho.

3.1 Conecte o núcleo: crie um executor

O que realmente resolve é sempre o mecanismo Capsolver de capsolver-core. A camada de agente apenas adiciona um ToolExecutor ao seu redor: internamente ela contém um Capsolver , despacha as chamadas de ferramenta do modelo para os métodos correspondentes do mecanismo e envolve o retorno em um resultado estruturado. Abaixo mostramos primeiro como esse wrapper é montado e depois a abreviação do unifilar.

Como o executor carrega o núcleo. Escrito, são duas linhas, com o núcleo criado na primeira:

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

O despacho é um mapeamento fixo; em última análise, cada chamada de ferramenta chega a um método principal:

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

Em cada chamada, o executor reúne os argumentos da ferramenta no formato que o núcleo espera, chama o núcleo e agrupa o resultado (ou erro) em um ditado que você pode enviar diretamente ao modelo - o sucesso é {"success": True, "solution": {...}} , a falha é {"success": False, "error": "..."} . Portanto, os métodos e parâmetros que você aprendeu na página Core SDK se aplicam aqui inalterados.

Uso. As duas linhas acima possuem um wrapper pronto; no uso diário, basta chamá-lo:

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

Quando você deseja personalizar o comportamento do núcleo, quaisquer argumentos de palavra-chave extras passados ​​para create_executor() são encaminhados como estão para Capsolver(...) — por exemplo, create_executor(api_key=..., default_timeout=180) .

3.2 Entregar as ferramentas ao modelo

get_all_tools() fornece todas as definições de ferramentas - a descrição externa dos recursos do núcleo. Exporte-os no formato da sua estrutura de destino e passe-os para o modelo como sua interface de chamada de função:

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 Execute a chamada que o modelo retorna, retransmitindo para o núcleo

Quando o modelo retornar um tool_call em alguma etapa, entregue-o ao executor de 3.1 - execute(tool_name, args) despacha a chamada para o método principal correspondente ( solve / detect / solve_on_page …), retorna um resultado estruturado e você devolve isso ao 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 Amarre-o em um loop completo

Incorpore as três etapas acima no loop de conversação do modelo e você terá um agente mínimo que resolve CAPTCHAs por conta própria (usando a chamada de função OpenAI como exemplo):

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

Quando você quiser executar uma ferramenta apenas uma vez em vez de construir o loop inteiro, chame execute_tool(name, args, api_key=...) de uma só vez.

4. Por estrutura: o mesmo loop, um shell diferente

As duas etapas acima constituem o esqueleto universal. Quando você se conecta a uma estrutura específica, as únicas diferenças são quem conduz o loop “chamar uma ferramenta → retornar o resultado” e quais dos recursos principais você usa - os parâmetros conhecidos do site passam pelo modo Token ( solve() ), enquanto a condução autônoma da página passa pelo modo Navegador ( detect() / solve_on_page() ).

Destes, O uso do navegador é o mais próximo da automação do mundo real: o agente navega por conta própria e, quando atinge um CAPTCHA no meio da tarefa, ele chama a resolução como uma ação — detectando, resolvendo e preenchendo a mesma sessão do navegador e, em seguida, continuando o fluxo original assim que obtiver o resultado, sem interromper o ritmo:

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

5. Executando os exemplos

Cada cenário na tabela acima vem com um exemplo executável, tudo em examples/ no repositório do agente. Clone-o, instale as dependências e execute.

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

As dependências extras de cada exemplo ( capsolver-agent / capsolver-core instalam no GitHub; o restante são pacotes PyPI regulares):

# 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