प्रतिनिधि

कैपसॉल्वर की समाधान क्षमता को किसी भी एलएलएम/एजेंट ढांचे में लाएं। capsolver-agent capsolver-core इंजन पर एक पतली परत है: यह कोर के solve / detect / solve_on_page तरीकों को उपकरण के रूप में लपेटता है जिसे LLM कॉल कर सकता है, जिससे “मॉडल निर्णय लेता है, कोर निष्पादित करता है” सीमा स्वाभाविक रूप से अपनी जगह पर आ जाती है।

श्रम का विभाजन: मॉडल नेविगेशन और निर्णय लेने को संभालता है, capsolver-core समाधान को संभालता है, और capsolver-agent बीच में टूल-एडाप्टर परत है - मॉडल “हल” को उसी तरह कहता है जैसे वह “क्लिक” या “टाइप” कहता है, बिना कैप्चा पर क्लिक किए।

1. capsolver-agent capsolver-core से कैसे संबंधित है

आप लगभग कभी भी कोर कॉल कोड सीधे नहीं लिखते हैं। जब एलएलएम किसी टूल को कॉल करने का निर्णय लेता है, तो एजेंट लेयर का निष्पादक आपके लिए संबंधित कोर विधि को कॉल करता है और मॉडल को एक संरचित परिणाम देता है:

LLM (decides)
   │  emits a tool call, e.g. solve_captcha(...)
   ▼
capsolver-agent (schema + executor)   ← tool-adapter layer
   │  executor.execute(...) internally relays to ↓
   ▼
capsolver-core (solve / detect / solve_on_page)
   │
   ▼
CapSolver API

प्रत्येक एजेंट टूल सीधे एक कोर विधि पर मैप करता है - जहां कोर हर परिदृश्य में वास्तविक कार्य करता है:

2. स्थापना

capsolver-agent capsolver-core के शीर्ष पर बनाया गया है (कोर समाधान करता है) और रनटाइम पर इस पर निर्भर करता है। दोनों GitHub पर खुले स्रोत हैं और अभी तक PyPI पर प्रकाशित नहीं हुए हैं, और capsolver-agent नाम से capsolver-core पर निर्भर करता है। पहले कोर स्थापित करें, फिर एजेंट:

# 1) Install the core engine first (agent depends on it)
pip install git+https://github.com/capsolver-ai/capsolver-core.git
 
# 2) Then install agent itself
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

आवश्यकतानुसार अतिरिक्त जोड़ें:

# With LangChain support
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"
# With Playwright (detect / solve_on_page)
pip install "capsolver-agent[browser] @ git+https://github.com/capsolver-ai/capsolver-agent.git"

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

3. उपयोग: वार्तालाप लूप में वायरिंग का समाधान

एकीकरण मॉडल के “वार्तालाप-उपकरण” लूप के अंदर आता है। एक पूरा दौर इस प्रकार चलता है:

1. Hand the tools to the model ───────────────────┐
2. The model answers and decides: do I need a tool here?
   ├─ No  → return the final answer, done         │
   └─ Yes → return a tool_call                    │
3. You execute the call → relay to core → get a result
4. Feed the result back to the model ─────────────┘  back to step 2, next round

व्यवहार में, मॉडल तय करता है कि किस उपकरण का उपयोग करना है या नहीं; आपका काम तीन चरणों में इस लूप में कोर को तार देना है: कोर को कनेक्ट करें → मॉडल को टूल सौंपें → लूप के अंदर मॉडल द्वारा लौटाए गए कॉल को निष्पादित करें, उन्हें एक कार्यशील लूप में स्ट्रिंग करें।

3.1 कोर कनेक्ट करें: एक निष्पादक बनाएं

जो चीज़ वास्तव में हल करती है वह हमेशा capsolver-core का Capsolver इंजन होता है। एजेंट परत इसके चारों ओर केवल ToolExecutor जोड़ती है: आंतरिक रूप से यह Capsolver रखती है, मॉडल के टूल कॉल को इंजन के संबंधित तरीकों तक भेजती है, और रिटर्न को एक संरचित परिणाम में लपेट देती है। नीचे हम पहले दिखाते हैं कि इस रैपर को कैसे इकट्ठा किया जाता है, फिर एक-पंक्ति शॉर्टहैंड।

निष्पादक कोर को कैसे लोड करता है। वर्तनी में, यह दो पंक्तियाँ हैं, जिनमें से पहले पर कोर बनाया गया है:

from capsolver_core import Capsolver               # capsolver-core engine
from capsolver_agent.schema import ToolExecutor
 
cap = Capsolver(api_key="YOUR_CAPSOLVER_KEY")       # the same Capsolver from the "Core SDK" page
executor = ToolExecutor(cap)                        # wrap a "tool call → core method" dispatcher around it

प्रेषण एक निश्चित मानचित्रण है; प्रत्येक टूल कॉल अंततः एक मूल विधि पर आती है:

executor.execute("solve_captcha",  {...})   # → cap.solve(CaptchaInfo(...))
executor.execute("detect_captchas", {...})  # → cap.detect(page)
executor.execute("get_balance",    {})      # → cap.get_balance()

प्रत्येक कॉल पर, निष्पादक टूल तर्कों को कोर अपेक्षाओं के रूप में इकट्ठा करता है, कोर को कॉल करता है, और परिणाम (या त्रुटि) को एक निर्देश में लपेटता है जिसे आप सीधे मॉडल पर फ़ीड कर सकते हैं - सफलता {"success": True, "solution": {...}} है, विफलता {"success": False, "error": "..."} है। इसलिए कोर एसडीके पेज पर आपने जो तरीके और पैरामीटर सीखे हैं, वे यहां अपरिवर्तित लागू होते हैं।

उपयोग. ऊपर की दो पंक्तियों में एक तैयार रैपर है; रोजमर्रा के उपयोग में, बस इसे कॉल करें:

from capsolver_agent.schema import create_executor
 
executor = create_executor(api_key="YOUR_CAPSOLVER_KEY")   # == Capsolver(...) + ToolExecutor(...)

जब आप कोर के व्यवहार को अनुकूलित करना चाहते हैं, तो create_executor() को दिए गए किसी भी अतिरिक्त कीवर्ड तर्क को Capsolver(...) की तरह अग्रेषित किया जाता है - उदाहरण के लिए, create_executor(api_key=..., default_timeout=180)।

3.2 मॉडल को उपकरण सौंपें

get_all_tools() आपको सभी टूल परिभाषाएँ देता है - कोर की क्षमताओं का बाहरी विवरण। उन्हें अपने लक्ष्य ढांचे के प्रारूप में निर्यात करें और उन्हें फ़ंक्शन-कॉलिंग इंटरफ़ेस के रूप में मॉडल में पास करें:

from capsolver_agent.schema import get_all_tools
 
tools = [t.to_openai_function() for t in get_all_tools()]
# to_openai_function() → {"type": "function", "function": {...}}, the format OpenAI's tools= expects
# you can also use t.to_json_schema() → an MCP-style tool description (name + inputSchema)

3.3 मॉडल द्वारा कोर पर रिले करते हुए कॉल निष्पादित करें

जब मॉडल किसी चरण में tool_call लौटाता है, तो उसे 3.1 से निष्पादक को सौंप दें - execute(tool_name, args) कॉल को संबंधित कोर विधि (solve / detect / solve_on_page …) पर भेजता है, एक संरचित परिणाम देता है, और आप उसे मॉडल पर वापस फ़ीड करते हैं:

result = await executor.execute("solve_captcha", {
    "captcha_type": "reCaptchaV2",
    "website_url": "https://example.com",
    "website_key": "6Le-wvkSAAAAAPBMRT...",
})
# result → {"success": True, "solution": {"token": "03AF...", ...}}

3.4 इसे एक पूर्ण लूप में पिरोएं

उपरोक्त तीन चरणों को मॉडल के वार्तालाप लूप में एम्बेड करें, और आपके पास एक न्यूनतम एजेंट है जो कैप्चा को स्वयं हल करता है (उदाहरण के रूप में ओपनएआई फ़ंक्शन कॉलिंग का उपयोग करके):

import asyncio, json
from openai import OpenAI
from capsolver_agent.schema import get_all_tools, create_executor
 
client = OpenAI()                                       # your LLM client
executor = create_executor(api_key="YOUR_CAPSOLVER_KEY") # 3.1 connect core
tools = [t.to_openai_function() for t in get_all_tools()] # 3.2 hand tools to the model
 
async def run(prompt: str) -> str:
    messages = [{"role": "user", "content": prompt}]
    while True:
        resp = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
        msg = resp.choices[0].message
        messages.append(msg)
 
        if not msg.tool_calls:                          # model no longer calls a tool
            return msg.content                          # → final answer, exit the loop
 
        for call in msg.tool_calls:                     # model wants to call a tool
            result = await executor.execute(            # 3.3 execute → relay to core
                call.function.name,
                json.loads(call.function.arguments),
            )
            messages.append({                           # feed the result back, next round
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result),
            })
 
asyncio.run(run("Solve the reCAPTCHA v2 on https://example.com for me; the sitekey is 6Lc..."))

जब आप संपूर्ण लूप बनाने के बजाय किसी टूल को केवल एक बार चलाना चाहते हैं, तो एक ही बार में execute_tool(name, args, api_key=...) को कॉल करें।

4. प्रति फ्रेमवर्क: एक ही लूप, एक अलग शेल

उपरोक्त दो चरण सार्वभौमिक कंकाल हैं। जब आप एक विशिष्ट ढांचे से जुड़ते हैं, तो केवल अंतर यह होता है कि “कॉल ए टूल → फीड द रिजल्ट बैक” लूप को कौन चलाता है, और आप किस कोर की क्षमताओं का उपयोग करते हैं - ज्ञात साइट पैरामीटर टोकन मोड (solve()) से गुजरते हैं, जबकि स्वायत्त रूप से ड्राइविंग करने पर पेज ब्राउज़र मोड (detect() / solve_on_page()) से गुजरता है।

इनमें से, ब्राउज़र का उपयोग वास्तविक दुनिया के स्वचालन के सबसे करीब है: एजेंट अपने आप ब्राउज़ करता है, और जब वह कार्य के बीच में कैप्चा प्राप्त करता है, तो वह समाधान को एक क्रिया के रूप में कहता है - पता लगाना, हल करना और उसी ब्राउज़र सत्र में वापस भरना, फिर परिणाम आने पर मूल प्रवाह को जारी रखना, बिना प्रगति को तोड़े:

Agent browses the page → hits a CAPTCHA → calls the solve action (core: solve_on_page) → gets a token → continues the task

5. उदाहरण चलाना

उपरोक्त तालिका में प्रत्येक परिदृश्य एक चलने योग्य उदाहरण के साथ आता है, सभी एजेंट रिपॉजिटरी में examples/ के अंतर्गत। इसे क्लोन करें, निर्भरताएँ स्थापित करें और चलाएँ।

git clone https://github.com/capsolver-ai/capsolver-agent.git
cd capsolver-agent
uv sync
 
export CAPSOLVER_API_KEY=CAP-XXXXXX
export OPENAI_API_KEY=sk-XXXXXX      # required by the LLM-based examples

प्रत्येक उदाहरण की अतिरिक्त निर्भरताएँ (capsolver-agent / capsolver-core GitHub से इंस्टॉल करें; बाकी नियमित PyPI पैकेज हैं):

# OpenAI Function Calling
pip install openai
# OpenAI Agents SDK
pip install openai-agents
# LangChain
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git" langchain-openai langgraph
# Browser Use
pip install browser-use langchain-openai playwright && playwright install chromium
# Playwright (no LLM)
pip install git+https://github.com/capsolver-ai/capsolver-core.git playwright && playwright install chromium