Navegação em portais

A percepção da página é textual. Cada ação devolve um snapshot da árvore de acessibilidade — papéis, nomes e referências de elementos —, não uma imagem.

Duas consequências que valem repetir:

• O agent não vê a captura de tela. browser_screenshot existe para o humano que audita a session: a imagem vai para o artifact store e o modelo recebe só a confirmação. A nota proíbe explicitamente concluir qualquer coisa "olhando" uma captura.
• browser_read é a leitura barata. Ela não invalida referências, então o agent extrai um valor de uma região sem repuxar a página inteira nem perder o alvo em que ia clicar.

O snapshot cobre a página inteira, não apenas a área visível, e é cortado quando estoura o orçamento de caracteres — o corte aparece como … (N nós omitidos). Nesse caso a nota manda focar a leitura numa região em vez de rolar atrás do resto.

O agent age por ref, nunca por seletor CSS. Um ref tem a forma e12@v3: o identificador do elemento mais a geração em que ele foi emitido. Elementos dentro de um iframe ganham prefixo de frame (f1e12@v3) e se usam do mesmo jeito.

A geração é da página, não da ação (ver D112). Ela avança quando a página navega — e só então. Enquanto o agent permanece na mesma página, os refs que ele já tem continuam válidos depois de digitar, clicar ou selecionar; é isso que permite preencher um formulário inteiro num browser_batch só.

Isso não afrouxa a segurança, porque as duas falhas possíveis são fechadas e distintas:

Por que a distinção importa: numa página nova o navegador reinicia a numeração de refs (e1, e2, …), então um ref antigo casaria outro elemento — daí a geração. Dentro da mesma página o número nunca é reaproveitado, então um ref cujo elemento morreu simplesmente não resolve. Em nenhum dos casos o agent aciona o elemento errado.

Falha de ação devolve o snapshot atual junto da mensagem. Sem observação nova, um agent tende a repetir a mesma chamada e queimar turnos; com o estado na mesma resposta, o turno seguinte já escolhe um ref que existe.

Três situações interrompem fluxos de portal em produção, e a nota trata as três nominalmente:

• Banner de cookie e modal interceptam clique. Diante de dialog/alertdialog/banner, o agent resolve o overlay antes de mirar o alvo real. Em escolha de privacidade, ele recusa os não-essenciais.
• Modal no meio do fluxo (aviso de expiração, confirmação, tour) é tratado como interrupção: o agent resolve e retoma o passo interrompido, sem reiniciar a tarefa.
• Portais deslogam sozinhos. Se o conteúdo esperado sumiu ou a tela de login reapareceu, o agent trata como sessão expirada e confirma o estado antes de seguir — em vez de reportar que o dado não existe.

A regra mais importante da nota: ação que falhou não se repete igual. O agent relê o estado e muda de abordagem — outro elemento com o mesmo papel, o menu em vez do atalho, a URL direta em vez do fluxo.

Isso vale para a falha de tool e vale para o silêncio: clique sem efeito é sinal de overlay ou de ref velho, não convite para clicar de novo.

Para browser_login a distinção é mais fina e está detalhada em Login em portal: "recusado pelo portal" é resultado (a credencial não presta, o agent para), enquanto captcha pendente ou estouro de orçamento não provam nada sobre a credencial (o agent tira um snapshot e tenta de novo).

browser_batch roda várias ações numa chamada, sem round-trip ao modelo entre passos. A nota o restringe a sequência já conhecida — tipicamente preencher N campos e submeter.

O limite que o agent respeita: todo ref do lote vem do snapshot que ele já tem, e vale por todos os passos enquanto nenhum passo navegar. Digitar N campos e clicar em enviar numa chamada só é exatamente o uso previsto. Assim que um passo navega (navigate, back, ou um clique que carrega outra página), os refs anteriores morrem e os passos seguintes que os usarem falham com browser.stale_ref — o agent faz uma chamada nova depois de ver o snapshot novo. Um passo também não pode usar um ref que só nasce depois de outro passo mudar a página. Em página imprevisível, a nota manda voltar para uma ação por vez.

Quando nenhum passo do lote dá certo, a resposta inclui o estado atual da página — o agent não fica sem informação nova para decidir o próximo turno.

browser_login recebe apenas um credentialId. Usuário e senha são resolvidos e digitados dentro do perímetro do navegador e nunca chegam ao modelo, ao log ou ao event log. A nota reforça a proibição do outro lado: o agent não pede, não escreve e não repete uma senha — nem quando a página pede.

Os ids disponíveis chegam ao agent numa seção própria do system prompt, montada a partir dos vaults da session. Ver Vaults.

A nota cabe no prompt de toda session com browser, então ela é curta de propósito. O procedimento longo — reconhecimento de página, formulário com campos que mudam a estrutura, paginação de resultados, extração fiel de valores, tabela de recuperação por tipo de erro e critérios de quando pedir ajuda — vive numa skill de fábrica, navegacao-de-portal, versionada no repositório da plataforma.

Skills são carregadas sob demanda: só o índice (nome + descrição) ocupa espaço no prompt, e o corpo entra quando o agent abre a skill. Anexe-a a agents de portal quando a tarefa for mais longa que "abrir uma página e ler um valor". Ver Skills.

• Login em portal (browser_login)
• Executor e browser
• Tools e MCP
• Vaults