Como verificar se um agente de IA realmente concluiu a tarefa

Você pediu ao Claude Code, Codex ou outro agente para organizar arquivos, atualizar uma planilha ou criar registros de negócio. O agente respondeu “concluído” e nenhum erro evidente apareceu. Isso mostra que a execução terminou; não prova que o resultado de negócio foi persistido.

Um aceite confiável começa pelo estado final esperado, relê o resultado nos sistemas de destino e verifica efeitos ausentes e inesperados. Só depois a tarefa deve ser encerrada. Quando o resultado é desconhecido, consulte os registros antes de executar todo o fluxo novamente.

Por que uma chamada bem-sucedida não prova a conclusão

Um agente pode produzir sinais tranquilizadores: uma ferramenta retorna sucesso, o processo sai com código 0, um relatório é criado ou a mensagem final afirma que tudo foi feito. Esses sinais não respondem às perguntas essenciais:

• O arquivo certo foi gravado no local certo e com o conteúdo certo?
• A planilha ou o banco persistiu todos os registros previstos?
• Surgiram linhas, pedidos, notificações ou arquivos duplicados?
• Um job assíncrono ainda está na fila ou a gravação foi revertida depois?
• O agente apenas consultou o registro e deixou de fazer a atualização?

O ThinkingBox-Bench v1.0, da Microsoft, é um benchmark sintético, não uma taxa de incidentes em produção. Ele contém 507 tarefas executáveis em cinco domínios e só aceita uma tentativa quando passam as verificações do estado final, dos efeitos colaterais e de propriedades designadas do diálogo. A documentação da versão não dá crédito parcial. Os estados “parcial” e “não verificado” abaixo são rótulos operacionais, não notas do benchmark.

Defina um contrato de aceite antes da execução

A verificação fica mais simples quando as condições finais são registradas antes do início:

Item	O que definir	Exemplo
Estado obrigatório	Objetos, campos, quantidades e relações que devem existir	120 arquivos renomeados; 120 IDs únicos na planilha
Estado proibido	Mudanças e efeitos que não podem ocorrer	Não apagar originais, não enviar segundo e-mail, não alterar outras abas
Fonte de verdade	Sistema cujo estado armazenado decide o aceite	Pasta de destino, células, CRM ou status do chamado
Identidade da repetição	Chave que identifica esta operação específica	Um operation_id ou pedido limitado à tarefa/operação atual; cliente, nome de arquivo, ID do objeto e hash do manifesto identificam alvos da consulta, não esta operação isoladamente

Descreva o resultado, não a ação do agente. “A ferramenta de planilha foi chamada” não é estado final. “A aba contém 120 linhas, IDs únicos e totais conciliados com o manifesto” é.

Defina também a ordem de ações irreversíveis. Faça e confira primeiro as alterações recuperáveis; só depois envie e-mail, registre pedido ou dispare pagamento. Assim, uma falha inicial não força a repetição cega da etapa sensível a duplicidade.

Preserve a evidência mínima da execução

Guarde o conjunto necessário para ligar uma execução às gravações:

• tarefa original, escopo permitido e estado esperado;
• horários de início e fim, diretório e manifesto de destinos;
• ID da sessão e qualquer job ID retornado;
• operation_id ou outra chave única;
• contagens, versões, campos ou hashes anteriores;
• erros, timeouts, recusas de permissão e etapas puladas.

O raciocínio privado do agente não é necessário para o aceite. Entradas reproduzíveis, identificadores, escopo e estado do destino são. Não grave API keys, tokens ou segredos de clientes.

Espere o estado final do sistema, não a última mensagem

Uploads, importações em lote, relatórios e gravações em terceiros podem continuar depois da resposta. Salve o job ID e consulte o sistema oficial em intervalos razoáveis até obter sucesso, falha, cancelamento ou timeout definidos.

Registre progresso e última atualização. Em sistemas eventualmente consistentes, use uma janela de estabilização e releia. Não declare falha porque uma gravação recente ainda não aparece, mas não espere para sempre. Sem evidência decisiva ao fim da janela, o estado é não verificado, não “não executado”.

Releia o resultado em seis camadas

1. Confirme que o objeto existe e pertence a esta execução

Verifique caminho, nome, ID, horário de modificação e versão. Um arquivo antigo com o mesmo nome não prova nada. Um registro novo ligado ao cliente errado também não é válido.

2. Verifique conteúdo e invariantes de negócio

Confira quantidades, unicidade, totais, campos obrigatórios, relações e formato. Na planilha, compare IDs, linhas e somas. Em arquivos, manifesto, tamanho, hash ou amostra. Em registros, status, valor, responsável e período.

3. Use o sistema oficial de registro

Resumo do agente, terminal e cache são evidências auxiliares. O aceite deve vir de onde o resultado é armazenado: serviço de arquivos, células reais, CRM, tickets, banco ou livro de pagamentos.

4. Confirme todos os efeitos obrigatórios

Uma tarefa pode exigir arquivo, atualização de índice, registro associado e notificação. Confira cada item com a mesma identidade de negócio. Se um faltar, a conclusão é parcial.

5. Procure efeitos que não deveriam existir

Busque linhas e registros duplicados, e-mail extra, arquivos apagados, alterações fora do escopo e gravações no objeto errado. Um efeito inesperado deve interromper a repetição automática.

6. Concilie entre sistemas

Quando a tarefa atravessa arquivos, planilhas e aplicações, primeiro limite cada consulta ao operation_id ou ao escopo da tarefa atual; depois confira cliente e ID do objeto, o status ou a versão exigidos e o manifesto. Encontrar o mesmo identificador de objeto não prova que esta operação foi aplicada. Compare conjuntos de IDs e liste faltantes e extras.

Classifique o resultado em quatro estados

Estado	Quando usar	Próxima ação
Concluído	Todas as condições foram verificadas e não há efeito extra inaceitável	Salvar evidência e encerrar
Parcial	Parte do resultado está confirmada, mas há itens específicos ausentes	Corrigir apenas o que falta
Não verificado	Sistema indisponível, ainda estabilizando ou evidência inconclusiva	Consultar ou esperar; não repetir às cegas
Efeito inesperado	Duplicidade, exclusão, mudança fora do escopo ou objeto errado	Parar automação e revisar

“Não verificado” não significa “falhou”. Significa que você ainda não sabe o que ocorreu.

Decida a repetição nesta ordem

1. Consulte primeiro esta operação. Restrinja a busca na fonte de verdade pelo operation_id ou pedido e combine-a com nome de arquivo, cliente ou ID do objeto e o status ou a versão exigidos. Encontrar apenas o objeto não comprova esta gravação.
2. Identifique o limite concluído. Liste objetos corretos e ausentes.
3. Corrija de forma idempotente. Se a mesma chave não pode criar um segundo resultado, envie só o que falta. Se a idempotência é desconhecida, não repita automaticamente uma ação irreversível.
4. Separe registros, notificações e transações. Se o registro existe e o e-mail falhou, reenvie apenas o e-mail. Se o e-mail foi enviado e o registro é incerto, consulte antes.
5. Pare diante de efeitos inesperados. Reverta ou corrija objetos errados antes de retomar.

Regra curta: repita somente após confirmar a ausência; em gravação parcial, complete apenas o que falta; em resultado desconhecido, consulte antes; em estado errado, pare.

Exemplo: arquivos, planilha e CRM

Este é um cenário hipotético, não um incidente de cliente nem um log reproduzido.

O agente deve renomear 120 arquivos, escrever 120 linhas, criar 12 registros-resumo no CRM e enviar um e-mail. A releitura mostra arquivos e linhas corretos, apenas 9 registros no CRM e o e-mail já enviado.

O estado correto é parcial. A recuperação segura é:

• consultar o CRM com operation_id e as 12 chaves esperadas;
• identificar os 9 existentes e criar só os 3 ausentes com chaves de deduplicação;
• conciliar os 12 IDs finais com os resumos de arquivos e planilha;
• não renomear arquivos outra vez, não reescrever 120 linhas e não reenviar o e-mail.

Se o CRM não puder ser consultado, marque não verificado. A repetição completa pode gerar duplicidades e outra notificação.

Copie este registro de aceite

Campo	O que registrar
Tarefa e escopo	Ação, destinos permitidos e mudanças proibidas
Estado final esperado	Objetos, campos, quantidades, relações e estados
Identidade da execução	Sessão, job ID, operation_id e chaves de negócio
Evidência oficial	Objetos de destino, horário da consulta, IDs e links
Efeitos ausentes	Objetos ou ações obrigatórios que faltam
Efeitos extras	Duplicidades, exclusões, mudanças fora do escopo ou notificações extras
Estado de aceite	Concluído, parcial, não verificado ou efeito inesperado
Próxima ação	Encerrar, esperar, corrigir, repetir, reverter ou encaminhar

Anexe listas de IDs, diferenças e horários. Escrever apenas “verificado” não basta.

BetterToken fornece a conexão do modelo, não o aceite do resultado

Para conectar o Claude Code pelo BetterToken, consulte o guia atual de configuração e teste de conexão. Uma resposta normal sem erros de conexão ou modelo confirma a configuração; não prova que arquivo, planilha ou registro externo chegou ao estado esperado.

Use identificadores da sessão para localizar a execução, mas aceite o trabalho pelos sistemas de destino. Disponibilidade do modelo, resposta bem-sucedida ou consumo de tokens não provam conclusão de negócio.

Encerre apenas após três perguntas

1. O estado final aparece no sistema oficial, e não só na descrição do agente?
2. Foram verificados faltantes, duplicidades e outros efeitos inesperados?
3. Se o resultado é desconhecido, será consultado por chave única antes de corrigir ou repetir?

Encerre somente quando as três respostas forem claras. Antes da próxima execução de alto impacto, copie o registro acima e preencha estado final, estado proibido e identidade da repetição. Isso custa menos do que desfazer uma operação duplicada.