Cách giải reCAPTCHA trong các Agent của LangGraph

TL;DR

• Cài đặt capsolver-agent với extra của LangChain và tải các công cụ sẵn có bằng get_langchain_tools().
• Gắn các công cụ này với mô hình chat và thực thi chúng bên trong ToolNode của LangGraph.
• Đối với chế độ token reCAPTCHA v2, cung cấp URL trang được ủy quyền chính xác và khóa trang; token trả về là gRecaptchaResponse ở cấp độ API.
• Đặt danh sách cho phép, giới hạn thử lại, tách biệt bí mật và định tuyến kiểm tra của con người xung quanh nút công cụ.
• Sử dụng chế độ trình duyệt phục hồi khi trang động yêu cầu phát hiện và chèn token trong cùng phiên.

Giới thiệu

Cách duy trì tốt nhất để giải reCAPTCHA trong các tác nhân LangGraph là xem việc phục hồi thách thức như một nút công cụ có kiểu thay vì nhúng logic mạng vào prompt mô hình. SDK Agent của CapSolver cung cấp các công cụ tương thích với LangChain, trong khi LangGraph cung cấp trạng thái rõ ràng, định tuyến, xử lý lỗi và khả năng tiếp tục. Mô hình có thể quyết định rằng một thách thức được hỗ trợ chặn bước tiếp theo được ủy quyền, nhưng một công cụ xác định sẽ kiểm tra các tham số trang, gọi người giải và trả về kết quả có cấu trúc. Kiến trúc này giữ API keys khỏi các thông điệp, làm cho việc thử lại có thể quan sát được và ngăn các mục tiêu không liên quan được gửi đi. Hướng dẫn này xây dựng một đồ thị tối giản, cho thấy cách định tuyến các cuộc gọi công cụ, giải thích các tham số reCAPTCHA v2 và thêm các biện pháp bảo vệ sản xuất cho tự động hóa trình duyệt, QA, RPA và quy trình dữ liệu công khai được phê duyệt.

CapSolver Nằm Ở Đâu Trong Máy Trạng Thái LangGraph

LangGraph được thiết kế cho các quy trình có trạng thái trong đó các nút thực hiện công việc giới hạn và các cạnh kiểm soát điều gì xảy ra tiếp theo. CapSolver phù hợp tự nhiên vào một nút công cụ chuyên dụng:

Nhiệm vụ do người dùng chỉ định
      ↓
Nút suy luận xác định một thách thức được hỗ trợ
      ↓
Nút công cụ thực thi công cụ CapSolver
      ↓
Kết quả có cấu trúc hoặc lỗi được chuẩn hóa
      ↓
Trình duyệt tiếp tục, thử lại hoặc yêu cầu kiểm tra của con người

Mô hình nên quyết định khi nào phục hồi là cần thiết. Nó không nên quyết định nơi lưu trữ bí mật, các máy chủ nào được ủy quyền hay số lần thử lại được phép. Những quyết định này thuộc về mã ứng dụng xác định.

Bài viết trên blog CapSolver AI bao gồm các mẫu tích hợp tác nhân, và FAQ CapSolver AI và tự động hóa giải thích cách lớp phục hồi bổ sung cho một ngăn xếp tác nhân hiện có.

Cài Đặt Công Cụ Agent và LangGraph

Tài liệu CapSolver Agent do người dùng cung cấp chỉ ra rằng capsolver-agent phụ thuộc vào capsolver-core. Cài đặt lõi trước, sau đó cài đặt gói agent với tích hợp LangChain.

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"
pip install langchain-openai langgraph

Cấu hình thông tin xác thực qua môi trường chạy:

export CAPSOLVER_API_KEY="CAP-xxxxxxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

Kho lưu trữ chính thức của CapSolver Agent ghi chú đường dẫn nhập:

from capsolver_agent.langchain_tools import get_langchain_tools

tools = get_langchain_tools(api_key="YOUR_API_KEY")

Các đối tượng trả về là các phiên bản BaseTool tương thích với LangChain. Hướng dẫn công cụ LangChain chính thức giải thích rằng các công cụ phơi bày đầu vào và đầu ra được xác định cho mô hình, trong khi thông tin kiểu và mô tả giúp mô hình chọn hành động đúng.

Hiểu Các Tham Số Nhiệm Vụ reCAPTCHA v2

Đối với nhiệm vụ reCAPTCHA v2 không dùng proxy, các đầu vào bắt buộc là URL trang và khóa trang. Tài liệu chính thức của CapSolver về reCAPTCHA v2 liệt kê ReCaptchaV2TaskProxyLess cho đường dẫn proxy tích hợp và các loại nhiệm vụ doanh nghiệp riêng biệt khi trang sử dụng reCAPTCHA Enterprise.

Ở cấp độ nhiệm vụ REST, token giải quyết được trả về dưới dạng solution.gRecaptchaResponse. SDK Tác nhân bao bọc kết quả lõi trong từ điển có cấu trúc để đồ thị có thể định tuyến trên thành công hoặc thất bại mà không cần phân tích văn bản tùy ý.

Đối với việc khám phá tham số, xem hướng dẫn mở rộng CapSolver và hướng dẫn triển khai reCAPTCHA v2.

Xây Dựng Một LangGraph Với Các Công Cụ CapSolver

Ví dụ dưới đây tải các công cụ CapSolver chính thức, gắn chúng với mô hình chat và đặt chúng trong ToolNode. Đồ thị quay lại nút suy luận sau mỗi phản hồi công cụ.

import os
from typing import Literal

from capsolver_agent.langchain_tools import get_langchain_tools
from langchain_openai import ChatOpenAI
from langgraph.graph import START, StateGraph
from langgraph.graph.message import MessagesState
from langgraph.prebuilt import ToolNode, tools_condition

capsolver_tools = get_langchain_tools(
    api_key=os.environ["CAPSOLVER_API_KEY"]
)

model = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
).bind_tools(capsolver_tools)


def agent_node(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}


def safe_tool_error(error: Exception) -> str:
    return (
        "Công cụ thách thức thất bại. Không thử lại tự động. "
        "Trả lại quy trình cho kiểm tra của người vận hành."
    )

builder = StateGraph(MessagesState)
builder.add_node("agent", agent_node)
builder.add_node(
    "tools",
    ToolNode(
        capsolver_tools,
        handle_tool_errors=safe_tool_error,
    ),
)
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")

graph = builder.compile()

Tài liệu tham khảo ToolNode của LangGraph ghi chú rằng ToolNode chấp nhận các phiên bản BaseTool, thực thi các cuộc gọi công cụ và hỗ trợ xử lý lỗi có thể cấu hình. Điều này làm cho nó phù hợp với nhánh phục hồi phải có thể quan sát và dự đoán được.

Giao Tiếp Rõ Ràng Cho Tác Nhân

Mô hình cần đủ bối cảnh để gọi công cụ đúng, nhưng nó không nên nhận quyền lực không giới hạn. Xây dựng thông điệp từ dữ liệu ứng dụng được xác minh:

request = {
    "website_url": "https://staging.example.com/approved-form",
    "website_key": "6LcXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
}

messages = [
    (
        "system",
        "Bạn chỉ hoạt động trên các quy trình được phê duyệt. Nếu reCAPTCHA được hỗ trợ "
        "cản bước tiếp theo, gọi công cụ solve_captcha của CapSolver một lần "
        "với URL và khóa trang chính xác do ứng dụng cung cấp. "
        "Không bao giờ tạo mục tiêu hoặc yêu cầu thông tin xác thực. Nếu giải quyết thất bại, "
        "dừng lại và yêu cầu kiểm tra của người vận hành.",
    ),
    (
        "user",
        "Tiếp tục nhiệm vụ thử nghiệm được phê duyệt. Trình duyệt báo cáo một "
        f"reCAPTCHA v2 tại {request['website_url']} với khóa trang "
        f"{request['website_key']}.",
    ),
]

result = graph.invoke(
    {"messages": messages},
    config={"recursion_limit": 6},
)

Giới hạn đệ quy ngăn vòng lặp đồ thị không kiểm soát. Trong sản xuất, cũng giới hạn hostname được phép trước khi xây dựng thông điệp và tránh lưu trữ token giải quyết trong các bản ghi.

Thêm Danh Sách Cho Phép Host Trước Đồ Thị

Các công cụ CapSolver giải quyết những gì chúng được yêu cầu; ứng dụng của bạn phải quyết định công việc nào được ủy quyền. Xác minh URL trang bên ngoài mô hình:

from urllib.parse import urlparse

ALLOWED_HOSTS = {
    "staging.example.com",
    "qa.example.com",
}


def validate_target(url: str) -> str:
    parsed = urlparse(url)
    if parsed.scheme != "https":
        raise ValueError("Chỉ các mục tiêu HTTPS được phép")
    if parsed.hostname not in ALLOWED_HOSTS:
        raise PermissionError("Máy chủ mục tiêu không được phê duyệt")
    return url

Sử dụng danh sách cho phép riêng cho khách hàng hoặc bản ghi quy trình được ký khi nhiều khách hàng chia sẻ cùng một nền tảng. Không cho phép các chỉ dẫn bằng ngôn ngữ tự nhiên thay đổi chính sách này.

Định tuyến Thành công, Thất bại và Kiểm tra Của Con Người

Một đồ thị phục hồi hữu ích cần ba kết quả, không chỉ "giải quyết" và "rơi". Chuẩn hóa đầu ra công cụ thành quyết định quy trình:

from typing import TypedDict

class RecoveryDecision(TypedDict):
    status: Literal["continue", "retry", "review"]
    reason: str


def classify_recovery(result: dict, attempt: int) -> RecoveryDecision:
    if result.get("success"):
        return {"status": "continue", "reason": "giải pháp được trả về"}

    error = str(result.get("error", "lỗi không xác định"))
    if attempt == 0 and "timeout" in error.lower():
        return {"status": "retry", "reason": "chỉ cho phép một lần thử lại giới hạn"}

    return {"status": "review", "reason": error}

Không bao giờ hiển thị token thô trong thông điệp mô hình khi trình duyệt có thể tiêu thụ trực tiếp. Giới hạn lý tưởng là: kết quả công cụ → điều khiển trình duyệt đáng tin cậy → kết quả gửi → trạng thái bị che đi trở lại đồ thị.

FAQ lỗi và khắc phục sự cố CapSolver cung cấp các con đường chẩn đoán phổ biến, trong khi hướng dẫn API phản hồi CapSolver giải thích cách xử lý kết quả.

Chế Độ Token So Với Chế Độ Trình Duyệt

Chế độ Token thường đơn giản hơn cho các tham số reCAPTCHA được biết. Chế độ Trình duyệt hữu ích khi luồng Playwright được ủy quyền cần detect() và solve_on_page() trong cùng phiên. Tài liệu CapSolver Agent ánh xạ solve_captcha đến giải quyết token lõi và solve_on_page đến phục hồi trình duyệt.

Quan sát Không Rò Rỉ Bí Mật

Ghi lại các chuyển tiếp đồ thị và chỉ số hoạt động, không phải giá trị nhạy cảm. Các trường hữu ích bao gồm:

safe_event = {
    "workflow_id": "wf_01J...",
    "node": "tools",
    "tool": "solve_captcha",
    "target_host": "staging.example.com",
    "challenge_type": "recaptcha_v2",
    "attempt": 1,
    "duration_ms": 6420,
    "outcome": "thành công",
}

Không bao giờ ghi nhật ký khóa API CapSolver, token giải quyết đầy đủ, cookie xác thực hoặc dữ liệu biểu mẫu. Áp dụng lọc bản ghi trước khi gửi sự kiện đến hệ thống quan sát bên ngoài.

Mã bổ sung: Sử dụng mã WEBS tại Bảng điều khiển CapSolver để nhận thêm 5% tiền thưởng cho mỗi lần nạp tiền.

Danh sách kiểm tra sản xuất

Một bộ giải quyết reCAPTCHA LangGraph sản xuất nên có danh sách cho phép hostname, chính sách nhiệm vụ cố định, xử lý thời gian sống ngắn của token, giới hạn thử lại, lọc bản ghi, điều kiện dừng rõ ràng và nút kiểm tra của người vận hành. Kiểm tra nó với trang thử nghiệm được phê duyệt trước khi kết nối với tự động hóa không người lái.

FAQ giải quyết CAPTCHA của CapSolver đề cập đến hành vi nhiệm vụ, và hướng dẫn quét bằng Python của CapSolver cung cấp các thực hành tự động hóa trình duyệt.

Sử dụng Có Trách nhiệm

Sử dụng quy trình này chỉ trên các hệ thống bạn sở hữu, kiểm tra hoặc có quyền hợp pháp để tự động hóa. Việc giải quyết thách thức không cấp quyền truy cập. Tôn trọng các điều khoản trang, giới hạn tốc độ, nghĩa vụ bảo mật và giới hạn mục đích. Yêu cầu xác nhận của con người trước khi đồ thị gửi biểu mẫu, thay đổi dữ liệu tài khoản hoặc thực hiện bất kỳ hành động có tác động lớn nào.

Kết luận

Một bộ giải quyết reCAPTCHA của LangGraph đáng tin cậy nhất khi giải quyết là nút công cụ rõ ràng với định tuyến nghiêm ngặt. Tải các công cụ LangChain sẵn có của CapSolver, gắn chúng với mô hình, thực thi chúng thông qua ToolNode, và giữ việc ủy quyền, bí mật, thử lại và tiêu thụ token trong mã ứng dụng xác định. Điều này mang lại khả năng phục hồi cho tác nhân mà không cung cấp quyền kiểm soát không giới hạn.

Bắt đầu với CapSolver, xác minh đồ thị với quy trình thử nghiệm được phê duyệt và thêm lọc bản ghi và kiểm tra của con người trước khi mở rộng.

Câu hỏi thường gặp

Tôi nên sử dụng import CapSolver nào với LangGraph?

Sử dụng from capsolver_agent.langchain_tools import get_langchain_tools, sau đó gọi get_langchain_tools(api_key=...) để nhận các công cụ tương thích với LangChain có thể truyền cho ToolNode.

Những đầu vào nào cần thiết cho chế độ token reCAPTCHA v2?

URL trang và khóa reCAPTCHA là bắt buộc. Các trường doanh nghiệp, ẩn, hành động hoặc phiên nên được bao gồm chỉ khi trang được ủy quyền thực sự sử dụng chúng.

Mô hình LangGraph có nên nhận token giải quyết không?

Ưu tiên gửi token trực tiếp từ lớp công cụ đáng tin cậy đến trình điều khiển trình duyệt. Trả lại chỉ sự kiện thành công hoặc thất bại bị che khi có thể.

Đồ thị nên cho phép bao nhiêu lần thử lại tự động?

Thông thường một lần thử lại giới hạn là đủ cho thời gian chờ tạm thời. Thất bại lặp lại nên định tuyến đến kiểm tra của con người vì URL, khóa, phiên hoặc cấu hình trang có thể sai.

Mẫu này có thể xử lý các thách thức trình duyệt động không?

Có. Sử dụng các phương pháp lõi CapSolver có khả năng trình duyệt thông qua công cụ được kiểm soát khi quy trình cần phát hiện và phục hồi cấp trang trong cùng phiên Playwright.