Login em portal (browser_login)
O contrato da tool que autentica o agent num portal: as três saídas possíveis, o orçamento de tempo e o que fazer em cada caso.
browser_login autentica a página atual do browser com uma credencial guardada em vault, referenciada por id. O usuário e a senha são resolvidos e digitados dentro do perímetro do browser e nunca voltam ao modelo, ao log ou ao event log.
Esta página interessa a quem constrói agent de portal: o agent precisa saber distinguir "a credencial não presta" de "o login não terminou", porque as duas levam a decisões opostas.
#Entrada
| Campo | Tipo | Observação |
|---|---|---|
credentialId | string | Credencial portal_login no vault montado na session. Obrigatório. |
usernameSelector | string | Seletor do campo de usuário. Opcional — há heurística padrão. |
passwordSelector | string | Seletor do campo de senha. Opcional. |
submitSelector | string | Seletor do botão de envio. Opcional. |
Navegue até a página de login antes de chamar a tool.
#Três saídas distintas
| Saída | Forma | O que significa |
|---|---|---|
| Sucesso | tool_result normal | Autenticado. A resposta é uma confirmação curta com o usuário mascarado. |
| Recusa do portal | tool_result normal | A credencial foi submetida e o portal recusou. Uma captura de diagnóstico fica armazenada. |
| Não concluiu | tool_result com isError | Nada foi provado sobre a credencial. Ver os códigos abaixo. |
A distinção é o ponto do contrato. Recusa quer dizer "a credencial não presta": o agent desiste ou tenta outra credencial. Não concluiu não diz nada sobre a credencial — devolver "recusado" ali empurraria o agent para a decisão errada.
| Código | Categoria | Quando |
|---|---|---|
browser.captcha_pending | unprocessable | O browser gerenciado ainda estava resolvendo um captcha quando o orçamento acabou. |
browser.login_timeout | unprocessable | O login não terminou dentro do orçamento (portal lento ou ainda carregando). |
Nos dois casos a mensagem instrui o agent a tirar um snapshot e chamar browser_login de novo. A categoria é unprocessable de propósito: uma categoria de indisponibilidade faria a infraestrutura reexecutar a chamada sozinha — ou seja, submeter a senha no portal outra vez, sem ninguém pedir, com risco de bloqueio de conta. Quem decide repetir é o modelo.
#Orçamento de 120 segundos
browser_login sempre retorna em até 2 minutos, ponta a ponta. O orçamento cobre tudo: provisionar o browser, resolver a credencial no vault, preencher, esperar captcha, submeter, esperar captcha de novo e guardar a captura de diagnóstico.
Estourado o orçamento, a resposta é browser.login_timeout — nunca uma espera indefinida.
#Espera de captcha
Quando o agent usa o browser gerenciado com resolução de captcha ligada (browser.provider: "steel_cloud" com solveCaptcha, ou "browserbase" — onde o solver já vem ligado por padrão), o login espera o solver em dois momentos:
- Antes do submit. Se o desafio não sair a tempo, nada é submetido e a resposta é
browser.captcha_pending. Clicar em "entrar" com o desafio em pé desperdiça uma tentativa de senha — e portal que conta tentativa bloqueia conta. - Depois do submit. O desafio pós-credencial é o caso comum. Sem essa segunda espera, a heurística de sucesso olharia para a tela do desafio e chamaria de "recusada" uma credencial perfeitamente válida.
Agents com browser self-hosted, ou com o gerenciado sem solveCaptcha, não pagam nada por isso: não há consulta ao provedor e o comportamento é o de antes.
Ver browser na config do agent para escolher o provedor.
#Diagnóstico
Quando o login não dá certo — recusa ou erro —, a plataforma guarda uma captura de tela mascarada (o campo de senha é borrado na origem, então o segredo nunca entra nos bytes) e devolve apenas a referência do artifact no evento. Se a captura falhar ou não couber no orçamento, o resultado degrada sem ela; o login não deixa de responder por causa do diagnóstico.