Como depurar e recuperar falhas de agentes de IA no celular Android

Primeiros cinco minutos após a falha

Quando uma tarefa de agente de IA falha no celular, a primeira decisão técnica é simples: não repita tudo imediatamente. Uma tarefa que apenas leu o estado da bateria pode ser repetida com baixo risco. Uma tarefa que preparou uma mensagem, alterou uma configuração, criou um evento ou chamou um serviço externo precisa de outro tratamento, porque repetir o fluxo inteiro pode duplicar efeitos que já aconteceram.

Nos primeiros minutos, pare novas execuções, mantenha o app no estado atual e registre o último resultado visível. Anote o pedido original, o ponto em que você percebeu a falha e o que esperava ver no final. Se a tela mudou, capture a tela atual ou descreva os elementos importantes sem incluir senhas, códigos, tokens, dados bancários ou conteúdo privado que não seja necessário para o diagnóstico.

A pesquisa AgentDebugX é útil aqui porque trata depuração de agentes como um ciclo de Detectar, Atribuir, Recuperar e Reexecutar. A parte mais importante para uso no telefone é a diferença entre erro aparente e causa raiz. O erro que apareceu no fim pode ter sido provocado por uma escolha de ferramenta errada, uma permissão revogada, uma tela fora de foco ou um dado ambíguo vários passos antes.

Use este checklist curto: a ação era somente leitura, reversível ou consequente? Algum envio, chamada, compra, alteração de configuração ou criação de item já ocorreu? A permissão necessária estava ativa no momento do uso? O agente pediu aprovação e você confirmou? O app-alvo estava aberto, desbloqueado e no estado esperado? Para aprofundar o desenho de aprovações no celular, o guia aprovação de agentes de IA no telefone com justificativa e confiança ajuda a separar decisão do usuário, execução da ferramenta e resultado final.

Monte um pacote mínimo de evidências

Um bom diagnóstico começa com evidência suficiente, não com um despejo completo de dados pessoais. O pacote mínimo deve permitir reconstruir a intenção, a trajetória, o estado do aparelho e o resultado observado. Em vez de enviar uma conversa inteira, prefira um resumo estruturado: pedido original, objetivo esperado, etapa em que parou, mensagem de erro, ferramenta ou ação envolvida, tela atual, permissões relevantes, conexão de rede, app de destino e confirmação feita pelo usuário.

Em tarefas de phone agent, a linha do tempo importa. Um erro de envio pode ter surgido no app de mensagens, mas a causa pode estar em um contato ambíguo escolhido antes. Uma falha ao alterar brilho pode parecer erro de sistema, mas o problema real pode ser uma permissão ausente, uma sobreposição em primeiro plano ou um estado de economia de bateria que alterou o comportamento esperado. Por isso, anote cada transição visível: pedido, plano, aprovação, execução, resposta da ferramenta e verificação final.

Inclua o mínimo necessário para reproduzir. Por exemplo: “Pedi para criar um lembrete para amanhã às 9h; o agente abriu a tela correta; a aprovação apareceu; depois o resultado disse que não conseguiu confirmar a criação; no calendário não encontrei o evento”. Esse relato é mais útil do que “não funcionou”. Também protege privacidade melhor do que enviar agenda, contatos e capturas sem edição.

Ao construir FoneClaw, aprendemos que evidência operacional precisa estar ligada a identidade, permissão e resultado. O artigo Identidade de agentes de IA: permissões, aprovação por ferramenta e auditoria no Android aprofunda essa parte: quem pediu, qual ferramenta executou, que permissão foi usada e qual estado ficou visível depois. Para suporte, remova nomes completos, números, endereços, tokens, chaves de API e conteúdo de mensagens, salvo quando o próprio usuário decidir que aquele trecho é indispensável para a reprodução.

Classifique a camada provável da falha

Depurar e recuperar falhas de agente no celular fica mais fácil quando você separa camadas. O mesmo sintoma pode nascer em pontos diferentes: modelo, contexto, roteamento, permissão, ferramenta, interface do app, rede, aprovação humana ou verificação. A documentação do Android sobre permissões em tempo de execução reforça um ponto essencial para agentes: permissões podem ser negadas, revogadas ou exigidas novamente, e o app precisa verificar o acesso quando vai usar a capacidade, não apenas na instalação.

Essa matriz evita uma armadilha comum: tratar todo erro como problema de “inteligência” do agente. Às vezes o modelo interpretou corretamente, mas a ferramenta não estava disponível. Em outros casos, a ferramenta estava certa, mas o app de destino mudou de tela. Também há falhas que parecem de permissão e na verdade são de roteamento: a capacidade existe, mas não foi escolhida. Para esse tipo de arquitetura, veja Roteamento de capacidades de agentes de IA no Android: AutoAttach, Suggest e Fallback, que explica como sugestão, anexo de contexto e fallback se encaixam sem transformar tudo em execução automática.

Encontre o primeiro passo causal

Depois de classificar a camada provável, trabalhe para trás. Comece no erro visível e pergunte: “Qual foi o primeiro passo que tornou esse erro inevitável?” Esse é o ponto em que o ciclo Detectar, Atribuir, Recuperar e Reexecutar se torna prático no telefone. Detectar é reconhecer que a saída final não atingiu o objetivo. Atribuir é localizar o passo causal mais antigo com evidência. Recuperar é reparar a precondição. Reexecutar é rodar só o trecho necessário.

Em uma tarefa como “mande uma mensagem para Paula dizendo que chego em 20 minutos”, o erro final pode ser “envio não confirmado”. O passo causal pode ser outro: contato errado por nomes duplicados, falta de permissão de contatos, app de mensagens sem conta ativa, tela bloqueada ou aprovação cancelada. Se você reenviar tudo sem atribuir, pode acabar com duas mensagens, uma para a pessoa errada ou um rascunho confuso.

Use testes somente leitura para confirmar precondições antes de qualquer retry consequente. Leia o contato escolhido. Verifique se a permissão existe. Confira se o app de destino está em primeiro plano. Cheque se a rede está ativa. Valide se a ação já aconteceu. Só depois execute. Quando houver duas causas possíveis, escreva as duas: “mais provável: permissão de calendário revogada; alternativa: app de calendário sem conta sincronizada”. Essa linguagem é mais honesta e acelera suporte.

A pesquisa AgentDebugX relata ganhos em atribuição e reparo nos benchmarks avaliados, mas isso não significa que todo phone agent em produção tenha a mesma instrumentação ou os mesmos resultados. Usamos o método como referência de investigação: olhar a trajetória inteira, separar causa aparente de causa raiz e aplicar recuperação mínima. Para transformar essa prática em avaliação formal, o guia Benchmark de agentes Android: como avaliar phone agents em 2026 mostra como criar casos de teste e critérios de aprovação para agentes no telefone.

Recupere sem duplicar efeitos concluídos

Quando uma tarefa falhou, a pergunta correta não é “posso tentar de novo?”, e sim “qual menor trecho pode ser repetido com segurança?”. Primeiro confirme o que já foi concluído. Uma configuração pode já ter sido alterada, mesmo que a verificação tenha falhado. Um evento pode existir no calendário. Uma mensagem pode ter sido enviada. Um arquivo pode ter sido renomeado. O retry seguro começa verificando efeitos externos antes de recriar passos.

Organize a recuperação em uma escada. No nível mais baixo, repita apenas uma checagem somente leitura: “confirme se o evento existe”. Depois, repare uma precondição: conceder permissão, desbloquear a tela, abrir o app correto, restaurar rede, escolher o contato certo ou ativar a conta necessária. Em seguida, reexecute a menor etapa pendente: enviar o rascunho já revisado, salvar o lembrete preparado ou confirmar a alteração que ainda não ocorreu. Pare depois da verificação final.

Evite limpar dados do app, reinstalar ou reiniciar o telefone como primeira resposta. Esses passos podem apagar estado útil para diagnóstico e não tratam a causa raiz em muitos casos. A orientação do Android sobre permissões também mostra que o usuário pode negar permanentemente uma permissão ou que o sistema pode revogar acessos não usados. Nesses cenários, um bom agente deve degradar com clareza: explicar qual capacidade ficou indisponível, abrir o caminho de recuperação e oferecer uma alternativa quando existir.

Em tarefas com fila ou múltiplas conversas, o cuidado aumenta. Não misture uma recuperação com outra tarefa em andamento, porque aprovações e resultados podem pertencer a contextos diferentes. Para entender como filas, estados de espera e continuidade mudam a segurança operacional, veja fila de tarefas de agentes de IA no Android com várias conversas. O princípio continua o mesmo: reparar a precondição, repetir o menor sufixo seguro e verificar o resultado no app ou sistema de destino.

Use os controles atuais da FoneClaw

Na FoneClaw, desenhamos a recuperação para aparecer no fluxo real de uso, não como uma tela separada que o usuário só descobre depois. A continuidade de tarefa permite voltar ao contexto em que o pedido estava sendo executado. A parada ajuda a interromper uma cadeia antes que uma ação consequente avance. Aprovações, resultados de ferramentas e mensagens de falha ficam visíveis para que o usuário não precise adivinhar se o problema foi modelo, permissão, ferramenta ou estado do aparelho.

O contexto de tela atual é deliberado e acionado pelo usuário. Isso importa para privacidade e para diagnóstico. Quando você chama o assistente flutuante a partir de outro app, pode anexar a tela atual quando ela é relevante para a tarefa; a FoneClaw evita tratar toda tela como dado automático. O guia Assistente de IA flutuante no Android: use a tela atual com controle explica esse caminho prático de contexto entre apps, com foco em controle do usuário.

Para solucionar assistente IA Android dentro da FoneClaw, siga esta ordem: volte para a tarefa original; leia o último resultado da ferramenta; confirme se havia aprovação pendente; confira se a permissão necessária está ativa; anexe a tela atual se o estado visual mudou; peça uma checagem somente leitura; só então use retry na etapa reparada. Essa sequência reduz duplicação e deixa mais claro quando a falha está em permissão, estado externo ou capacidade ausente.

Também separe tipos de ferramenta. As 100+ built-in tools da FoneClaw cobrem famílias de ações com riscos diferentes: leitura de estado do telefone, ajustes reversíveis, comunicação, calendário, localização, workflows e extensões. Uma leitura de bateria pode ser repetida sem grande custo. Um envio de SMS, uma chamada, uma alteração de calendário ou uma ação em app externo pede confirmação e verificação de efeito anterior. É por isso que nossas superfícies de aprovação, parada, retry e recuperação de permissão são parte do produto, não decoração.

Quando a FoneClaw não encontra uma capacidade suportada, o melhor comportamento é mostrar a fronteira e oferecer um caminho possível, em vez de fingir conclusão. Estamos construindo nessa direção: mais estado visível, melhor classificação de falhas, recuperação por precondição e reexecução menor. A meta para o leitor é operacional: entender o que aconteceu, manter controle sobre ações consequentes e sair da falha com um estado verificável.

Crie um relato útil para suporte ou bug

Escalone quando a falha se repete depois de reparar a precondição, quando há risco de efeito externo duplicado, quando a ferramenta retorna resultado inconsistente ou quando você não consegue separar permissão, app e modelo com segurança. Um bom relato não precisa expor a vida digital do usuário; ele precisa ser reproduzível.

Use este modelo: objetivo da tarefa; texto aproximado do pedido; app ou recurso envolvido; última etapa concluída; erro visível; efeito externo já verificado; permissões relevantes; estado de rede; modelo ou configuração usada quando isso for pertinente; horário aproximado; passos para reproduzir; resultado esperado; resultado real. Remova credenciais, códigos de verificação, tokens, chaves, números completos, mensagens privadas e nomes de terceiros quando não forem essenciais.

Exemplo de relato útil: “Pedi para criar um evento amanhã às 9h. A aprovação apareceu e confirmei. A resposta final disse que não conseguiu verificar. Abri o calendário e o evento não estava lá. Permissão de calendário estava concedida; rede ativa; app de calendário aberto; tentei novamente só a etapa de criação e recebi o mesmo erro”. Isso dá suporte para investigar causa raiz agente sem forçar o usuário a compartilhar dados demais.

Evite recorrência com testes de aceitação

Depois de recuperar, transforme a falha em teste pequeno. Uma única execução bem-sucedida não prova que o problema acabou; ela mostra que aquele caminho funcionou naquele estado. A orientação de boas práticas de permissões do Android recomenda testar combinações com permissões concedidas e revogadas. Para phone agents, acrescente interrupções, tela bloqueada, app fora de foco, rede instável, nomes ambíguos e aprovação cancelada.

Monte uma matriz curta: permissão concedida, permissão revogada, permissão negada permanentemente, app em primeiro plano, app em segundo plano, rede desligada, tela bloqueada e contato duplicado. Para cada caso, defina o comportamento aceitável: concluir, pedir permissão, degradar com explicação, parar antes da ação consequente ou solicitar nova confirmação. A evidência de aprovação deve incluir estado inicial, passo executado, resultado visível e verificação final.

Para times que testam agentes de telefone de forma contínua, vale transformar cada incidente em caso de regressão. O artigo harness de phone agent autoaperfeiçoável com governança mostra como conectar falhas reais a testes, revisão e controles de evolução. No uso diário, basta manter o hábito: não repetir tudo, atribuir a causa, reparar a precondição, rodar o menor trecho seguro e registrar o que evitar na próxima vez.