← Back to Docs

CrewAI Integration

Add CAPTCHA solving to CrewAI agents and multi-agent crews.

pip install gatesolve+pip install crewai

Step 1: Create the Tool

Wrap GateSolve as a CrewAI tool using the @tool decorator.

python
from crewai.tools import tool
from gatesolve import GateSolve

gs = GateSolve(api_key="gs_your_key")

@tool("Solve CAPTCHA")
def solve_captcha(captcha_type: str, site_key: str, page_url: str) -> str:
    """Solve a CAPTCHA and return the solution token.
    Use this when a web page shows a CAPTCHA challenge.
    
    Args:
        captcha_type: turnstile, recaptcha_v2, recaptcha_v3, or hcaptcha
        site_key: The site key from the CAPTCHA element
        page_url: URL of the page containing the CAPTCHA
    """
    solution = gs.solve(
        captcha_type=captcha_type,
        sitekey=site_key,
        pageurl=page_url,
    )
    return f"Solved! Token: {solution.token} (took {solution.solve_time})"

Step 2: Use in a Crew

Give the tool to an agent. When the agent encounters a CAPTCHA during web scraping, it calls the tool automatically.

python
from crewai import Agent, Task, Crew

# Create an agent with CAPTCHA solving ability
scraper = Agent(
    role="Web Scraper",
    goal="Extract data from websites, solving any CAPTCHAs encountered",
    backstory="You are an expert web scraper that can bypass "
              "anti-bot protections by solving CAPTCHAs.",
    tools=[solve_captcha],
    verbose=True,
)

# Define a task that might encounter CAPTCHAs
scrape_task = Task(
    description=(
        "Go to https://example.com/data and extract the pricing table. "
        "If you encounter a CAPTCHA, solve it using the solve_captcha tool. "
        "The site uses Cloudflare Turnstile protection."
    ),
    expected_output="A structured list of pricing tiers and features",
    agent=scraper,
)

# Run the crew
crew = Crew(agents=[scraper], tasks=[scrape_task], verbose=True)
result = crew.kickoff()
print(result)

Multi-Agent: CAPTCHA Specialist

For complex crews, create a dedicated CAPTCHA-solving agent. Other agents can delegate to it when they hit a challenge.

python
from crewai import Agent, Task, Crew

# Specialist agent just for CAPTCHA solving
captcha_solver = Agent(
    role="CAPTCHA Specialist",
    goal="Solve any CAPTCHA challenges encountered during web operations",
    backstory="You specialize in solving CAPTCHAs using the GateSolve API.",
    tools=[solve_captcha],
)

# Main scraper agent delegates CAPTCHA solving
scraper = Agent(
    role="Data Extractor",
    goal="Extract structured data from protected websites",
    backstory="You navigate websites and extract data. "
              "Delegate CAPTCHA solving to the specialist.",
    allow_delegation=True,
)

solve_task = Task(
    description="Solve the Turnstile CAPTCHA on https://example.com/login",
    expected_output="The CAPTCHA solution token",
    agent=captcha_solver,
)

extract_task = Task(
    description="Extract all product data from the dashboard after login",
    expected_output="Structured product data in JSON format",
    agent=scraper,
    context=[solve_task],
)

crew = Crew(
    agents=[captcha_solver, scraper],
    tasks=[solve_task, extract_task],
    verbose=True,
)
result = crew.kickoff()

Non-blocking: Submit + Poll

For workflows where the agent can do other work while waiting for the CAPTCHA to solve.

python
from crewai.tools import tool
from gatesolve import GateSolve

gs = GateSolve(api_key="gs_your_key")

@tool("Submit CAPTCHA")
def submit_captcha(captcha_type: str, site_key: str, page_url: str) -> str:
    """Submit a CAPTCHA for solving. Returns a job ID to check later."""
    job_id = gs.submit(
        captcha_type=captcha_type,
        sitekey=site_key,
        pageurl=page_url,
    )
    return f"Job submitted: {job_id}"

@tool("Check CAPTCHA Result")
def check_captcha(job_id: str) -> str:
    """Check if a CAPTCHA solve job is complete."""
    result = gs.poll(job_id)
    if result["status"] == "solved":
        return f"Solved! Token: {result['token']}"
    return f"Still {result['status']}. Check again in a few seconds."

Supported CAPTCHAs

Cloudflare Turnstile
turnstile · 8-12s
reCAPTCHA v2
recaptcha_v2 · 10-15s
reCAPTCHA v3
recaptcha_v3 · 8-12s
hCaptcha
hcaptcha · 10-15s

Get Started Free

100 free CAPTCHA solves. No credit card required.