stagehand
v1.3.0
Un cadre de navigation sur le Web AI s'est concentré sur la simplicité et l'extensibilité.
Note
Stagehand est actuellement disponible en première version, et nous recherchons activement les commentaires de la communauté. Veuillez rejoindre notre communauté Slack pour rester à jour sur les derniers développements et fournir des commentaires.
StageHand est le successeur alimenté par l'IA du dramaturge, offrant trois API simples ( act , extract et observe ) qui fournissent les éléments constitutifs de l'automatisation Web du langage naturel.
L'objectif de la main-d'œuvre est de fournir un cadre léger et configurable, sans abstractions trop complexes, ainsi qu'un support modulaire pour différents modèles et fournisseurs de modèles. Cela ne vous commandera pas une pizza, mais cela vous aidera à automatiser de manière fiable le Web.
Chaque fonction de stade-hand prend une instruction atomique, telle que act("click the login button") ou extract("find the red shoes") , génère le code du dramaturge approprié pour accomplir cette instruction et l'exécute.
Les instructions doivent être atomiques pour accroître la fiabilité, et la planification des étapes doit être gérée par l'agent de niveau supérieur. Vous pouvez utiliser observe() pour obtenir une liste suggérée d'actions qui peuvent être prises sur la page actuelle, puis les utiliser pour fonder vos invites de planification de pas.
StageHand est open source et maintenu par l'équipe Browserbase. Nous pensons qu'en permettant à plus de développeurs de créer des automatisations Web fiables, nous élargirons le marché des développeurs qui bénéficient de notre infrastructure de navigateur sans tête. C'est le cadre que nous souhaitions avoir en bricolant sur nos propres applications, et nous sommes ravis de le partager avec vous.
Nous installons également ZOD pour alimenter l'extraction dactylographiée
npm install @browserbasehq/stagehand zodVous devrez fournir votre clé API pour le fournisseur de modèles que vous souhaitez utiliser. Le fournisseur de modèles par défaut est OpenAI, mais vous pouvez également utiliser Anthropic ou d'autres. Plus d'informations sur les modèles pris en charge peuvent être trouvés dans la référence de l'API.
Assurez-vous qu'une clé API OpenAI ou une clé API anthropique est accessible dans votre environnement local.
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-...
Si vous prévoyez d'exécuter le navigateur localement, vous devrez également installer les dépendances du navigateur de Playwright.
npm exec playwright installEnsuite, vous pouvez créer une instance de scène comme tel:
import { Stagehand } from "@browserbasehq/stagehand" ;
import { z } from "zod" ;
const stagehand = new Stagehand ( {
env : "LOCAL" ,
} ) ;Si vous prévoyez d'exécuter le navigateur à distance, vous devrez définir une clé API et un ID de projet 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 } ` ) ;Cet extrait simple ouvrira un navigateur, accédera au dépôt de scène et enregistrera le meilleur contributeur.
Stagehand()Ce constructeur est utilisé pour créer une instance d'Handon.
Arguments:
env : 'LOCAL' ou 'BROWSERBASE' . Par défaut 'BROWSERBASE' .modelName : (facultatif) Une chaîne AvailableModel pour spécifier le modèle par défaut à utiliser.modelClientOptions : (facultatif) Options de configuration pour le client modèle.enableCaching : un boolean qui permet la mise en cache des réponses LLM. Lorsqu'il est défini sur true , les demandes LLM seront mises en cache sur le disque et réutilisées pour des demandes identiques. Par défaut est false .headless : un boolean qui détermine si le navigateur fonctionne en mode sans tête. Par défaut est false . Lorsque l'env est défini sur BROWSERBASE , cela sera ignoré.domSettleTimeoutMs : un integer qui spécifie le délai d'expiration en millisecondes pour attendre que le Dom se régalait. Par défaut, 30000 (30 secondes).apiKey : (facultatif) Votre clé API BrowserBase. Par défaut, la variable d'environnement BROWSERBASE_API_KEY .projectId : (facultatif) votre ID de projet BrowserBase. Par défaut, la variable d'environnement BROWSERBASE_PROJECT_ID .browserBaseSessionCreateParams : Options de configuration pour créer de nouvelles sessions BrowserBase.browserbaseResumeSessionID : ID d'une session de base de navigation existante à reprendre.logger : une fonction qui gère les messages de journal. Utile pour les implémentations de journalisation personnalisées.verbose : un integer qui permet plusieurs niveaux de journalisation pendant l'automatisation:0 : limité à aucune journalisation1 : journalisation de niveau SDK2 : journalisation de niveau LLM-Client (la plus granulaire)debugDom : Un boolean qui attire des boîtes de délimitation autour des éléments présentés au LLM pendant l'automatisation.Renvoie:
Stagehand configurée avec les options spécifiées.Exemple:
// 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() initialise de manière asynchrone l'instance stagehand. Il doit être appelé avant toute autre méthode.
Arguments:
modelName : (facultatif) Une chaîne AvailableModel pour spécifier le modèle à utiliser. Ceci sera utilisé pour toutes les autres méthodes à moins d'être remplacés.modelClientOptions : (facultatif) Options de configuration pour le client modèledomSettleTimeoutMs : (facultatif) Timeout en millisecondes pour attendre que le Dom se régalaitRenvoie:
Promise qui se résout à un objet contenant:debugUrl : une string représentant l'URL du débogage en direct. Ceci n'est disponible que lors de l'utilisation d'un navigateur BrowserBase.sessionUrl : une string représentant l'URL de session. Ceci n'est disponible que lors de l'utilisation d'un navigateur BrowserBase.Exemple:
await stagehand . init ( { modelName : "gpt-4o" } ) ; act() act() permet à StageHand d'interagir avec une page Web. Fournissez une action comme "search for 'x'" ou "select the cheapest flight presented" (les petits objectifs atomiques effectuent le meilleur).
Arguments:
action : une string décrivant l'action à effectuermodelName : (facultatif) Une chaîne AvailableModel pour spécifier le modèle à utilisermodelClientOptions : (facultatif) Options de configuration pour le client modèleuseVision : (facultatif) Un boolean ou un "fallback" pour déterminer si le traitement basé sur la vision doit être utilisé. Par défaut est "fallback"variables : (facultatif) Un Record<string, string> de variables à utiliser dans l'action. Les variables de la chaîne d'action sont référencées à l'aide de %variable_name%domSettleTimeoutMs : (facultatif) Timeout en millisecondes pour attendre que le Dom se régalaitRenvoie:
Promise qui se résout à un objet contenant:success : Un boolean indiquant si l'action a été achevée avec succès.message : une string fournissant des détails sur l'exécution de l'action.action : une string décrivant l'action effectuée.Exemple:
// 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() saisit du texte structuré de la page actuelle à l'aide de ZOD. Étant donné les instructions et schema , vous recevrez des données structurées. Contrairement à certaines bibliothèques d'extraction, StageHand peut extraire toutes les informations sur une page, pas seulement sur le contenu de l'article principal.
Arguments:
instruction : une string fournissant des instructions pour l'extractionschema : un z.AnyZodObject définissant la structure des données à extrairemodelName : (facultatif) Une chaîne AvailableModel pour spécifier le modèle à utilisermodelClientOptions : (facultatif) Options de configuration pour le client modèledomSettleTimeoutMs : (facultatif) Timeout en millisecondes pour attendre que le Dom se régalaitRenvoie:
Promise qui résout les données structurées telles que définies par le schema fourni.Exemple:
const price = await stagehand . extract ( {
instruction : "extract the price of the item" ,
schema : z . object ( {
price : z . number ( ) ,
} ) ,
} ) ; observe()Note
observe() n'évalue actuellement que le premier morceau de la page.
observe() est utilisé pour obtenir une liste d'actions qui peuvent être prises sur la page actuelle. Il est utile pour ajouter un contexte à votre étape de planification, ou si vous ne savez pas sur quelle page vous vous trouvez.
Si vous recherchez un élément spécifique, vous pouvez également transmettre une instruction à observer via: observe({ instruction: "{your instruction}"}) .
Arguments:
instruction : (facultatif) Une string fournissant des instructions pour l'observation. Par défaut «trouver des actions qui peuvent être effectuées sur cette page».modelName : (facultatif) Une chaîne AvailableModel pour spécifier le modèle à utilisermodelClientOptions : (facultatif) Options de configuration pour le client modèleuseVision : (facultatif) Un boolean pour déterminer si le traitement basé sur la vision doit être utilisé. Par défaut est falsedomSettleTimeoutMs : (facultatif) Timeout en millisecondes pour attendre que le Dom se régalaitRenvoie:
Promise qui se résout à un tableau d'objets contenant:selector : une string représentant le sélecteur d'élémentdescription : une string décrivant l'action possibleExemple:
const actions = await stagehand . observe ( ) ; page et context page et context sont les instances de Page de Playwright et respectivement BrowserContext . Utilisez ces méthodes pour interagir avec l'instance de dramaturge que StageHand utilise. Le plus souvent, vous utiliserez page.goto() pour naviguer vers une URL.
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;log() log() est utilisé pour imprimer un message à la console du navigateur. Ces messages seront persistés dans les journaux de session BrowserBase et peuvent être utilisés pour déboguer les sessions une fois qu'ils ont terminé.
Assurez-vous que le niveau de journal est au-dessus du niveau verbeux que vous définissez lors de l'initialisation de l'instance de scène.
stagehand . log ( "Hello, world!" ) ; STACKHand exploite une architecture client Generic LLM pour prendre en charge divers modèles de langue de différents fournisseurs. Cette conception permet la flexibilité, permettant l'intégration de nouveaux modèles avec un minimum de modifications du système central. Différents modèles fonctionnent mieux pour différentes tâches, vous pouvez donc choisir le modèle qui convient le mieux à vos besoins.
StageHand prend actuellement en charge les modèles suivants d'Openai et Anthropic:
Modèles Openai:
gpt-4ogpt-4o-minigpt-4o-2024-08-06Modèles anthropiques:
claude-3-5-sonnet-latestclaude-3-5-sonnet-20240620claude-3-5-sonnet-20241022 Ces modèles peuvent être spécifiés lors de l'initialisation de l'instance Stagehand ou lors de l'appel des méthodes comme act() et extract() .
Le SDK a deux phases majeures:
StageHand utilise une combinaison de techniques pour préparer le DOM.
Les étapes de traitement DOM sont comme suit:
Alors que les LLM continueront d'augmenter la longueur des fenêtres du contexte et de réduire la latence, donner à n'importe quel système de raisonnement moins à penser devrait le rendre plus fiable. En conséquence, le traitement DOM est effectué en morceaux afin de garder le contexte petit par appel d'inférence. Afin de se procurer, le SDK considère un élément candidat qui commence dans une section de la fenêtre pour faire partie de cette partie. À l'avenir, un rembourrage sera ajouté pour s'assurer qu'une partie individuelle ne manque pas de contexte pertinent. Voir ce diagramme pour son apparence:
Les méthodes act() et observe() peuvent prendre un drapeau useVision . Si cela est défini sur true , le LLM recevra une capture d'écran annotée de la page actuelle pour identifier les éléments à agir. Ceci est utile pour les DOM complexes sur lesquels le LLM a du mal à raisonner, même après le traitement et le groupe. Par défaut, ce drapeau est défini sur "fallback" , ce qui signifie que si le LLM ne parvient pas à identifier avec succès un seul élément, StageHand réessayera la tentative en utilisant la vision.
Nous avons maintenant une liste d'éléments candidats et un moyen de les sélectionner. Nous pouvons présenter ces éléments avec un contexte supplémentaire au LLM pour l'extraction ou l'action. Bien que non testé à grande échelle, la présentation d'une "liste numérotée d'éléments" guide le modèle pour ne pas traiter le contexte comme un DOM complet, mais comme une liste d'éléments connexes mais indépendants sur lesquels opérer.
Dans le cas de l'action, nous demandons au LLM d'écrire une méthode de dramaturge afin de faire la bonne chose. Dans nos tests limités, la syntaxe du dramaturge est beaucoup plus efficace que de compter sur les API JavaScript intégrées, peut-être en raison de la tokenisation.
Enfin, nous utilisons le LLM pour se rédiger des instructions futures pour aider à gérer ses progrès et ses objectifs lorsque vous opérez sur des morceaux.
Vous trouverez ci-dessous un exemple de la façon d'extraire une liste d'entreprises du site Web de la subvention AI en utilisant à la fois Stagehand et dramaturge.
Inviter StageHand est plus littéral et atomique que les autres cadres de niveau supérieur, y compris les cadres agentiques. Voici quelques directives pour vous aider à élaborer des invites efficaces:
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 ( ) ,
} ) ,
} ) ;Au lieu de combiner des actions:
// Avoid this
await stagehand . act ( { action : "log in and purchase the first item" } ) ;Les diviser en étapes individuelles:
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() pour obtenir des suggestions exploitables à partir de la page actuelle 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" } ) ;En suivant ces directives, vous augmenterez la fiabilité et l'efficacité de vos automations Web avec StageHand. N'oubliez pas que StageHand excelle à exécuter des actions précises et bien définies, donc garder vos instructions atomiques mènera aux meilleurs résultats.
Nous laissons le comportement agentique aux systèmes agents de niveau supérieur qui peuvent utiliser le hand-hand comme outil.
À un niveau élevé, nous nous sommes concentrés sur l'amélioration de la fiabilité, de la vitesse et du coût de cet ordre de priorité.
Vous pouvez voir la feuille de route ici. Vous cherchez à contribuer? Lisez la suite!
Note
Nous apprécions fortement les contributions à StageHand! Pour un soutien ou un examen du code, veuillez rejoindre notre communauté Slack.
Premièrement, cloner le repo
git clone [email protected]:browserbase/stagehand.gitPuis installez les dépendances
npm install Assurez-vous d'avoir le fichier .env comme documenté ci-dessus dans la section de démarrage.
Ensuite, exécutez l'exemple de script npm run example .
Une bonne boucle de développement est:
Vous aurez besoin d'une clé API cerclée pour exécuter des évals
BRAINTRUST_API_KEY = " " Après cela, vous pouvez exécuter l'évaluation en utilisant npm run evals
La gestion de tous les évals peut prendre un certain temps. Nous avons un example.ts de script de commodité.
Vous pouvez exécuter npm run example à exécuter et à itérer sur l'évalue que vous développez actuellement.
Pour ajouter un nouveau modèle à Handhand, suivez ces étapes:
Définissez le modèle : Ajoutez le nouveau nom du modèle au type AvailableModel dans le fichier LLMProvider.ts . Cela garantit que le modèle est reconnu par le système.
Carte le modèle à un fournisseur : Mettez à jour le modelToProviderMap dans la classe LLMProvider pour associer le nouveau modèle à son fournisseur correspondant. Cette cartographie est cruciale pour déterminer le client à utiliser.
Implémentez le client : si le nouveau modèle nécessite un nouveau client, implémentez une classe qui adhère à l'interface LLMClient . Cette classe doit définir toutes les méthodes nécessaires, telles que createChatCompletion .
Mettez à jour la méthode getClient : modifiez la méthode getClient dans la classe LLMProvider pour renvoyer une instance du nouveau client lorsque le nouveau modèle est demandé.
StageHand utilise TSUP pour construire le SDK et la vanille esbuild pour construire des scripts qui s'exécutent dans le DOM.
npm run buildnpm pack pour obtenir un tarball pour la distribution Ce projet s'appuie fortement sur le dramaturge en tant que dorsale résiliente pour automatiser le Web. Il ne serait pas non plus possible sans les techniques et découvertes impressionnantes faites par Tarsier et Fuji-Web.
Jeremy Press a écrit le MVP original de Stagehand et continue d'être un allié majeur du projet.
Licencié sous la licence du MIT.
Copyright 2024 Browserbase, Inc.
