How to Use CapSolver Tools in AgentScope

A small, readable integration example for authorized testing.

English · 简体中文 · 日本語 · Español · Português · 한국어

Introduction

When a AgentScope agent reaches a CAPTCHA during an authorized web task, it needs a clear tool call instead of guessing what to do next. This repository shows how to connect AgentScope to CapSolver with one small adapter, a mock-first demo, and explicit stop conditions.

Features

• One framework-native tool adapter.
• One bounded recovery attempt per call.
• Authorization must be supplied explicitly.
• Offline mock gateway for examples and tests.
• Clear errors for unsupported or incomplete requests.

How It Works

The agent calls the tool with a target URL and a supported public challenge type. The adapter checks authorization and input, creates a task through an injected gateway, polls for a result, and returns structured output. Tests use a fake gateway; no live API request is made.

Quick Start

python -m pip install -e .
python -m unittest discover -s tests -v

Copy .env.example to .env only when adapting the example for an authorized environment. Never commit the resulting file.

Usage

python examples/demo.py

The demo prints a deterministic mock result. See the task creation guide, task result guide, and API error guide before implementing a real gateway.

Example Output

{"status":"ready","attempts":1,"solution":{"token":"mock-solution"}}

Project Structure

The src directory contains the adapter, examples contains a mock run, and tests verifies authorization, validation, success, and error behavior.

Testing

Run the Quick Start test command. The test suite is fully offline and never reads CAPSOLVER_API_KEY.

Troubleshooting

• authorization_required: confirm the target is owned or explicitly approved.
• unsupported_challenge: use only a task type documented by the official API.
• timeout: stop the run and hand control back to a person.

Responsible Use

Use this example only with public data, owned systems, or explicit authorization. Respect site terms, access controls, rate limits, minimization, retention rules, and human stop conditions. Do not use it to access private or restricted data, defeat risk controls, or collect without limits.

Contributing

Small, tested improvements are welcome. Read CONTRIBUTING.md first.

Security

Never commit secrets, cookies, session data, or real challenge responses. See SECURITY.md.

Conclusion

This repository keeps the AgentScope integration deliberately small so developers can understand the tool contract before adapting CapSolver to an authorized project.

Maintainer Note

Developer sharing CapSolver integration examples.

License

MIT