stagehand
v1.3.0
Un marco de navegación web de IA se centró en la simplicidad y la extensibilidad.
Nota
Stagehand está actualmente disponible como lanzamiento temprano, y estamos buscando activamente comentarios de la comunidad. Únase a nuestra comunidad Slack para mantenerse actualizado sobre los últimos desarrollos y proporcionar comentarios.
StageHand es el sucesor de IA para el dramaturgo, que ofrece tres API simples ( act , extract y observe ) que proporcionan los bloques de construcción para la automatización web impulsada por el lenguaje natural.
El objetivo de StageHand es proporcionar un marco liviano y configurable, sin abstracciones demasiado complejas, así como soporte modular para diferentes modelos y proveedores de modelos. No le pedirá una pizza, pero le ayudará a automatizar de manera confiable la web.
Cada función de StageHand toma una instrucción atómica, como act("click the login button") o extract("find the red shoes") , genera el código de dramaturgo apropiado para lograr esa instrucción y lo ejecuta.
Las instrucciones deben ser atómicas para aumentar la confiabilidad, y el agente de nivel superior debe manejar la planificación de pasos. Puede usar observe() para obtener una lista sugerida de acciones que se pueden tomar en la página actual, y luego usarlas para fundamentar sus indicaciones de planificación de pasos.
StageHand es de código abierto y mantenido por el equipo de BrowserBase. Creemos que al permitir que más desarrolladores creen automatizaciones web confiables, ampliaremos el mercado de desarrolladores que se benefician de nuestra infraestructura de navegador sin cabeza. Este es el marco que deseamos tener mientras jugamos en nuestras propias aplicaciones, y estamos emocionados de compartirlo con usted.
También instalamos ZOD a la extracción de Tipado de alimentación
npm install @browserbasehq/stagehand zodDeberá proporcionar su clave API para el proveedor de modelos que desea usar. El proveedor de modelos predeterminado es OpenAI, pero también puede usar antrópico u otros. Puede encontrar más información sobre los modelos compatibles en la referencia de la API.
Asegúrese de que se pueda acceder a una tecla API de OpenAI o una clave API antrópica en su entorno local.
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-...
Si planea ejecutar el navegador localmente, también necesitará instalar las dependencias del navegador del dramaturgo.
npm exec playwright installEntonces puede crear una instancia de HapeHand como así:
import { Stagehand } from "@browserbasehq/stagehand" ;
import { z } from "zod" ;
const stagehand = new Stagehand ( {
env : "LOCAL" ,
} ) ;Si planea ejecutar el navegador de forma remota, necesitará establecer una clave de API de BrowserBase e ID de proyecto.
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 } ` ) ;Este sencillo fragmento abrirá un navegador, navegará al repositorio de Stagehand y registrará el mejor contribuyente.
Stagehand()Este constructor se utiliza para crear una instancia de StageHand.
Argumentos:
env : 'LOCAL' o 'BROWSERBASE' . El valor predeterminado es 'BROWSERBASE' .modelName : (Opcional) Una cadena de información AvailableModel para especificar el modelo predeterminado que se utilizará.modelClientOptions : (opcional) Opciones de configuración para el cliente modelo.enableCaching : un boolean que permite el almacenamiento en caché de las respuestas de LLM. Cuando se establece en true , las solicitudes de LLM se almacenarán en caché en el disco y se reutilizarán para solicitudes idénticas. El valor predeterminado es false .headless : un boolean que determina si el navegador se ejecuta en modo sin cabeza. El valor predeterminado es false . Cuando el ENV se establece en BROWSERBASE , esto será ignorado.domSettleTimeoutMs : un integer que especifica el tiempo de espera en milisegundos para esperar a que el DOM se asiente. El valor predeterminado a 30000 (30 segundos).apiKey : (Opcional) Su tecla API de BrowserBase. El valor predeterminado a BROWSERBASE_API_KEY Variable de entorno.projectId : (opcional) Su ID de proyecto de BrowserBase. El valor predeterminado a BROWSERBASE_PROJECT_ID Variable de entorno.browserBaseSessionCreateParams : Opciones de configuración para crear nuevas sesiones de BrowserBase.browserbaseResumeSessionID : ID de una sesión de BrowserBase existente para reanudar.logger : una función que maneja los mensajes de registro. Útil para implementaciones de registro personalizadas.verbose : un integer que permite varios niveles de registro durante la automatización:0 : limitado a no registrar1 : Registro de nivel SDK2 : LLM-Client Rogging (más granular)debugDom : un boolean que dibuja cajas delimitadoras alrededor de elementos presentados a la LLM durante la automatización.Devoluciones:
Stagehand configurada con las opciones especificadas.Ejemplo:
// 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() inicializa asynchronamente la instancia de StageHand. Debe llamarse antes de cualquier otro método.
Argumentos:
modelName : (Opcional) Una cadena de Emodelo AvailableModel para especificar el modelo a usar. Esto se utilizará para todos los demás métodos a menos que se anule.modelClientOptions : (opcional) Opciones de configuración para el cliente modelodomSettleTimeoutMs : (opcional) Tiempo de espera en milisegundos para esperar a que el DOM se asienteDevoluciones:
Promise que se resuelve a un objeto que contiene:debugUrl : una string que representa la URL para la depuración en vivo. Esto solo está disponible cuando se usa un navegador BrowserBase.sessionUrl : una string que representa la URL de la sesión. Esto solo está disponible cuando se usa un navegador BrowserBase.Ejemplo:
await stagehand . init ( { modelName : "gpt-4o" } ) ; act() act() permite que StageHand interactúe con una página web. Proporcione una action como "search for 'x'" o "select the cheapest flight presented" (pequeños objetivos atómicos realizan lo mejor).
Argumentos:
action : una string que describe la acción para realizarmodelName : (Opcional) Una cadena de información AvailableModel para especificar el modelo para usarmodelClientOptions : (opcional) Opciones de configuración para el cliente modelouseVision : (opcional) Un boolean o "fallback" para determinar si se debe utilizar el procesamiento basado en la visión. El valor predeterminado es "fallback"variables : (opcional) Un Record<string, string> de variables para usar en la acción. Se hace referencia a las variables en la cadena de acción utilizando %variable_name%domSettleTimeoutMs : (opcional) Tiempo de espera en milisegundos para esperar a que el DOM se asienteDevoluciones:
Promise que se resuelve a un objeto que contiene:success : un boolean que indica si la acción se completó con éxito.message : una string que proporciona detalles sobre la ejecución de la acción.action : una string que describe la acción realizada.Ejemplo:
// 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() toma texto estructurado de la página actual usando Zod. Dadas las instrucciones y schema , recibirá datos estructurados. A diferencia de algunas bibliotecas de extracción, StageHand puede extraer cualquier información en una página, no solo el contenido principal del artículo.
Argumentos:
instruction : una string que proporciona instrucciones para la extracciónschema : un z.AnyZodObject que define la estructura de los datos para extraermodelName : (Opcional) Una cadena de información AvailableModel para especificar el modelo para usarmodelClientOptions : (opcional) Opciones de configuración para el cliente modelodomSettleTimeoutMs : (opcional) Tiempo de espera en milisegundos para esperar a que el DOM se asienteDevoluciones:
Promise que se resuelve a los datos estructurados definidos por el schema proporcionado.Ejemplo:
const price = await stagehand . extract ( {
instruction : "extract the price of the item" ,
schema : z . object ( {
price : z . number ( ) ,
} ) ,
} ) ; observe()Nota
observe() actualmente solo evalúa la primera fragmentación en la página.
observe() se usa para obtener una lista de acciones que se pueden tomar en la página actual. Es útil para agregar contexto a su paso de planificación, o si no está seguro de en qué página se encuentra.
Si está buscando un elemento específico, también puede pasar una instrucción para observar a través de: observe({ instruction: "{your instruction}"}) .
Argumentos:
instruction : (Opcional) Una string que proporciona instrucciones para la observación. Los valores predeterminados para "encontrar acciones que se puedan realizar en esta página".modelName : (Opcional) Una cadena de información AvailableModel para especificar el modelo para usarmodelClientOptions : (opcional) Opciones de configuración para el cliente modelouseVision : (opcional) Un boolean para determinar si se debe utilizar el procesamiento basado en la visión. El valor predeterminado a falsedomSettleTimeoutMs : (opcional) Tiempo de espera en milisegundos para esperar a que el DOM se asienteDevoluciones:
Promise que resuelve a una matriz de objetos que contienen:selector : una string que representa el selector de elementosdescription : Una string que describe la posible acciónEjemplo:
const actions = await stagehand . observe ( ) ; page y context page y context son instancias de Page del dramaturgo y BrowserContext respectivamente. Use estos métodos para interactuar con la instancia de dramaturgo que está utilizando StageHand. Más comúnmente, usará page.goto() para navegar a una URL.
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;log() log() se usa para imprimir un mensaje en la consola del navegador. Estos mensajes se persistirán en los registros de la sesión de BrowserBase y se pueden usar para depurar sesiones después de que se hayan completado.
Asegúrese de que el nivel de registro esté por encima del nivel detallado que establezca al inicializar la instancia de StageHand.
stagehand . log ( "Hello, world!" ) ; StageHand aprovecha una arquitectura de cliente Generic LLM para admitir varios modelos de idiomas de diferentes proveedores. Este diseño permite flexibilidad, lo que permite la integración de nuevos modelos con cambios mínimos en el sistema central. Diferentes modelos funcionan mejor para diferentes tareas, por lo que puede elegir el modelo que mejor se adapte a sus necesidades.
StageHand actualmente admite los siguientes modelos de OpenAI y Anthrope:
Modelos OpenAI:
gpt-4ogpt-4o-minigpt-4o-2024-08-06Modelos antrópicos:
claude-3-5-sonnet-latestclaude-3-5-sonnet-20240620claude-3-5-sonnet-20241022 Estos modelos se pueden especificar al inicializar la instancia Stagehand o al llamar a los métodos como act() y extract() .
El SDK tiene dos fases principales:
StageHand utiliza una combinación de técnicas para preparar el DOM.
Los pasos de procesamiento DOM se ven de la siguiente manera:
Si bien los LLM continuarán aumentando la longitud de la ventana de contexto y reducirán la latencia, dar a cualquier sistema de razonamiento menos cosas en las que pensar debería hacerlo más confiable. Como resultado, el procesamiento DOM se realiza en fragmentos para mantener el contexto pequeño por llamada de inferencia. Para fragmentar, el SDK considera un elemento candidato que comienza en una sección de la ventana gráfica para ser parte de ese fragmento. En el futuro, se agregará relleno para garantizar que una fragmentación individual no carezca de contexto relevante. Vea este diagrama de cómo se ve:
Los métodos act() y observe() pueden tomar un indicador useVision . Si esto se establece en true , el LLM se proporcionará con una captura de pantalla anotada de la página actual para identificar qué elementos actuar. Esto es útil para DOM complejos de los que el LLM tiene dificultades para razonar, incluso después del procesamiento y fragmentación. De manera predeterminada, este indicador está configurado en "fallback" , lo que significa que si el LLM no identifica con éxito un solo elemento, StageHand volverá a intentar el intento de usar Visión.
Ahora tenemos una lista de elementos candidatos y una forma de seleccionarlos. Podemos presentar esos elementos con contexto adicional a la LLM para la extracción o acción. Si bien no se probó a gran escala, la presentación de una "lista numerada de elementos" guía el modelo para no tratar el contexto como un DOM completo, sino como una lista de elementos relacionados pero independientes para operar.
En el caso de la acción, le pedimos a la LLM que escriba un método de dramaturgo para hacer lo correcto. En nuestras pruebas limitadas, la sintaxis del dramaturgo es mucho más efectivo que confiar en las API de JavaScript incorporadas, posiblemente debido a la tokenización.
Por último, usamos el LLM para escribir instrucciones futuras para ayudar a administrar su progreso y objetivos cuando operamos a través de fragmentos.
A continuación se muestra un ejemplo de cómo extraer una lista de empresas del sitio web de AI Grant utilizando StageHand y Playwright.
La solicitud de StageHand es más literal y atómica que otros marcos de nivel superior, incluidos los marcos de agente. Aquí hay algunas pautas para ayudarlo a crear indicaciones efectivas:
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 ( ) ,
} ) ,
} ) ;En lugar de combinar acciones:
// Avoid this
await stagehand . act ( { action : "log in and purchase the first item" } ) ;Dividirlos en pasos individuales:
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() para obtener sugerencias procesables de la página actual 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" } ) ;Siguiendo estas pautas, aumentará la confiabilidad y la efectividad de sus automatizaciones web con StageHand. Recuerde, StageHand se destaca para ejecutar acciones precisas y bien definidas para que mantener sus instrucciones atómicas conduzca a los mejores resultados.
Dejamos el comportamiento de agente a sistemas de agente de nivel superior que pueden usar StageHand como herramienta.
En un alto nivel, estamos enfocados en mejorar la confiabilidad, la velocidad y el costo en ese orden de prioridad.
Puedes ver la hoja de ruta aquí. ¿Buscas contribuir? ¡Sigue leyendo!
Nota
¡Valoramos mucho las contribuciones a StageHand! Para el soporte o la revisión del código, únase a nuestra comunidad Slack.
Primero, clona el repositorio
git clone [email protected]:browserbase/stagehand.gitLuego instale dependencias
npm install Asegúrese de tener el archivo .env como se documenta anteriormente en la sección de inicio.
Luego, ejecute el ejemplo de npm run example .
Un buen bucle de desarrollo es:
Necesitarás una tecla API Braintust para ejecutar Evals
BRAINTRUST_API_KEY = " " Después de eso, puede ejecutar la evaluación de Evals con npm run evals
Ejecutar todas las evals puede llevar algún tiempo. Tenemos un example.ts de script de conveniencia.
Puede ejecutar npm run example para ejecutar e iterar en la evaluación que está desarrollando actualmente.
Para agregar un nuevo modelo a StageHand, siga estos pasos:
Defina el modelo : Agregue el nuevo nombre del modelo al tipo de AvailableModel en el archivo LLMProvider.ts . Esto asegura que el modelo sea reconocido por el sistema.
Mapee el modelo a un proveedor : actualice el modelToProviderMap en la clase LLMProvider para asociar el nuevo modelo con su proveedor correspondiente. Este mapeo es crucial para determinar qué cliente usar.
Implemente el cliente : si el nuevo modelo requiere un nuevo cliente, implementa una clase que se adhiere a la interfaz LLMClient . Esta clase debe definir todos los métodos necesarios, como createChatCompletion .
Actualice el método getClient : Modifique el método getClient en la clase LLMProvider para devolver una instancia del nuevo cliente cuando se solicita el nuevo modelo.
StageHand usa TSUP para construir el SDK y Vanilla esbuild para construir scripts que se ejecutan en el DOM.
npm run buildnpm pack para obtener un tarball para su distribución Este proyecto se basa en gran medida en el dramaturgo como una columna vertebral resistente para automatizar la web. Tampoco sería posible sin las increíbles técnicas y descubrimientos hechos por Tarsier y Fuji-Web.
Jeremy Press escribió el MVP original de StageHand y sigue siendo un gran aliado del proyecto.
Licenciado bajo la licencia del MIT.
Copyright 2024 BrowserBase, Inc.
