# Interaja após o scraping
> Interaja com uma página que você obteve usando prompts ou executando código.
import QuickstartPython from "/snippets/pt-BR/v2/interact/quickstart/python.mdx";
import QuickstartJS from "/snippets/pt-BR/v2/interact/quickstart/js.mdx";
import QuickstartCURL from "/snippets/pt-BR/v2/interact/quickstart/curl.mdx";
import QuickstartCLI from "/snippets/pt-BR/v2/interact/quickstart/cli.mdx";
import ExecNodePython from "/snippets/pt-BR/v2/interact/execute-node/python.mdx";
import ExecNodeJS from "/snippets/pt-BR/v2/interact/execute-node/js.mdx";
import ExecNodeCURL from "/snippets/pt-BR/v2/interact/execute-node/curl.mdx";
import ExecNodeCLI from "/snippets/pt-BR/v2/interact/execute-node/cli.mdx";
import ExecPythonPython from "/snippets/pt-BR/v2/interact/execute-python/python.mdx";
import ExecPythonJS from "/snippets/pt-BR/v2/interact/execute-python/js.mdx";
import ExecPythonCURL from "/snippets/pt-BR/v2/interact/execute-python/curl.mdx";
import ExecPythonCLI from "/snippets/pt-BR/v2/interact/execute-python/cli.mdx";
import ExecBashPython from "/snippets/pt-BR/v2/interact/execute-bash/python.mdx";
import ExecBashJS from "/snippets/pt-BR/v2/interact/execute-bash/js.mdx";
import ExecBashCURL from "/snippets/pt-BR/v2/interact/execute-bash/curl.mdx";
import ExecBashCLI from "/snippets/pt-BR/v2/interact/execute-bash/cli.mdx";
import PromptPython from "/snippets/pt-BR/v2/interact/prompt/python.mdx";
import PromptJS from "/snippets/pt-BR/v2/interact/prompt/js.mdx";
import PromptCURL from "/snippets/pt-BR/v2/interact/prompt/curl.mdx";
import PromptCLI from "/snippets/pt-BR/v2/interact/prompt/cli.mdx";
import PromptFormPython from "/snippets/pt-BR/v2/interact/prompt/python-form.mdx";
import PromptFormJS from "/snippets/pt-BR/v2/interact/prompt/js-form.mdx";
import PromptFormCURL from "/snippets/pt-BR/v2/interact/prompt/curl-form.mdx";
import PromptFormCLI from "/snippets/pt-BR/v2/interact/prompt/cli-form.mdx";
import PromptNavPython from "/snippets/pt-BR/v2/interact/prompt/python-navigate.mdx";
import PromptNavJS from "/snippets/pt-BR/v2/interact/prompt/js-navigate.mdx";
import PromptNavCURL from "/snippets/pt-BR/v2/interact/prompt/curl-navigate.mdx";
import PromptNavCLI from "/snippets/pt-BR/v2/interact/prompt/cli-navigate.mdx";
import PromptOutput from "/snippets/pt-BR/v2/interact/response/prompt-output.mdx";
import ResponseOutput from "/snippets/pt-BR/v2/interact/response/output.mdx";
import StopPython from "/snippets/pt-BR/v2/interact/stop/python.mdx";
import StopJS from "/snippets/pt-BR/v2/interact/stop/js.mdx";
import StopCURL from "/snippets/pt-BR/v2/interact/stop/curl.mdx";
import StopCLI from "/snippets/pt-BR/v2/interact/stop/cli.mdx";
import ProfilePython from "/snippets/pt-BR/v2/interact/profile/python.mdx";
import ProfileJS from "/snippets/pt-BR/v2/interact/profile/js.mdx";
import ProfileCURL from "/snippets/pt-BR/v2/interact/profile/curl.mdx";
import ProfileCLI from "/snippets/pt-BR/v2/interact/profile/cli.mdx";
import InteractFeedbackCTA from "/snippets/pt-BR/interact-feedback-cta.mdx";
Faça o scraping de uma página para obter dados limpos e, em seguida, chame `/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.
## Escolha o modelo de interação certo
| Necessidade | Use | Documentação canônica | Métodos do SDK (Node) |
| ---------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| Inicie uma sessão autônoma do navegador sem fazer scraping antes | Browser Sandbox / sessão autônoma do interagir | [Browser Sandbox](/pt-BR/features/browser), [Criar sessão do navegador](/pt-BR/api-reference/endpoint/browser-create), [Executar código no navegador](/pt-BR/api-reference/endpoint/browser-execute), [Listar sessões do navegador](/pt-BR/api-reference/endpoint/browser-list), [Excluir sessão do navegador](/pt-BR/api-reference/endpoint/browser-delete) | `browser()`, `browserExecute()`, `listBrowsers()`, `deleteBrowser()` |
| Continue a partir de um resultado de scraping usando `scrapeId` | Interagir após o scraping | [Executar interagir](/pt-BR/api-reference/endpoint/scrape-execute), [Stop interagir](/pt-BR/api-reference/endpoint/scrape-browser-delete) | `interact()`, `stopInteraction()` |
Use o interagir vinculado ao scraping quando o fluxo de trabalho começar com `POST /v2/scrape` e a resposta incluir `data.metadata.scrapeId`. Use o Browser Sandbox quando precisar de uma sessão autônoma com seu próprio ciclo de vida. O SDK Python usa os equivalentes em snake_case (`browser()`, `browser_execute()`, `list_browsers()`, `delete_browser()`, `interact()`, `stop_interaction()`).
Descreva a ação que você quer executar na página
Interaja com segurança por meio da execução de código usando playwright, agent-browser
Assista ou interaja com o navegador em tempo real por meio de um stream incorporável
## Como funciona
1. **Faça o scraping** de uma URL com `POST /v2/scrape`. A resposta inclui um `scrapeId` em `data.metadata.scrapeId`. Se você quiser persistir o estado do navegador, passe `profile` nesta solicitação.
2. **Interaja** chamando `POST /v2/scrape/{scrapeId}/interact` com um `prompt` ou com `code` do Playwright. Não passe `profile` aqui; a sessão de interação herda o perfil do job de scraping.
3. **Encerre** a sessão com `DELETE /v2/scrape/{scrapeId}/interact` quando terminar. Para perfis graváveis, as mudanças são salvas quando a sessão é encerrada.
## Início rápido
Faça o scraping de uma página, interaja com ela e encerre a sessão:
## Interaja usando prompts
A forma mais simples de interagir com uma página. Descreva o que você quer em linguagem natural, e ele clicará, digitará, rolará a página e extrairá dados automaticamente.
A resposta inclui um campo `output` com a resposta do agente:
### Mantenha os Prompts Pequenos e Focados
Prompts funcionam melhor quando cada um é uma **tarefa única e clara**. Em vez de pedir ao agente para executar um fluxo de trabalho complexo com várias etapas de uma só vez, divida isso em chamadas `interact` separadas. Cada chamada reutiliza a mesma sessão do navegador, então o estado é mantido entre elas.
## Executando código
Para ter controle total, você pode executar código diretamente no sandbox do navegador. A variável `page` (um objeto `Page` do Playwright) está disponível tanto em Node.js quanto em Python. O modo Bash vem com [agent-browser](https://github.com/vercel-labs/agent-browser) pré-instalado. Você também pode fazer capturas de tela na sessão: use `(await page.screenshot()).toString("base64")` em Node.js, `await page.screenshot(path="/tmp/screenshot.png")` em Python ou `agent-browser screenshot` no Bash.
### Node.js (Playwright)
A linguagem padrão. Escreva código Playwright diretamente. `page` já está conectado ao navegador.
### Python
Defina `language` como `"python"` para a API do Python do Playwright.
### Bash (agent-browser)
[agent-browser](https://github.com/vercel-labs/agent-browser) é uma CLI pré-instalada no sandbox com mais de 60 comandos. Ela fornece uma árvore de acessibilidade com refs de elementos (`@e1`, `@e2`, ...), o que é ideal para automação conduzida por LLM.
Comandos comuns do agent-browser:
| 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 |
| `screenshot` | Tira uma captura de tela da página atual |
| `eval "js code"` | Executa JavaScript na página |
## Visualização em tempo real
Toda resposta de `interact` retorna uma `liveViewUrl` que você pode incorporar para acompanhar o navegador em tempo real. Útil para depuração, demonstrações ou para criar UIs com navegador.
```json Response
{
"success": true,
"cdpUrl": "wss://browser.firecrawl.dev/...",
"liveViewUrl": "https://liveview.firecrawl.dev/...",
"interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
"stdout": "",
"result": "...",
"exitCode": 0
}
```
```html
```
### Visualização em tempo real interativa
A resposta também inclui uma `interactiveLiveViewUrl`. Diferentemente da visualização em tempo real padrão, que é somente para visualização, a visualização em tempo real interativa permite que os usuários cliquem, digitem e interajam com a sessão do navegador diretamente pelo stream incorporado. Isso é útil para criar interfaces de navegador voltadas para o usuário final, como fluxos de login ou fluxos de trabalho guiados em que os usuários finais precisam controlar o navegador.
```html
```
### URL do CDP
Toda resposta de interação também retorna uma `cdpUrl`: a URL WebSocket bruta do Chrome DevTools Protocol (CDP) da sessão do navegador. Use-a para se conectar diretamente à sessão ativa pelo Playwright, Puppeteer ou qualquer cliente CDP e controlar o navegador com seu próprio código.
```js
import { chromium } from "playwright";
const browser = await chromium.connectOverCDP(cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0];
```
## Ciclo de vida da sessão
### Criação
A primeira `POST /v2/scrape/{scrapeId}/interact` dá continuidade à sessão de scraping e inicia a interação.
### Reutilização
Chamadas subsequentes de `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:
```python Python
# Primeira chamada: clicar em uma aba
app.interact(scrape_id, code="await page.click('#tab-2')")
# Segunda chamada: a aba ainda está selecionada, extrair seu conteúdo
result = app.interact(scrape_id, code="await page.$eval('#tab-2-content', el => el.textContent)")
print(result.result)
```
```js Node
// Primeira chamada: clicar em uma aba
await app.interact(scrapeId, { code: "await page.click('#tab-2')" });
// Segunda chamada: a aba ainda está selecionada, extrair seu conteúdo
const result = await app.interact(scrapeId, {
code: "await page.$eval('#tab-2-content', el => el.textContent)",
});
console.log(result.result);
```
```bash CLI
# Primeira chamada: clicar em uma aba
firecrawl interact -c "await page.click('#tab-2')"
# Segunda chamada: a aba ainda está selecionada, extrair seu conteúdo
firecrawl interact -c "await page.\$eval('#tab-2-content', el => el.textContent)"
```
### Limpeza
Encerre a sessão explicitamente quando terminar:
As sessões também expiram automaticamente com base no TTL (padrão: 10 minutes) ou no tempo limite de inatividade (padrão: 5 minutes).
Sempre encerre as sessões quando terminar para evitar cobrança desnecessária. Os créditos são rateados por segundo, com uma cobrança mínima de um minuto de navegador. Sessões que usam um `prompt` consomem 7 créditos por minuto de navegador; sessões sem um prompt consomem 2. Consulte [cobrança](/pt-BR/billing#credit-costs-per-endpoint) para ver os detalhes.
## Perfis persistentes com Scrape + Interagir
Por padrão, cada sessão de scraping + interagir começa com um navegador limpo. Com `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 objeto `profile` na requisição inicial `POST /v2/scrape`. Não passe `profile` para `POST /v2/scrape/{scrapeId}/interact`; a sessão de interagir reutiliza a sessão do navegador e as configurações de perfil do scrape job. Encerre a sessão de interagir com `DELETE /v2/scrape/{scrapeId}/interact` para que mudanças graváveis no perfil possam ser salvas.
```bash cURL
curl -X POST "https://api.firecrawl.dev/v2/scrape" \
-H "Authorization: Bearer fc-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"formats": ["markdown"],
"profile": {
"name": "my-profile",
"saveChanges": true
}
}'
curl -X POST "https://api.firecrawl.dev/v2/scrape/SCRAPE_ID/interact" \
-H "Authorization: Bearer fc-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Click the login button"
}'
curl -X DELETE "https://api.firecrawl.dev/v2/scrape/SCRAPE_ID/interact" \
-H "Authorization: Bearer fc-YOUR_API_KEY"
```
O ciclo de vida do perfil é:
1. Crie o scraping com `profile.name` e `saveChanges: true`.
2. Execute interações por prompt ou código usando o `scrapeId` retornado.
3. Encerre a sessão para salvar cookies, localStorage e outros estados do navegador.
4. Inicie um scraping posterior com o mesmo `profile.name`. Use `saveChanges: false` quando quiser apenas ler o estado existente sem gravar as mudanças de volta.
| Parâmetro | Padrão | Descrição |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | None | 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 interagir é encerrada. Defina como `false` para carregar dados existentes sem gravar, o que é ú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.
O estado do navegador é salvo quando a sessão de interagir é encerrada. Sempre encerre a sessão quando terminar para que o perfil possa ser reutilizado.
### Validar a persistência
Você pode testar a persistência sem depender de um fluxo de login real gravando um valor no `localStorage` em uma sessão, encerrando-a e, em seguida, lendo esse valor em uma segunda sessão com o mesmo perfil.
```bash cURL
# Sessão 1: gravar o estado do navegador e salvá-lo
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"formats": ["markdown"],
"profile": { "name": "profile-validation", "saveChanges": true }
}')
SCRAPE_ID=$(echo "$RESPONSE" | jq -r ".data.metadata.scrapeId")
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "await page.evaluate(() => { localStorage.setItem(\"firecrawlProfileCheck\", \"saved\"); document.cookie = \"firecrawl_profile_check=saved; path=/; max-age=3600\"; return localStorage.getItem(\"firecrawlProfileCheck\"); });"
}'
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY"
```
A segunda resposta do Interagir deve mostrar `localStorage` como `"saved"` e `cookie` como `true`.
Os perfis criados via API talvez ainda não apareçam em painel > Interagir > Perfis. No momento, o painel ainda não oferece uma visão completa dos perfis persistentes criados via API.
## Quando usar o quê
| Use Case | Recommended | Why |
| --------------------------------------- | -------------------------- | --------------------------------------------- |
| Busca na web | [Search](/pt-BR/features/search) | Endpoint de busca dedicado |
| Obter conteúdo limpo de uma URL | [Scrape](/pt-BR/features/scrape) | Uma chamada de API, sem necessidade de sessão |
| Clicar, digitar e navegar em uma página | **Interagir** (prompt) | Basta descrever em inglês |
| Extrair dados por trás das interações | **Interagir** (prompt) | Não são necessários seletores |
| Lógica de scraping complexa | **Interagir** (code) | Controle total do Playwright |
**Interagir vs Browser Sandbox**: O Interagir é construído sobre a mesma infraestrutura que o [Browser Sandbox](/pt-BR/features/browser), 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
* **Somente código** (sem `prompt`): 2 créditos por minuto de sessão
* **Com prompts de IA**: 7 créditos por minuto de sessão
* **Scraping**: cobrado separadamente (1 crédito por scraping, além de quaisquer custos específicos do formato)
## Referência da API
* [Execute Interagir](/pt-BR/api-reference/endpoint/scrape-execute): `POST /v2/scrape/{scrapeId}/interact`
* [Stop Interagir](/pt-BR/api-reference/endpoint/scrape-browser-delete): `DELETE /v2/scrape/{scrapeId}/interact`
### Corpo da Requisição (POST)
| Campo | Tipo | Padrão | Descrição |
| ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `prompt` | `string` | Nenhum | Tarefa em linguagem natural para o agente de IA. Obrigatório se `code` não estiver definido. Máx. 10.000 caracteres. |
| `code` | `string` | Nenhum | 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` | Nenhum | Identificador do chamador para acompanhamento de atividades. |
### Resposta
| Field | Description |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success` | `true` se a execução for concluída sem erros |
| `cdpUrl` | URL WebSocket bruta do Chrome DevTools Protocol (CDP) para a sessão do navegador. Conecte-se diretamente com Playwright, Puppeteer ou qualquer cliente CDP |
| `liveViewUrl` | URL de visualização em tempo real somente leitura para a sessão do navegador |
| `interactiveLiveViewUrl` | URL de visualização em tempo real 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](mailto:help@firecrawl.com) ou entre em contato no [Discord](https://discord.gg/firecrawl).