अपना ब्राउज़र टास्क लिखें: 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_dir | stale प्रबंधन, बजट नियंत्रण, 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 से):
Agent(url, goals, *, record_dir=None, screenshots=False)| पैरामीटर | प्रकार | विवरण |
|---|---|---|
url | str | प्रारंभिक पेज। निर्माण के समय ही एक बैकग्राउंड टैब खुलता है (1120×780 व्यूपोर्ट) और पेज लोड होने तक प्रतीक्षा करता है (अधिकतम 15 सेकंड) |
goals | str या सूची | एक लक्ष्य वाक्य; सूची दें तो क्रम से नई लाइन से जोड़कर एक कार्य पाठ बनता है। खाली लक्ष्य पर सीधे ValueError: Supply a task |
record_dir | पाथ (वैकल्पिक) | रिकॉर्डिंग डायरेक्टरी: सेट करने पर हर चरण में अपने-आप एक jpg सहेजी जाती है (पहली स्क्रीन 000000.jpg, उसके बाद संचित मिलीसेकंड के नाम पर) |
screenshots | bool (वैकल्पिक) | अवलोकन के समय स्क्रीनशॉट लेना है या नहीं, डिफ़ॉल्ट False — डिफ़ॉल्ट लूप स्क्रीनशॉट नहीं लेता (README में साफ़ कहा गया है); record_dir सेट करने पर यह अपने आप साथ चला जाता है |
उपयोग के तीन मुख्य बिंदु:
- **
with** का उपयोग करें: Agent एक कॉन्टेक्स्ट मैनेजर है,withब्लॉक समाप्त होने पर टैब अपने आप बंद हो जाता है; निर्माण विफल होने पर (जैसे पेज न खुलना) भी पहले ब्राउज़र बंद होता है और फिर एरर थ्रो होता है - निर्माण के साथ ही अवलोकन:
Agent(...)निष्पादित होते ही ब्राउज़र खुल चुका होता है और पहला अवलोकन पूरा हो चुका होता है, यह आपकेrun()कॉल करने का इंतज़ार नहीं करता - एक बार का: done या blocked तक पहुँचने के बाद यह Agent समाप्त हो जाता है, इसे दोबारा नहीं चलाया जा सकता (पिटफॉल अनुस्मारक बिंदु 4)
आपको यह दिखना चाहिए: रिपॉज़िटरी की रूट डायरेक्टरी में एंट्री पॉइंट की पुष्टि करें (uv sync पहले ही पैकेज को एनवायरनमेंट में डाल चुका है):
uv run python -c "from jev_ultrafast import Agent; print(Agent)"<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 को रिपॉज़िटरी की रूट डायरेक्टरी से निष्पादित करना होता है):
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 में वही एक-लाइन लक्ष्य चलता है, अगले चरण में देखें)। चलाएँ:
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):
<मिलीसेकंड> ready
<मिलीसेकंड> ready
……
<मिलीसेकंड> done
<अंतिम URL — गोडेल की अपूर्णता प्रमेय का एंट्री पेज>(मिलीसेकंड संख्या और URL का सटीक एन्कोडिंग आपके इस रन पर निर्भर करता है)
my_task.pyपूरा चलने के बाद, आख़िरी लाइन में प्रिंट हुआ URL गोडेल की अपूर्णता प्रमेय का एंट्री पेज है
चरण 3: examples/run.py से बिना कोड लिखे कोई भी टास्क चलाएँ
क्यों: कोई टास्क बस जल्दी आज़माना हो, तो फ़ाइल बनाने की भी ज़रूरत नहीं — रिपॉज़िटरी में शामिल सामान्य runner URL और लक्ष्य दोनों को कमांड-लाइन पैरामीटर बना देता है।
README की मूल कमांड (शब्दशः):
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 प्रिंट करें:
<मिलीसेकंड> 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() से):
| फ़ील्ड | सामग्री | आप इससे क्या कर सकते हैं |
|---|---|---|
status | ready / 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 जैसा ही पैटर्न):
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 कार्य के लिए इसी तरह का एक बनाएँ:
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 जैसा ही अंत):
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 हो, त्रुटि का मूल पाठ:
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 में केवल एक पंक्ति भरना:
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 भी टाइप नहीं होगा, और यह त्रुटि फेंकी जाएगी:
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 प्रत्येक क्या हैं
- अपने कार्य के लिए स्वतंत्र सत्यापन कॉन्फ़िगर किया गया है,
passedtrue होने पर ही सफल माना जाता है; 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 के समापन पैटर्न की तरह स्नैपशॉट डिस्क पर लिखें:
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 / --goal | run.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.py | L1–6 __all__ = ["Agent", "Browser"] |
| Agent सिग्नेचर और कंस्ट्रक्टर | jev_ultrafast/agent.py | L12–26 Agent(url, goals, *, record_dir=None, screenshots=False); goals स्ट्रिंग/लिस्ट को नई लाइन से जोड़ा जाता है; खाली लक्ष्य Supply a task; कंस्ट्रक्शन पर ही ब्राउज़र खुलकर अवलोकन करता है, विफलता पर पहले बंद करें फिर throw करें |
| state के सभी फ़ील्ड | jev_ultrafast/agent.py | L27–41 goal / page / decision / history / status / plan / plan_index / decisions / text_calls / elapsed_ms / started_at / record |
| snapshot() (स्नैपशट में browser हटाकर elements जोड़े जाते हैं) | jev_ultrafast/agent.py | L46–50 |
| run() (done/blocked तक yield करता है) | jev_ultrafast/agent.py | L163–165 |
| बजट और blocked | jev_ultrafast/agent.py | L75–76 मॉडल कॉल बजट MAX_STEPS * 2; L102–104 60 एक्शन बजट पर blocked सेट; L153–157 लगातार 3 बार कोई बदलाव न होने पर और wait न होने पर blocked सेट |
| निर्णय केवल एक बार उपयोग होता है / stale होने पर स्वतः पुनः अवलोकन | jev_ultrafast/agent.py | L55–64 tick StalePage पकड़कर पुनः अवलोकन करता है; L90–91 निर्णय को पहले खाली करके फिर निष्पादित किया जाता है |
| history / text_calls एंट्री फ़ील्ड | jev_ultrafast/agent.py | L115 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.py | L73–74 This run has stopped. Start a fresh demo. |
| कॉन्टेक्स्ट मैनेजर | jev_ultrafast/agent.py | L167–174 close() / __enter__ / __exit__ |
| सामान्य runner | examples/run.py | L7–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.py | L160–168 TEXT_MODEL_API_KEY आवश्यक (त्रुटि का मूल पाठ), DeepSeek का डिफ़ॉल्ट एंडपॉइंट और मॉडल, reasoning की तीन शाखाएँ; L187–193 आउटपुट अवश्य एकल-की {"text": …}, गैर-रिक्त, ≤2000 वर्ण होना चाहिए, अन्यथा टाइप नहीं किया जाता |
| टेक्स्ट helper निर्देश | jev_ultrafast/questions.py | TEXT_VALUE: मान अनुपस्थित होने पर {"text": null} लौटाता है, व्यक्तिगत जानकारी का आविष्कार नहीं करता; MAX_STEPS = 60 |
| verify मोड का नमूना | examples/flights.py | L18–38 verify() 7 मदों की स्वतंत्र जाँच; L63–64 सत्यापन असफल होने पर SystemExit |
| Wikipedia स्मोक डेटा | docs/performance.md | Other checks: उसी नीति से 2.798 s में वह प्रविष्टि खुलती है; स्थानीय होटल कार्य 1.896 s |
| क्लाउड सेवा और ओपन-सोर्स संस्करण का संबंध | README.md | शीर्ष पर IMPORTANT: BU Ultrafast (model: "bu-ultrafast") Browser Use Cloud का होस्टेड संस्करण है; .env छह चर देखें .env.example |
| पेज ऑब्ज़र्व फ़ील्ड | jev_ultrafast/browser.py | L115–117 fingerprint की गणना url/text/actions/scroll से की जाती है; L188–193 ऑब्ज़र्व info + fingerprint लौटाता है (+screenshot वैकल्पिक); model.py L110 page का url/title/text लेता है |
| inspector ही खुद .env पढ़ता है | jev_ultrafast/demo.py | L23–29 load_environment() (cwd का .env), L132 स्टार्टअप पर कॉल होता है |
| trace git में नहीं जाता | .gitignore | .env, .venv/, artifacts/ तीनों इग्नोर किए जाते हैं |