Skip to content

अपना ब्राउज़र टास्क लिखें: Agent लाइब्रेरी व्यावहारिक गाइड ​

पिछले चार पाठों में आप लगातार Ultrafast को "इस्तेमाल" करते रहे हैं: inspector में निर्णय देखना, flights.py से रिकॉर्डिंग दोबारा चलाना, परफ़ॉर्मेंस पाठ में स्टॉपवॉच तोड़ना। यह पाठ Jev Ultrafast ट्यूटोरियल का "照着跑" (बस चलाते जाओ) से "自己写" (खुद लिखो) तक का मोड़ है——Ultrafast को एक डेमो से बदलकर आपके कोड की एक लाइब्रेरी बनाना: from jev_ultrafast import Agent, इसे एक URL और एक लक्ष्य दें, और यह हर कदम की स्थिति आपको वापस थूक देगा।

इस इस्तेमाल की आधिकारिक पोज़िशन सिर्फ़ एक वाक्य है: एक ही पॉलिसी, URL और लक्ष्य बदल दो, तो यही नया टास्क है (README: The same policy can run a different task)। इस पाठ में आप अपना my_task.py लिखेंगे, रिपॉज़िटरी के साथ आए run.py से बिना कोड लिखे किसी भी वेबपेज पर टास्क चलाएँगे, state के हर फ़ील्ड को समझेंगे, और flights.py के पैटर्न के अनुसार अपने टास्क के लिए अलग वेरिफ़िकेशन लगाएँगे।

पाठ पूरा करने के बाद आप क्या कर सकेंगे ​

  • from jev_ultrafast import Agent से अपना खुद का ब्राउज़र ऑटोमेशन टास्क स्क्रिप्ट लिखना और रिपॉज़िटरी की रूट डायरेक्टरी में uv run --env-file .env python my_task.py से चलाना
  • बताना कि Agent(url, goals, *, record_dir=None, screenshots=False) का हर पैरामीटर क्या काम करता है, और goals में स्ट्रिंग पास करने और लिस्ट पास करने में क्या फ़र्क़ है
  • examples/run.py --url … --goal … से एक लाइन कोड लिखे बिना किसी भी वेबपेज का टास्क चलाना, --goal को बार-बार पास करके क्रमबद्ध लक्ष्यों की लिस्ट बनाना
  • run() के हर कदम पर लौटाए गए state को पढ़ना: history, decisions, text_calls, status, elapsed_ms — हर फ़ील्ड का इस्तेमाल कैसे करें
  • 60 एक्शन / 120 मॉडल कॉल का बजट, blocked के ट्रिगर होने की शर्तें, और यह कि DONE के बाद भी वेरिफ़िकेशन खुद क्यों लिखना पड़ता है — यह सब जानना

आपकी मौजूदा दुविधा ​

  • inspector सिर्फ़ पहले से तय सीनेरियो चला सकता है, टास्क बॉक्स में एक-दो लाइन बदलना ठीक है, लेकिन agent को अपनी स्क्रिप्ट में जोड़ना हो — चलने के बाद ऑटो वेरिफ़िकेशन, trace सेव करना, फ़ेल होने पर अलर्ट — तो समझ नहीं आता कहाँ से शुरू करें
  • चाहते हैं कि ब्राउज़र रोज़ आपके लिए कुछ खोजे या फ़ॉर्म भरे, लेकिन सिलेक्टर लिखने, लोडिंग का इंतज़ार करने और तरह-तरह के कंट्रोल संभालने का ख़याल आते ही मन टूट जाता है
  • agent.py खोलकर कोड कॉपी करना चाहते हैं, लेकिन लूप, निर्णय और स्टेट के ढेर सारे फ़ील्ड में समझ नहीं आता कि कौन-से आपके लिए हैं और कौन-से अंदरूनी इम्प्लीमेंटेशन हैं

यह तरीक़ा कब इस्तेमाल करें ​

जब आपको चाहिए:

  • Ultrafast को अपने कोड में जोड़ना: चलने के बाद नतीजा लेना, trace सेव करना, ऑटो वेरिफ़िकेशन, फ़ेल होने पर अलर्ट
  • एक ही कस्टम ब्राउज़र agent से अलग-अलग साइटों पर अलग-अलग टास्क चलाना, हर साइट के लिए सिलेक्टर स्क्रिप्ट हाथ से लिखना नहीं चाहते
  • हर कदम का डेटा (एक्शन, प्रॉबेबिलिटी, लेटेंसी, टेक्स्ट कॉल) क्रम-क्रम पाना — डिबगिंग या आँकड़ों के लिए

और नहीं चाहते:

  • inspector के पहले से तय सीनेरियो तक सीमित रहकर बटन दबाना
  • हर वेबसाइट के लिए DOM सिलेक्टर मेंटेन करना, जिससे पेज का लेआउट बदलते ही सब एक साथ टूट जाता है
  • मॉडल के खुद DONE कह देने भर से टास्क सफल घोषित करना

🎒 शुरू करने से पहले की तैयारी ​

  • Ultrafast इंस्टॉल और रन पूरा कर लिया है: uv sync से डिपेंडेंसी इंस्टॉल हैं, .env में TYPESAFE_API_KEY भरा जा चुका है (टाइपिंग वाले टास्क के लिए TEXT_MODEL_API_KEY भी चाहिए, विवरण पाठ 6 में)
  • (अनुशंसित) Google Flights व्यावहारिक अभ्यास एक बार चला चुके हों, और देख चुके हों कि verify() स्वतंत्र सत्यापन कैसा दिखता है
  • नेटवर्क से api.typesafe.ai और वह लक्ष्य वेबसाइट जो आप परिचालित करना चाहते हैं, एक्सेस हो सकती हो
  • एक ऐसा वेब कार्य सोच लें जो 5 कदमों के भीतर पूरा हो सके (पहले छोटा, फिर बड़ा; 60 कदम का बजट कदम 4 में समझाया गया है)
  • Python स्क्रिप्ट लिखना आता हो, with का उपयोग किया हो — आज बस इतना ही चाहिए

मूल विचार ​

पहले एक आम भ्रम दूर कर लें: Ultrafast कोई 「एक demo जिसके साथ थोड़ा कोड जुड़ा है」 नहीं है, यह एक import करने योग्य Python पैकेज है। पैकेज के प्रवेश बिंदु पर केवल दो नाम हैं (__init__.py का __all__): Agent और Browser — रोज़मर्रा में आपको केवल Agent चाहिए।

मानसिक मॉडल एक वाक्य में: आप URL और लक्ष्य देते हैं, Agent लूप चलाता है, आप state का उपभोग करते हैं।

आप जो देते हैंAgent जो करता हैआप जो पाते हैं
url: शुरुआती पेजबैकग्राउंड टैब खोलता है, पहली बार अवलोकनrun() कदम-दर-कदम yield होने वाला state
goals: एक वाक्य का लक्ष्य (या सूची)लूप: अवलोकन → एक TypeSafe अनुरोध में दोहरा निर्णय → निष्पादनहर कदम का history / decisions / text_calls
(वैकल्पिक) record_dirstale प्रबंधन, बजट नियंत्रण, blocked निर्धारणअंतिम status: done या blocked

तीन मुख्य समझें:

**1. एक ही रणनीति, URL और लक्ष्य बदलते ही नया कार्य बन जाता है। ** रणनीति में कोई साइट-विशिष्ट स्क्रिप्ट नहीं, कोई प्री-निर्मित फ़ील्ड स्ट्रिंग नहीं (पाठ 3 में मूल शब्द बताए गए थे), इसलिए 「कस्टम कार्य」 का मतलब 「ऑटोमेशन स्क्रिप्ट लिखना」 नहीं है — आप सिलेक्टर नहीं लिखते, केवल लक्ष्य लिखते हैं।

**2. state ही आपकी सब कुछ है। ** आपका कोड जो कर सकता है, वह इस पर निर्भर करता है कि run() आपको state में क्या देता है। पिछले पाठ में खोला गया बिल (17 अनुरोध, 178 ms माध्य विलंबता, 2 बार टेक्स्ट निर्माण) पूरी तरह इन्हीं फ़ील्ड से आया था — यह पाठ आपको इन्हें सीधे पढ़ना सिखाता है।

**3. लूप में बीमा अंतर्निहित है। ** निर्णय के बाद पेज बदल जाए (stale), तो लूप निर्णय को छोड़कर फिर से अवलोकन करता है; एक निर्णय केवल एक बार उपभोग होता है, दोबारा कोशिश से डबल-क्लिक नहीं होता; पहले से निर्मित टेक्स्ट मान केवल तभी पुनः उपयोग होते हैं जब इनपुट पूरी तरह अपरिवर्तित हो। ये सब आपको लिखने की ज़रूरत नहीं।

तीन तरीकों की तुलना, और यही इस पाठ का मार्ग-नक्शा भी है:

inspector (uv run jev)examples/run.pyआपकी अपनी स्क्रिप्ट
कोड लिखेंज़रूरत नहींज़रूरत नहींएक my_task.py
कार्य का स्रोतप्रीसेट परिदृश्य + कार्य बॉक्स--url / --goal पैरामीटरआप कोड में तय करते हैं
क्या मिलता हैआँखों से पैनल देखेंटर्मिनल में प्रगति + अंतिम URLपूरा state, जैसा चाहें प्रोसेस करें
स्वचालित सत्यापननहींनहींआप खुद लिखते हैं (चरण 5)
किसके लिए उपयुक्तनिर्णय समझनाएक कार्य जल्दी आज़मानाअपने सिस्टम में जोड़ना

💡 agent के व्यवहार को बदलना चाहते हैं?

सिद्धांत पाठ में कहा गया था: कस्टम कार्य Agent लाइब्रेरी के स्टैंडर्ड इंटरफ़ेस से चलाएँ, न कि पॉलिसी में लॉजिक ठूँसें। लक्ष्य जितना विशिष्ट लिखेंगे, agent उतना स्थिर चलेगा — यही लक्ष्य वाक्य आपका「प्रोग्रामिंग इंटरफ़ेस」है।

मेरे साथ करें ​

चरण 1: jev_ultrafast Agent से परिचय — कस्टम कार्यों का एकमात्र प्रवेश द्वार ​

क्यों: स्क्रिप्ट लिखने से पहले जान लें कि यह क्लास आपके लिए कौन-कौन से नॉब्स छोड़ती है — कुल चार पैरामीटर, दो मिनट में आप सब पहचान जाएँगे।

सिग्नेचर (agent.py से):

python
Agent(url, goals, *, record_dir=None, screenshots=False)
पैरामीटरप्रकारविवरण
urlstrप्रारंभिक पेज। निर्माण के समय ही एक बैकग्राउंड टैब खुलता है (1120×780 व्यूपोर्ट) और पेज लोड होने तक प्रतीक्षा करता है (अधिकतम 15 सेकंड)
goalsstr या सूचीएक लक्ष्य वाक्य; सूची दें तो क्रम से नई लाइन से जोड़कर एक कार्य पाठ बनता है। खाली लक्ष्य पर सीधे ValueError: Supply a task
record_dirपाथ (वैकल्पिक)रिकॉर्डिंग डायरेक्टरी: सेट करने पर हर चरण में अपने-आप एक jpg सहेजी जाती है (पहली स्क्रीन 000000.jpg, उसके बाद संचित मिलीसेकंड के नाम पर)
screenshotsbool (वैकल्पिक)अवलोकन के समय स्क्रीनशॉट लेना है या नहीं, डिफ़ॉल्ट False — डिफ़ॉल्ट लूप स्क्रीनशॉट नहीं लेता (README में साफ़ कहा गया है); record_dir सेट करने पर यह अपने आप साथ चला जाता है

उपयोग के तीन मुख्य बिंदु:

  • ** with** का उपयोग करें: Agent एक कॉन्टेक्स्ट मैनेजर है, with ब्लॉक समाप्त होने पर टैब अपने आप बंद हो जाता है; निर्माण विफल होने पर (जैसे पेज न खुलना) भी पहले ब्राउज़र बंद होता है और फिर एरर थ्रो होता है
  • निर्माण के साथ ही अवलोकन: Agent(...) निष्पादित होते ही ब्राउज़र खुल चुका होता है और पहला अवलोकन पूरा हो चुका होता है, यह आपके run() कॉल करने का इंतज़ार नहीं करता
  • एक बार का: done या blocked तक पहुँचने के बाद यह Agent समाप्त हो जाता है, इसे दोबारा नहीं चलाया जा सकता (पिटफॉल अनुस्मारक बिंदु 4)

आपको यह दिखना चाहिए: रिपॉज़िटरी की रूट डायरेक्टरी में एंट्री पॉइंट की पुष्टि करें (uv sync पहले ही पैकेज को एनवायरनमेंट में डाल चुका है):

bash
uv run python -c "from jev_ultrafast import Agent; print(Agent)"
text
<class 'jev_ultrafast.agent.Agent'>
  • चार पैरामीटरों में से वे दो बता सकते हैं जो आज उपयोग होंगे: url और goals

चरण 2: अपनी पहली कस्टम ब्राउज़र टास्क स्क्रिप्ट लिखें ​

क्यों: README का "Use the library" अनुभाग पहले कुछ स्केलेटन लाइनें देता है (आधिकारिक स्केलेटन में भरा गया लक्ष्य ठीक पाठ 3 का Flights लक्ष्य है), और तुरंत बाद में कहता है The same policy can run a different task, साथ ही Wikipedia का कमांड-लाइन उदाहरण देता है — पहले आधिकारिक उदाहरण को स्क्रिप्ट में लिखकर चलाएँ, फिर URL और लक्ष्य को अपने हिसाब से बदलें।

रिपॉज़िटरी की रूट डायरेक्टरी में my_task.py बनाएँ (examples/ के समान स्तर पर; रूट में इसलिए क्योंकि uv run को रिपॉज़िटरी की रूट डायरेक्टरी से निष्पादित करना होता है):

python
from jev_ultrafast import Agent

URL = "https://en.wikipedia.org/wiki/Main_Page"
GOAL = "Find and open the Wikipedia article about Gödel’s incompleteness theorems."

with Agent(URL, GOAL) as agent:
    for state in agent.run():
        print(state["elapsed_ms"], state["status"])
print(state["page"]["url"])

यही आधिकारिक README का Wikipedia उदाहरण स्क्रिप्ट में रूपांतरित है (run.py में वही एक-लाइन लक्ष्य चलता है, अगले चरण में देखें)। चलाएँ:

bash
uv run --env-file .env python my_task.py

ध्यान दें: यह टास्क सर्च बॉक्स में टाइप करता है, इसलिए .env में TEXT_MODEL_API_KEY का भी मान होना चाहिए (कॉन्फ़िगरेशन का विवरण चरण 6 में)।

आपको यह दिखना चाहिए: Chrome में एक बैकग्राउंड टैब खुलकर विकिपीडिया का मुख्य पेज दिखाई देता है, टर्मिनल लाइन-दर-लाइन "संचित मिलीसेकंड + स्थिति" प्रिंट करता है, ज़्यादातर लाइनें ready होती हैं, आख़िरी लाइन की स्थिति done है (अगर blocked हो, तो चरण 4 के बजट और अमान्य एक्शन निर्धारण में कारण खोजें, या अगले पाठ का डिबगिंग देखें), फिर ब्राउज़र का अंतिम URL प्रिंट होता है — आधिकारिक स्मोक टेस्ट में यही पॉलिसी इस एंट्री को खोलने में 2.798 सेकंड लेती है (performance.md का Other checks):

text
<मिलीसेकंड> ready
<मिलीसेकंड> ready
……
<मिलीसेकंड> done
<अंतिम URL — गोडेल की अपूर्णता प्रमेय का एंट्री पेज>

(मिलीसेकंड संख्या और URL का सटीक एन्कोडिंग आपके इस रन पर निर्भर करता है)

  • my_task.py पूरा चलने के बाद, आख़िरी लाइन में प्रिंट हुआ URL गोडेल की अपूर्णता प्रमेय का एंट्री पेज है

चरण 3: examples/run.py से बिना कोड लिखे कोई भी टास्क चलाएँ ​

क्यों: कोई टास्क बस जल्दी आज़माना हो, तो फ़ाइल बनाने की भी ज़रूरत नहीं — रिपॉज़िटरी में शामिल सामान्य runner URL और लक्ष्य दोनों को कमांड-लाइन पैरामीटर बना देता है।

README की मूल कमांड (शब्दशः):

bash
uv run --env-file .env python examples/run.py \
  --url https://en.wikipedia.org/wiki/Main_Page \
  --goal 'Find and open the Wikipedia article about Gödel’s incompleteness theorems.'

दो पैरामीटर (run.py के सोर्स कोड से):

पैरामीटरविवरण
--urlअनिवार्य, शुरुआती पेज
--goalअनिवार्य, बार-बार दिया जा सकता है (argparse का action="append"), क्रम में एक क्रमबद्ध लक्ष्य सूची बनाता है

run.py का लूप बॉडी में सिर्फ दो काम हैं: हर कदम पर प्रिंट करें「दाएं-संरेखित मिलीसेकंड + निष्पादित एक्शन की संख्या + स्थिति」, और पूरा होने पर ब्राउज़र का वर्तमान URL प्रिंट करें:

text
<मिलीसेकंड> ms  <एक्शन संख्या> actions  <स्थिति>
……
<अंतिम URL>

आपको यह दिखना चाहिए: चरण 2 जैसा ही वही कार्य, वही परिणाम——यही「एक ही रणनीति, URL और लक्ष्य बदलने पर ही नया कार्य」का सबसे छोटा प्रमाण है। कोई भी वेबसाइट चलेगी: --url को अपने इस्तेमाल किए जाने वाले सर्च पेज या डॉक्युमेंटेशन साइट से बदलें, और --goal में एक ठोस लक्ष्य लिखें (अच्छा लक्ष्य कैसे लिखें, इसके लिए गलतियों की चेतावनी का 2 नंबर देखें)।

💡 लक्ष्य कई बार देने पर क्या होगा?

--goal कई बार देने पर, Agent कई लक्ष्यों को क्रम से नई लाइन से जोड़कर एक कार्य पाठ बनाता है (agent.py की लाइन 14)——उनका मूल्यांकन एक समग्र कार्य के रूप में एक साथ होता है, एक पूरा होने पर अपने आप अगली नहीं चलती।

  • अपने --url और --goal से एक बार run.py चलाएं, और अंतिम लाइन का URL अपेक्षा के अनुरूप होना चाहिए

चरण 4: run() से निकले state को समझें——कस्टम कार्य का डैशबोर्ड ​

क्यों: पिछले पाठ का बिल निकालना इन्हीं फ़ील्ड्स की मदद से संभव हुआ; आपके अपने कार्य में यह तय करने के लिए कि「कहाँ तक पहुँचे, कितना खर्च हुआ, क्या किया」भी सब यहीं है। run() एक जनरेटर है, हर कदम चलाने पर एक state स्नैपशॉट yield करता है——done / blocked वाला कदम भी yield होने के बाद ही समाप्त होता है।

state के मुख्य फ़ील्ड (agent.py के self.state और snapshot() से):

फ़ील्डसामग्रीआप इससे क्या कर सकते हैं
statusready / predicted / done / blockedलूप समाप्ति का निर्धारण; blocked होने पर history में कारण खोजें
elapsed_msपहली प्रेडिक्शन से जमा मिलीसेकंडटाइमिंग, परफ़ॉर्मेंस आँकड़े
historyनिष्पादित क्रियाओं की सूचीप्रत्येक में action (एलिमेंट टैग), kind, choice, probability, confidence, latency_ms, text, operation, target, page_changed, url, usage, executed_ms आदि शामिल हैं
decisionsप्रत्येक प्रेडिक्शन का रिकॉर्ड (fingerprint, elapsed_ms, request, raw_answers सहित)रिव्यू करें कि मॉडल ने हर राउंड में क्या देखा, क्या चुना
text_callsटेक्स्ट helper कॉल रिकॉर्ड (model, latency_ms, usage, field, value)छोटे LLM के कॉल की संख्या, विलंबता और जेनरेट किए गए मानों का आँकड़ा
pageसबसे हाल का पेज अवलोकन: url, title, text, actions, fingerprintचरण 5 का सत्यापन इसी को पढ़ता है
goalसंयोजित कार्य पाठसत्यापित करें कि agent को कौन सा लक्ष्य मिला
elementsवर्तमान क्रमांकित एलिमेंट तालिका (snapshot() अतिरिक्त)देखें पेज को agent की दृष्टि से

(इसके अतिरिक्त plan / plan_index / decision / started_at / record जैसे आंतरिक फ़ील्ड हैं; browser ऑब्जेक्ट स्नैपशॉट में दिखाई नहीं देता।)

दो बजट और एक ऑटो-ब्रेक याद रखना है (सभी agent.py से, MAX_STEPS = 60):

  • क्रिया बजट: 60 निष्पादित क्रियाएँ, सीमा पार होने पर स्थिति blocked सेट होती है और ValueError: Stopped at the 60-action demo budget थ्रो होता है
  • मॉडल कॉल बजट: 120 प्रेडिक्शन (MAX_STEPS * 2), सीमा पार होने पर ValueError: Reached the demo's model-call budget थ्रो होता है
  • लगातार अमान्य क्रियाएँ: पिछले 3 क्रिया-पृष्ठों में कोई बदलाव नहीं हुआ और वे सभी wait प्रकार के नहीं थे, तो स्थिति अपने आप blocked हो जाती है

लूप में एक उपयोगी प्रिंट जोड़ें (flights.py जैसा ही पैटर्न):

python
with Agent(URL, GOAL) as agent:
    for state in agent.run():
        last = state["history"][-1] if state["history"] else {}
        print(state["elapsed_ms"], state["status"], last.get("action", ""))

आपको यह दिखना चाहिए: हर पंक्ति में एक अतिरिक्त 「अभी-अभी निष्पादित तत्व का लेबल」 (जैसे सर्च बॉक्स, कोई सुझाव, कोई लिंक) दिखेगा, जो केवल स्थिति देखने से कहीं अधिक सहज बोध देता है——यही inspector के Decision trail का डेटा संस्करण है।

  • history के कम से कम 3 फ़ील्ड के अर्थ बता सकते हैं
  • जानते हैं कि आपका कार्य अधिकतम कितने चरण तक चल सकता है (60 क्रियाएँ / 120 मॉडल कॉल)

चरण 5: अपने ब्राउज़र कार्य के लिए स्वतंत्र सत्यापन कॉन्फ़िगर करें——Jev Ultrafast ट्यूटोरियल का सख़्त नियम ​

क्यों: README का Evidence and limits सीधे-सीधे कहता है: A DONE choice still requires independent outcome verification। आधिकारिक उदाहरण में verify() मदद करता है, लेकिन आपके अपने कार्य में नहीं——यह चरण नहीं छोड़ा जा सकता। सत्यापन परिणाम पृष्ठ को पढ़ता है, मॉडल के उत्तर को नहीं।

आदर्श उदाहरण है पाठ 3 में तोड़ा गया flights.py का verify(): इसने page["url"], फ़ील्ड मानों और पृष्ठ पाठ के साथ 7 जाँचें कीं, और कोई भी असफल होने पर SystemExit के साथ गैर-शून्य निकास होता है। Wikipedia कार्य के लिए इसी तरह का एक बनाएँ:

python
def verify(page):
    """独立检查结果页面,不读模型的 DONE 回答。"""
    ok_url = page["url"].startswith("https://en.wikipedia.org/wiki/")
    ok_title = "incompleteness theorems" in page["title"].lower()
    return {"passed": ok_url and ok_title, "url": page["url"], "title": page["title"]}

स्क्रिप्ट में जोड़ें (चलने के तुरंत बाद सत्यापन, असफल होने पर गैर-शून्य निकास——flights.py जैसा ही अंत):

python
with Agent(URL, GOAL) as agent:
    for state in agent.run():
        pass  # 想看进度,照第 4 步打印

    result = verify(state["page"])
    print(result)

if not result["passed"]:
    raise SystemExit("Final page did not satisfy the checks")

अभिकथन (assertion) कैसे लिखें, यह आपके कार्य पर निर्भर करता है; तीनों रास्ते ठीक हैं:

सत्यापन की वस्तुstate में मौजूदउदाहरण
सही पृष्ठ पर पहुँचाpage["url"]URL प्रीफ़िक्स / पाथ अभिकथन (flights.py का search_page hostname और पाथ जाँचता है)
पृष्ठ सामग्री सहीpage["title"], page["text"]शीर्षक या मुख्य पाठ में अपेक्षित सामग्री शामिल हो
नियंत्रण का मान सहीpage["actions"]तत्व लेबल से मान लेकर अभिकथन (flights.py का origin Where from? का मान जाँचता है)

आपको यह दिखना चाहिए: चलने के बाद टर्मिनल में एक अतिरिक्त डिक्शनरी प्रिंट होगी; कार्य तभी सफल माना जाएगा जब passed का मान true हो। जानबूझकर अभिकथन गलत लिखकर एक बार आज़माएँ——स्क्रिप्ट गैर-शून्य कोड से बाहर निकलनी चाहिए, यानी सत्यापन सचमुच नियंत्रण कर रहा है।

  • अपने कार्य में verify जुड़ गया, और यह state["page"] को पढ़ता है, मॉडल के उत्तर को नहीं

चरण 6: कार्य में टाइपिंग है? टेक्स्ट helper को DeepSeek या GLM पर कॉन्फ़िगर करें ​

क्यों: जब भी कार्य में इनपुट बॉक्स हो (चरण 2 का सर्च उदाहरण है), TYPE_TEXT का स्ट्रिंग एक OpenAI-संगत छोटे LLM से बनता है—नमूना कॉन्फ़िगरेशन OpenRouter के Mercury का उपयोग करता है; README साफ़ कहता है कि Gemini, GLM, DeepSeek सभी इस helper के साथ काम कर सकते हैं। .env का पूरा लेखआउटचरण 2 पाठ के तरीके A/B/C में पूरी तरह बताया गया है, यहाँ केवल कार्य-दृष्टिकोण से तीन तथ्य जोड़े जाते हैं।

तथ्य 1: Key गायब होने पर शुरुआत में नहीं, टाइप करते समय त्रुटि आती है। TEXT_MODEL_API_KEY की जाँच केवल तब होती है जब ऑपरेशन TYPE_TEXT हो, त्रुटि का मूल पाठ:

text
ValueError: TYPE_TEXT needs TEXT_MODEL_API_KEY; no text is hardcoded or guessed by the executor.

तथ्य 2: बिना कॉन्फ़िगरेशन के कोड का डिफ़ॉल्ट ही DeepSeek है। अगर TEXT_MODEL_BASE_URL / TEXT_MODEL सेट न हों, तो डिफ़ॉल्ट मान https://api.deepseek.com/v1 + deepseek-chat हैं (model.py की पंक्ति 164–165)—इसलिए "DeepSeek पर स्विच करें" का सबसे आसान तरीका है .env में केवल एक पंक्ति भरना:

bash
TEXT_MODEL_API_KEY=<你的 DeepSeek Key>

(अगर .env.example से कॉपी किया है, तो TEXT_MODEL_BASE_URL और TEXT_MODEL दोनों पंक्तियाँ हटानी होंगी—खाली स्ट्रिंग छोड़ना भी "सेट" ही माना जाता है, डिफ़ॉल्ट पर वापस नहीं जाएगा। GLM जैसे अन्य OpenAI-संगत एंडपॉइंट पर जाने के लिए संगत मॉडल नाम, एंडपॉइंट और reasoning सेटिंग कॉन्फ़िगर करनी होंगी, README का मूल कथन: configure the appropriate model, endpoint, and reasoning setting।)

तथ्य 3: helper का आउटपुट सख्ती से सत्यापित होता है, अयोग्य होने पर टाइप नहीं होता। इसे केवल एक की वाला JSON ऑब्जेक्ट {"text": "…"} लौटाना होगा: गैर-रिक्त स्ट्रिंग, अधिकतम 2000 अक्षर; मान गायब होने पर निर्देशानुसार {"text": null} लौटाना होगा—null भी टाइप नहीं होगा, और यह त्रुटि फेंकी जाएगी:

text
ValueError: Text helper returned no valid field value; nothing typed.

आपको यह दिखना चाहिए: Key सेट करने के बाद चरण 2 दोबारा चलाएँ, सर्च बॉक्स में मॉडल-निर्मित सर्च शब्द दिखेगा और सुझाव चुना जाएगा—state["text_calls"] में इस कॉल का मॉडल नाम, विलंबता और निर्मित मान दिखेंगे।

  • .env में TEXT_MODEL_API_KEY का मान है (DeepSeek / OpenRouter / GLM में से कोई एक)

चेकपॉइंट ✅ ​

  • my_task.py रिपॉज़िटरी की मूल डायरेक्टरी में uv run --env-file .env python my_task.py से सफलतापूर्वक चलता है, टर्मिनल मिलीसेकंड और स्थिति पंक्ति-दर-पंक्ति प्रिंट करता है
  • Agent(url, goals, *, record_dir=None, screenshots=False) के चार पैरामीटरों के उपयोग बता सकते हैं
  • examples/run.py अपने --url और --goal से पूरा चला सकते हैं, अंतिम URL अपेक्षा के अनुरूप है
  • बता सकते हैं कि state में history / decisions / text_calls / status / elapsed_ms प्रत्येक क्या हैं
  • अपने कार्य के लिए स्वतंत्र सत्यापन कॉन्फ़िगर किया गया है, passed true होने पर ही सफल माना जाता है; 60 क्रियाओं / 120 मॉडल कॉल का बजट पता है

आम गलतियों की चेतावनी ​

❌ --env-file .env के बिना ही स्क्रिप्ट चलाना ​

लक्षण: uv run python my_task.py शुरू होते ही KeyError: 'TYPESAFE_API_KEY' थ्रो करता है।

कारण: आपके खुद के लिखे स्क्रिप्ट (run.py और flights.py की तरह) स्वयं .env नहीं पढ़ते—केवल inspector (demo.py) शुरू होने पर पढ़ता है। पर्यावरण चर पूरी तरह uv run --env-file .env से इंजेक्ट होते हैं, और model.py os.environ["TYPESAFE_API_KEY"] से सीधे मान लेता है, जो गायब हो तो KeyError होता है।

सही तरीका: कमांड में --env-file .env को शब्दशः शामिल करें, और रिपॉज़िटरी की रूट डायरेक्टरी में निष्पादित करें (पाठ 3 की आम गलतियों की चेतावनी में पूरा विश्लेषण है)।

❌ लक्ष्य बहुत अस्पष्ट लिखा गया, agent समय से पहले DONE घोषित कर देता है ​

लक्षण: स्थिति done हो जाती है, लेकिन पेज वह नहीं है जो आप चाहते थे—जैसे केवल होमपेज का कोई «प्रासंगिक दिखने वाला» लिंक खोल दिया।

कारण: मॉडल निर्देश मांगते हैं कि DONE के लिए «सभी आवश्यकताएँ पूरी होने का दृश्य साक्ष्य» (DONE requires visible evidence that ALL requirements are satisfied) चाहिए, लेकिन निर्णय का आधार केवल आपका वह लक्ष्य वाक्य है। लक्ष्य में पूर्णता का मानक स्पष्ट न लिखा तो agent अपनी समझ से काम पूरा कर देता है।

सही तरीका: पूर्णता का मानक लक्ष्य में लिखें—flights का लक्ष्य ही नमूना है: Stop when matching flight options are visible. Do not select or book a flight. (मिलते-जुलते परिणाम दिखते ही रुकें; कोई उड़ान चुनें या बुक न करें)। एक अच्छा लक्ष्य = कार्य + रुकने की शर्त + सीमा। साथ ही चरण 5 के स्वतंत्र सत्यापन से बैकअप पाएं।

❌ कार्य बहुत बड़ा, चलते-चलते बजट त्रुटि थ्रो होती है ​

लक्षण: टर्मिनल ValueError: Stopped at the 60-action demo budget (या Reached the demo's model-call budget) थ्रो करता है, स्थिति blocked।

कारण: Agent के पास दो कठोर बजट हैं: 60 निष्पादित क्रियाएँ, 120 मॉडल कॉल (MAX_STEPS * 2); इसके अलावा हाल की 3 क्रियाओं में पेज न बदले तो भी स्वतः blocked हो जाता है। कार्य के चरण बहुत अधिक हों, या पेज देर से प्रतिक्रिया दे, तो सीमा टकरा जाती है।

सही तरीका: बड़े कार्य को छोटा तोड़ें—एक बार में Agent एक ही ऐसा लक्ष्य चलाए जो «5 चरणों में पूरा हो सके»। वाकई अधिक चरण चाहिए तो कई Agent जोड़ें (हर with ब्लॉक में एक, अगले का url पिछले के state["page"]["url"] से आगे बढ़े), या सीधे प्रारंभिक URL को मध्यवर्ती पेज पर इंगित करें।

❌ चल चुके Agent को आगे जारी रखना ​

लक्षण: लूप समाप्त होने के बाद एक बार और agent.run() चलाना चाहें, या उसी agent को दूसरा लक्ष्य दें, तो ValueError: This run has stopped. Start a fresh demo. उठता है।

कारण: status done या blocked होने के बाद, Agent का prediction प्रवेशद्वार बंद हो जाता है (agent.py की पंक्ति 73–74) — एक निर्माण एक ही कार्य है।

सही तरीका: नए कार्य के लिए नया with Agent(...) खोलें; लगातार कार्य चाहिए तो लूप लिखें, हर चरण में एक Agent। टैब with ब्लॉक के साथ अपने आप बंद हो जाते हैं, जमा होते नहीं जाते।

उन्नत तकनीकें (वैकल्पिक) ​

एक बार रिकॉर्ड करके रिप्ले करें। Agent(URL, GOAL, record_dir="artifacts/mytask") हर कदम को jpg में सहेजता है (पहली स्क्रीन 000000.jpg, उसके बाद संचित मिलीसेकंड के छह-अंकीय नाम से) — चलने के बाद इमेज व्यूअर से तेज़ी से पलटें, trace पढ़ने से ज़्यादा सहज। record_dir सेट करने पर स्क्रीनशॉट अपने आप चालू हो जाते हैं, screenshots=True अलग से पास करने की ज़रूरत नहीं।

विश्लेषण के लिए trace सहेजें। flights.py के समापन पैटर्न की तरह स्नैपशॉट डिस्क पर लिखें:

python
import json
from pathlib import Path

# with 块内、run() 结束后:
state = agent.snapshot()
folder = Path("artifacts/mytask")
folder.mkdir(parents=True, exist_ok=True)
(folder / "state.json").write_text(json.dumps(state, indent=2))

state.json में पूरा history / decisions / text_calls होता है — पिछले पाठ का बिल इसी तरह के डेटा से निकला था। artifacts/ रिपॉज़िटरी की .gitignore में है, गलती से कमिट नहीं होगा।

केवल स्क्रीनशॉट, डिस्क पर नहीं। state में base64 स्क्रीनशॉट (page["screenshot"]) चाहिए ताकि खुद प्रोसेस कर सकें, तो screenshots=True पास करना काफ़ी है, record_dir सेट न करें।

ब्राउज़र स्थानीय रूप से मेंटेन नहीं करना चाहते? README के शीर्ष पर एक ज़रूरी नोट है: Browser Use Cloud द्वारा होस्ट किया गया BU Ultrafast लाइव हो चुका है (क्लाउड सेवा में model: "bu-ultrafast" सेट करें), ओपन-सोर्स संस्करण स्थानीय रूप से चलने वाला संदर्भ कार्यान्वयन है — दोनों एक ही चीज़ नहीं हैं, इस पृष्ठ के jev_ultrafast.Agent के उपयोग को सीधे क्लाउड सेवा पर न लगाएँ। विवरण के लिए देखें सिद्धांत पाठ।

पाठ का सारांश ​

✅ jev_ultrafast एक लाइब्रेरी है: प्रवेशद्वार केवल Agent (और Browser) है, Agent(url, goals, *, record_dir=None, screenshots=False) एक निर्माण एक ही कार्य है, with से समापन करें।

✅ वही रणनीति URL और लक्ष्य बदलने पर नया कार्य बन जाती है: आप सिलेक्टर नहीं लिखते, केवल लक्ष्य लिखते हैं — एक अच्छा लक्ष्य = कार्य + रुकने की शर्त + सीमा।

✅ run() कदम-दर-कदम state yield करता है: history (क्रियाएँ), decisions (पूर्वानुमान), text_calls (टेक्स्ट निर्माण), status, elapsed_ms — पिछले पाठ का बिल इन्हीं फ़ील्ड से आया था।

✅ बजट और बीमा: 60 क्रियाएँ / 120 बार मॉडल कॉल, लगातार 3 बार कोई बदलाव न होने पर अपने आप blocked; stale पर अपने आप पुनः अवलोकन, निर्णय केवल एक बार उपभोग — ये सब आपको लिखने की ज़रूरत नहीं।

✅ Jev Ultrafast ट्यूटोरियल का सख़्त नियम: DONE मान्य नहीं — flights.py के verify() पैटर्न की तरह अपने कार्य के लिए स्वतंत्र सत्यापन रखें, परिणाम पृष्ठ पढ़ें, मॉडल का उत्तर नहीं।

मुख्य पैरामीटर और फ़ील्ड की समीक्षा:

पैरामीटर / फ़ील्डअनुशंसित मानविवरण
Agent(url, goals)आवश्यकurl शुरुआती पेज; goals एक-पंक्ति लक्ष्य या सूची (सूची क्रम में नई पंक्तियों पर जोड़ी जाती है)
record_dirप्लेबैक चाहिए हो तो सेट करेंहर स्टेप पर jpg सेव होता है, स्क्रीनशॉट अपने आप चालू हो जाते हैं
screenshotsडिफ़ॉल्ट Falseडिफ़ॉल्ट लूप में स्क्रीनशॉट नहीं लिए जाते
रन कमांडuv run --env-file .env python my_task.pyरिपॉज़िटरी की रूट डायरेक्टरी में निष्पादित करें, --env-file छोड़ा नहीं जा सकता
--url / --goalrun.py आवश्यक--goal बार-बार पास किया जा सकता है, जिससे क्रमबद्ध लक्ष्य सूची बनती है
TEXT_MODEL_API_KEYटाइपिंग हो तो कॉन्फ़िगर करना ज़रूरी हैगायब होने पर TYPE_TEXT वाले स्टेप पर ही एरर आता है; एंडपॉइंट/मॉडल नाम न सेट करने पर कोड डिफ़ॉल्ट रूप से DeepSeek उपयोग करता है
सत्यापनहर टास्क में होना चाहिएपढ़ें state["page"], passed true होने पर ही सफल माना जाता है

अगले पाठ का पूर्वावलोकन ​

अपने टास्क चलाने के बाद, कनेक्ट न होना, क्लिक न चलना, या भटक जाना जैसी समस्याएँ आना स्वाभाविक है। अगला पाठ Ultrafast ट्रबलशूटिंग: कनेक्ट न होने, क्लिक न चलने, भटक जाने पर क्या करें इन सबको एक साथ संभालता है। आप सीखेंगे:

  • Chrome कनेक्ट न होने पर uv run browser-harness --doctor का उपयोग कैसे करें
  • 常见 एरर स्ट्रिंग्स की तुलना: TEXT_MODEL एरर, Model provider returned HTTP … प्रत्येक का क्या अर्थ है
  • इस MVP में कौन-सी पेज क्षमताएँ समर्थित नहीं हैं (shadow DOM, canvas, अपलोड, नया tab खुलना……), भटकने पर पहले समर्थन सूची से मिलान करें
  • blocked के कुछ परिदृश्यों की जाँच कैसे करें: लगातार अमान्य एक्शन, बजट सीमा पार होना

परिशिष्ट: सोर्स कोड संदर्भ ​

पर क्लिक करके विस्तारित करें और सोर्स कोड स्थान देखें

अपडेट समय: 2026-11-04 (रिपॉज़िटरी github.com/browser-use/jev-ultrafast, स्थानीय सूचना स्रोत sources/jev/repo-ultrafast/)

फ़ीचरफ़ाइल पथमुख्य स्थान
लाइब्रेरी प्रवेश बिंदु (केवल Agent, Browser एक्सपोर्ट करता है)jev_ultrafast/init.pyL1–6 __all__ = ["Agent", "Browser"]
Agent सिग्नेचर और कंस्ट्रक्टरjev_ultrafast/agent.pyL12–26 Agent(url, goals, *, record_dir=None, screenshots=False); goals स्ट्रिंग/लिस्ट को नई लाइन से जोड़ा जाता है; खाली लक्ष्य Supply a task; कंस्ट्रक्शन पर ही ब्राउज़र खुलकर अवलोकन करता है, विफलता पर पहले बंद करें फिर throw करें
state के सभी फ़ील्डjev_ultrafast/agent.pyL27–41 goal / page / decision / history / status / plan / plan_index / decisions / text_calls / elapsed_ms / started_at / record
snapshot() (स्नैपशट में browser हटाकर elements जोड़े जाते हैं)jev_ultrafast/agent.pyL46–50
run() (done/blocked तक yield करता है)jev_ultrafast/agent.pyL163–165
बजट और blockedjev_ultrafast/agent.pyL75–76 मॉडल कॉल बजट MAX_STEPS * 2; L102–104 60 एक्शन बजट पर blocked सेट; L153–157 लगातार 3 बार कोई बदलाव न होने पर और wait न होने पर blocked सेट
निर्णय केवल एक बार उपयोग होता है / stale होने पर स्वतः पुनः अवलोकनjev_ultrafast/agent.pyL55–64 tick StalePage पकड़कर पुनः अवलोकन करता है; L90–91 निर्णय को पहले खाली करके फिर निष्पादित किया जाता है
history / text_calls एंट्री फ़ील्डjev_ultrafast/agent.pyL115 text_calls (model / latency_ms / usage / field / value); L121–141 history (step / action / kind / choice / probability / confidence / latency_ms / text / text_helper / text_latency_ms / operation / target / page_changed / url / usage / executed_ms / elapsed_ms)
समाप्त Agent का पुनः उपयोग नहीं किया जा सकताjev_ultrafast/agent.pyL73–74 This run has stopped. Start a fresh demo.
कॉन्टेक्स्ट मैनेजरjev_ultrafast/agent.pyL167–174 close() / __enter__ / __exit__
सामान्य runnerexamples/run.pyL7–10 --url अनिवार्य, --goal दोहराया जा सकता है (action="append", help: Repeat for an ordered list of goals); L12–15 प्रिंट फ़ॉर्मैट और अंतिम URL
लाइब्रेरी उपयोग का कंकाल और रन कमांडREADME.md「Use the library」: uv run --env-file .env python your_script.py; Wikipedia कमांड-लाइन उदाहरण; The same policy can run a different task
टेक्स्ट helper कॉन्फ़िगरेशन और सत्यापनjev_ultrafast/model.pyL160–168 TEXT_MODEL_API_KEY आवश्यक (त्रुटि का मूल पाठ), DeepSeek का डिफ़ॉल्ट एंडपॉइंट और मॉडल, reasoning की तीन शाखाएँ; L187–193 आउटपुट अवश्य एकल-की {"text": …}, गैर-रिक्त, ≤2000 वर्ण होना चाहिए, अन्यथा टाइप नहीं किया जाता
टेक्स्ट helper निर्देशjev_ultrafast/questions.pyTEXT_VALUE: मान अनुपस्थित होने पर {"text": null} लौटाता है, व्यक्तिगत जानकारी का आविष्कार नहीं करता; MAX_STEPS = 60
verify मोड का नमूनाexamples/flights.pyL18–38 verify() 7 मदों की स्वतंत्र जाँच; L63–64 सत्यापन असफल होने पर SystemExit
Wikipedia स्मोक डेटाdocs/performance.mdOther checks: उसी नीति से 2.798 s में वह प्रविष्टि खुलती है; स्थानीय होटल कार्य 1.896 s
क्लाउड सेवा और ओपन-सोर्स संस्करण का संबंधREADME.mdशीर्ष पर IMPORTANT: BU Ultrafast (model: "bu-ultrafast") Browser Use Cloud का होस्टेड संस्करण है; .env छह चर देखें .env.example
पेज ऑब्ज़र्व फ़ील्डjev_ultrafast/browser.pyL115–117 fingerprint की गणना url/text/actions/scroll से की जाती है; L188–193 ऑब्ज़र्व info + fingerprint लौटाता है (+screenshot वैकल्पिक); model.py L110 page का url/title/text लेता है
inspector ही खुद .env पढ़ता हैjev_ultrafast/demo.pyL23–29 load_environment() (cwd का .env), L132 स्टार्टअप पर कॉल होता है
trace git में नहीं जाता.gitignore.env, .venv/, artifacts/ तीनों इग्नोर किए जाते हैं
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.