stagehand
v1.3.0
Uma estrutura de navegação na Web da AI focada na simplicidade e extensibilidade.
Observação
Atualmente, Stagehand está disponível como um lançamento antecipado e estamos buscando ativamente feedback da comunidade. Junte -se à nossa comunidade Slack para se manter atualizado sobre os últimos desenvolvimentos e forneça feedback.
O StageHand é o sucessor de AI a dramaturgo, oferecendo três APIs simples ( act , extract e observe ) que fornecem os blocos de construção para a automação da Web de linguagem natural.
O objetivo do Stagehand é fornecer uma estrutura leve e configurável, sem abstrações excessivamente complexas, bem como suporte modular para diferentes modelos e provedores de modelos. Não vai pedir uma pizza para você, mas ajudará você a automatizar com segurança a web.
Cada função de mão de palco recebe uma instrução atômica, como act("click the login button") ou extract("find the red shoes") , gera o código de dramaturgo apropriado para realizar essa instrução e a executa.
As instruções devem ser atômicas para aumentar a confiabilidade, e o planejamento de etapas deve ser tratado pelo agente de nível superior. Você pode usar observe() para obter uma lista sugerida de ações que podem ser tomadas na página atual e, em seguida, usá -las para fundamentar seus avisos de planejamento de etapas.
O StageHand é de código aberto e mantido pela equipe de navegador. Acreditamos que, ao permitir que mais desenvolvedores criem automações da Web confiáveis, expandiremos o mercado de desenvolvedores que se beneficiam de nossa infraestrutura de navegador sem cabeça. Essa é a estrutura que desejávamos que tivéssemos em nossas próprias aplicações, e estamos animados em compartilhá -la com você.
Também instalamos o Zod para a extração digitada
npm install @browserbasehq/stagehand zodVocê precisará fornecer sua chave da API para o provedor de modelos que você deseja usar. O provedor de modelos padrão é o OpenAI, mas você também pode usar antropia ou outros. Mais informações sobre modelos suportados podem ser encontrados na referência da API.
Certifique -se de que uma chave da API OpenAI ou a chave API antrópica seja acessível em seu ambiente local.
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-...
Se você planeja executar o navegador localmente, também precisará instalar as dependências do navegador do dramaturgo.
npm exec playwright installEntão você pode criar uma instância de mão de palco como assim:
import { Stagehand } from "@browserbasehq/stagehand" ;
import { z } from "zod" ;
const stagehand = new Stagehand ( {
env : "LOCAL" ,
} ) ;Se você planeja executar o navegador remotamente, precisará definir uma chave de API do BrowserBase e ID do projeto.
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 snippet simples abrirá um navegador, navegará até o repositório de palco e registrará o principal colaborador.
Stagehand()Este construtor é usado para criar uma instância do StageHand.
Argumentos:
env : 'LOCAL' ou 'BROWSERBASE' . Padrões para 'BROWSERBASE' .modelName : (Opcional) Uma string AvailableModel para especificar o modelo padrão a ser usado.modelClientOptions : (opcional) Opções de configuração para o cliente Model.enableCaching : um boolean que permite o cache de respostas de LLM. Quando definido como true , as solicitações LLM serão armazenadas em cache no disco e reutilizadas para solicitações idênticas. Padrões para false .headless : um boolean que determina se o navegador é executado no modo sem cabeça. Padrões para false . Quando o Env estiver definido como BROWSERBASE , isso será ignorado.domSettleTimeoutMs : um integer que especifica o tempo limite em milissegundos por esperar que o DOM resolva. Padrão para 30000 (30 segundos).apiKey : (Opcional) Sua chave da API de navegador. Padrão para BROWSERBASE_API_KEY Ambiente Variável.projectId : (Opcional) Seu ID do projeto de navegador. Padrão para BROWSERBASE_PROJECT_ID Ambiente Variável.browserBaseSessionCreateParams : Opções de configuração para criar novas sessões de navegador.browserbaseResumeSessionID : ID de uma sessão de navegador existente para retomar.logger : uma função que lida com mensagens de log. Útil para implementações de log personalizadas.verbose : um integer que permite vários níveis de log durante a automação:0 : limitado a nenhum registro1 : registro de nível SDK2 : Freeção de nível LLM-Client (mais granular)debugDom : um boolean que atrai caixas delimitadoras em torno dos elementos apresentados ao LLM durante a automação.Retornos:
Stagehand configurada com as opções especificadas.Exemplo:
// 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 assíncrona a instância do palco. Deve ser chamado antes de quaisquer outros métodos.
Argumentos:
modelName : (Opcional) Uma string AvailableModel para especificar o modelo a ser usado. Isso será usado para todos os outros métodos, a menos que seja substituído.modelClientOptions : (opcional) Opções de configuração para o cliente Model ClientdomSettleTimeoutMs : (Opcional) Timeout em milissegundos por esperar que o DOM resolvaRetornos:
Promise que resolve a um objeto que contém:debugUrl : Uma string que representa o URL para depuração ao vivo. Isso só está disponível ao usar um navegador de navegador.sessionUrl : uma string representando o URL da sessão. Isso só está disponível ao usar um navegador de navegador.Exemplo:
await stagehand . init ( { modelName : "gpt-4o" } ) ; act() act() permite que o StageHand interaja com uma página da web. Forneça uma action como "search for 'x'" ou "select the cheapest flight presented" (pequenos objetivos atômicos têm o melhor desempenho).
Argumentos:
action : Uma string descrevendo a ação para executarmodelName : (Opcional) Uma sequência AvailableModel para especificar o modelo para usarmodelClientOptions : (opcional) Opções de configuração para o cliente Model ClientuseVision : (Opcional) Um boolean ou "fallback" para determinar se o processamento baseado na visão deve ser usado. Padrões de "fallback"variables : (opcional) Um Record<string, string> de variáveis a serem usadas na ação. As variáveis na sequência de ação são referenciadas usando %variable_name%domSettleTimeoutMs : (Opcional) Timeout em milissegundos por esperar que o DOM resolvaRetornos:
Promise que resolve a um objeto que contém:success : um boolean indicando se a ação foi concluída com sucesso.message : uma string fornecendo detalhes sobre a execução da ação.action : Uma string descrevendo a ação executada.Exemplo:
// 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() pega texto estruturado na página atual usando o Zod. Dadas as instruções e schema , você receberá dados estruturados. Ao contrário de algumas bibliotecas de extração, o StageHand pode extrair qualquer informação em uma página, não apenas o conteúdo principal do artigo.
Argumentos:
instruction : Uma string fornecendo instruções para extraçãoschema : um z.AnyZodObject Definindo a estrutura dos dados para extrairmodelName : (Opcional) Uma sequência AvailableModel para especificar o modelo para usarmodelClientOptions : (opcional) Opções de configuração para o cliente Model ClientdomSettleTimeoutMs : (Opcional) Timeout em milissegundos por esperar que o DOM resolvaRetornos:
Promise que resolve os dados estruturados, conforme definido pelo schema fornecido.Exemplo:
const price = await stagehand . extract ( {
instruction : "extract the price of the item" ,
schema : z . object ( {
price : z . number ( ) ,
} ) ,
} ) ; observe()Observação
observe() atualmente avalia apenas o primeiro pedaço da página.
observe() é usado para obter uma lista de ações que podem ser tomadas na página atual. É útil para adicionar contexto à sua etapa de planejamento ou se você não tiver certeza de em que página está.
Se você estiver procurando por um elemento específico, também pode passar uma instrução para observar via: observe({ instruction: "{your instruction}"}) .
Argumentos:
instruction : (Opcional) Uma string que fornece instruções para a observação. Padrões para "encontrar ações que possam ser executadas nesta página".modelName : (Opcional) Uma sequência AvailableModel para especificar o modelo para usarmodelClientOptions : (opcional) Opções de configuração para o cliente Model ClientuseVision : (Opcional) Um boolean para determinar se o processamento baseado na visão deve ser usado. Padrões para falsedomSettleTimeoutMs : (Opcional) Timeout em milissegundos por esperar que o DOM resolvaRetornos:
Promise que resolve uma variedade de objetos contendo:selector : uma string representando o seletor de elementosdescription : Uma string descrevendo a ação possívelExemplo:
const actions = await stagehand . observe ( ) ; page e context page e context são instâncias da Page e do dramaturgo e BrowserContext , respectivamente. Use esses métodos para interagir com a instância do dramaturgo que o StageHand está usando. Geralmente, você usará page.goto() para navegar para um URL.
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;log() log() é usado para imprimir uma mensagem no console do navegador. Essas mensagens serão persistidas nos logs da sessão do navegador e podem ser usados para depurar sessões após a conclusão.
Verifique se o nível de log está acima do nível detalhado que você define ao inicializar a instância do StageHand.
stagehand . log ( "Hello, world!" ) ; O StageHand aproveita uma arquitetura genérica de clientes LLM para suportar vários modelos de idiomas de diferentes fornecedores. Esse design permite flexibilidade, permitindo a integração de novos modelos com alterações mínimas no sistema principal. Modelos diferentes funcionam melhor para tarefas diferentes, para que você possa escolher o modelo que melhor atenda às suas necessidades.
Atualmente, o StageHand suporta os seguintes modelos do OpenAI e Antrópico:
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 Esses modelos podem ser especificados ao inicializar a instância Stagehand ou quando chama métodos como act() e extract() .
O SDK tem duas fases principais:
O StageHand usa uma combinação de técnicas para preparar o DOM.
As etapas de processamento DOM parecem o seguinte:
Enquanto o LLMS continuará aumentando a comprimento da janela de contexto e reduzindo a latência, oferecendo a qualquer sistema de raciocínio que menos o que pensar deve torná -lo mais confiável. Como resultado, o processamento DOM é feito em pedaços para manter o contexto pequeno por chamada de inferência. Para se fundir, o SDK considera um elemento candidato que começa em uma seção da viewport como parte desse pedaço. No futuro, o preenchimento será adicionado para garantir que um pedaço individual não tenha um contexto relevante. Veja este diagrama de como ele parece:
Os métodos act() e observe() podem assumir um sinalizador useVision . Se isso estiver definido como true , o LLM receberá uma captura de tela anotada da página atual para identificar em quais elementos agirem. Isso é útil para DOMs complexos sobre os quais o LLM tem dificuldade em raciocinar, mesmo após o processamento e o ritmo. Por padrão, esse sinalizador está definido como "fallback" , o que significa que, se o LLM não conseguir identificar com êxito um único elemento, o StageHand voltará a tentar usar a visão.
Agora temos uma lista de elementos candidatos e uma maneira de selecioná -los. Podemos apresentar esses elementos com contexto adicional ao LLM para extração ou ação. Embora não testado em larga escala, apresentar uma "lista numerada de elementos" orienta o modelo a não tratar o contexto como um DOM completo, mas como uma lista de elementos relacionados, mas independentes, para operar.
No caso de ação, pedimos ao LLM que escreva um método dramaturgo para fazer a coisa correta. Em nossos testes limitados, a sintaxe do dramaturgo é muito mais eficaz do que confiar nas APIs de JavaScript incorporadas, possivelmente devido à tokenização.
Por fim, usamos o LLM para escrever instruções futuras para ajudar a gerenciar seus progressos e objetivos ao operar em pedaços.
Abaixo está um exemplo de como extrair uma lista de empresas do site da AI Grant usando o Stagehand e o dramaturgo.
A solicitação de palco é mais literal e atômica do que outras estruturas de nível superior, incluindo estruturas Agentic. Aqui estão algumas diretrizes para ajudá -lo a criar instruções eficazes:
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 ( ) ,
} ) ,
} ) ;Em vez de combinar ações:
// Avoid this
await stagehand . act ( { action : "log in and purchase the first item" } ) ;Divida -os em etapas individuais:
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 obter sugestões acionáveis da página atual 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" } ) ;Seguindo essas diretrizes, você aumentará a confiabilidade e a eficácia de suas automações na Web com o StageHand. Lembre-se de que o Stagehand se destaca na execução de ações precisas e bem definidas, portanto, manter suas instruções Atomic levará aos melhores resultados.
Deixamos o comportamento agêntico para sistemas agênticos de nível superior que podem usar o StageHand como uma ferramenta.
Em um nível alto, estamos focados em melhorar a confiabilidade, velocidade e custo nessa ordem de prioridade.
Você pode ver o roteiro aqui. Procurando contribuir? Leia!
Observação
Valorizamos muito as contribuições para o StageHand! Para obter suporte ou revisão de código, junte -se à nossa comunidade Slack.
Primeiro, clone o repo
git clone [email protected]:browserbase/stagehand.gitEm seguida, instale dependências
npm install Certifique -se de ter o arquivo .env , conforme documentado acima na seção de início.
Em seguida, execute o exemplo de exemplo de script npm run example .
Um bom loop de desenvolvimento é:
Você precisará de uma chave de API Braintrust para executar o Evalals
BRAINTRUST_API_KEY = " " Depois disso, você pode executar a avaliação usando npm run evals
Executar todos os Evalas pode levar algum tempo. Temos um example.ts de script de conveniência.
Você pode executar npm run example para executar e iterar na avaliação que está desenvolvendo atualmente.
Para adicionar um novo modelo ao palco, siga estas etapas:
Defina o modelo : adicione o novo nome do modelo ao tipo de modelo AvailableModel no arquivo LLMProvider.ts . Isso garante que o modelo seja reconhecido pelo sistema.
Mapeie o modelo para um provedor : atualize o modelToProviderMap na classe LLMProvider para associar o novo modelo ao seu provedor correspondente. Esse mapeamento é crucial para determinar qual cliente usar.
Implementar o cliente : se o novo modelo exigir um novo cliente, implemente uma classe que adere à interface LLMClient . Esta classe deve definir todos os métodos necessários, como createChatCompletion .
Atualize o método getClient : modifique o método getClient na classe LLMProvider para retornar uma instância do novo cliente quando o novo modelo for solicitado.
O StageHand usa o TSUP para construir o SDK e a baunilha esbuild para criar scripts que são executados no DOM.
npm run buildnpm pack para obter um tarball para distribuição Este projeto depende muito do dramaturgo como uma espinha dorsal resiliente para automatizar a web. Também não seria possível sem as impressionantes técnicas e descobertas feitas por Tarsier e Fuji-Web.
Jeremy Press escreveu o MVP original do Stagehand e continua sendo um grande aliado do projeto.
Licenciado sob a licença do MIT.
Copyright 2024 BrowserBase, Inc.
