Revise Seu Agente Enquanto Ele Trabalha

Às 10h40 você inicia uma execução gerenciada no serviço de faturamento: "Documente como configurar e rodar o serviço localmente." Às 11h02 chega um pull request com um docs/setup.md novo. Está razoável. A linha 12 manda quem acabou de entrar no time rodar go build ./..., que ignora as build tags de que o serviço precisa, então o primeiro build dessas pessoas falha de um jeito que o documento nunca explica. E em algum momento perto do sexto minuto, o agente decidiu que a seção de Docker do README estava desatualizada e a reescreveu. Ninguém pediu isso.

Nada disso é difícil de corrigir no review. O que o review não consegue devolver são os vinte minutos no meio do caminho. O agente fez essas escolhas cedo, sem ninguém para conferir, e construiu todo o resto em cima delas. A correção passa a ser uma segunda execução que começa do zero, lê os mesmos arquivos de novo e abre um segundo pull request.

Era assim que as execuções gerenciadas de agentes do Archyl funcionavam até agora. A página da execução tinha um feed de eventos e uma caixa de orientação, então dava para acompanhar as chamadas de tools se você deixasse a aba aberta, no notebook ou pelo celular. Mas o que o agente pretendia fazer, e o que ele já tinha gravado, você montava a partir dos payloads das chamadas de tools ou descobria no pull request. Para uma auditoria noturna de dependências, tudo bem. Para uma mudança que você vai revisar de qualquer jeito, isso coloca o review justamente no ponto em que ele custa mais caro.

Agora as execuções têm um ciclo de review. Veja o que mudou:

O resto deste post refaz a mesma tarefa, do jeito novo, na ordem em que você viveria. A tarefa é um exemplo; cada mensagem citada abaixo está no formato que o agente realmente recebe.

Primeiro vem o plano

Antes de tocar em um arquivo, o agente é instruído a chamar propose_plan com um resumo de uma frase e algumas etapas concretas. O prompt pede de 3 a 8, e a tool recusa mais de 12, para que um plano continue legível de relance. O painel Plano, no topo da página da execução, transforma isso em uma checklist. Conforme trabalha, o agente marca cada etapa como Em andamento, Concluída ou Ignorada, às vezes com uma nota curta, e o painel mostra a etapa atual e o progresso (2/4).

Por padrão, o plano é compartilhado e o agente começa na hora. Ative Revisar o plano primeiro, em Coordenação no perfil do agente, e ele espera por você. O painel entra no modo de review, onde você pode renomear etapas, adicionar detalhes e adicionar, remover ou reordenar etapas.

Para o documento de setup, o agente propôs cinco etapas. A quarta era "Atualizar a seção de Docker do README", a reescrita que ninguém pediu. Você a remove, adiciona um detalhe na etapa 2, e o botão que dizia Aprovar plano agora diz Aprovar plano editado. Isto é o que o agente recebe de volta:

The plan was approved with edits. Follow this plan:
1. Read the Makefile, docker-compose.yml and the config loader
2. Write prerequisites and environment variables — take values from .env.example, never from a real .env
3. Document the build, test and run commands
4. Link docs/setup.md from the README
Call update_plan when each step starts and when it is done or skipped.

A sua versão editada é o plano que o agente segue, e o que a checklist acompanha. Quando um plano está errado, e não só um pouco fora, Solicitar alterações envia feedback no lugar. O agente revisa o plano e propõe uma nova revisão, e as revisões anteriores ficam no feed, para você ver o que o seu feedback mudou.

Enquanto nenhum plano for aprovado, o agente não pode gravar arquivos, alterar o modelo de arquitetura pelas tools do Archyl nem fazer push em um repositório por meio de um conector. Não é uma linha no prompt que ele poderia se convencer a contornar. As chamadas são recusadas, e o agente lê:

changes are refused until your plan is approved: call propose_plan and wait for the review

Se ninguém revisar o plano em até uma hora, a execução falha sem ter alterado nada. Um perfil que exige review não pode pular essa etapa só porque ninguém apareceu.

Perguntas, quando uma pessoa precisa decidir

Algumas decisões o agente não deveria tomar sozinho: um requisito ambíguo, um trade-off sem vencedor claro, algo destrutivo. Para essas ele tem ask_human. As instruções dele dizem para nunca perguntar algo que ele possa consultar, e ele tem no máximo 5 perguntas por execução, então não consegue devolver o trabalho para você uma pergunta de cada vez.

No meio da etapa 2, o agente encontra uma STAGING_DATABASE_URL na configuração. Documentá-la ajudaria, só que staging exige um acesso por VPN que quem acabou de entrar não recebe na primeira semana. Nada no repositório diz isso, então ele pergunta.

A pergunta aparece acima do feed, com Respostas sugeridas quando o agente oferece algumas ("Deixe staging de fora", "Mencione, com uma nota sobre o acesso por VPN"), e uma caixa para a sua própria resposta (Cmd/Ctrl + Enter envia). Qualquer pessoa que possa editar o projeto pode responder, e o feed registra quem respondeu. O agente lê The human answered: Leave staging out e segue em frente.

Uma pergunta que ninguém responde em até uma hora não faz a execução falhar. O agente continua pelo próprio julgamento e informa no resultado a suposição que fez. É o oposto do plano, e a diferença está no que está em jogo: um plano não revisado significa que nada foi combinado, enquanto uma pergunta sem resposta é só mais uma decisão do tipo que o agente toma a execução inteira.

Quanto custa esperar

Enquanto o agente aguarda uma revisão do plano ou uma resposta, a execução mostra Aguardando você, e a lista de execuções a coloca em Precisa de você. Um banner acima do feed diz o que ele está aguardando, Aguardando sua revisão do plano ou O agente tem uma pergunta, e leva você até lá.

A espera não conta para o limite de tempo da execução. O prazo é adiado pelo tempo passado esperando, então uma execução com limite de 30 minutos que esperou 20 minutos por você continua tendo 30 minutos de trabalho. Mas ela mantém a vaga de execução simultânea. Uma execução em Aguardando aprovação ainda não começou, então não segura nada, mas uma execução em espera está no meio de uma conversa, com o workspace aberto, pronta para retomar assim que a sua resposta chegar.

O diff, enquanto é escrito

A página da execução agora tem duas visualizações: Atividade, o feed de eventos, e Alterações. Alterações lista cada arquivo que o agente grava, no momento em que grava, com um status (Adicionado, Modificado ou Bloqueado) e as linhas adicionadas e removidas, por arquivo e na execução inteira. Selecione um arquivo para ver o que cada gravação mudou (Edição 2 de 3), não só o estado final.

O Guard, a verificação de conformidade em cada gravação de arquivo que agora roda dentro do worker, também aparece aqui. Uma gravação que ele recusou fica Bloqueado: o diff mostra o que o agente tentou gravar, com a regra violada, mesmo que esse conteúdo nunca tenha chegado ao arquivo. Uma gravação que ele apenas sinalizou passa, com um aviso no arquivo. Uma recusa que você antes encontrava no resultado de uma tool agora é um diff que dá para ler.

Dois limites: diffs longos são cortados após 600 linhas, e arquivos com mais de 128 KB aparecem sem diff.

Um comentário na linha 12

De volta ao go build ./.... Você não precisa esperar o pull request. Em Alterações, clique no número da linha, escreva o comentário e use Enviar ao agente (Cmd/Ctrl + Enter). No próximo passo, o agente o recebe como um comentário de code review, com o arquivo, a linha e o conteúdo dela:

[Review comment from a human operator on docs/setup.md, line 12 of the file as you wrote it]
> go build ./...
Use the make target instead, it sets the build tags.
Address the comment in that file, then carry on with your plan.

Ele corrige a linha e volta para a etapa em que estava. Abaixo da linha, o comentário mostra Na fila até o agente pegá-lo, depois Entregue. Ele também aparece em Atividade, e cada arquivo da lista mostra quantos comentários tem. A correção, quando vem, chega como a próxima edição do arquivo, então o diff em que você deixou o comentário é também onde você confere a correção.

Você pode comentar linhas adicionadas, inalteradas e removidas. Um comentário em uma linha removida chega ao agente como um comentário sobre "the lines you removed", e é assim que você diz a ele para recolocar uma verificação. Os comentários são aceitos enquanto o agente trabalha ou aguarda você, e um agente em espera os lê quando retoma. Um comentário ainda Na fila quando a execução termina mostra Não entregue. Gravações bloqueadas pelo Guard não aceitam comentários.

A caixa de orientação continua lá, para redirecionar o agente em texto livre sem cancelar a execução ("pule a migração, foque no handler"). Um comentário de linha é o mesmo mecanismo preso a uma linha. O que ele poupa é o preâmbulo: "em docs/setup.md, onde você escreveu go build" já está na mensagem.

A execução que não tinha nada para revisar

Enquanto construía Alterações, pedi a uma execução que adicionasse documentação a um dos nossos repositórios Git, e fiquei vendo a visualização continuar vazia. Nenhum arquivo, nenhum diff, nada para comentar.

O projeto não tinha repositório vinculado, então o Archyl não tinha clonado nada. O que a execução tinha era um conector do GitHub, e o agente fez o que era razoável com as tools que tinha à mão: gravou os arquivos direto no GitHub com a tool push_files do conector. Nada passou por um workspace. Então nada passou pelo Guard, nada apareceu em Alterações, e o ciclo de review que eu estava construindo não tinha nada para revisar.

Agora o agente trabalha em um workspace nos dois casos:

• Há um repositório vinculado ao projeto. O Archyl o clona quando a execução começa, como antes.
• Nenhum repositório vinculado, mas há um conector do GitHub anexado. O próprio agente clona o repositório de que trata a tarefa, chamando open_repository com as credenciais do conector, antes de tocar em qualquer arquivo. Isso só funciona com o servidor MCP hospedado do GitHub (api.githubcopilot.com), e o token precisa de acesso ao repositório.

Depois que um workspace é aberto, as tools do conector que gravam em um repositório (push_files, create_or_update_file, delete_file, create_pull_request) são recusadas, e o agente lê:

a repository workspace is open: change files with write_file and edit_file instead. Archyl commits your changes and opens the pull request when the run ends.

É essa regra que faz toda alteração passar pelo Guard, aparecer em Alterações e ir para um único pull request.

Quando a execução termina

O Archyl faz commit das alterações do workspace em archyl/agent-<run id>, usando os oito primeiros caracteres do ID da execução, e abre um pull request contra a branch de onde o clone partiu. O link fica no topo de Alterações (Abrir pull request) e no resultado. A forma como a execução termina decide o que é publicado:

No GitLab, o rascunho é um merge request Draft:. No Bitbucket, a branch é enviada sem pull request. Uma execução que não alterou nenhum arquivo não publica nada.

Seus comentários viram a próxima execução

O review não para quando a execução para. O pull request está aberto, e você está lendo o diff final em Alterações. Um comentário em uma execução encerrada não tem mais um agente para alcançar, então vira uma nota para a próxima: Guardar para continuar o mantém no seu navegador. Uma barra acima dos arquivos conta esses comentários (3 comentários para uma continuação) e oferece Continuar com eles.

Toda execução encerrada, qualquer que seja o resultado, oferece dois botões. Executar novamente abre a janela de início com a mesma tarefa e o mesmo perfil, para uma nova execução do zero: a escolha certa quando a primeira tentativa foi para um lado sobre o qual você não quer construir. Continuar inicia uma nova execução que retoma o trabalho desta, com as instruções preenchidas a partir dos seus comentários para continuar, se você deixou algum, um por linha:

- docs/setup.md:28 — Say that make seed needs the database container running.
- docs/setup.md:44 — Add how to run the tests for a single package.
- README.md:18 (removed line) — Keep the troubleshooting note for port 5432, setup.md doesn't have it.

Edite como quiser. O perfil padrão é o da execução, e você pode escolher conectores.

Mesma branch, mesmo pull request

Uma continuação é mais do que uma nova execução com um prompt mais longo. Ela parte da branch que a execução anterior publicou, faz commit nela e adiciona suas alterações ao mesmo pull request em vez de abrir outro. Se a execução anterior abriu o repositório pelo conector do GitHub, a continuação o abre de novo nessa branch antes de o agente começar.

O agente também fica sabendo sobre o que está construindo. A tarefa anterior, o que aquela execução fez (o resumo do resultado, ou por que ela parou) e onde está o trabalho dela vão todos no topo do prompt (os IDs, a URL e o resumo são exemplos):

# Continuing a previous run
This run continues the work of run `4f1c2a9e-7b3d-4e0a-9c6f-2d8b1a5e3c70`. Build on what it did rather than starting over.

## What it was asked
Document how to set up and run the service locally.

## What it did
Added docs/setup.md with prerequisites, environment variables and the make targets, and linked it from the README. Left the staging database out, as answered.

Its changes are on the branch `archyl/agent-4f1c2a9e`, which your workspace starts from. Your changes are added to its pull request: https://github.com/acme/billing/pull/212. If the workspace could not start from that branch, the run feed says so and your changes go to a new pull request.

The task below is what the person wants now, often review comments on that work: address each of them.

Quem revisa vê um único pull request crescer, não um rastro deles. O Copilot cloud agent do GitHub trata os follow-ups do mesmo jeito: você menciona @copilot em um comentário de um pull request e, por padrão, ele faz push de commits na branch desse pull request (GitHub Docs). Um pull request por unidade de trabalho é o formato certo, e as continuações seguem esse formato.

O que esperar nos casos de borda:

• A branch não existe mais, por exemplo porque foi mesclada e excluída. A continuação parte da branch padrão e abre um novo pull request, e uma linha âmbar no feed avisa: "Não foi possível obter o branch archyl/agent-4f1c2a9e da execução anterior. Esta execução parte do branch padrão e abrirá um novo pull request."
• O pull request está em rascunho. Continua em rascunho. Marque-o como pronto para revisão quando o trabalho estiver concluído.
• Só branches de agentes. O Archyl continua em branches que os agentes dele criaram, as que ficam em archyl/, e nunca faz commit em uma branch criada por uma pessoa.

As duas execuções apontam uma para a outra: a nova mostra Continua a execução, a anterior Continuada em. Uma execução ainda em andamento não pode ser continuada. Comente as linhas dela.

A continuação também mantém o contexto de arquitetura. A sessão de trabalho dela é aberta para a tarefa anterior mais o follow-up, não só para o follow-up, então ela encontra os mesmos elementos de arquitetura e a mesma memória que a execução que continua. Isso importa mais do que parece. "Diga que make seed precisa do container do banco de dados rodando" não nomeia serviço nenhum, e uma sessão aberta só com essa linha teria pouca coisa com que casar.

O que isso não faz

O worker não tem shell. Ele lê, grava, edita, lista e busca arquivos, mas não consegue buildar o projeto nem rodar os testes. Neste exemplo, ele pode ler o Makefile, mas não rodar make build para conferir se o documento está certo. Um diff limpo não é um build passando, e a CI continua fazendo esse trabalho.

Um comentário de linha é orientação, não um gate. Não existe estado de resolvido, e nada verifica se o agente tratou um comentário. Você vê a próxima edição dele no diff e julga.

As notas para continuar ficam em um só navegador. Até você continuar a execução, seus colegas não veem os comentários que você guardou para continuar. Comentários enviados a um agente em andamento são diferentes: ficam no feed, visíveis para todos.

A revisão do plano pressupõe que tem alguém por perto. É uma configuração por perfil, desativada por padrão, e toda execução naquele perfil a respeita, inclusive as agendadas. Uma execução às 3 da manhã em um perfil com a revisão ativada espera uma hora e depois falha sem alterar nada. As perguntas também esperam uma hora, e depois o agente decide sozinho.

O clone via conector só funciona com GitHub. open_repository funciona com o servidor MCP hospedado do GitHub. Para qualquer outro host, vincule o repositório ao projeto.

Por onde começar

Escolha uma tarefa pequena que você revisaria de qualquer jeito e rode em um perfil com Revisar o plano primeiro ativado. Deixe a página da execução aberta. Edite o plano antes de aprovar, mesmo que tudo o que você faça seja remover a etapa que você não teria pedido. Em Alterações, comente a primeira linha que você teria apontado no pull request e veja o comentário passar de Na fila para Entregue. Quando a execução terminar, deixe o resto como comentários para continuar e clique em Continuar.

Deixe a revisão do plano desativada nos perfis que seus agendamentos usam, a menos que alguém vá estar acordado para revisar.

Planos, perguntas, o diff ao vivo, comentários de linha e continuações fazem parte das execuções gerenciadas de agentes no Archyl. Todas as configurações e rótulos citados acima estão na documentação de execuções gerenciadas de agentes. Leituras relacionadas: agentes gerenciados agora respondem ao Harness, sobre o Guard e as sessões de trabalho em que isso se apoia, e o lançamento das execuções gerenciadas de agentes.