A maioria dos fluxos de trabalho com múltiplos agentes não falha na parte difícil. O agente escreve o código, executa os testes e abre o pull request. A falha ocorre na transição: no exato momento em que o trabalho sai de um agente e deveria chegar a outro lugar. Um agente de backend finaliza um endpoint, mas o agente de frontend nunca descobre que ele está pronto. Uma refatoração vai parar em uma worktree e fica lá, com testes passando no verde, porque nenhum humano foi avisado para avaliar. A tarefa não quebrou. O handoff, sim.
O handoff entre agentes de IA é a transferência de uma etapa de trabalho, somada ao seu contexto, de um executor para o seguinte: de agente para agente, ou de agente para humano. Quando você roda um único agente de código em um terminal, os handoffs são invisíveis porque simplesmente não existem. A partir do momento em que você executa dois agentes, ou um agente e um revisor humano, cada etapa concluída precisa ser entregue em um local onde o próximo executor consiga encontrá-la. Esse ponto de encontro é o segredo de todo o processo.
Este artigo explora os padrões de handoff que realmente funcionam na prática, usando o Sharkly como modelo de fluxo de trabalho: a camada posicionada acima dos seus agentes de programação que mantém contexto, progresso, bloqueios, resultados e revisão humana visíveis desde a solicitação inicial até a publicação em produção. Você já conta com agentes de código. O problema que este artigo resolve é o que acontece nas lacunas entre eles.
Resumo direto ao ponto
O handoff é o momento em que o trabalho e seu contexto passam de um executor para o próximo. Os handoffs de agente para agente transferem uma subtarefa concluída para o próximo agente; os handoffs de agente para humano interrompem a execução autônoma em um ponto de controle de revisão. Torne ambos explícitos por meio de status: os Agentes movem uma Tarefa para Ready for review, e as Pessoas a movem para Done. Quando o handoff é uma mudança de status em uma Tarefa compartilhada, em vez de uma mensagem perdida no terminal, nada é esquecido silenciosamente.
O que é exatamente um handoff entre agentes
Um handoff é composto por três partes essenciais, e negligenciar qualquer uma delas é o motivo pelo qual tarefas se perdem: o artefato (o diff, o PR, a migration), o contexto (o que foi pedido, o que mudou, o que ainda é incerto) e o destinatário (o agente específico ou a pessoa responsável pela etapa seguinte).
Fluxos de trabalho baseados em terminal carregam o artefato, mas perdem os outros dois elementos. O commit existe, mas toda a linha de raciocínio fica restrita a um histórico de rolagem do terminal que apenas um agente viu, e o “próximo da fila” é quem por acaso resolver conferir. É por isso que a orquestração de agentes tem menos a ver com iniciá-los e mais com rotear o que eles produzem.
Um handoff bem estruturado transfere os três elementos em conjunto: a alteração, o resumo do que foi e do que não foi feito, e um sinal inequívoco de que chegou a vez do destinatário. Na prática com o Sharkly, a execução, os bloqueios, os resultados e as discussões de acompanhamento retornam para a linha do tempo da Tarefa, permitindo que o próximo executor consulte um único registro centralizado em vez de ter que remontar três fontes distintas.
Dois padrões de handoff
Os dois padrões parecem semelhantes na superfície, mas possuem premissas opostas. Um handoff de agente para agente deve ocorrer automaticamente: o próximo Agente assume uma subtarefa pronta e segue em frente. Já o handoff de agente para humano deve pausar por padrão: o Agente finaliza sua parte e aguarda, pois a tomada de decisão cabe a uma pessoa.
| De agente para agente | De agente para humano | |
|---|---|---|
| Gatilho | Uma subtarefa é marcada como pronta | O trabalho atinge um portão de revisão |
| Comportamento padrão | Continuar automaticamente | Parar e aguardar |
| Conteúdo transferido | Artefato + contexto + critérios de aceitação | Diff + resumo das alterações + limitações conhecidas |
| Risco em caso de ausência | Trabalho duplicado ou conflitante | Código sem revisão mesclado às cegas |
Aqui está o critério que mantém o processo confiável. Automatize o handoff de agente para agente quando o próximo passo for bem delimitado e seus critérios de aceitação já estiverem documentados: “executar a suíte de testes”, “gerar a migration”, “atualizar a especificação OpenAPI”. Force um handoff de agente para humano quando a etapa seguinte exigir um julgamento que o agente não tem autonomia para assumir: fazer merge na branch main, alterar contratos públicos de API, mexer em autenticação ou faturamento, ou homologar uma entrega como concluída.
O erro clássico é tratar todos os handoffs da mesma forma. Automatizar tudo sem travas faz com que alterações sem revisão cheguem a produção; colocar travas em tudo recria um pipeline manual lento com etapas extras desnecessárias. Isso está diretamente ligado a saber onde posicionar portões de aprovação, garantindo que os agentes parem antes de erros que custam caro, e não a cada detalhe insignificante.
Status tornam o handoff um ponto de controle, não uma torcida
O modelo operacional se resume a quatro ações fundamentais e a quem responde por cada uma: quem atribui, quem executa, quem revisa e quem aprova. Agentes pesquisam, executam, testam e reportam. Pessoas estabelecem o direcionamento, concedem autorizações e validam o resultado. A automação para exatamente onde o discernimento da equipe passa a ser indispensável.
Os status são o que transformam esse acordo em uma engrenagem prática, e não em mera intenção. Toda Tarefa passa pelo mesmo fluxo:
- Todo: atribuída, mas não iniciada. Uma pessoa ou um Agente líder a posicionou aqui.
- In progress: um Agente assumiu a tarefa e está trabalhando nela em uma worktree isolada.
- Ready for review: o limite de atuação do Agente. Ele executou a checagem de tipos (typecheck), os testes e o build, anexou o resumo das mudanças e as limitações conhecidas, e encerrou sua parte.
- Done: a fronteira humana. Uma pessoa validou a entrega e tomou a decisão de merge e release.
A regra que torna toda a operação transparente: Agentes movem a Tarefa para Ready for review; Pessoas a movem para Done. Um Agente nunca marca a própria entrega como Done, e ninguém da equipe precisa adivinhar se uma Tarefa com status verde está realmente pronta para ir ao ar. O próprio status é o handoff. Quando há dez agentes em execução simultânea, você não precisa ficar vasculhando dez terminais; basta olhar o painel para ver exatamente o que está aguardando você, o que depende de outro agente e o que ainda está em execução. Essa clareza é o que separa acompanhar o que os agentes concluíram de apenas torcer para que o log de commits explique tudo mais tarde.
Um exemplo prático: do ticket ao PR mesclado
Vejamos uma Tarefa real, a SH-312: “Adicionar rate limiting à API pública”. Acompanhe os handoffs, não o código.
Uma pessoa descreve a necessidade em linguagem natural e faz a atribuição da tarefa. Um Agente líder analisa a base de código e o histórico de tarefas anteriores, define o escopo e os critérios de aceitação (limite por chave de API, resposta HTTP 429 com cabeçalho Retry-After, cobertura para os três endpoints de maior tráfego) e decompõe a SH-312 em três subtarefas executáveis. Esse é o primeiro handoff de agente para agente: entra um objetivo, saem subtarefas prontas para execução.
As subtarefas fluem de forma automática. Um Agente de backend assume a lógica do limitador de taxa; um Agente de testes assume a cobertura de código. Como cada um opera em uma worktree isolada, eles não colidem ao editar os mesmos arquivos, e os resultados retornam diretamente para a SH-312, em vez de ficarem restritos a uma sessão isolada. Quando o Agente de backend conclui, ele não notifica um humano; ele marca sua subtarefa como pronta, e o Agente de testes passa a utilizar a implementação concreta no lugar de um mock.
Em seguida, o tipo de handoff se inverte. Com o limitador pronto, a checagem de tipos limpa, os testes passando e o build no verde, a entrega atinge o portão de controle entre agente e humano. O Agente move a SH-312 para Ready for review e anexa o diff, um resumo das alterações e uma limitação conhecida: “O contador em Redis assume uma única região; suporte a múltiplas regiões requer uma etapa complementar”. Um revisor humano confere essas informações em um único local, valida o comportamento do status 429 e move a tarefa para Done, acionando a mesclagem. Do ticket ao PR mesclado, com o histórico auditável de quem fez o quê em cada transição. É o mesmo princípio que torna o fluxo dos requisitos ao código rastreável de ponta a ponta.
Onde os handoffs falham e como mantê-los sob controle
Os handoffs falham em três pontos previsíveis, e cada um deles exige uma solução estrutural em vez de contar com a boa memória de alguém.
O contexto se perde. O agente sabia a razão de cada escolha de implementação; o revisor não sabe. Solução: o handoff carrega o resumo das alterações e as limitações conhecidas como pré-requisito para avançar para Ready for review, não como algo secundário. A responsabilidade fica indefinida. Dois agentes assumem o mesmo trabalho, ou nenhum assume. Solução: definir um responsável (Assignee) em cada Tarefa e subtarefa, transformando a vez de agir em um campo formal, não em uma suposição. A revisão nunca acontece. Código autônomo é integrado porque ninguém foi acionado para pausá-lo. Solução: um status intransponível para o agente sem intervenção humana.
É possível organizar toda essa estrutura manualmente combinando worktrees, convenções de nomenclatura e disciplina da equipe. Essa abordagem até funciona no início, até que o número de agentes, tarefas e repositórios cresça e a disciplina seja a primeira coisa a falhar. Para quem já gerencia múltiplos agentes, o Sharkly centraliza o controle de tarefas e resultados em um só lugar: Tarefas compartilhadas, responsáveis bem definidos por item, worktrees isoladas e um fluxo de status no qual Agentes chegam até Ready for review e Pessoas decidem o Done. Continue usando seus agentes de código atuais e adicione a camada que torna as transições entre eles visíveis. Baixe o Sharkly quando o atrito nas transições entre seus agentes começar a custar mais caro do que o desenvolvimento em si.
FAQ
O que é um handoff de agentes de IA? É a transferência de uma tarefa, acompanhada de todo o seu contexto e da sinalização formal de quem é o próximo responsável, de um executor para o seguinte. As duas modalidades principais são: de agente para agente (uma subtarefa finalizada é encaminhada ao agente seguinte) e de agente para humano (o trabalho autônomo é interrompido em um portão de revisão).
Qual é a diferença entre handoffs de agente para agente e de agente para humano? Handoffs de agente para agente devem prosseguir de forma autônoma sempre que os critérios de aceitação da próxima fase já estiverem claros e definidos. Já os handoffs de agente para humano devem pausar por padrão e aguardar uma validação, pois exigem julgamento crítico: fazer merge, alterar uma API pública ou homologar uma entrega.
Os agentes devem marcar o próprio trabalho como concluído? Não. Os Agentes devem avançar a Tarefa para Ready for review após executarem os testes e anexarem o resumo das alterações; a transição para Done e a decisão final de merge devem ser exclusivas de uma pessoa. Separar essas duas fronteiras é a garantia de que código não revisado não chegará a produção. Saiba mais sobre agentes de código com humanos no circuito (human-in-the-loop).
Como o uso de status evita que tarefas sejam esquecidas? Quando o handoff ocorre por meio de uma mudança de status em uma Tarefa compartilhada, em vez de uma mensagem solta no terminal, o próximo responsável enxerga exatamente o que está aguardando sua ação. O fluxo deixa de depender de alguém conferir o histórico do terminal no momento certo. Uma Inbox de agentes reúne e destaca as demandas que precisam da sua atenção.
É obrigatório usar uma ferramenta para isso ou posso fazer tudo manualmente? É perfeitamente possível operar com worktrees e um quadro de tarefas compartilhado. Contudo, adotar uma camada dedicada se paga rapidamente assim que você precisa orquestrar múltiplos agentes em vários repositórios e o acompanhamento manual se torna o principal gargalo. Analise o modelo mental de assistentes versus colegas de equipe de IA para tomar a melhor decisão.
