stagehand
v1.3.0
Ein AI -Web -Browser -Framework konzentrierte sich auf Einfachheit und Erweiterbarkeit.
Notiz
Stagehand ist derzeit als frühe Veröffentlichung erhältlich und wir suchen aktiv nach Feedback der Community. Bitte schließen Sie sich unserer Slack -Community an, um über die neuesten Entwicklungen auf dem Laufenden zu bleiben und Feedback zu geben.
StageHand ist der KI-betriebene Nachfolger des Dramatikers und bietet drei einfache APIs ( act , extract und observe ), die die Bausteine für die natürliche Sprachantriebs-Webautomation bereitstellen.
Das Ziel von StageHand ist es, ein leichtes, konfigurierbares Framework ohne übermäßig komplexe Abstraktionen sowie modulare Unterstützung für verschiedene Modelle und Modellanbieter bereitzustellen. Es wird Ihnen keine Pizza bestellen, aber es wird Ihnen helfen, das Web zuverlässig zu automatisieren.
Jede Stufe -Funktion nimmt eine Atomanweisung auf, z. B. act("click the login button") oder extract("find the red shoes") , erzeugt den entsprechenden Dramatikercode, um diese Anweisung zu erfüllen, und führt sie aus.
Anweisungen sollten atomar sein, um die Zuverlässigkeit zu erhöhen, und die Schrittplanung sollte vom Agenten auf höherer Ebene behandelt werden. Sie können observe() verwenden, um eine vorgeschlagene Liste von Aktionen zu erhalten, die auf der aktuellen Seite ergriffen werden können, und dann diese mithilfe dieser Stufenplanungsaufforderungen zu erdenken.
StageHand ist Open Source und wird vom Browserbase -Team gepflegt. Wir sind der Ansicht, dass wir den Markt der Entwickler erweitern, die von unserer kopflosen Browserinfrastruktur profitieren, indem wir mehr Entwicklern ermöglichen, zuverlässige Webautomatisierung aufzubauen. Dies ist der Rahmen, den wir uns wünschten, wir hätten unsere eigenen Anwendungen basteln, und wir freuen uns, es mit Ihnen zu teilen.
Wir installieren auch ZOD für die Stromversorgungsextraktion
npm install @browserbasehq/stagehand zodSie müssen Ihren API -Schlüssel für den Modellanbieter bereitstellen, den Sie verwenden möchten. Der Standardmodellanbieter ist offen, aber Sie können auch Anthropic oder andere verwenden. Weitere Informationen zu unterstützten Modellen finden Sie in der API -Referenz.
Stellen Sie sicher, dass in Ihrer lokalen Umgebung ein OpenAI -API -Schlüssel oder ein anthropischer API -Schlüssel zugänglich ist.
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-...
Wenn Sie vorhaben, den Browser lokal auszuführen, müssen Sie auch die Browser -Abhängigkeiten des Dramatiker installieren.
npm exec playwright installAnschließend können Sie eine Bühnenhandinstanz wie SO erstellen:
import { Stagehand } from "@browserbasehq/stagehand" ;
import { z } from "zod" ;
const stagehand = new Stagehand ( {
env : "LOCAL" ,
} ) ;Wenn Sie vorhaben, den Browser remote auszuführen, müssen Sie eine Browserbase -API -Taste und eine Projekt -ID festlegen.
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 } ` ) ;Dieser einfache Ausschnitt öffnet einen Browser, navigieren zum Bühnenhand -Repo und protokolliert den Top -Mitwirkenden.
Stagehand()Dieser Konstruktor wird verwendet, um eine Instanz von Bühnenhand zu erstellen.
Argumente:
env : 'LOCAL' oder 'BROWSERBASE' . Standardeinstellungen zu 'BROWSERBASE' .modelName : (optional) Eine AvailableModel -Zeichenfolge, mit der das verwendete Standardmodell angegeben werden kann.modelClientOptions : (optionale) Konfigurationsoptionen für den Modellclient.enableCaching : Ein boolean , das das Zwischenspeichern von LLM -Antworten ermöglicht. Wenn auf true festgelegt wird, werden die LLM -Anfragen auf der Festplatte zwischengespeichert und für identische Anfragen wiederverwendet. Standardmäßig false .headless : Ein boolean , der feststellt, ob der Browser im Kopflosenmodus läuft. Standardmäßig false . Wenn die Env auf BROWSERBASE eingestellt ist, wird dies ignoriert.domSettleTimeoutMs : Eine integer , die die Zeitüberschreitung in Millisekunden dafür angibt, dass das DOM gewartet wird. Standardeinstellung auf 30000 (30 Sekunden).apiKey : (optional) Ihre Browserbase -API -Schlüssel. Standardeinstellungen zur Umgebungsvariablen BROWSERBASE_API_KEY .projectId : (optional) Ihre Browserbase -Projekt -ID. Standardeinstellungen zur Umgebungsvariablen BROWSERBASE_PROJECT_ID .browserBaseSessionCreateParams : Konfigurationsoptionen zum Erstellen neuer Browserbase -Sitzungen.browserbaseResumeSessionID : ID einer vorhandenen Browserbase -Sitzung, um wieder aufzunehmen.logger : Eine Funktion, die Protokollnachrichten übernimmt. Nützlich für benutzerdefinierte Protokollierungsimplementierungen.verbose : Eine integer , die während der Automatisierung mehrere Protokollierungsstufen ermöglicht:0 : begrenzt auf keine Protokollierung1 : Protokollierung auf SDK-Ebene2 : LLM-Client Level-Protokollierung (am körnigsten)debugDom : Ein boolean , der Begrenzungsboxen um Elemente zieht, die während der Automatisierung dem LLM präsentiert werden.Rückgaben:
Stagehand .Beispiel:
// 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() initialisiert asynchron die Bühnenhandinstanz. Es sollte vor anderen Methoden aufgerufen werden.
Argumente:
modelName : (optional) Eine AvailableModel -Zeichenfolge, die das zu verwendende Modell angeben kann. Dies wird für alle anderen Methoden verwendet, sofern nicht überschrieben.modelClientOptions : (optionale) Konfigurationsoptionen für den Modell ClientdomSettleTimeoutMs : (optional) Zeitüberschreitung in Millisekunden, um darauf zu warten, dass sich das DOM niedergelassen hatRückgaben:
Promise , das sich auf ein Objekt enthält, das enthält:debugUrl : Eine string , die die URL für Live -Debugging darstellt. Dies ist nur bei Verwendung eines Browserbase -Browsers verfügbar.sessionUrl : Eine string die die Sitzungs -URL darstellt. Dies ist nur bei Verwendung eines Browserbase -Browsers verfügbar.Beispiel:
await stagehand . init ( { modelName : "gpt-4o" } ) ; act() act() ermöglicht das Bühnenhand, mit einer Webseite zu interagieren. Geben Sie eine action wie "search for 'x'" oder "select the cheapest flight presented" (kleine Atomziele geben das Beste aus).
Argumente:
action : Eine string die die auszuführende Aktion beschreibtmodelName : (optional) Eine AvailableModel -Zeichenfolge, die das verwendete Modell angeben kannmodelClientOptions : (optionale) Konfigurationsoptionen für den Modell ClientuseVision : (optional) Ein boolean oder "fallback" um festzustellen, ob eine sehbasierte Verarbeitung verwendet werden sollte. Standardeinstellungen zu "fallback"variables : (optional) Ein Record<string, string> von Variablen, die in der Aktion verwendet werden sollen. Variablen in der Aktionszeichenfolge werden mit %variable_name% referenziertdomSettleTimeoutMs : (optional) Zeitüberschreitung in Millisekunden, um darauf zu warten, dass sich das DOM niedergelassen hatRückgaben:
Promise , das sich auf ein Objekt enthält, das enthält:success : Ein boolean Angabe, ob die Aktion erfolgreich abgeschlossen wurde.message : Eine string , die Details zur Ausführung der Aktion enthält.action : Eine string die die durchgeführte Aktion beschreibt.Beispiel:
// 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() greift strukturierten Text von der aktuellen Seite mit ZOD ab. Bei Anweisungen und schema erhalten Sie strukturierte Daten. Im Gegensatz zu einigen Extraktionsbibliotheken kann StageHand Informationen auf einer Seite extrahieren, nicht nur auf dem Hauptartikelgehalt.
Argumente:
instruction : Eine string die Anweisungen zur Extraktion bereitstelltschema : Ein z.AnyZodObject das die Struktur der zu extrahierenden Daten definiertmodelName : (optional) Eine AvailableModel -Zeichenfolge, die das verwendete Modell angeben kannmodelClientOptions : (optionale) Konfigurationsoptionen für den Modell ClientdomSettleTimeoutMs : (optional) Zeitüberschreitung in Millisekunden, um darauf zu warten, dass sich das DOM niedergelassen hatRückgaben:
Promise , das sich auf die strukturierten Daten gemäß den vom bereitgestellten schema definierten Daten auflöst.Beispiel:
const price = await stagehand . extract ( {
instruction : "extract the price of the item" ,
schema : z . object ( {
price : z . number ( ) ,
} ) ,
} ) ; observe()Notiz
observe() bewertet derzeit nur den ersten Stück auf der Seite.
observe() wird verwendet, um eine Liste von Aktionen zu erhalten, die auf der aktuellen Seite ergriffen werden können. Es ist nützlich, um Ihren Planungsschritt Kontext hinzuzufügen oder ob Sie sich nicht sicher sind, auf welcher Seite Sie sich befinden.
Wenn Sie nach einem bestimmten Element suchen, können Sie auch eine Anweisung übergeben, um sie zu beobachten: observe({ instruction: "{your instruction}"}) .
Argumente:
instruction : (optional) Eine string , die Anweisungen für die Beobachtung enthält. Standardeinstellungen zum "Suchen Sie Aktionen, die auf dieser Seite ausgeführt werden können".modelName : (optional) Eine AvailableModel -Zeichenfolge, die das verwendete Modell angeben kannmodelClientOptions : (optionale) Konfigurationsoptionen für den Modell ClientuseVision : (optional) Ein boolean , um festzustellen, ob eine sehbasierte Verarbeitung verwendet werden sollte. Standardmäßig falsedomSettleTimeoutMs : (optional) Zeitüberschreitung in Millisekunden, um darauf zu warten, dass sich das DOM niedergelassen hatRückgaben:
Promise , das sich auf eine Reihe von Objekten enthält, die enthalten:selector : Eine string , die den Element -Selektor darstelltdescription : Eine string die die mögliche Aktion beschreibtBeispiel:
const actions = await stagehand . observe ( ) ; page und context page und context sind Instanzen der Page von Dramatikern und BrowserContext . Verwenden Sie diese Methoden, um mit der Dramatikerininstanz zu interagieren, die Bühnenhand verwendet. Am häufigsten verwenden Sie page.goto() um zu einer URL zu navigieren.
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;log() log() wird verwendet, um eine Nachricht an die Browserkonsole zu drucken. Diese Nachrichten werden in den Browserbase -Sitzungsprotokollen bestehen und können nach Abschluss der Sitzungen zum Debuggen verwendet werden.
Stellen Sie sicher, dass die Protokollebene über der ausführlichen Ebene liegt, die Sie bei der Initialisierung der Bühnenhandinstanz festgelegt haben.
stagehand . log ( "Hello, world!" ) ; StageHand nutzt eine generische LLM -Kundenarchitektur, um verschiedene Sprachmodelle von verschiedenen Anbietern zu unterstützen. Dieses Design ermöglicht Flexibilität und ermöglicht die Integration neuer Modelle mit minimalen Änderungen am Kernsystem. Verschiedene Modelle funktionieren besser für verschiedene Aufgaben, sodass Sie das Modell auswählen können, das Ihren Anforderungen am besten entspricht.
StageHand unterstützt derzeit die folgenden Modelle von OpenAI und Anthropic:
OpenAI -Modelle:
gpt-4ogpt-4o-minigpt-4o-2024-08-06Anthropische Modelle:
claude-3-5-sonnet-latestclaude-3-5-sonnet-20240620claude-3-5-sonnet-20241022 Diese Modelle können bei der Initialisierung der Stagehand -Instanz oder beim Aufrufen von Methoden wie act() und extract() angegeben werden.
Der SDK hat zwei Hauptphasen:
StageHand verwendet eine Kombination von Techniken, um das DOM vorzubereiten.
Die DOM -Verarbeitungsschritte sehen wie folgt aus:
Während LLMs die Kontextfensterlänge weiter erhöhen und die Latenz verringern, sollte es zuverlässiger werden, dass ein Argumentationssystem weniger nachdenkt. Infolgedessen erfolgt die DOM -Verarbeitung in Stücken, um den Kontext pro Inferenzaufruf gering zu halten. Um zu chunkieren, betrachtet der SDK ein Kandidatenelement, das in einem Abschnitt des Ansichtsfensters als Teil dieses Stücks beginnt. In Zukunft wird die Polsterung hinzugefügt, um sicherzustellen, dass ein einzelner Teil nicht den relevanten Kontext fehlt. Sehen Sie dieses Diagramm, wie es aussieht:
Die Methoden act() und observe() können ein useVision -Flag annehmen. Wenn dies auf true eingestellt ist, wird dem LLM einen kommentierten Screenshot der aktuellen Seite zur Verfügung gestellt, um zu ermitteln, auf welche Elemente zu reagieren sind. Dies ist nützlich für komplexe DOMs, über die die LLM auch nach der Verarbeitung und dem Knacken schwer zu denken hat. Standardmäßig ist dieses Flag auf "fallback" festgelegt, was bedeutet, dass StageHand, wenn das LLM ein einzelnes Element nicht erfolgreich identifiziert, den Versuch mit Vision wiederholt.
Jetzt haben wir eine Liste von Kandidatenelementen und eine Möglichkeit, sie auszuwählen. Wir können diese Elemente mit zusätzlichem Kontext für die LLM zur Extraktion oder Aktion präsentieren. Während sie in großem Maßstab nicht getestet werden, führt die Präsentation einer "nummerierten Liste von Elementen" das Modell, um den Kontext nicht als vollständige DOM zu behandeln, sondern als eine Liste der verwandten, aber unabhängigen Elemente, die Sie operieren können.
Im Handlungsfall bitten wir die LLM, eine Dramatikerinmethode zu schreiben, um die richtige Sache zu tun. Bei unseren begrenzten Tests ist die Dramatiker -Syntax viel effektiver, als sich auf eingebaute JavaScript -APIs zu verlassen, möglicherweise aufgrund der Tokenisierung.
Zuletzt verwenden wir die LLM, um zukünftige Anweisungen an sich selbst zu schreiben, um die Fortschritte und Ziele bei der Arbeit in den Teilen zu verwalten.
Im Folgenden finden Sie ein Beispiel dafür, wie Sie eine Liste von Unternehmen aus der AI Grant -Website mit StageHand und Dramatikern extrahieren können.
Das Aufsuchen von StageHand ist wörtlicher und atomischer als andere Rahmenbedingungen auf höherer Ebene, einschließlich agentener Rahmenbedingungen. Hier sind einige Richtlinien, mit denen Sie effektive Eingabeaufforderungen erstellen können:
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 ( ) ,
} ) ,
} ) ;Anstatt Aktionen zu kombinieren:
// Avoid this
await stagehand . act ( { action : "log in and purchase the first item" } ) ;Teilen Sie sie in individuelle Schritte auf:
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() um umsetzbare Vorschläge von der aktuellen Seite zu erhalten 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" } ) ;Durch die Befolgung dieser Richtlinien erhöhen Sie die Zuverlässigkeit und Effektivität Ihrer Webautomationen mit StageHand. Denken Sie daran, dass Bühnenhand sich über die Ausführung präziser, genau definierter Aktionen ausführt, sodass Ihr Anweisungen zu den besten Ergebnissen führt.
Wir überlassen das Agentenverhalten auf höhere Agentensysteme, die StageHand als Werkzeug verwenden können.
Auf hohem Niveau konzentrieren wir uns auf die Verbesserung der Zuverlässigkeit, Geschwindigkeit und Kosten in dieser Reihenfolge der Priorität.
Sie können die Roadmap hier sehen. Möchten Sie einen Beitrag leisten? Lesen Sie weiter!
Notiz
Wir schätzen die Beiträge für Bühnenhand sehr! Für Unterstützung oder Code -Überprüfung treten Sie unserer Slack -Community bei.
Zuerst klonen Sie das Repo
git clone [email protected]:browserbase/stagehand.gitDann Abhängigkeiten installieren
npm install Stellen Sie sicher, dass Sie die .env -Datei wie oben im Abschnitt Erste Schritte dokumentiert haben.
Führen Sie dann das Beispiel -Skript npm run example aus.
Eine gute Entwicklungsschleife ist:
Sie benötigen einen Braintrust -API -Schlüssel, um Evals zu führen
BRAINTRUST_API_KEY = " " Danach können Sie die Eval mit npm run evals ausführen
Es kann einige Zeit in Anspruch nehmen. Wir haben ein Convenience -Skript example.ts , in dem Sie Ihre neue Single Eval entwickeln können, bevor Sie sie zum Satz aller Evals hinzufügen.
Sie können npm run example ausführen, um die Bewertung auszuführen und zu iterieren, die Sie derzeit entwickeln.
Um dem Bühnenhand ein neues Modell hinzuzufügen, befolgen Sie die folgenden Schritte:
Definieren Sie das Modell : Fügen Sie den neuen Modellnamen dem AvailableModel -Typ in der Datei LLMProvider.ts hinzu. Dies stellt sicher, dass das Modell vom System erkannt wird.
Kartieren Sie das Modell einem Anbieter : Aktualisieren Sie die modelToProviderMap in der LLMProvider -Klasse, um das neue Modell mit seinem entsprechenden Anbieter zu verknüpfen. Diese Zuordnung ist entscheidend, um festzustellen, welcher Client verwendet werden soll.
Implementieren Sie den Client : Wenn das neue Modell einen neuen Client benötigt, implementieren Sie eine Klasse, die an der LLMClient -Schnittstelle hält. Diese Klasse sollte alle notwendigen Methoden definieren, wie z createChatCompletion .
Aktualisieren Sie die getClient -Methode : Ändern Sie die getClient -Methode in der LLMProvider -Klasse, um eine Instanz des neuen Clients zurückzugeben, wenn das neue Modell angefordert wird.
StageHand verwendet TSUP, um die SDK- und Vanille esbuild zu erstellen, um Skripte zu erstellen, die im DOM ausgeführt werden.
npm run buildnpm pack aus, um einen Tarball für die Verteilung zu erhalten Dieses Projekt stützt sich stark auf Dramatiker als ein belastbares Rückgrat, um das Web zu automatisieren. Ohne die fantastischen Techniken und Entdeckungen von Tarsier und Fuji-Web wäre es auch nicht möglich.
Jeremy Press schrieb das ursprüngliche MVP von StageHand und ist weiterhin ein wichtiger Verbündeter des Projekts.
Lizenziert unter der MIT -Lizenz.
Copyright 2024 Browserbase, Inc.
