/interact para começar a realizar ações nessa página - clicar em botões, preencher formulários, extrair conteúdo dinâmico ou navegar mais profundamente. Basta descrever o que você quer, ou escrever código se precisar de controle total.
Prompts de IA
Descreva a ação que você quer executar na página
Execução de código
Interaja com segurança por meio da execução de código usando playwright, agent-browser
Visualização em tempo real
Assista ou interaja com o navegador em tempo real por meio de um stream incorporável
Como funciona
- Faça o scraping de uma URL com
POST /v2/scrape. A resposta inclui umscrapeIdemdata.metadata.scrapeId. Opcionalmente, passe umprofilepara persistir o estado do navegador entre sessões. - Interaja chamando
POST /v2/scrape/{scrapeId}/interactcom umpromptou comcodedo Playwright. Na primeira chamada, a sessão extraída é retomada e você pode começar a interagir com a página. - Encerre a sessão com
DELETE /v2/scrape/{scrapeId}/interactquando terminar.
Início rápido
Response
Interaja usando prompts
output com a resposta do agente:
Response
Mantenha os Prompts Pequenos e Focados
interact separadas. Cada chamada reutiliza a mesma sessão do navegador, então o estado é mantido entre elas.
Executando código
page (um objeto Page do Playwright) está disponível tanto em Node.js quanto em Python. O modo Bash vem com agent-browser pré-instalado.
Node.js (Playwright)
page já está conectado ao navegador.
Python
language como "python" para a API do Python do Playwright.
Bash (agent-browser)
@e1, @e2, …) — ideal para automação conduzida por LLM.
| Comando | Descrição |
|---|---|
snapshot | Árvore de acessibilidade completa com refs de elementos |
snapshot -i | Apenas elementos interativos |
click @e1 | Clica no elemento pela ref |
fill @e1 "text" | Limpa o campo e digita o texto |
type @e1 "text" | Digita sem limpar |
press Enter | Pressiona uma tecla do teclado |
scroll down 500 | Rola 500 pixels para baixo |
get text @e1 | Obtém o conteúdo de texto |
get url | Obtém a URL atual |
wait @e1 | Aguarda o elemento |
wait --load networkidle | Aguarda a rede ficar inativa |
find text "X" click | Encontra o elemento pelo texto e clica |
eval "js code" | Executa JavaScript na página |
visualização em tempo real
| Field | Description |
|---|---|
liveViewUrl | Transmissão somente leitura — incorpore para assistir à sessão |
interactiveLiveViewUrl | Transmissão interativa — os espectadores podem clicar, digitar e interagir |
Ciclo de vida da sessão
Criação
POST /v2/scrape/{scrapeId}/interact cria uma sessão do navegador em sandbox no mesmo estado da página que o seu scrape.
Reutilização
interact no mesmo scrapeId reutilizam a sessão existente. O navegador permanece aberto e mantém seu estado entre as chamadas, para que você possa encadear várias interações:
Limpeza
Perfis persistentes
profile, você pode salvar e reutilizar o estado do navegador (cookies, localStorage, sessões) entre scrapes. Isso é útil para continuar conectado e preservar preferências.
Passe o parâmetro profile ao chamar o scraping. Sessões com o mesmo nome de perfil compartilham o estado.
| Parâmetro | Padrão | Descrição |
|---|---|---|
name | — | Um nome para o perfil persistente. Scrapes com o mesmo nome compartilham o estado do navegador. |
saveChanges | true | Quando true, o estado do navegador é salvo novamente no perfil quando a sessão de interact é encerrada. Defina como false para carregar dados existentes sem gravar — útil quando você precisa de vários leitores simultâneos. |
Apenas uma sessão pode salvar em um perfil por vez. Se outra sessão já estiver salvando, você receberá um erro
409. Você ainda pode abrir o mesmo perfil com saveChanges: false ou tentar novamente mais tarde.Quando usar o quê
| Use Case | Recommended | Why |
|---|---|---|
| Busca na web | Search | Endpoint de busca dedicado |
| Obter conteúdo limpo de uma URL | Scrape | Uma chamada de API, sem necessidade de sessão |
| Clicar, digitar e navegar em uma página | Interact (prompt) | Basta descrever em inglês |
| Extrair dados por trás das interações | Interact (prompt) | Não são necessários seletores |
| Lógica de scraping complexa | Interact (code) | Controle total do Playwright |
Interact vs Browser Sandbox: O Interact é construído sobre a mesma infraestrutura que o Browser Sandbox, mas oferece uma interface melhor para o padrão mais comum — fazer scrape de uma página e depois se aprofundar. O Browser Sandbox é melhor quando você precisa de uma sessão do navegador independente que não esteja vinculada a um scrape específico.
Preços
Referência da API
- Execute Interact —
POST /v2/scrape/{scrapeId}/interact - Stop Interact —
DELETE /v2/scrape/{scrapeId}/interact
Corpo da Requisição (POST)
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
prompt | string | — | Tarefa em linguagem natural para o agente de IA. Obrigatório se code não estiver definido. Máx. 10.000 caracteres. |
code | string | — | Código a ser executado (Node.js, Python ou Bash). Obrigatório se prompt não estiver definido. Máx. 100.000 caracteres. |
language | string | "node" | "node", "python" ou "bash". Usado apenas com code. |
timeout | number | 30 | Tempo limite em segundos (1–300). |
origin | string | — | Identificador do chamador para acompanhamento de atividades. |
Resposta
| Field | Description |
|---|---|
success | true se a execução for concluída sem erros |
liveViewUrl | URL de visualização ao vivo somente leitura para a sessão do navegador |
interactiveLiveViewUrl | URL de visualização ao vivo interativa (os visualizadores podem controlar o navegador) |
output | A resposta em linguagem natural do agente ao seu prompt. Presente apenas ao usar prompt. |
stdout | Saída padrão da execução do código |
result | Valor bruto retornado do sandbox. Para code: a última expressão avaliada. Para prompt: o snapshot bruto da página que o agente usou para produzir output. |
stderr | Saída de erro padrão |
exitCode | Código de saída (0 = sucesso) |
killed | true se a execução tiver sido encerrada devido a tempo limite |
Tem feedback ou precisa de ajuda? Envie um e-mail para help@firecrawl.com ou entre em contato no Discord.

