CrewAI CAPTCHA Solver: Agent Tool Code Guide

TL;DR

• crewai captcha solver work should use CapSolver's AI agent stack as an explicit recovery layer, not hidden retry logic.
• capsolver-core fits Playwright scripts, capsolver-agent fits tool-calling agents, and capsolver-mcp fits MCP-compatible clients.
• The safe pattern is detect, read parameters, solve once with bounded retries, fill back, then record the request state for review.
• Agents should stop when the task scope changes, the page asks for restricted access, or challenge handling repeats without progress.

Introduction

CrewAI CAPTCHA solver work needs a code-level tool boundary between planning, browser control, and review. CapSolver should be wired as a documented agent capability: the browser or model detects a verification challenge, the approved tool handles it, and the agent resumes only when the original user-authorized task is still valid. The official CapSolver AI documentation describes three practical layers: CapSolver for AI Agents for architecture, Core SDK browser mode for Playwright flows, agent tool schemas for model-controlled calls, and MCP service tools for clients that discover tools over the Model Context Protocol. This article turns those docs into a production-minded crewai captcha solver workflow with code, stop rules, and logging fields.

Use the Official CapSolver AI Packages

The CapSolver AI docs describe three layers. Use the lowest layer that matches your ownership model: core SDK when your code controls the browser, agent tools when a model decides when to call a tool, and MCP service when your AI client should discover solving tools automatically.

pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
pip install git+https://github.com/capsolver-ai/capsolver-agent.git
pip install "capsolver-mcp[browser] @ git+https://github.com/capsolver-ai/capsolver-mcp.git"
playwright install chromium
export CAPSOLVER_API_KEY="your-capsolver-api-key"

The Introduction and Quick Start explains the package roles: capsolver-core exposes the engine, capsolver-agent wraps it as tools, and capsolver-mcp exposes the same capability to MCP clients. Keep the API key in environment configuration and avoid putting it in prompts, logs, screenshots, or article examples.

CrewAI Role Design

A CrewAI implementation should give each role a narrow responsibility. The planner identifies that a page is blocked by a verification challenge. The browser worker owns navigation. The CapSolver tool handler owns the challenge step. The reviewer owns the final decision when the run is uncertain.

crew_state = {
    "task_id": "lead-enrichment-042",
    "allowed_domains": ["example.com"],
    "captcha_attempts": 0,
    "max_captcha_attempts": 1,
    "final_state": "planning",
}

def may_call_capsolver(state, current_url):
    if state["captcha_attempts"] >= state["max_captcha_attempts"]:
        return False
    return any(domain in current_url for domain in state["allowed_domains"])

This small gate is what keeps crewai captcha solver behavior visible. The crew can ask for help only when the page is in scope and the retry budget is still available.

Agent Tool Pattern for Model-Controlled Decisions

Use capsolver-agent when the model should choose when challenge handling is needed. The Agent Tools guide exposes tool definitions with get_all_tools() and routes model tool calls through create_executor().

import json
from openai import OpenAI
from capsolver_agent.schema import create_executor, get_all_tools

client = OpenAI()
executor = create_executor(api_key="YOUR_CAPSOLVER_KEY", default_timeout=120)
tools = [tool.to_openai_function() for tool in get_all_tools()]

messages = [{
    "role": "user",
    "content": "Continue the approved browser task. If a CAPTCHA appears, call the CapSolver tool once and report the outcome."
}]

async def run_one_turn():
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools,
    )

    for call in response.choices[0].message.tool_calls or []:
        args = json.loads(call.function.arguments)
        result = await executor.execute(call.function.name, args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

For crewai captcha solver, bind this tool path to a reviewer policy. The model can request the tool, but your application decides the allowed URL scope, maximum attempts, and whether the result may be used to continue.

Core SDK Pattern for Browser-Controlled Agents

Use capsolver-core when your crewai captcha solver flow already owns a Playwright page. The official Core SDK path is detect, read CAPTCHA info, solve, and fill the token back into the page. The all-in-one browser call is useful when the page structure is dynamic.

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

TARGET_URL = "https://example.com/approved-workflow"

async def run_agent_step():
    async with async_playwright() as pw:
        browser = await pw.chromium.launch()
        page = await browser.new_page()
        await page.goto(TARGET_URL, wait_until="domcontentloaded")

        async with create_capsolver(api_key="YOUR_CAPSOLVER_KEY") as cap:
            captcha_types = await cap.detect(page)
            if not captcha_types:
                return "continue_without_challenge"

            results = await cap.solve_on_page(page)
            solved = [r for r in results if r.solution and not r.error]
            if not solved:
                return "stop_for_review"

        return "resume_original_authorized_task"

asyncio.run(run_agent_step())

The important engineering detail is the return value, not only the token. Your agent should continue only when the original task is still lawful, reasonable, and user-authorized. It should stop when the page asks for private, restricted, sensitive, or unauthorized data.

Redeem Your CapSolver Bonus Code

Boost your automation budget instantly!
Use bonus code CAP26 when topping up your CapSolver account to get an extra 5% bonus on every recharge — with no limits.
Redeem it now in your CapSolver Dashboard

Guardrails That Belong in the Agent Loop

Scope Checks

Before calling any challenge tool, confirm that the user authorized the task, the target is within the approved domain list, and the data being accessed is public or otherwise permitted. A crewai captcha solver workflow should never treat technical capability as permission.

Retry Limits

Use a small retry budget. One browser-state retry and one cooldown retry are usually enough. Repeated challenge events should create a review ticket instead of continuing silently.

Observability

Capture URL, timestamp, challenge type, CapSolver package path, attempt number, result state, and final page state. Do not store unrelated page content, credentials, session secrets, or personal data unless your policy explicitly allows it.

For crewai captcha solver, keep the run lawful and evidence-based: respect HTTP status code behavior, accessibility requirements, privacy risk management, and public data stewardship.

Conclusion

A strong crewai captcha solver article should show real implementation paths, and a strong production workflow should do the same. The practical choice is simple: use capsolver-core for code-owned browser automation, capsolver-agent for tool-calling agents, and capsolver-mcp for MCP-compatible clients. Keep challenge handling bounded, logged, and tied to lawful user-authorized work. When your team is ready to add that recovery layer to an agent workflow, start with CapSolver and the official AI agent docs.

FAQ

Which CapSolver package should an AI agent use first?

Use capsolver-core when your application owns the browser code, capsolver-agent when a model should call a tool, and capsolver-mcp when the AI client should discover tools through MCP.

Should the model decide every CAPTCHA retry?

No. The model can request a tool call, but the application should enforce scope, retry limits, and stop conditions.

Can this workflow be used on private or restricted data?

No. CAPTCHA handling does not grant permission. Use it only for lawful, reasonable, user-authorized workflows that respect site terms and data rights.

What should be logged for review?

Log the source URL, challenge type, tool path, attempt count, result state, and final page state. Keep credentials and unrelated page content out of logs.