stagehand
v1.3.0
ركز إطار تصفح الويب AI على البساطة والتوسيع.
ملحوظة
تتوفر Stagehand حاليًا كإصدار مبكر ، ونحن نبحث بنشاط عن ملاحظات من المجتمع. يرجى الانضمام إلى مجتمع Slack الخاص بنا للبقاء على اطلاع على أحدث التطورات وتقديم ملاحظات.
StageHand هو الخلف الذي يعمل به منظمة العفو الدولية للكاتب المسرحي ، حيث يقدم ثلاثة واجهات برمجة التطبيقات البسيطة ( act ، extract ، observe ) التي توفر لبنات البناء لأتمتة الويب التي تعتمد على اللغة الطبيعية.
الهدف من المسرح هو توفير إطار عمل خفيف الوزن قابل للتكوين ، دون تجريدات معقدة بشكل مفرط ، وكذلك الدعم المعياري للنماذج المختلفة ومقدمي النماذج. لن تطلب لك بيتزا ، ولكنها ستساعدك على أتمتة الويب بشكل موثوق.
يأخذ كل وظيفة stageHand في تعليمات ذرية ، مثل act("click the login button") أو extract("find the red shoes") ، وإنشاء رمز الكاتب المسرحي المناسب لإنجاز تلك التعليمات ، وتنفيذها.
يجب أن تكون التعليمات ذرية لزيادة الموثوقية ، ويجب التعامل مع تخطيط الخطوة من قبل وكيل المستوى الأعلى. يمكنك استخدام observe() للحصول على قائمة مقترحة من الإجراءات التي يمكن اتخاذها على الصفحة الحالية ، ثم استخدامها لتأسيس مطالبات تخطيط الخطوة.
StageHand مفتوح المصدر ويتم الحفاظ عليه من قبل فريق BrowserBase. نحن نعتقد أنه من خلال تمكين المزيد من المطورين من بناء أتمتة ويب موثوقة ، سنوسع سوق المطورين الذين يستفيدون من البنية التحتية للمستعرضات المقطوعة الرأس الخاصة بنا. هذا هو الإطار الذي كنا نتمنى أن يكون لدينا أثناء العبث بتطبيقاتنا الخاصة ، ونحن متحمسون لمشاركته معك.
نقوم أيضًا بتثبيت Zod على استخراج الطاقة المكتوبة بالطاقة
npm install @browserbasehq/stagehand zodستحتاج إلى توفير مفتاح API لمزود النموذج الذي ترغب في استخدامه. مزود النموذج الافتراضي هو Openai ، ولكن يمكنك أيضًا استخدام الأنثروبور أو غيرها. يمكن العثور على مزيد من المعلومات حول النماذج المدعومة في مرجع API.
تأكد من الوصول إلى مفتاح API Openai أو مفتاح واجهة برمجة تطبيقات الإنسان في بيئتك المحلية.
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-...
إذا كنت تخطط لتشغيل المتصفح محليًا ، فستحتاج أيضًا إلى تثبيت تبعيات متصفح الكاتب المسرحي.
npm exec playwright installثم يمكنك إنشاء مثيل stateHand مثل ذلك:
import { Stagehand } from "@browserbasehq/stagehand" ;
import { z } from "zod" ;
const stagehand = new Stagehand ( {
env : "LOCAL" ,
} ) ;إذا كنت تخطط لتشغيل المتصفح عن بُعد ، فستحتاج إلى تعيين مفتاح API BrowserBase ومعرف المشروع.
export BROWSERBASE_API_KEY=...
export BROWSERBASE_PROJECT_ID=... import { Stagehand } from "@browserbasehq/stagehand" ;
import { z } from "zod" ;
const stagehand = new Stagehand ( {
env : "BROWSERBASE" ,
enableCaching : true ,
} ) ; await stagehand . init ( ) ;
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;
await stagehand . act ( { action : "click on the contributors" } ) ;
const contributor = await stagehand . extract ( {
instruction : "extract the top contributor" ,
schema : z . object ( {
username : z . string ( ) ,
url : z . string ( ) ,
} ) ,
} ) ;
console . log ( `Our favorite contributor is ${ contributor . username } ` ) ;سيفتح هذا المقتطف البسيط متصفحًا ، وانتقل إلى إعادة الريبو المسرحية ، وتسجيل المساهم الأعلى.
Stagehand()يتم استخدام هذا المنشئ لإنشاء مثيل من المسرح.
الحجج:
env : 'LOCAL' أو 'BROWSERBASE' . الإعدادات الافتراضية إلى 'BROWSERBASE' .modelName : (اختياري) سلسلة AvailableModel لتحديد النموذج الافتراضي للاستخدام.modelClientOptions : (اختياري) خيارات التكوين لعميل النموذج.enableCaching : boolean تتيح التخزين المؤقت لاستجابات LLM. عند التعيين على true ، سيتم تخزين طلبات LLM على القرص وإعادة استخدامها للطلبات المتطابقة. الإعدادات الافتراضية إلى false .headless : boolean تحدد ما إذا كان المتصفح يعمل في وضع مقطوع الرأس. الإعدادات الافتراضية إلى false . عندما يتم تعيين ENV على BROWSERBASE ، سيتم تجاهل هذا.domSettleTimeoutMs : integer يحدد المهلة بالميلي ثانية لانتظار DOM لتستقر. الافتراضات إلى 30000 (30 ثانية).apiKey : (اختياري) مفتاح API BrowserBase. الافتراضات إلى متغير بيئة BROWSERBASE_API_KEY .projectId : (اختياري) معرف مشروع BrowserBase الخاص بك. الإعدادات الافتراضية إلى متغير BROWSERBASE_PROJECT_ID .browserBaseSessionCreateParams : خيارات التكوين لإنشاء جلسات BrowserBase جديدة.browserbaseResumeSessionID : معرف جلسة BrowserBase الحالية لاستئنافها.logger : وظيفة تعالج رسائل السجل. مفيد لتطبيقات التسجيل المخصصة.verbose : integer يمكّن عدة مستويات من التسجيل أثناء الأتمتة:0 : يقتصر على عدم وجود قطع تسجيل1 : تسجيل مستوى SDK2 : تسجيل مستوى LLM-Client (الأكثر حبيبًا)debugDom : boolean ترسم صناديق محيطة حول العناصر المقدمة إلى LLM أثناء الأتمتة.عائدات:
Stagehand مع الخيارات المحددة.مثال:
// Basic usage
const stagehand = new Stagehand ( ) ;
// Custom configuration
const stagehand = new Stagehand ( {
env : "LOCAL" ,
verbose : 1 ,
headless : true ,
enableCaching : true ,
logger : ( logLine ) => {
console . log ( `[ ${ logLine . category } ] ${ logLine . message } ` ) ;
} ,
} ) ;
// Resume existing Browserbase session
const stagehand = new Stagehand ( {
env : "BROWSERBASE" ,
browserbaseResumeSessionID : "existing-session-id" ,
} ) ;init() init() تهيئة بشكل غير متزامن مثيل المسرح. يجب استدعاؤه قبل أي طرق أخرى.
الحجج:
modelName : (اختياري) سلسلة AvailableModel لتحديد النموذج المراد استخدامه. سيتم استخدام هذا لجميع الطرق الأخرى ما لم يتم تجاوزها.modelClientOptions : خيارات التكوين (الاختيارية) لعميل النموذجdomSettleTimeoutMs : مهلة (اختيارية) بالمللي ثانية لانتظار الاستقرارعائدات:
Promise يحل على كائن يحتوي على:debugUrl : string تمثل عنوان URL للتصحيح المباشر. هذا متاح فقط عند استخدام متصفح BrowserBase.sessionUrl : string تمثل عنوان URL للجلسة. هذا متاح فقط عند استخدام متصفح BrowserBase.مثال:
await stagehand . init ( { modelName : "gpt-4o" } ) ; act() act() يسمح للتفاعل مع صفحة ويب. قدم action مثل "search for 'x'" ، أو "select the cheapest flight presented" (الأهداف الذرية الصغيرة تؤدي الأفضل).
الحجج:
action : string تصف الإجراء المطلوب تنفيذهاmodelName : (اختياري) سلسلة AvailableModel لتحديد النموذج للاستخدامmodelClientOptions : خيارات التكوين (الاختيارية) لعميل النموذجuseVision : (اختياري) boolean أو "fallback" لتحديد ما إذا كان ينبغي استخدام المعالجة القائمة على الرؤية. الإعدادات الافتراضية إلى "fallback"variables : (اختياري) Record<string, string> من المتغيرات لاستخدامها في الإجراء. يتم الرجوع إلى المتغيرات في سلسلة الإجراء باستخدام %variable_name%domSettleTimeoutMs : مهلة (اختيارية) بالمللي ثانية لانتظار الاستقرارعائدات:
Promise يحل على كائن يحتوي على:success : boolean تشير إلى ما إذا تم الانتهاء من الإجراء بنجاح.message : string توفر تفاصيل حول تنفيذ الإجراء.action : string تصف الإجراء الذي تم تنفيذه.مثال:
// Basic usage
await stagehand . act ( { action : "click on add to cart" } ) ;
// Using variables
await stagehand . act ( {
action : "enter %username% into the username field" ,
variables : {
username : "[email protected]" ,
} ,
} ) ;
// Multiple variables
await stagehand . act ( {
action : "fill in the form with %username% and %password%" ,
variables : {
username : "john.doe" ,
password : "secretpass123" ,
} ,
} ) ; extract() extract() يمسك النص منظم من الصفحة الحالية باستخدام ZOD. تعليمات schema ، ستتلقى بيانات منظمة. على عكس بعض مكتبات الاستخراج ، يمكن لـ StageHand استخراج أي معلومات على صفحة ، وليس فقط محتويات المقالة الرئيسية.
الحجج:
instruction : string توفر إرشادات للاستخراجschema : z.AnyZodObjectmodelName : (اختياري) سلسلة AvailableModel لتحديد النموذج للاستخدامmodelClientOptions : خيارات التكوين (الاختيارية) لعميل النموذجdomSettleTimeoutMs : مهلة (اختيارية) بالمللي ثانية لانتظار الاستقرارعائدات:
Promise الذي يحل إلى البيانات المنظمة على النحو المحدد في schema المقدم.مثال:
const price = await stagehand . extract ( {
instruction : "extract the price of the item" ,
schema : z . object ( {
price : z . number ( ) ,
} ) ,
} ) ; observe()ملحوظة
observe() حاليًا يقيم فقط الجزء الأول في الصفحة.
يتم استخدام observe() للحصول على قائمة بالإجراءات التي يمكن اتخاذها على الصفحة الحالية. من المفيد إضافة سياق إلى خطوة التخطيط الخاصة بك ، أو إذا لم تكن متأكدًا من الصفحة التي تقوم بها.
إذا كنت تبحث عن عنصر معين ، فيمكنك أيضًا تمرير تعليمات لمراقبة عبر: observe({ instruction: "{your instruction}"}) .
الحجج:
instruction : (اختياري) string توفر إرشادات للمراقبة. الافتراضيات إلى "العثور على إجراءات يمكن تنفيذها في هذه الصفحة."modelName : (اختياري) سلسلة AvailableModel لتحديد النموذج للاستخدامmodelClientOptions : خيارات التكوين (الاختيارية) لعميل النموذجuseVision : (اختياري) boolean لتحديد ما إذا كان ينبغي استخدام المعالجة القائمة على الرؤية. الإعدادات الافتراضية إلى falsedomSettleTimeoutMs : مهلة (اختيارية) بالمللي ثانية لانتظار الاستقرارعائدات:
Promise يحل على مجموعة من الأشياء التي تحتوي على:selector : string تمثل العنصر المحددdescription : string تصف الإجراء المحتملمثال:
const actions = await stagehand . observe ( ) ; page context page context هما مثيلات Page الكاتب المسرحي و BrowserContext على التوالي. استخدم هذه الطرق للتفاعل مع مثيل الكاتب المسرحي الذي تستخدمه المسرح. الأكثر شيوعًا ، ستستخدم page.goto() للتنقل إلى عنوان URL.
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;log() يستخدم log() لطباعة رسالة إلى وحدة التحكم في المتصفح. سيتم استمرار هذه الرسائل في سجلات جلسة BrowserBase ، ويمكن استخدامها لتصحيح جلسات بعد الانتهاء منها.
تأكد من أن مستوى السجل أعلى من المستوى المطول الذي تقوم بتعيينه عند تهيئة المثيل المسرحي.
stagehand . log ( "Hello, world!" ) ; يقوم StageHand بالتعزيز على بنية عميل LLM العامة لدعم نماذج اللغة المختلفة من مختلف مقدمي الخدمات. يسمح هذا التصميم بالمرونة ، مما يتيح دمج النماذج الجديدة مع الحد الأدنى من التغييرات على النظام الأساسي. تعمل النماذج المختلفة بشكل أفضل لمهام مختلفة ، بحيث يمكنك اختيار النموذج الذي يناسب احتياجاتك.
يدعم StageHand حاليًا النماذج التالية من Openai و Anthropic:
نماذج Openai:
gpt-4ogpt-4o-minigpt-4o-2024-08-06النماذج البشرية:
claude-3-5-sonnet-latestclaude-3-5-sonnet-20240620claude-3-5-sonnet-20241022 يمكن تحديد هذه النماذج عند تهيئة مثيل Stagehand أو عند استدعاء طرق مثل act() و extract() .
SDK لديه مرحلتان رئيسيتان:
يستخدم StageHand مجموعة من التقنيات لإعداد DOM.
تبدو خطوات معالجة DOM على النحو التالي:
على الرغم من أن LLMS ستستمر في زيادة طول نافذة السياق وتقليل الكمون ، فإن إعطاء أي نظام تفكير أقل للتفكير يجب أن يجعله أكثر موثوقية. نتيجة لذلك ، تتم معالجة DOM في قطع من أجل الحفاظ على السياق الصغير لكل مكالمة استنتاج. من أجل القطع ، تدرس SDK عنصرًا مرشحًا يبدأ في قسم من منفذ العرض ليكون جزءًا من هذا الجزء. في المستقبل ، ستتم إضافة الحشو للتأكد من أن قطعة فردية لا تفتقر إلى السياق ذي الصلة. انظر هذا الرسم التخطيطي لكيفية ظهوره:
يمكن أن تأخذ act() و observe() علامة useVision . إذا تم ضبط هذا على true ، فسيتم تزويد LLM بلقطة شاشة مشروحة للصفحة الحالية لتحديد عناصر العمل عليها. هذا مفيد لـ DOMs المعقدة التي تواجه LLM وقتًا عصيبًا في التفكير ، حتى بعد المعالجة والتشكيل. بشكل افتراضي ، تم تعيين هذه العلامة على "fallback" ، مما يعني أنه إذا فشل LLM في تحديد عنصر واحد بنجاح ، فسيقوم StateHand بإعادة محاولة محاولة استخدام الرؤية.
الآن لدينا قائمة بالعناصر المرشحة وطريقة لاختيارها. يمكننا تقديم تلك العناصر مع سياق إضافي إلى LLM للاستخراج أو العمل. على الرغم من عدم اختباره على نطاق واسع ، فإن تقديم "قائمة مرقمة للعناصر" يوجه النموذج لعدم التعامل مع السياق كدوام كامل ، ولكن كقائمة من العناصر ذات الصلة ولكن المستقلة للعمل عليها.
في حالة العمل ، نطلب من LLM كتابة طريقة للكاتب المسرحي من أجل القيام بالشيء الصحيح. في اختبارنا المحدود ، يكون بناء جملة الكاتب المسرحي أكثر فعالية من الاعتماد على واجهات برمجة تطبيقات JavaScript المدمجة ، وربما بسبب الرمز المميز.
أخيرًا ، نستخدم LLM لكتابة التعليمات المستقبلية لنفسها للمساعدة في إدارة تقدمه وأهدافه عند العمل عبر القطع.
فيما يلي مثال على كيفية استخراج قائمة الشركات من موقع AI Grant باستخدام كل من المسرح والكاتب المسرحي.
إن المطالبة بـ StageHand هي أكثر حرفية وذرية من الأطر غير الأخرى ذات المستوى الأعلى ، بما في ذلك الأطر عمل الوكيل. فيما يلي بعض الإرشادات لمساعدتك في صياغة مطالبات فعالة:
await stagehand . act ( { action : "click the login button" } ) ;
const productInfo = await stagehand . extract ( {
instruction : "find the red shoes" ,
schema : z . object ( {
productName : z . string ( ) ,
price : z . number ( ) ,
} ) ,
} ) ;بدلاً من الجمع بين الإجراءات:
// Avoid this
await stagehand . act ( { action : "log in and purchase the first item" } ) ;تقسيمها إلى خطوات فردية:
await stagehand . act ( { action : "click the login button" } ) ;
// ...additional steps to log in...
await stagehand . act ( { action : "click on the first item" } ) ;
await stagehand . act ( { action : "click the purchase button" } ) ;observe() للحصول على اقتراحات قابلة للتنفيذ من الصفحة الحالية const actions = await stagehand . observe ( ) ;
console . log ( "Possible actions:" , actions ) ; // Too vague
await stagehand . act ( { action : "find something interesting on the page" } ) ; // Avoid combining actions
await stagehand . act ( { action : "fill out the form and submit it" } ) ; // Outside Stagehand's scope
await stagehand . act ( { action : "book the cheapest flight available" } ) ;من خلال اتباع هذه الإرشادات ، ستقوم بزيادة موثوقية وفعالية أتمتة الويب الخاصة بك مع المسرح. تذكر أن المسرح يتفوق على تنفيذ إجراءات دقيقة ومحددة جيدًا ، لذا فإن الحفاظ على تعليماتك الذرية ستؤدي إلى أفضل النتائج.
نترك السلوك الوكيل للأنظمة العليا ذات المستوى الأعلى والتي يمكن أن تستخدم المسرح كأداة.
على مستوى عال ، نركز على تحسين الموثوقية والسرعة والتكلفة بترتيب الأولوية.
يمكنك رؤية خريطة الطريق هنا. تبحث للمساهمة؟ اقرأ!
ملحوظة
نحن نقدر بشدة المساهمات في المسرح! للحصول على الدعم أو مراجعة الرمز ، يرجى الانضمام إلى مجتمع Slack الخاص بنا.
أولا ، استنساخ الريبو
git clone [email protected]:browserbase/stagehand.gitثم تثبيت التبعيات
npm install تأكد من أن لديك ملف .env كما هو موثق أعلاه في قسم البدء.
بعد ذلك ، قم بتشغيل npm run example .
حلقة تطوير جيدة هي:
ستحتاج إلى مفتاح API Braintrust لتشغيل Evals
BRAINTRUST_API_KEY = " " بعد ذلك ، يمكنك تشغيل Eval باستخدام npm run evals
تشغيل جميع evals يمكن أن يستغرق بعض الوقت. لدينا example.ts نص راحة. حيث يمكنك تطوير Eval الفردي الجديد قبل إضافته إلى مجموعة جميع EVALs.
يمكنك تشغيل npm run example على التنفيذ والتكرار في Eval الذي تقوم بتطويره حاليًا.
لإضافة نموذج جديد إلى المسرح ، اتبع هذه الخطوات:
حدد النموذج : أضف اسم الطراز الجديد إلى نوع AvailableModel في ملف LLMProvider.ts . هذا يضمن أن النموذج معترف به من قبل النظام.
قم بتخطيط النموذج إلى مزود : قم بتحديث modelToProviderMap في فئة LLMProvider لربط النموذج الجديد بمزوده المقابل. هذا التعيين أمر بالغ الأهمية لتحديد العميل الذي يجب استخدامه.
قم بتنفيذ العميل : إذا كان النموذج الجديد يتطلب عميلًا جديدًا ، فعليك تطبيق فئة تلتزم بواجهة LLMClient . يجب أن تحدد هذه الفئة جميع الأساليب اللازمة ، مثل createChatCompletion .
قم بتحديث طريقة getClient : تعديل طريقة getClient في فئة LLMProvider لإرجاع مثيل للعميل الجديد عند طلب النموذج الجديد.
يستخدم StageHand TSUP لبناء SDK و Vanilla esbuild لبناء البرامج النصية التي تعمل في DOM.
npm run buildnpm pack للحصول على طفيف لتوزيعها يعتمد هذا المشروع اعتمادًا كبيرًا على الكاتب المسرحي باعتباره العمود الفقري المرن لأتمتة الويب. كما أنه لن يكون ذلك ممكنًا بدون التقنيات والاكتشافات الرائعة التي قام بها Tarsier ، و Fuji-Web.
كتب Jeremy Press MVP الأصلي لـ StageHand ويظل حليفًا رئيسيًا للمشروع.
مرخصة بموجب ترخيص معهد ماساتشوستس للتكنولوجيا.
حقوق الطبع والنشر 2024 BrowserBase ، Inc.
