How to Add a Bounded CAPTCHA Solver Tool to a VoltAgent Agent

This builder-oriented example turns CAPTCHA recovery into a VoltAgent createTool with explicit authorization, challenge detection, duplicate protection, a five-poll ceiling, and structured human handoff. It is designed for fixture-first evaluation before any live transport is connected.

What developers can build

• A browser agent that pauses on a supported challenge and requests one controlled recovery
• A policy-aware tool that rejects missing authorization and repeated recovery IDs
• An observable workflow that returns either a validated solution or a stop code with handoff: true
• Offline evaluations covering ready, authorization failure, budget exhaustion, duplicate recovery, and the createTool contract

Try the local fixture

npm test\nnpm run smoke

The 5/5 unit tests and smoke test make no live API request and use no real key. When adapting the client, verify task fields against the official createTask documentation and polling behavior against getTaskResult.

Responsible use

Use only on owned systems, explicitly authorized QA targets, or approved public-data workflows. Keep the one-recovery boundary and route exhausted or malformed states to a human. CapSolver overview.