How to Solve CAPTCHA in LlamaIndex Agents

LlamaIndex agents orchestrate data retrieval, indexing, and query workflows across diverse sources. When these agents access web-based data sources protected by CAPTCHA challenges, they need a solving mechanism to continue data ingestion. CapSolver's capsolver-agent package provides tool schemas compatible with LlamaIndex's FunctionTool system, enabling your agent to clear reCAPTCHA, Cloudflare Turnstile, and other verification challenges as part of its data pipeline.

TL;DR

• LlamaIndex agents stall when web data sources are protected by CAPTCHA verification
• CapSolver integrates through LlamaIndex's FunctionTool wrapper with async solving
• The capsolver-agent executor handles solving and returns structured results for the agent's reasoning loop
• Supports reCAPTCHA v2/v3 and Cloudflare Turnstile — the most common web verification types
• Integration takes under 15 lines using create_executor() and FunctionTool.from_defaults()

Why LlamaIndex Agents Need CAPTCHA Solving

LlamaIndex excels at building agents that retrieve, index, and query data from multiple sources. When these sources include web pages, APIs, or databases protected by CAPTCHA systems, the agent's data ingestion pipeline breaks. A RAG agent that needs to index documentation from a CAPTCHA-protected site, or a research agent that queries multiple web sources, cannot proceed without verification clearing.

The problem is particularly acute for LlamaIndex's data connector ecosystem. Web-based connectors that fetch pages for indexing encounter CAPTCHAs after repeated access. Without a solving tool, the agent either skips the source (incomplete data) or fails entirely (broken pipeline).

CapSolver's tool integration follows LlamaIndex's standard pattern: define a function, wrap it as a FunctionTool, and add it to the agent's tool list. The agent's reasoning engine decides when to invoke solving based on the task context.

What You Need Before Starting

# CapSolver packages
pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

# LlamaIndex
pip install llama-index llama-index-llms-openai

export CAPSOLVER_API_KEY="your-capsolver-api-key"
export OPENAI_API_KEY="your-openai-api-key"

Step 1 — Create a CAPTCHA Solving FunctionTool

import asyncio
from llama_index.core.tools import FunctionTool
from capsolver_agent.schema import create_executor

executor = create_executor(api_key="YOUR_CAPSOLVER_API_KEY")

def solve_captcha(captcha_type: str, website_url: str, website_key: str) -> str:
    """Solve a CAPTCHA challenge and return the verification token.
    
    Use when accessing a web resource protected by CAPTCHA verification.
    
    Args:
        captcha_type: 'reCaptchaV2', 'reCaptchaV3', or 'cloudflare'
        website_url: Full URL of the CAPTCHA-protected page
        website_key: The site key (data-sitekey attribute value)
    
    Returns:
        Solved token string or error message
    """
    result = asyncio.run(executor.execute("solve_captcha", {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }))
    if result["success"]:
        return f"CAPTCHA solved. Token: {result['solution']['token']}"
    return f"Failed: {result['error']}"

# Wrap as LlamaIndex FunctionTool
captcha_tool = FunctionTool.from_defaults(
    fn=solve_captcha,
    name="solve_captcha",
    description="Solve CAPTCHA challenges (reCAPTCHA v2/v3, Cloudflare Turnstile) on protected web pages"
)

Step 2 — Build a LlamaIndex Agent with CAPTCHA Capability

from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI

# Create LLM
llm = OpenAI(model="gpt-4o", temperature=0)

# Create agent with CAPTCHA solving tool
agent = ReActAgent.from_tools(
    tools=[captcha_tool],
    llm=llm,
    verbose=True
)

# Run the agent
response = agent.chat(
    "I need to access https://example.com/data which has a reCAPTCHA v2. "
    "The site key is 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. "
    "Solve it and give me the token."
)
print(response)

Step 3 — Integrate with LlamaIndex Data Connectors

For agents that ingest web data, combine CAPTCHA solving with data loading:

from llama_index.core import VectorStoreIndex, Document

def fetch_protected_page(url: str, site_key: str) -> str:
    """Fetch a CAPTCHA-protected page by solving first."""
    # Solve the CAPTCHA
    token = solve_captcha("reCaptchaV2", url, site_key)
    if "Failed" in token:
        return ""
    
    # Use token to access the page
    import requests
    response = requests.post(url, data={"g-recaptcha-response": token.split("Token: ")[1]})
    return response.text

# Create a custom tool for protected data ingestion
protected_fetch_tool = FunctionTool.from_defaults(
    fn=fetch_protected_page,
    name="fetch_protected_page",
    description="Fetch content from a CAPTCHA-protected web page by solving the verification first"
)

# Agent with both solving and fetching capability
data_agent = ReActAgent.from_tools(
    tools=[captcha_tool, protected_fetch_tool],
    llm=llm,
    verbose=True
)

Step 4 — Production Patterns

def solve_captcha_with_retry(captcha_type: str, website_url: str, website_key: str, max_retries: int = 3) -> str:
    """Production-grade CAPTCHA solving with retry logic."""
    for attempt in range(max_retries):
        result = asyncio.run(executor.execute("solve_captcha", {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key
        }))
        if result["success"]:
            return f"Solved (attempt {attempt+1}). Token: {result['solution']['token']}"
        if attempt < max_retries - 1:
            import time
            time.sleep(3)
    return f"Failed after {max_retries} attempts: {result.get('error')}"

# Production tool with retry
production_captcha_tool = FunctionTool.from_defaults(
    fn=solve_captcha_with_retry,
    name="solve_captcha",
    description="Solve CAPTCHA with automatic retry on failure"
)

Claim Your Bonus Code: Use code WEBS at CapSolver Dashboard to get an extra 5% bonus on every recharge.

The CapSolver API documentation covers additional parameters. For identifying CAPTCHA types, use the CapSolver extension. The CapSolver web scraping guide covers data collection patterns applicable to LlamaIndex data connectors.

Conclusion

Integrating CAPTCHA solving into LlamaIndex agents requires wrapping CapSolver's executor in a FunctionTool and adding it to your ReAct agent's tool list. The agent's reasoning loop decides when to invoke solving based on task context. CapSolver provides the solving infrastructure that handles reCAPTCHA and Cloudflare Turnstile through a unified API, keeping your LlamaIndex data pipelines running without interruption.

FAQ

Does CapSolver work with LlamaIndex's async agent?

Yes. The capsolver-agent executor is fully async. For LlamaIndex's async agents, use await executor.execute() directly instead of wrapping with asyncio.run().

Can I use this with LlamaIndex's web reader connectors?

Yes. Combine the CAPTCHA solving tool with custom web readers that handle verification before fetching page content. The agent can solve the CAPTCHA first, then pass the token to the web reader for authenticated access.

What if my LlamaIndex agent encounters an unknown CAPTCHA type?

The get_supported_captchas tool returns the list of supported types. If the agent encounters an unsupported type, it receives a clear error message and can report this to the user rather than failing silently.

How does this compare to using capsolver-mcp with LlamaIndex?

capsolver-mcp is for MCP clients (Claude Desktop, Cursor). For LlamaIndex agents running in code, use capsolver-agent with FunctionTool — it gives you direct programmatic control within the LlamaIndex framework.