Uma das dificuldades mais comuns ao utilizar inteligência artificial para gerar código é que o resultado pode parecer correto na teoria, mas falhar na prática. O Claude Code introduziu uma nova funcionalidade chamada Outcomes, que transforma essa experiência. Agora, o sistema é capaz de validar se o código gerado atende aos critérios especificados pelo usuário desde o início.
Outcomes faz parte da API de Managed Agents do Claude e representa um avanço significativo na forma como os agentes de código operam. Ao ser ativada, a interação muda de uma conversa para uma sessão focada em uma tarefa com condições claras de aceitação. O usuário define as expectativas para o resultado final, e o agente trabalha em direção a esse objetivo, autoavaliando-se e iterando até que os requisitos sejam cumpridos.
O mecanismo principal por trás dessa funcionalidade é o evento user.define_outcome. Ao enviá-lo, a plataforma aciona um segundo agente independente, apelidado de ‘grader’ (ou avaliador), cuja única responsabilidade é realizar a verificação. Este avaliador opera com base em uma rubrica definida pelo usuário, que detalha como um trabalho bem-feito deve ser e como verificá-lo.
O avaliador opera em sua própria janela de contexto para evitar influências do agente escritor. Uma nova instância do avaliador revisa o artefato completo em cada iteração. Após cada ciclo do agente principal, o avaliador retorna um detalhamento por critério, confirmando se o artefato atende à rubrica ou apontando as lacunas específicas entre o trabalho atual e os requisitos. Esse feedback é então direcionado de volta ao agente para a próxima iteração.
A rubrica é o componente central de todo o sistema. A precisão com que ela é redigida determina a eficácia da verificação. Uma rubrica vaga, como ‘verificar se o código lida com erros’, pode permitir que o avaliador apenas identifique a presença de um bloco try-catch, sem realmente executar o código.
Como Configurar Outcomes Passo a Passo
Para ativar Outcomes, é necessário incluir o cabeçalho beta managed-agents-2026-04-01 nas chamadas à API. O SDK da Anthropic já inclui isso automaticamente, eliminando a necessidade de configurações adicionais caso você o utilize.
O primeiro passo é criar a rubrica. Isso é feito através de um documento em Markdown, onde você descreve, critério a critério, o que constitui um resultado válido. A rubrica pode ser passada diretamente como texto no evento user.define_outcome, ou enviada através da Files API para reutilização em múltiplas sessões (o que requer o cabeçalho adicional files-api-2025-04-14).
Com a rubrica pronta, você cria a sessão e envia o evento user.define_outcome, contendo dois campos essenciais: description, que o agente escritor lerá para entender a tarefa; e rubric, utilizada pelo avaliador para julgar o resultado. Você também pode definir max_iterations para limitar o número de rodadas de revisão permitidas antes que o sistema pare.
O agente iniciará o trabalho assim que receber o evento, sem a necessidade de mensagens adicionais. Você pode enviar mensagens user.message durante o processo para fornecer orientações mais específicas, mas elas não são obrigatórias. O agente continuará trabalhando até que as iterações se esgotem ou o resultado desejado seja alcançado.
Como Revisar se Seu Código Funciona no Claude Code
Para acompanhar o progresso, os eventos span.outcome_evaluation_start e span.outcome_evaluation_end informam quando o avaliador está em ação e quais foram suas descobertas. O campo iteration dentro desses eventos é um contador que inicia em zero: o zero representa a primeira avaliação, o um a revisão após a primeira correção, e assim por diante.
Ao final de cada ciclo, a sessão retorna ao modo conversacional, e um novo evento user.define_outcome inicia um novo ciclo. Apenas um Outcome pode estar ativo por vez, mas é possível encadeá-los sequencialmente. Isso permite, por exemplo, solicitar a geração de uma função com critérios de correção e, em seguida, iniciar um segundo Outcome para verificar a cobertura de testes.
O resultado final é que você não precisará mais ser o revisor em cada iteração. O Claude Code entregará código que não apenas parece funcionar, mas que foi validado de acordo com os critérios que você mesmo definiu.
