Resposta rápida
Se um agente na Cloudflare perde a aba ou volta deslogado a cada turno, use Agents SDK 0.28.0 ou posterior e instale uma única instância de Browser com o provedor browserRun. Registre esse Browser e o harness no Lifecycle do Durable Object e entregue ao modelo o novo browserTool. Enquanto a sessão do Browser Run permanecer ativa, o agente pode retomar abas, cookies e login depois de novas mensagens e da hibernação do objeto.
Isso não cria uma sessão permanente. O navegador pode expirar por inatividade, ser fechado, falhar ou ser reciclado. Quando o resultado trouxer restarted: true, considere todo o estado anterior perdido: reabra a página, confirme a conta e recupere o contexto antes de qualquer ação de escrita. Não repita automaticamente um clique ou envio interrompido, pois ele pode já ter sido concluído.
O que mudou em 13 de outubro de 2026
A Cloudflare adicionou ao Agents SDK um browserTool persistente baseado em Browser Run. O modelo continua controlando Chromium por Chrome DevTools Protocol, mas agora a classe Browser guarda o identificador remoto e permite que o Durable Object se reconecte depois de hibernar, desde que a sessão ainda exista.
O recurso resolve o padrão em que uma ferramenta de navegador abre uma sessão nova a cada chamada e perde navegação, cookies e autenticação. A nota oficial exige Agents SDK 0.28.0 ou posterior. Cada conversa Pi recebe uma aba ativa própria por padrão, embora cookies e logins continuem compartilhados dentro da mesma instância de Browser.
Estrutura mínima para ativar a persistência
O Worker precisa dos bindings Browser Run e Worker Loader. No código, importe Browser e browserRun de agents/browser, browserTool de agents/browser/pi e Lifecycle de agents/lifecycle. Crie Browser com o binding BROWSER, instale browserTool no registro do harness usando ctx, browser e LOADER e inclua browser e harness no mesmo Lifecycle.
Exporte também CodemodeRuntime de agents/browser, conforme o exemplo oficial. Sem o Loader ou sem o runtime durável, o modelo não terá o ambiente usado para executar os comandos CDP. Depois do deploy, faça um teste simples em duas mensagens: abra uma página na primeira, leia a URL e um elemento na segunda e confirme que o agente voltou à mesma aba.
- Atualize o pacote agents para a versão 0.28.0 ou posterior.
- Declare os bindings BROWSER e LOADER no projeto.
- Crie uma instância de Browser com browserRun(this.env.BROWSER).
- Instale browserTool no registro do harness e passe this.ctx, browser e LOADER.
- Registre browser e harness com Lifecycle.install(this).use(...).
- Faça deploy e valide a retomada em uma conversa de teste sem dados reais.
Hibernação do agente não garante navegador vivo
O Browser roda fora do Durable Object. Quando o objeto hiberna, ele preserva o identificador da sessão e tenta se reconectar depois. A retomada só funciona se o navegador remoto continuar ativo. Por padrão, a integração persistente mantém uma sessão ociosa por até dez minutos; um crash, encerramento explícito ou evento de infraestrutura também pode eliminar o estado.
Trate a página atual como cache operacional, não como banco de dados. Guarde no armazenamento do agente apenas o mínimo necessário para reconstruir a tarefa, como URL segura, etapa confirmada e identificador interno idempotente. Não armazene senha, cookie ou token em mensagens, logs ou estado de aplicação para tentar recriar o login.
Como tratar restarted sem duplicar ações
Quando a sessão anterior expira ou falha, a próxima utilização cria outro navegador e sinaliza restarted: true ao escopo que retornou. O browserTool continua executando na nova sessão, mas não restaura as abas antigas. Antes de navegar, o agente precisa abandonar seletores e identificadores de elementos coletados na sessão anterior.
Uma chamada interrompida não é repetida automaticamente pelo Pi porque um novo envio poderia duplicar uma compra, mensagem, formulário ou alteração. A recuperação segura é baseada no estado do sistema de destino: confira histórico, confirmação, identificador idempotente ou resposta da API antes de decidir entre continuar, repetir ou pedir aprovação humana.
- Detecte restarted: true e invalide todo o estado de página guardado em memória.
- Volte a uma URL conhecida e confirme domínio, conta e ambiente.
- Consulte o sistema de destino para verificar se a ação anterior foi concluída.
- Repita apenas operações idempotentes ou comprovadamente não executadas.
- Exija aprovação humana novamente quando o efeito externo não puder ser confirmado.
Separe abas de conversas e sessões de usuários
Cada conversa Pi recebe uma aba ativa própria por padrão, e sessões, forks ou subagentes podem trabalhar em páginas diferentes. Esse isolamento de aba não separa cookies nem login. Se duas pessoas compartilharem o mesmo Browser, ambas poderão herdar a mesma sessão autenticada; use navegadores distintos quando contas ou usuários precisarem de isolamento real.
Dentro de uma conversa, as chamadas do navegador são executadas em sequência. Para compartilhar deliberadamente uma aba entre escopos, use a mesma scope string. Evite esse compartilhamento em tarefas de clientes diferentes e não dependa do nome da aba como controle de autorização. A autorização deve ser validada no servidor e no início de cada fluxo sensível.
Controle tempo, concorrência e custo
No plano Workers Free, o Browser Run inclui dez minutos por dia, até três navegadores concorrentes e a criação de uma nova instância a cada vinte segundos. No plano pago, há dez horas mensais incluídas e cobrança informada de US$ 0,09 por hora adicional; sessões diretas também entram no cálculo de navegadores concorrentes.
Persistência reduz inicializações, mas uma sessão esquecida continua consumindo tempo até expirar. Mantenha o browser vivo somente durante a janela em que o agente realmente precisará retornar. Ao concluir o fluxo, chame browser.close(); a próxima utilização criará uma sessão nova e marcará restarted. Monitore o painel Browser Run para encontrar sessões ociosas e picos de concorrência.
Live View e gravação exigem cuidado com privacidade
A classe Browser pode fornecer Live View das abas e também trabalhar com gravação de sessão. A gravação persistente atravessa turnos e todos os escopos que compartilham o mesmo Browser até o encerramento. Mesmo com campos de entrada mascarados pelo rrweb, páginas, respostas, nomes de conta e outras informações internas podem aparecer.
As gravações ficam retidas por 30 dias e são limitadas a duas horas por sessão, segundo a documentação atual. Restrinja quem recebe a URL de Live View, proteja o token usado para buscar a gravação e nunca anexe o arquivo bruto a uma issue pública. Use uma instância separada para homologação quando precisar depurar um fluxo autenticado.
Limitações e próxima ação útil
Este guia foi verificado em 14 de outubro de 2026. O browserTool persistente documentado é voltado ao Agents SDK e a adaptadores compatíveis; ele não transforma Quick Actions nem o navegador Kitesurf em uma sessão autenticada de longa duração. Kitesurf permanece inadequado para esse caso, e a persistência depende do Chromium do Browser Run.
Crie agora um agente de homologação com uma conta sem privilégios: abra uma página, volte em outro turno, force browser.close() e confirme que restarted aparece e que o fluxo não repete uma ação. Depois valide isolamento entre duas conversas, tempo ocioso, custo, Live View e recuperação antes de liberar acesso a contas reais.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- New persistent browser tool in the Agents SDKCloudflare Changelog
- BrowserCloudflare Agents Docs
- Browser agentCloudflare Agents Docs
- Browser Run limitsCloudflare Docs
- Browser Run pricingCloudflare Docs
- Browser close reasonsCloudflare Docs
- Cloudflare StatusCloudflare