[ AGENTES ]

Resolução de captcha para
agentes Browser Use

Um agente que encontra um desafio não tem nada no seu conjunto de ferramentas que consiga respondê-lo, então ele trava ou alucina para contorná-lo. Dê a ele um solucionador como ferramenta e o bloqueio vira só mais uma chamada.

python · browser use

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 browser_use import Agent, Tools, ActionResult

tools = Tools()

@tools.action("Solve a captcha that is blocking the current page")
def solve_captcha(kind: str, sitekey: str, url: str) -> ActionResult:
    solution = solve({"type": kind, "sitekey": sitekey, "url": url})
    return ActionResult(extracted_content=solution["token"])

agent = Agent(task="...", llm=llm, tools=tools)

Por que agentes precisam especificamente disso

Um scraper que encontra um desafio falha de forma evidente e você corrige. Um agente falha em silêncio: ele raciocina sobre a página bloqueada, inventa um próximo passo plausível e relata um progresso que nunca fez. A falha é pior porque é silenciosa. Uma ferramenta de resolução tipada transforma um beco sem saída ambíguo em um resultado determinístico a partir do qual o agente pode decidir.

O que a ferramenta retorna

Um token ou cookie — dependendo do tipo de desafio. Sistemas avaliados por sessão retornam um cookie e o conjunto de headers usado para obtê-lo.
O user agent usado, para que o agente possa reutilizá-lo no envio.
O custo da resolução, para que um agente que opera com orçamento possa contabilizá-lo em vez de gastar às cegas.

Mantendo o loop sob controle

Dê ao agente um orçamento de resoluções por execução. Toda resposta informa o seu custo, então um supervisor pode cortar o loop quando o gasto passar de um limite, em vez de descobrir isso na fatura. A $0.00598 por resolução, uma execução típica de agente custa alguns centavos ou menos, mas um loop de novas tentativas sem limite continua sendo um loop sem limite.

Mantenha a chamada da ferramenta bloqueante

Os exemplos chamam ?wait=60, então a ferramenta retorna um token pronto em uma única etapa. Isso importa mais para agentes do que para scripts: uma ferramenta que retorna "ainda resolvendo" obriga o modelo a raciocinar sobre polling, algo que ele faz mal. Se você precisar de um teto maior, aumente wait para até 120 segundos. Os formatos de requisição de cada tipo de desafio estão na referência da API.

[ COMO SE ENCAIXA ]

Como a resolução se encaixa no Browser Use

O Browser Use permite registrar ações personalizadas. Uma ação de resolução lê a sitekey da página atual, obtém um token e o injeta, para que o agente continue no mesmo navegador.

01
Registre uma ação
Adicione uma ação de resolução às ferramentas do agente com uma descrição clara.
02
Leia a página atual
A ação lê a sitekey e a URL da sessão de navegador que ele já tem.
03
Resolva e injete
Chame a API e depois injete o token na mesma página.
04
Informe o resultado
Retorne um resultado curto para que o agente saiba que pode continuar.

Colocando o token na página

A ação executa JavaScript na própria página do agente para preencher o campo e disparar o callback.

[ ARMADILHAS ]

Onde as integrações costumam dar errado

Proxy diferente

Envie o proxy que o navegador do agente usa para que o token e a página compartilhem o mesmo IP.

Agente clicando no checkbox

Diga ao agente, na descrição da ação, para não clicar no widget por conta própria; a ação cuida disso.

[ FAQ ]

Perguntas frequentes sobre captcha no Browser Use

O Browser Use resolve captchas sozinho?

Ele consegue clicar em um checkbox, mas não consegue responder a desafios de imagem, e navegadores automatizados recebem esses desafios com frequência. Uma ação de resolução personalizada torna o resultado determinístico.

Funciona com o Browser Use cloud?

A ação só precisa de HTTPS de saída e da capacidade de executar JavaScript na página, então funciona onde quer que o seu agente rode.

E o Turnstile?

Mesma ação, tipo diferente. Leia a sitekey do Turnstile e envie type turnstile.

Como evitar que o agente entre em loop?

Conte as resoluções por tarefa e pare o agente ao passar de um limite. Cada resultado inclui o custo, se você preferir um orçamento de gastos.

[ LEIA A SEGUIR ]