stagehand
v1.3.0
AI Webブラウジングフレームワークは、シンプルさと拡張性に焦点を当てています。
注記
Stagehandは現在、早期リリースとして利用可能であり、コミュニティからのフィードバックを積極的に求めています。 Slackコミュニティに参加して、最新の開発を最新の状態に保ち、フィードバックを提供してください。
StageHandは、PlaywrightのAI駆動の後継者であり、自然言語主導のWebオートメーションの構成要素を提供する3つの単純なAPI（ act 、 extract 、およびobserve ）を提供します。
StageHandの目標は、過度に複雑な抽象化なしに、軽量で構成可能なフレームワークを提供すること、およびさまざまなモデルとモデルプロバイダーのモジュールサポートを提供することです。ピザを注文するつもりはありませんが、Webを確実に自動化するのに役立ちます。
各ステージハンド関数は、 act("click the login button")またはextract("find the red shoes")などの原子指示を取り入れ、適切な劇作家コードを生成してその命令を達成し、実行します。
指示は信頼性を高めるためにアトミックである必要があり、ステップ計画はより高いレベルのエージェントが処理する必要があります。 observe()を使用して、現在のページで取得できるアクションの提案リストを取得し、それらを使用してステップ計画プロンプトを接地します。
StageHandはオープンソースであり、Browserbaseチームによって維持されています。より多くの開発者が信頼できるWebオートメーションを構築できるようにすることにより、当社のヘッドレスブラウザインフラストラクチャの恩恵を受ける開発者の市場を拡大すると考えています。これは、私たちが自分のアプリケーションをいじくりながら私たちが望んでいたフレームワークであり、あなたとそれを共有できることを楽しみにしています。
また、ZODを入力型抽出にインストールします
npm install @browserbasehq/stagehand zod使用するモデルプロバイダーにAPIキーを提供する必要があります。デフォルトのモデルプロバイダーはOpenAIですが、人類などを使用することもできます。サポートされているモデルの詳細については、APIリファレンスをご覧ください。
OpenAI APIキーまたは人類のAPIキーにローカル環境でアクセスできることを確認してください。
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-...
ブラウザをローカルに実行する場合は、Playwrightのブラウザ依存関係もインストールする必要があります。
npm exec playwright install次に、次のようなステージハンドインスタンスを作成できます。
import { Stagehand } from "@browserbasehq/stagehand" ;
import { z } from "zod" ;
const stagehand = new Stagehand ( {
env : "LOCAL" ,
} ) ;ブラウザをリモートで実行する予定がある場合は、ブラウザーベースAPIキーとプロジェクトIDを設定する必要があります。
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 ：LLM応答のキャッシュを可能にするboolean 。 trueに設定すると、LLMリクエストはディスクにキャッシュされ、同一のリクエストのために再利用されます。デフォルトはfalseになります。headless ：ブラウザがヘッドレスモードで実行されるかどうかを判断するboolean 。デフォルトはfalseになります。 ENVがBROWSERBASEに設定されると、これは無視されます。domSettleTimeoutMs ：DOMが落ち着くのを待つためにミリ秒単位でタイムアウトを指定するinteger 。デフォルトは30000（30秒）です。apiKey ：（オプション）ブラウザーベースAPIキー。デフォルトはBROWSERBASE_API_KEY環境変数になります。projectId ：（オプション）ブラウザーベースプロジェクトID。デフォルトはBROWSERBASE_PROJECT_ID環境変数になります。browserBaseSessionCreateParams ：新しいBrowserBaseセッションを作成するための構成オプション。browserbaseResumeSessionID ：再開する既存のbrowserbaseセッションのID。logger ：ログメッセージを処理する関数。カスタムロギングの実装に役立ちます。verbose ：自動化中にいくつかのレベルのロギングを可能にするinteger ：0 ：ロギングなしに制限されています1 ：SDKレベルのロギング2 ：LLMクライアントレベルロギング（ほとんどの粒状）debugDom ：自動化中にLLMに提示された要素の周りに境界ボックスを描くboolean 。返品：
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 ：（オプション）DOMが解決するのを待つためのミリ秒単位でのタイムアウト返品：
Promise ：debugUrl ：ライブデバッグ用のURLを表すstring 。これは、ブラウザーベースブラウザを使用する場合にのみ使用できます。sessionUrl ：セッションURLを表すstring 。これは、ブラウザーベースブラウザを使用する場合にのみ使用できます。例：
await stagehand . init ( { modelName : "gpt-4o" } ) ; act() act()を使用すると、StageHandがWebページと対話できます。 "search for 'x'"または"select the cheapest flight presented"などのactionを提供します（小さな原子の目標は最高のパフォーマンスを発揮します）。
議論：
action ：実行するアクションを説明するstringmodelName ：（オプション）使用するモデルを指定するAvailableModel文字列modelClientOptions ：（オプション）モデルクライアントの構成オプションuseVision ：（オプション）視覚ベースの処理を使用するかどうかを判断するためのbooleanまたは"fallback" 。デフォルトは"fallback"になりますvariables ：（オプション）アクションで使用する変数のRecord<string, string> 。アクション文字列の変数は%variable_name%を使用して参照されますdomSettleTimeoutMs ：（オプション）DOMが解決するのを待つためのミリ秒単位でのタイムアウト返品：
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() ZODを使用して、現在のページから構造化されたテキストをextract() 。指示とschemaが与えられていると、構造化されたデータが受信されます。一部の抽出ライブラリとは異なり、ステージハンドは、メインの記事の内容だけでなく、ページ上の情報を抽出できます。
議論：
instruction ：抽出の指示を提供するstringschema ：データの構造を定義するz.AnyZodObjectmodelName ：（オプション）使用するモデルを指定するAvailableModel文字列modelClientOptions ：（オプション）モデルクライアントの構成オプションdomSettleTimeoutMs ：（オプション）DOMが解決するのを待つためのミリ秒単位でのタイムアウト返品：
schemaで定義されているように、構造化されたデータに解決するPromise 。例：
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 。デフォルトはfalseになりますdomSettleTimeoutMs ：（オプション）DOMが解決するのを待つためのミリ秒単位でのタイムアウト返品：
Promise ：selector ：要素セレクターを表すstringdescription ：可能なアクションを説明するstring例：
const actions = await stagehand . observe ( ) ; pageとcontext pageとcontextそれぞれPlaywrightのPageとBrowserContextのインスタンスです。これらの方法を使用して、ステージハンドが使用している劇作家インスタンスと対話します。最も一般的には、 page.goto()を使用してURLに移動します。
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;log() log()は、メッセージをブラウザコンソールに印刷するために使用されます。これらのメッセージは、Browserbaseセッションログに保持され、完了後にセッションをデバッグするために使用できます。
ステージハンドインスタンスを初期化するときに設定した冗長レベルを上回っていることを確認してください。
stagehand . log ( "Hello, world!" ) ; ステージハンドは、一般的なLLMクライアントアーキテクチャを活用して、さまざまなプロバイダーのさまざまな言語モデルをサポートします。この設計により、柔軟性が可能になり、コアシステムを最小限に抑えて新しいモデルを統合できます。さまざまなモデルがさまざまなタスクに適しているため、ニーズに最適なモデルを選択できます。
StageHandは現在、Openaiおよび人類の次のモデルをサポートしています。
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には2つの主要なフェーズがあります。
ステージハンドは、テクニックの組み合わせを使用してDOMを準備します。
DOM処理手順は次のように見えます。
LLMSはコンテキストのウィンドウの長さを増やし、遅延を減らし続けますが、推論システムに考えるべきものが少なくなると、より信頼性が高くなります。その結果、推論ごとの呼び出しを小さく保つために、DOM処理はチャンクで行われます。チャンクのために、SDKは、ビューポートのセクションで始まる候補要素をそのチャンクの一部であると考えています。将来的には、個々のチャンクに関連するコンテキストがないことを確認するために、パディングが追加されます。この図を参照してください。
act()およびobserve()メソッドは、 useVisionフラグを取ることができます。これがtrueに設定されている場合、LLMには現在のページの注釈付きスクリーンショットが提供され、どの要素に作用する要素を特定します。これは、LLMが処理やチャンキング後であっても、LLMが推論するのに苦労するのに役立ちます。デフォルトでは、このフラグは"fallback"に設定されています。つまり、LLMが単一の要素を正常に識別できなかった場合、ステージハンドはビジョンを使用して試みを再試行します。
これで、候補要素のリストとそれらを選択する方法があります。これらの要素を、抽出またはアクションのためにLLMに追加のコンテキストで提示できます。大規模にテストされていませんが、「要素の番号付きリスト」を提示することは、モデルを完全なDOMとしてではなく、関連するが独立した要素のリストとして扱うようにモデルを導きます。
アクションの場合、正しいことをするためにLLMに劇作家の方法を書くように依頼します。限られたテストでは、Playwrightの構文は、おそらくトークン化のために、組み込みのJavaScript APIに依存するよりもはるかに効果的です。
最後に、LLMを使用して、将来の指示を自分自身に書き、チャンクを横切って動作するときに進捗と目標を管理するのに役立ちます。
以下は、StageHandとPlaywrightの両方を使用して、AI Grant Webサイトから企業のリストを抽出する方法の例です。
ステージハンドのプロンプトは、エージェントフレームワークを含む他の高レベルのフレームワークよりも文字通り原子的です。効果的なプロンプトを作成するのに役立ついくつかのガイドラインを次に示します。
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" } ) ;これらのガイドラインに従うことにより、ステージハンドでWebオートメーションの信頼性と有効性を高めます。ステージハンドは、正確で明確に定義されたアクションを実行することに優れているため、アトミックの指示を維持すると最高の結果につながることを忘れないでください。
エージェントの動作は、ステージハンドをツールとして使用できる高レベルのエージェントシステムに任せます。
高レベルでは、その優先順位の信頼性、速度、コストの改善に焦点を当てています。
ここでロードマップを見ることができます。貢献したいですか？読んでください！
注記
StageHandへの貢献を非常に高く評価しています！サポートまたはコードレビューについては、Slackコミュニティに参加してください。
まず、レポをクローンします
git clone [email protected]:browserbase/stagehand.git次に、依存関係をインストールします
npm install上記の[開始]セクションに記載されているように、 .envファイルがあることを確認してください。
次に、Sprict npm run exampleを実行します。
優れた開発ループは次のとおりです。
Evalsを実行するには、BrainTrust APIキーが必要です
BRAINTRUST_API_KEY = " "その後、 npm run evalsを使用して評価を実行できます
すべてのエバルを実行するには時間がかかります。すべてのエバルのセットに追加する前に、新しいシングル評価を開発できる便利なスクリプトexample.tsがあります。
npm run exampleを実行して、現在開発中の評価を実行および反復させることができます。
ステージハンドに新しいモデルを追加するには、次の手順に従ってください。
モデルの定義： LLMProvider.tsファイルのAvailableModelタイプに新しいモデル名を追加します。これにより、モデルがシステムによって認識されることが保証されます。
モデルをプロバイダーにマップします。LLMProviderクラスのmodelToProviderMap LLMProvider更新して、新しいモデルを対応するプロバイダーに関連付けます。このマッピングは、使用するクライアントを決定するために重要です。
クライアントの実装：新しいモデルが新しいクライアントを必要とする場合、 LLMClientインターフェイスを順守するクラスを実装します。このクラスは、 createChatCompletionなどのすべての必要な方法を定義する必要があります。
getClientメソッドを更新します： LLMProviderクラスのgetClientメソッドを変更して、新しいモデルが要求されたときに新しいクライアントのインスタンスを返すようにします。
StageHandは、TSUPを使用してSDKとVanilla esbuildを構築して、DOMで実行されるスクリプトを構築します。
npm run build実行しますnpm packを実行して、配信用のターボールを取得しますこのプロジェクトは、Webを自動化するための回復力のあるバックボーンとしてPlaywrightに大きく依存しています。また、TarsierとFuji-Webによって作られた素晴らしいテクニックと発見がなければ、それは不可能です。
ジェレミー・プレスは、ステージハンドの元のMVPを書き、プロジェクトの主要な同盟国であり続けています。
MITライセンスに基づいてライセンスされています。
Copyright 2024 Browserbase、Inc。
