[ АГЕНТЫ ]

Решение капчи для
агентов на LangChain

У агента, встретившего проверку, нет в наборе инструментов ничего, что могло бы на неё ответить, поэтому он зависает или галлюцинирует обходной путь. Дайте ему сервис решения капчи как инструмент, и блокировка станет ещё одним вызовом.

python · langchain

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 langchain_core.tools import tool

@tool
def solve_captcha(kind: str, sitekey: str, url: str) -> str:
    """Call when a captcha blocks the task. kind is recaptcha_v2, recaptcha_v3
    or turnstile. Returns the token to submit with the form."""
    return solve({"type": kind, "sitekey": sitekey, "url": url})["token"]

# add solve_captcha to your agent's tools list

Почему это нужно именно агентам

Парсер, наткнувшийся на проверку, падает с ошибкой, и вы его чините. Агент проваливается молча: он рассуждает о заблокированной странице, придумывает правдоподобный следующий шаг и сообщает о прогрессе, которого не было. Такой сбой хуже, потому что он незаметен. Типизированный инструмент решения превращает неоднозначный тупик в детерминированный результат, по которому агент может ветвиться.

Что возвращает инструмент

Токен или cookie — в зависимости от типа проверки. Системы с оценкой сессии возвращают cookie и набор заголовков, с которыми она была получена.
Использованный user agent, чтобы агент мог воспроизвести его при отправке.
Стоимость решения, чтобы агент, работающий в рамках бюджета, мог её учитывать, а не тратить вслепую.

Как ограничить цикл

Задайте агенту бюджет решений на запуск. Каждый ответ сообщает свою стоимость, поэтому супервизор может прервать цикл, когда расходы превысят порог, а не узнать об этом из счёта. При цене $0.00598 за решение типичный запуск агента стоит несколько центов или меньше, но бесконечный цикл повторов — всё равно бесконечный цикл повторов.

Оставьте вызов инструмента блокирующим

Примеры вызывают ?wait=60, поэтому инструмент возвращает готовый токен за один шаг. Для агентов это важнее, чем для скриптов: инструмент, который возвращает «ещё решается», заставляет модель рассуждать об опросе, а с этим она справляется плохо. Если нужен больший предел, увеличьте wait до 120 секунд. Форматы запросов для всех типов проверок — в справочнике API.

[ КАК ЭТО РАБОТАЕТ ]

Как решение встраивается в LangChain

В LangChain сервис решения капчи — это инструмент с типизированной схемой. Агент вызывает его, когда браузерный инструмент сообщает о проверке.

01
Определите инструмент
Оберните вызов API декоратором @tool и понятным docstring.
02
Привяжите его к агенту
Добавьте его в список инструментов рядом с браузерными инструментами.
03
Опишите, когда его использовать
Docstring указывает модели вызывать инструмент только при наличии капчи.
04
Возвращайте понятный результат
Возвращайте токен или короткую ошибку, на которую модель может отреагировать.

Как передать токен на страницу

Инструмент возвращает токен строкой, которую агент передаёт своему браузерному или HTTP-инструменту.

[ ПОДВОДНЫЕ КАМНИ ]

Где интеграции обычно ломаются

Расплывчатые docstring

Модель решает, когда вызывать инструмент, по его описанию. Укажите точно, какие входные данные ему нужны и что он возвращает.

Неограниченные повторы

Ограничьте число решений на запуск, чтобы запутавшийся агент не зациклился на странице, которая постоянно показывает проверку.

[ ВОПРОСЫ ]

Частые вопросы о капче в LangChain

Работает ли это с LangGraph?

Да. Инструмент LangChain в LangGraph тоже является функцией, вызываемой из узла, поэтому одно и то же определение работает в обоих.

Какая модель лучше всего работает с инструментом?

Любая модель с поддержкой вызова инструментов. Входные данные инструмента — простые строки, поэтому с ним хорошо справляются и небольшие модели.

Как агент узнаёт, что на странице капча?

Об этом должен сообщать его браузерный инструмент или инструмент скрейпинга, например возвращая sitekey, если он его нашёл. Сделайте это частью вывода инструмента.

Можно ли использовать его в асинхронном агенте?

Да. Используйте асинхронный HTTP-клиент внутри инструмента и определите его через async def.

[ ЧТО ПОЧИТАТЬ ]