Nota do autor: neste artigo, explico em 5 passos como projetar portões de aceitação para agentes, para que agentes que rodam por muito tempo tenham um ponto de término claro, feedback confiável e custo controlável.
Depois que um agente roda por horas ou até dias sem parar, o resultado entregue parece completo, mas ninguém tem coragem de fazer merge diretamente. Esse é um problema que muitas equipes de desenvolvimento enfrentam. Neste artigo, vou apresentar o método de 5 passos para projetar portões de aceitação para agentes, para ajudar você, antes de iniciar uma tarefa longa, a definir “concluído” como um critério que a máquina consegue verificar repetidamente.
Em 27 de outubro de 2026, Gregory Kurtzer, um dos fundadores do CentOS, anunciou o projeto Ginux. Segundo relatos, em 11 dias ele contou principalmente com uma tarefa Codex em execução contínua, deixou cerca de 139 mil linhas de código e fez esse kernel independente inicializar o Rocky Linux 10 e rodar o systemd. Quando alguém perguntou como ele colocava de volta nos trilhos um agente que saía do rumo, a resposta foi simples: definir muitos portões de aceitação.
Este não é mais um artigo de dicas sobre comandos. O foco aqui é a estrutura de engenharia da qual tarefas longas realmente dependem: objetivos, portões de aceitação, evidências, regressão e condições de parada.
Valor central: ao terminar a leitura, você será capaz de escrever um conjunto de portões de aceitação de agente para o seu projeto e decidir quais etapas entregar à máquina e quais decisões precisam permanecer com as pessoas.
Pontos centrais dos checkpoints de aceitação do Agent
Um checkpoint de aceitação do Agent é um conjunto de pontos de verificação predefinidos e repetíveis. Ele diz ao Agent se o resultado atual atende ao padrão e também mostra às pessoas quais evidências vale a pena revisar.
| Ponto | Descrição | Valor |
|---|---|---|
| Critérios de aceitação definidos antes | Antes de iniciar tarefas longas, deixe claro o objetivo final e as metas de cada etapa | Reduz a chance de o Agent substituir a conclusão geral por um sucesso parcial |
| Checkpoint executável | Validar com comandos, scripts, CI ou resultados reais de execução | O Agent consegue iterar sozinho sem esperar por uma pessoa |
| Verificar o comportamento do sistema | Focar no que o programa realmente faz quando roda | Encontrar saídas erradas que “parecem confiáveis” |
| Responsabilidades em camadas entre humano e máquina | A pessoa define arquitetura e aceitação; o Agent implementa e faz regressão | A pessoa deixa de ser o elo mais lento do ciclo |
| Orçamento controlável | Definir antecipadamente número de falhas, uso e condições de pausa | Evitar que tarefas longas continuem consumindo recursos na direção errada |
Checkpoints de aceitação do Agent no caso Ginux
Kurtzer não entregou simplesmente “escrever um kernel” ao Agent. Em vez disso, escolheu checkpoints rígidos, como a capacidade de executar programas no espaço de usuário do Linux e de o systemd iniciar. O systemd depende de muitos componentes do sistema e é o processo central para iniciar e operar todo o sistema, então é uma ótima forma de testar se o kernel é realmente utilizável.
O projeto roda em dois ciclos que trabalham juntos. O ciclo externo é conduzido por pessoas: vai da visão, passando por arquitetura e restrições, checkpoints de aceitação, até a revisão do comportamento real e a decisão de corrigir ou aceitar. O ciclo interno fica com o Agent, repetindo implementação, build e execução no QEMU, medição e análise de falhas, correções e testes de regressão.
Kurtzer também faz um alerta especial: muitas falhas produzem saídas bastante convincentes, mas que na prática violam a semântica, requisitos de isolamento ou comportamento de ciclo de vida. Sem checkpoints, é fácil terminar com um código que parece funcionar na superfície, mas é estruturalmente frágil.
Por que os checkpoints de aceitação do Agent precisam rodar automaticamente
A engenheira da Cursor Lauren Tan também considera a validação a habilidade mais importante ao usar Agents. Para ela, validar inclui fazer o Agent realmente executar o código, coletar traces de CPU ou snapshots de heap, abrir o simulador do iOS e operar o aplicativo como um usuário faria.
Ela declarou publicamente que consegue fazer merge de 4.000 PRs por mês em produção. Mesmo que cada PR leve só 5 minutos de revisão humana, isso soma cerca de 333 horas, então um sistema de verificação nessa escala precisa funcionar sem intervenção. Esse caso extremo gera bastante controvérsia, mas ilustra uma lição que também vale para equipes comuns: o Agent só consegue trabalhar de forma contínua se puder verificar a própria saída; quando não consegue, ele só pode entregar o diff para você e parar.
O ciclo duplo do diagrama pode ser aplicado diretamente a projetos do dia a dia. Se você quiser usar modelos diferentes para cuidar da implementação e da revisão, pode conectá-los via APIYI apiyi.com e então incluir a invocação do modelo no ciclo interno.
Guia rápido para os gates de aceitação do Agent: método de design em 5 etapas
A seguir, usamos uma tarefa comum como exemplo: fazer o Agent migrar um serviço REST legado para um novo framework, mantendo os clientes existentes sem impacto. Você pode substituir os itens de verificação do exemplo pelo fluxo de build, teste e deploy do seu próprio projeto.
Etapa 1: definir o ponto final em nível de sistema para o gate de aceitação do Agent
Primeiro, escreva uma frase observável que descreva o que deve acontecer no sistema ao final da tarefa. “Concluir a migração do serviço” é vago demais; já “usar o mesmo lote de requisições de replay e manter os códigos de status e os campos-chave de resposta consistentes entre o serviço antigo e o novo” pode ser verificado.
Um bom ponto final geralmente vem de caminhos de uso reais. O ponto final do Ginux é o Rocky Linux 10 chegar ao multi-user.target do systemd; o de uma aplicação web pode ser o fluxo principal do usuário funcionar de ponta a ponta; o de uma tarefa de dados pode ser o resultado de saída coincidir com o conjunto de dados de referência.
Etapa 2: divida os portões de aceitação do Agent em cinco camadas
Um único teste final de feedback é lento demais e, quando o Agent falha, fica difícil localizar o problema. A recomendação é definir portões ordenados do custo de execução mais baixo para o mais alto, deixando que as verificações baratas bloqueiem primeiro os erros óbvios.
| Camada do portão | O que verifica | Exemplo | Ação após falha |
|---|---|---|---|
| L1 Restrições estáticas | Formato, tipos, limites de dependência | Proibir importações cruzadas entre módulos | O Agent corrige imediatamente |
| L2 Comportamento unitário | Lógica de funções e módulos | Testes unitários do núcleo | O Agent localiza e corrige |
| L3 Contrato de integração | Interfaces, banco de dados, dependências externas | Testes de contrato de interface | O Agent compara as diferenças e revisa |
| L4 Execução do sistema | Comportamento real do serviço completo | Subir o serviço e reproduzir requisições | O Agent coleta logs e dados de performance |
| L5 Aceitação humana | Arquitetura, riscos e decisões de negócio | Revisar o pacote de evidências e decidir se integra | A pessoa fornece novas restrições ou encerra a tarefa |
A arquitetura Dune de Lauren Tan é um exemplo extremo do L1. Ela refatorou o projeto por meio de mais de 600 PRs e usa a CI para validar o grafo de dependências, garantindo que os diretórios main e renderer do Electron não façam importações cruzadas, além de desativar useEffect e proibir a escrita de comentários. Essas regras podem não servir para o seu código, mas a prática de transformar as restrições da equipe em verificações automáticas vale a pena ser adotada.
Etapa 3: Transforme os gates de aceitação do Agent em cartões executáveis
Cada gate deve ter um cartão curto, colocado na documentação do projeto que o Agent consegue ler na inicialização. Com o cartão bem escrito, o Agent não precisa adivinhar “o que significa passar”, e as pessoas também conseguem rastrear as evidências.
| Campo | Requisito de preenchimento | Exemplo de migração de serviço |
|---|---|---|
| Nome do gate | Nomear pelo comportamento | Consistência de requisições em replay |
| Ambiente de execução | Versões e dependências fixas | Ambiente de teste isolado, usando snapshot de dados fixo |
| Ponto de entrada de execução | Fornecer um comando claro | make gate-replay (comando de exemplo) |
| Critério de aprovação | Usar resultados comparáveis | Códigos de status e campos-chave totalmente consistentes |
| Artefatos de evidência | Salvar arquivos auditáveis | Relatório de diferenças, logs do serviço, registro de desempenho |
| Regras de proteção | Indicar o que não pode ser modificado | Amostras de aceitação e script de avaliação somente leitura |
| Estratégia de falha | Descrever a próxima ação | Se o mesmo erro não for resolvido por 3 rodadas consecutivas, pausar |
Entre eles, as regras de proteção são as mais fáceis de passar despercebidas. O Agent tende a escolher o caminho de menor esforço imediato; se ele puder alterar as amostras de aceitação ou afrouxar o script de avaliação, os resultados dos testes perdem o sentido. Recomenda-se colocar essa parte em um diretório protegido e verificar alterações relacionadas no CI.
Etapa 4: colocar os checkpoints de aceitação do Agent no ciclo de regressão automatizada
Coloque o loop interno na descrição da tarefa: primeiro conclua uma pequena alteração, execute o checkpoint do nível atual, leia as evidências de falha, faça as correções e então rode novamente os checkpoints que já tinham passado antes. A regressão aqui é essencial — senão, depois que o Agent corrige um ponto, ele pode silenciosamente quebrar outro.
Ao final de cada rodada, peça ao Agent para registrar o que mudou, quais checkpoints foram executados, os resultados e os problemas em aberto. O contexto de tarefas longas só cresce, e esse registro ajuda as sessões seguintes a retomar o estado rapidamente e também facilita para o humano avaliar se ele está de fato avançando ou apenas andando em círculos.
Os checkpoints de aceitação também precisam se proteger contra “aprovações falsas”. Alguns casos são especialmente comuns em execuções de longa duração:
| Tipo de falsa aprovação | Manifestação típica | Defesa correspondente |
|---|---|---|
| Testes modificados | Casos de falha excluídos ou critérios afrouxados | Arquivos de aceitação somente leitura, CI verifica alterações |
| Testar apenas o caminho feliz | Requisições normais passam, cenários de exceção quebram | Adicionar injeção de falhas e amostras de borda |
| Simulação no lugar de dependências reais | Mock todo verde, ambiente de integração falha | L4 precisa executar serviços reais |
| Saída parece certa mas semântica errada | Logs completos, comportamento de ciclo de vida errado | Comparar estado, timing e efeitos colaterais |
| Sucesso local mascara riscos | Métrica individual melhora, estabilidade geral cai | Executar regressão completa em cada marco |
Etapa 5: definir pontos de decisão humana e condições de parada para os checkpoints de aceitação do Agent
O trabalho humano deve se concentrar nos julgamentos que o Agent dificilmente consegue substituir. Kurtzer fica responsável pela arquitetura, pelos objetivos de compatibilidade com Linux, pelo modelo operacional, pela interpretação de falhas e pela decisão de parar; quando não fica satisfeito com o código gerado pelo Agent, ele chega a fechar a IDE, segura o impulso de editar com as próprias mãos e, em vez disso, fornece novas orientações.
Recomenda-se definir pelo menos três tipos de condição de pausa: falha repetida no mesmo checkpoint por várias rodadas, tentativa do Agent de alterar conteúdo protegido e uso da tarefa próximo do orçamento. Depois de uma pausa, o foco da revisão também deve se deslocar para o pacote de evidências: primeiro olhar o comportamento do sistema e os riscos, e só então decidir se vale a pena se aprofundar na leitura do diff.
Dica para começar rápido: escolha primeiro um pequeno marco que possa ser concluído em um dia e escreva apenas de 3 a 5 cartões de checkpoint. A APIYI apiyi.com oferece chamadas de API para modelos das séries GPT, Claude e outros mencionados neste artigo, e é compatível com os formatos de interface da OpenAI e da Anthropic. Ferramentas existentes normalmente só precisam ajustar o endereço da interface e a chave API conforme a documentação; os modelos disponíveis podem ser confirmados na página de preços da APIYI.
Como os checkpoints de aceitação do Agent mudam o custo de tarefas longas
O custo de tarefas longas não pode ser medido apenas por “quantos tokens foram usados no total”. A reportagem menciona que os tokens contabilizados na página inicial do Cursor incluem pelo menos quatro categorias: entrada comum, saída do modelo, gravação em cache e leitura de cache, com diferenças de preço consideráveis. A comunidade já usou o mesmo consumo de 1,5 trilhão de tokens para estimar a conta, e os resultados de algoritmos diferentes ficaram muito distantes; a principal divergência vem dos critérios de cobrança e da proporção de cache.
| Item de cobrança | Principal origem em tarefas longas | Método de controle | Critério de preço |
|---|---|---|---|
| Entrada comum | Descrição da tarefa, logs, trechos de código | Enviar apenas evidências relacionadas à falha | Conforme os dados reais da página de preços da APIYI |
| Saída do modelo | Código, análise e plano de revisão | Limitar o escopo da saída a cada rodada | Conforme os dados reais da página de preços da APIYI |
| Gravação em cache | Contexto estável novo ou alterado | Manter estável a estrutura das regras do projeto | Conforme os dados reais da página de preços da APIYI |
| Leitura de cache | Contexto reutilizado em várias rodadas | Observar a taxa de acerto e evitar alterar o prefixo com frequência | Conforme os dados reais da página de preços da APIYI |
O custo total de casos públicos pode ajudar a entender a escala do projeto, mas não pode ser convertido diretamente em preço unitário. O custo de chamadas de API do Ginux foi reportado em cerca de US$ 8.000, e o experimento de Nicholas Carlini que usou 16 agentes Claude em paralelo para construir um compilador C custou aproximadamente US$ 20.000. Os modelos, caches e estruturas de tarefa por trás desses números são diferentes, então seu projeto ainda precisa de uma estimativa própria.
Uma abordagem mais segura é executar primeiro um marco completo, registrar o uso das quatro categorias de tokens e o número de falhas nos checkpoints, e então calcular com os dados atuais da página de preços da APIYI em https://docs.apiyi.com/models. O orçamento assim obtido vem do formato da sua própria tarefa e é mais confiável do que simplesmente aplicar o preço unitário médio de outra pessoa.
O que a figura acima quer mostrar é que o checkpoint também consome recursos, mas consegue expor as falhas mais cedo. Para equipes comuns, o objetivo deve ser trocar um orçamento limitado por confiança suficiente, e não buscar rodar a verificação completa mais cara em toda alteração.
Perguntas frequentes (FAQ) sobre checkpoints de aceitação de Agentes
Q1: O que é um checkpoint de aceitação de Agente?
É um ponto de verificação executável, predefinido, usado para determinar se os resultados de cada etapa do Agente atingiram o padrão esperado. Um checkpoint completo inclui ambiente de execução, ponto de entrada de execução, critérios de aprovação, artefatos de evidência e estratégia em caso de falha.
Q2: Qual é a diferença entre um checkpoint de aceitação de Agente e um CI comum?
O CI é um veículo de execução comum; o checkpoint de aceitação é um design de controle de tarefa mais completo. Além de julgar se o código passa nos testes, ele também define o comportamento do sistema, as evidências, o escopo de regressão, os pontos de decisão humana e as condições de pausa.
Q3: Quando é obrigatório projetar um checkpoint de aceitação de Agente?
Quando a tarefa exige várias rodadas de modificação, atravessa diversos módulos, tem tempo de execução longo, ou quando a saída incorreta não é fácil de perceber a olho nu, vale a pena projetar o checkpoint com antecedência. Scripts pequenos e pontuais podem ser simplificados, mas ao menos uma forma de verificação executável precisa estar bem definida.
Q4: Com um checkpoint de aceitação de Agente, ainda é necessário Code Review humano?
Sim. Checkpoints automáticos são bons para julgar critérios já conhecidos; os humanos continuam responsáveis pela escolha de arquitetura, pelos trade-offs de risco e pela aceitação final. Kurtzer também destaca que, ao avaliar se o resultado está completo e se um sucesso local pode gerar risco sistêmico, a experiência continua sendo essencial.
Q5: Como integrar modelos via API para rodar esse fluxo?
1. Registre-se no APIYI (apiyi.com) e crie uma chave API.
2. Consulte o centro de documentação `docs.apiyi.com` para confirmar o endereço do endpoint e a forma de invocação.
3. Escolha o formato de interface OpenAI ou Anthropic conforme a ferramenta e conclua a configuração.
4. Confirme o modelo e o preço em `https://docs.apiyi.com/models` e só então inicie um teste piloto em pequena escala.
Q6: Com orçamento limitado, como enxugar o checkpoint de aceitação de Agente?
Priorize manter os checkpoints de baixo custo L1 e L2 rodando a cada rodada; deixe os L3 e L4 para execução na conclusão da funcionalidade ou em marcos do projeto. O levantamento da Jellyfish com 12 mil desenvolvedores mostra que um usuário típico consome cerca de 51 milhões de tokens por mês, uma diferença enorme em relação aos casos extremos — por isso, a frequência de validação deve ser definida conforme o risco da tarefa. Para os custos de modelo, considere os dados reais da página de preços do APIYI.
Q7: Quais são as limitações dos checkpoints de aceitação de Agente?
Os checkpoints só cobrem os riscos que foram definidos — testes todos verdes não significam que o código é adequado para manutenção a longo prazo. O Ginux consegue dar boot no Rocky Linux 10, mas ainda há um longo caminho até um kernel de nível de produção: suporte de hardware, estabilidade de interfaces, revisão de segurança e manutenção pela comunidade não se comprovam com uma única execução. As críticas da comunidade ao modelo de PRs em alta frequência também servem de lembrete para acompanharmos continuamente a manutenibilidade do código.
Pontos-chave: gates de aceitação para Agent
- Defina o ponto de chegada primeiro: descreva a conclusão da tarefa por meio de comportamentos observáveis do sistema, evitando objetivos vagos.
- Os gates devem ser em camadas: avance gradualmente de restrições estáticas para execução real e aceitação humana.
- As evidências precisam ser preservadas: salve logs, relatórios de diferenças e registros de desempenho em cada execução.
- A avaliação não pode ser alterada: as amostras e os scripts de aceitação devem ser protegidos para impedir que o Agent tome atalhos.
- Regressão como rotina: após corrigir um novo problema, execute novamente os gates relacionados que já haviam passado.
- A decisão é humana: arquitetura, riscos, parada e aceitação final ficam a critério do responsável.
- Teste o custo antes: valide em pequena escala via APIYI apiyi.com e depois estime o orçamento com base na página de preços.
Resumo: comece pelos gates de aceitação para construir fluxos de trabalho autônomos
Se um Agent consegue ou não trabalhar de forma autônoma por longos períodos depende de ele ter objetivos claros e feedback confiável. Ao projetar gates de aceitação para Agent, lembre-se de três pontos:
- Transforme “concluído” em um critério executável: faça o Agent julgar o progresso com base nos resultados da execução.
- Deixe a máquina cuidar da verificação de alta frequência: use gates em camadas, regressão automática e pacotes de evidências para encurtar o ciclo de feedback.
- Reserve as decisões críticas para as pessoas: o responsável decide a direção da arquitetura, os limites de risco e o momento de parar.
Sugiro começar pela próxima tarefa de porte médio: primeiro escreva o cartão do gate e só depois inicie o Agent. Quando precisar testar diferentes modelos, você pode usar a APIYI apiyi.com para integração por meio de interfaces compatíveis com os formatos OpenAI e Anthropic. Para detalhes de configuração, consulte a central de documentação em docs.apiyi.com; os preços dos modelos e os critérios de cobrança seguem os dados reais em https://docs.apiyi.com/models.
📚 Materiais de referência
- InfoQ – Reportagem sobre o projeto Ginux: o processo e os critérios de aceitação do kernel compatível com Linux construído pelo Codex
- Link:
infoq.cn/article/OiyNEtFwV05opvsLTcvK -
Descrição: inclui o duplo ciclo HDAE, o dimensionamento do projeto e a análise das limitações
-
InfoQ – Reportagem sobre a conta de tokens de um engenheiro da Cursor: fluxo de trabalho intensivo com Agent e a controvérsia sobre custos
- Link:
infoq.cn/article/q9iebpvFozfy4bgCYUyE -
Descrição: inclui o ciclo fechado de validação, a arquitetura Dune e as críticas da comunidade
-
Relatório técnico do Ginux: relatório técnico do projeto publicado por Gregory Kurtzer
- Link:
zenodo.org/records/23682548 -
Descrição: indicado para se aprofundar nos objetivos da pesquisa, nos métodos e nos limites dos resultados
-
Repositório do Ginux no GitHub: código-fonte do projeto
- Link:
github.com/gmkurtzer/ginux -
Descrição: permite consultar o código do projeto e as informações de licença open source
-
Documentação e página de preços do APIYI: configuração da interface e explicação dos preços dos modelos
- Link da documentação:
docs.apiyi.com - Link de preços:
https://docs.apiyi.com/models - Descrição: consulte os modelos, preços e critérios de cobrança com base nos dados reais da página
Autor: equipe técnica da APIYI
Intercâmbio técnico: fique à vontade para visitar o APIYI em apiyi.com e conversar conosco sobre práticas de engenharia com Agent; mais materiais de integração estão disponíveis no centro de documentação docs.apiyi.com.
