stagehand
v1.3.0
Kerangka Penjelajahan Web AI yang berfokus pada kesederhanaan dan ekstensibilitas.
Catatan
Stagehand saat ini tersedia sebagai rilis awal, dan kami secara aktif mencari umpan balik dari masyarakat. Silakan bergabung dengan komunitas Slack kami untuk tetap diperbarui tentang perkembangan terbaru dan memberikan umpan balik.
StageHand adalah penerus drama yang bertenaga AI, menawarkan tiga API sederhana ( act , extract , dan observe ) yang menyediakan blok bangunan untuk otomatisasi web yang digerakkan oleh bahasa alami.
Tujuan dari StageHand adalah untuk memberikan kerangka kerja yang ringan dan dapat dikonfigurasi, tanpa abstraksi yang terlalu kompleks, serta dukungan modular untuk berbagai model dan penyedia model. Ini tidak akan memesan pizza, tetapi itu akan membantu Anda mengotomatiskan web dengan andal.
Setiap fungsi tahap mengambil instruksi atom, seperti act("click the login button") atau extract("find the red shoes") , menghasilkan kode penulis naskah yang sesuai untuk mencapai instruksi itu, dan menjalankannya.
Instruksi harus atom untuk meningkatkan keandalan, dan perencanaan langkah harus ditangani oleh agen tingkat yang lebih tinggi. Anda dapat menggunakan observe() untuk mendapatkan daftar tindakan yang disarankan yang dapat diambil pada halaman saat ini, dan kemudian menggunakannya untuk mendaratkan petunjuk perencanaan langkah Anda.
StageHand adalah open source dan dikelola oleh tim Browserbase. Kami percaya bahwa dengan memungkinkan lebih banyak pengembang untuk membangun otomatisasi web yang andal, kami akan memperluas pasar pengembang yang mendapat manfaat dari infrastruktur browser tanpa kepala kami. Ini adalah kerangka kerja yang kami harapkan saat mengutak -atik aplikasi kami sendiri, dan kami senang membagikannya kepada Anda.
Kami juga menginstal ekstraksi Zod ke Power Typed
npm install @browserbasehq/stagehand zodAnda harus menyediakan kunci API Anda untuk penyedia model yang ingin Anda gunakan. Penyedia model default adalah Openai, tetapi Anda juga dapat menggunakan antropik atau orang lain. Informasi lebih lanjut tentang model yang didukung dapat ditemukan dalam referensi API.
Pastikan kunci API OpenAI atau kunci API antropik dapat diakses di lingkungan lokal Anda.
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-...
Jika Anda berencana untuk menjalankan browser secara lokal, Anda juga harus menginstal dependensi browser penulis naskah.
npm exec playwright installMaka Anda dapat membuat instance panggung seperti itu seperti:
import { Stagehand } from "@browserbasehq/stagehand" ;
import { z } from "zod" ;
const stagehand = new Stagehand ( {
env : "LOCAL" ,
} ) ;Jika Anda berencana untuk menjalankan browser dari jarak jauh, Anda harus mengatur kunci API Browserbase dan ID proyek.
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 } ` ) ;Cuplikan sederhana ini akan membuka browser, menavigasi ke repo panggung, dan mencatat kontributor teratas.
Stagehand()Konstruktor ini digunakan untuk membuat instance stageHand.
Argumen:
env : 'LOCAL' atau 'BROWSERBASE' . Default ke 'BROWSERBASE' .modelName : (Opsional) String AvailableModel untuk menentukan model default yang akan digunakan.modelClientOptions : (Opsional) Opsi konfigurasi untuk klien model.enableCaching : boolean yang memungkinkan caching respons LLM. Ketika diatur ke true , permintaan LLM akan di -cache pada disk dan digunakan kembali untuk permintaan yang identik. Default ke false .headless : boolean yang menentukan apakah browser berjalan dalam mode tanpa kepala. Default ke false . Ketika Env diatur ke BROWSERBASE , ini akan diabaikan.domSettleTimeoutMs : integer yang menentukan batas waktu dalam milidetik untuk menunggu DOM menyelesaikan. Default ke 30000 (30 detik).apiKey : (Opsional) Kunci API Browserbase Anda. Default ke variabel lingkungan BROWSERBASE_API_KEY .projectId : (Opsional) ID Proyek Browserbase Anda. Default ke variabel lingkungan BROWSERBASE_PROJECT_ID .browserBaseSessionCreateParams : Opsi Konfigurasi untuk Membuat Sesi Browserbase Baru.browserbaseResumeSessionID : ID dari sesi browserbase yang ada untuk dilanjutkan.logger : Fungsi yang menangani pesan log. Berguna untuk implementasi logging khusus.verbose : integer yang memungkinkan beberapa level logging selama otomatisasi:0 : Terbatas untuk No Logging1 : Penebangan Tingkat SDK2 : LLM-CLient Level Logging (kebanyakan granular)debugDom : boolean yang menggambar kotak -kotak pembatas di sekitar elemen yang disajikan kepada LLM selama otomatisasi.Kembali:
Stagehand yang dikonfigurasi dengan opsi yang ditentukan.Contoh:
// 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() secara tidak sinkron menginisialisasi instance stageHand. Itu harus dipanggil sebelum metode lain.
Argumen:
modelName : (Opsional) String AvailableModel untuk menentukan model yang akan digunakan. Ini akan digunakan untuk semua metode lain kecuali ditimpa.modelClientOptions : (Opsional) Opsi Konfigurasi untuk Klien ModeldomSettleTimeoutMs : (Opsional) Batas waktu dalam milidetik untuk menunggu DOM menyelesaikanKembali:
Promise yang diselesaikan menjadi objek yang berisi:debugUrl : Sebuah string yang mewakili URL untuk debugging langsung. Ini hanya tersedia saat menggunakan browser browserbase.sessionUrl : Sebuah string yang mewakili URL sesi. Ini hanya tersedia saat menggunakan browser browserbase.Contoh:
await stagehand . init ( { modelName : "gpt-4o" } ) ; act() act() memungkinkan panggung untuk berinteraksi dengan halaman web. Berikan action seperti "search for 'x'" , atau "select the cheapest flight presented" (tujuan atom kecil melakukan yang terbaik).
Argumen:
action : string yang menggambarkan tindakan yang akan dilakukanmodelName : (Opsional) String AvailableModel untuk Menentukan Model yang akan DigunakanmodelClientOptions : (Opsional) Opsi Konfigurasi untuk Klien ModeluseVision : (Opsional) boolean atau "fallback" untuk menentukan apakah pemrosesan berbasis penglihatan harus digunakan. Default ke "fallback"variables : (Opsional) Record<string, string> variabel untuk digunakan dalam tindakan. Variabel dalam string aksi direferensikan menggunakan %variable_name%domSettleTimeoutMs : (Opsional) Batas waktu dalam milidetik untuk menunggu DOM menyelesaikanKembali:
Promise yang diselesaikan menjadi objek yang berisi:success : boolean yang menunjukkan jika tindakan itu selesai dengan sukses.message : string yang memberikan detail tentang eksekusi tindakan.action : string yang menggambarkan tindakan yang dilakukan.Contoh:
// 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() mengambil teks terstruktur dari halaman saat ini menggunakan ZOD. Diberikan instruksi dan schema , Anda akan menerima data terstruktur. Tidak seperti beberapa perpustakaan ekstraksi, StageHand dapat mengekstraksi informasi apa pun pada halaman, bukan hanya konten artikel utama.
Argumen:
instruction : string yang memberikan instruksi untuk ekstraksischema : z.AnyZodObject yang mendefinisikan struktur data untuk mengekstrakmodelName : (Opsional) String AvailableModel untuk Menentukan Model yang akan DigunakanmodelClientOptions : (Opsional) Opsi Konfigurasi untuk Klien ModeldomSettleTimeoutMs : (Opsional) Batas waktu dalam milidetik untuk menunggu DOM menyelesaikanKembali:
Promise yang menyelesaikan data terstruktur sebagaimana didefinisikan oleh schema yang disediakan.Contoh:
const price = await stagehand . extract ( {
instruction : "extract the price of the item" ,
schema : z . object ( {
price : z . number ( ) ,
} ) ,
} ) ; observe()Catatan
observe() saat ini hanya mengevaluasi potongan pertama di halaman.
observe() digunakan untuk mendapatkan daftar tindakan yang dapat diambil pada halaman saat ini. Ini berguna untuk menambahkan konteks ke langkah perencanaan Anda, atau jika Anda tidak yakin dengan halaman apa Anda berada.
Jika Anda mencari elemen tertentu, Anda juga dapat meneruskan instruksi untuk mengamati melalui: observe({ instruction: "{your instruction}"}) .
Argumen:
instruction : (Opsional) Suatu string yang memberikan instruksi untuk pengamatan. Default untuk "menemukan tindakan yang dapat dilakukan di halaman ini."modelName : (Opsional) String AvailableModel untuk Menentukan Model yang akan DigunakanmodelClientOptions : (Opsional) Opsi Konfigurasi untuk Klien ModeluseVision : (Opsional) boolean untuk menentukan apakah pemrosesan berbasis penglihatan harus digunakan. Default ke falsedomSettleTimeoutMs : (Opsional) Batas waktu dalam milidetik untuk menunggu DOM menyelesaikanKembali:
Promise yang diselesaikan menjadi berbagai objek yang berisi:selector : string yang mewakili pemilih elemendescription : string yang menggambarkan kemungkinan tindakanContoh:
const actions = await stagehand . observe ( ) ; page dan context page dan context adalah contoh dari Playwright's Page dan BrowserContext masing -masing. Gunakan metode ini untuk berinteraksi dengan instance penulis naskah yang digunakan StageHand. Paling umum, Anda akan menggunakan page.goto() untuk menavigasi ke URL.
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;log() log() digunakan untuk mencetak pesan ke konsol browser. Pesan -pesan ini akan bertahan dalam log sesi browserbase, dan dapat digunakan untuk men -debug sesi setelah selesai.
Pastikan level log di atas level verbose yang Anda atur saat menginisialisasi instance stageHand.
stagehand . log ( "Hello, world!" ) ; StageHand memanfaatkan arsitektur klien LLM generik untuk mendukung berbagai model bahasa dari penyedia yang berbeda. Desain ini memungkinkan fleksibilitas, memungkinkan integrasi model baru dengan perubahan minimal pada sistem inti. Model yang berbeda bekerja lebih baik untuk tugas yang berbeda, sehingga Anda dapat memilih model yang paling sesuai dengan kebutuhan Anda.
StageHand saat ini mendukung model -model berikut dari Openai dan Anthropic:
Model Openai:
gpt-4ogpt-4o-minigpt-4o-2024-08-06Model antropik:
claude-3-5-sonnet-latestclaude-3-5-sonnet-20240620claude-3-5-sonnet-20241022 Model -model ini dapat ditentukan saat menginisialisasi instance Stagehand atau ketika metode panggilan seperti act() dan extract() .
SDK memiliki dua fase utama:
StageHand menggunakan kombinasi teknik untuk menyiapkan DOM.
Langkah -langkah pemrosesan DOM terlihat sebagai berikut:
Sementara LLMS akan terus meningkatkan panjang jendela konteks dan mengurangi latensi, memberikan sistem penalaran yang lebih sedikit untuk dipikirkan harus membuatnya lebih dapat diandalkan. Akibatnya, pemrosesan DOM dilakukan dalam potongan untuk menjaga konteks kecil per panggilan inferensi. Untuk dipotong, SDK mempertimbangkan elemen kandidat yang dimulai di bagian viewport sebagai bagian dari potongan itu. Di masa depan, padding akan ditambahkan untuk memastikan bahwa potongan individu tidak kekurangan konteks yang relevan. Lihat diagram ini untuk tampilannya:
Metode act() dan observe() dapat mengambil bendera useVision . Jika ini diatur ke true , LLM akan dilengkapi dengan tangkapan layar beranotasi dari halaman saat ini untuk mengidentifikasi elemen mana yang akan ditindaklanjuti. Ini berguna untuk DOM yang kompleks bahwa LLM mengalami kesulitan, bahkan setelah diproses dan chunking. Secara default, bendera ini diatur ke "fallback" , yang berarti bahwa jika LLM gagal untuk berhasil mengidentifikasi satu elemen, StageHand akan mencoba lagi upaya menggunakan visi.
Sekarang kami memiliki daftar elemen kandidat dan cara untuk memilihnya. Kami dapat menyajikan elemen -elemen itu dengan konteks tambahan ke LLM untuk ekstraksi atau tindakan. Sementara belum teruji dalam skala besar, menyajikan "daftar elemen bernomor" memandu model untuk tidak memperlakukan konteks sebagai DOM penuh, tetapi sebagai daftar elemen terkait tetapi independen untuk dioperasikan.
Dalam kasus tindakan, kami meminta LLM untuk menulis metode penulis naskah untuk melakukan hal yang benar. Dalam pengujian kami yang terbatas, sintaksis penulis naskah jauh lebih efektif daripada mengandalkan API JavaScript bawaan, mungkin karena tokenisasi.
Terakhir, kami menggunakan LLM untuk menulis instruksi masa depan untuk dirinya sendiri untuk membantu mengelola kemajuan dan tujuannya saat beroperasi di seluruh potongan.
Di bawah ini adalah contoh cara mengekstrak daftar perusahaan dari situs web hibah AI menggunakan StageHand dan Playwright.
Memicu StageHand lebih literal dan atom daripada kerangka kerja tingkat lebih tinggi lainnya, termasuk kerangka kerja agen. Berikut adalah beberapa pedoman untuk membantu Anda membuat permintaan yang efektif:
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 ( ) ,
} ) ,
} ) ;Alih -alih menggabungkan tindakan:
// Avoid this
await stagehand . act ( { action : "log in and purchase the first item" } ) ;Pisahkan menjadi langkah -langkah individual:
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() untuk mendapatkan saran yang dapat ditindaklanjuti dari halaman saat ini 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" } ) ;Dengan mengikuti pedoman ini, Anda akan meningkatkan keandalan dan efektivitas otomatisasi web Anda dengan StageHand. Ingat, Stagehand unggul dalam mengeksekusi tindakan yang tepat dan terdefinisi dengan baik sehingga menjaga instruksi Anda atom akan mengarah pada hasil terbaik.
Kami meninggalkan perilaku agen ke sistem agen tingkat tinggi yang dapat menggunakan stageHand sebagai alat.
Pada tingkat tinggi, kami fokus pada peningkatan keandalan, kecepatan, dan biaya dalam urutan prioritas itu.
Anda dapat melihat peta jalan di sini. Ingin berkontribusi? Baca terus!
Catatan
Kami sangat menghargai kontribusi untuk StageHand! Untuk dukungan atau tinjauan kode, silakan bergabung dengan komunitas Slack kami.
Pertama, klon repo
git clone [email protected]:browserbase/stagehand.gitKemudian instal dependensi
npm install Pastikan Anda memiliki file .env seperti yang didokumentasikan di atas di bagian Memulai.
Kemudian, jalankan contoh skrip npm run example .
Lingkaran pengembangan yang baik adalah:
Anda akan membutuhkan kunci API braintrust untuk menjalankan eval
BRAINTRUST_API_KEY = " " Setelah itu, Anda dapat menjalankan eval menggunakan npm run evals
Menjalankan semua eval bisa memakan waktu. Kami memiliki example.ts skrip kenyamanan.ts di mana Anda dapat mengembangkan eval tunggal baru Anda sebelum menambahkannya ke set semua eval.
Anda dapat menjalankan npm run example untuk mengeksekusi dan mengulangi eval yang sedang Anda kembangkan.
Untuk menambahkan model baru ke StageHand, ikuti langkah -langkah ini:
Tentukan model : Tambahkan nama model baru ke jenis AvailableModel di file LLMProvider.ts . Ini memastikan bahwa model diakui oleh sistem.
Peta model ke penyedia : Perbarui modelToProviderMap di kelas LLMProvider untuk mengaitkan model baru dengan penyedia yang sesuai. Pemetaan ini sangat penting untuk menentukan klien mana yang akan digunakan.
Menerapkan klien : Jika model baru membutuhkan klien baru, implementasikan kelas yang melekat pada antarmuka LLMClient . Kelas ini harus mendefinisikan semua metode yang diperlukan, seperti createChatCompletion .
Perbarui Metode getClient : Ubah Metode getClient di kelas LLMProvider untuk mengembalikan instance klien baru ketika model baru diminta.
StageHand menggunakan TSUP untuk membangun SDK dan Vanilla esbuild untuk membangun skrip yang berjalan di DOM.
npm run buildnpm pack untuk mendapatkan tarball untuk distribusi Proyek ini sangat bergantung pada penulis naskah sebagai tulang punggung yang tangguh untuk mengotomatiskan web. Itu juga tidak akan mungkin terjadi tanpa teknik dan penemuan yang luar biasa yang dibuat oleh Tarsier, dan Fuji-Web.
Jeremy Press menulis MVP asli StageHand dan terus menjadi sekutu utama proyek.
Berlisensi di bawah lisensi MIT.
Hak Cipta 2024 Browserbase, Inc.
