Encadear agentes usando transferências para tarefas de várias etapas

Concluído

Agentes personalizados individuais são poderosos por conta própria, mas todo o seu potencial surge quando você os conecta em sequência para lidar com tarefas complexas de desenvolvimento de várias etapas. A transferência de responsabilidades permite que um agente sugira a próxima etapa a outro agente, mantendo o contexto da conversa e proporcionando uma transição perfeita entre funções especializadas.

O que são transferências?

A transferência é um mecanismo que permite que um agente personalizado proponha uma transição para outro agente após concluir sua parte de uma tarefa. Quando um agente conclui sua resposta, ele pode apresentar um botão de entrega — uma "próxima ação" sugerida que, quando selecionado, alterna o chat para um agente de destino e, opcionalmente, pré-filtra um prompt para continuar o fluxo de trabalho.

Por exemplo, um agente do Planner pode produzir um plano de implementação detalhado e exibir um botão "Iniciar Implementação". Quando o desenvolvedor seleciona esse botão, o GitHub Copilot Chat alterna para um agente do Implementador que recebe o plano como contexto, juntamente com um prompt como "Agora implemente seu plano sugerido". O desenvolvedor analisa o plano antes de selecionar o botão, mantendo o controle sobre o fluxo de trabalho enquanto os agentes lidam com o trabalho especializado.

Essa abordagem cria um fluxo de trabalho estruturado de vários agentes em que cada agente lida com uma fase específica do processo de desenvolvimento. O desenvolvedor supervisiona cada transição, garantindo a qualidade e a correção em cada etapa. As transferências não são executadas automaticamente por padrão — elas exigem que o desenvolvedor selecione o botão de transferência, o que mantém o usuário no processo.

Configurando as transferências

Para configurar uma transferência, adicione uma seção handoffs no frontmatter YAML do arquivo de um agente personalizado .agent.md. Cada entrada de transferência especifica a conexão entre o agente atual e o agente de destino.

Uma entrada de entrega inclui os seguintes campos:

• rótulo: o texto exibido no botão de entrega (por exemplo, "Iniciar Implementação" ou "Executar Testes").

• agente: o nome ou o identificador do agente de destino para o qual alternar. Esse nome deve corresponder ao nome do arquivo (sem a .agent.md extensão) ou ao name campo do agente de destino.

• prompt: uma mensagem opcional a ser enviada para o próximo agente. Esse prompt fornece contexto ou instruções para o agente de destino, como "Agora implemente seu plano sugerido" ou "Examine as alterações de código feitas na etapa anterior".

• send: um valor booliano que controla se o prompt é enviado automaticamente. Quando definido como false (o padrão), o prompt é preenchido previamente no campo de entrada de chat para o desenvolvedor revisar e editar antes de enviar. Quando definido como true, o prompt é enviado imediatamente e o agente de destino começa a funcionar imediatamente.

• modelo: um campo opcional que especifica um modelo de IA específico a ser usado quando a entrega é executada. O formato é Model Name (vendor), como GPT-4.1 (OpenAI) ou Claude Sonnet 4 (Anthropic). Esse campo é útil quando diferentes estágios de um fluxo de trabalho se beneficiam de diferentes funcionalidades de modelo, por exemplo, usando um modelo de raciocínio para planejamento e um modelo mais rápido para implementação.

O seguinte trecho do YAML mostra um agente Planner configurado com uma transferência para um agente Implementador:

---
description: Generates high-level implementation plans without writing code
tools: ['search', 'read', 'fetch']
handoffs:
  - label: Start Implementation
    agent: implementer
    prompt: Now implement the plan outlined above.
    send: false
---

Quando o agente planner conclui sua resposta, um botão "Iniciar Implementação" é exibido no chat. Selecionar este botão alterna para o agente Implementador, mantém o histórico da conversa (incluindo o plano) e preenche previamente o texto de instruções para o desenvolvedor revisar.

Um agente pode definir várias transferências para oferecer diferentes alternativas de próximos passos. Por exemplo, um agente do Planner pode oferecer botões "Iniciar Implementação" e "Gravar Testes Primeiro", permitindo que o desenvolvedor escolha o caminho apropriado com base na situação.

Revisão e aceitação de transferências

As entregas sempre envolvem uma ação explícita do usuário, selecionando o botão de entrega, a menos que o send campo esteja definido como true. Esse design garante que o desenvolvedor permaneça no controle do fluxo de trabalho e possa examinar a saída de cada agente antes de passar para a próxima etapa.

Cada agente em uma cadeia opera dentro de seu próprio conjunto de ferramentas e conjunto de instruções definidos. Esse ambiente fornece guardrails em cada etapa do fluxo de trabalho. Por exemplo:

• Um agente de planejamento com apenas read e search ferramentas pode coletar informações e propor planos, mas não pode modificar acidentalmente o código.
• Um agente de implementação com read, edite terminal ferramentas podem escrever código e executar comandos de build, mas segue as diretrizes de codificação específicas em suas instruções.
• Um agente de revisão com apenas read e search ferramentas pode analisar o código gerado, mas não pode modificá-lo, garantindo que sua revisão seja puramente consultiva.

Essas restrições específicas de função tornam os processos de várias etapas mais confiáveis, impedindo ações não intencionais em cada fase. O desenvolvedor revisa a saída em cada ponto de entrega e só prossegue quando satisfeito com o resultado.

Fluxos de trabalho comuns de várias etapas

Os cenários a seguir demonstram como encadear agentes personalizados pode melhorar a produtividade em diferentes atividades de desenvolvimento.

Planejando → implementação

Use um agente do Planner para analisar os requisitos e produzir um plano de implementação detalhado para um novo recurso. O plano identifica quais arquivos precisam de alterações, descreve as etapas de implementação e realça possíveis riscos. A tarefa é então transferida para um agente Implementador que escreve o código de acordo com o plano, seguindo os arquivos de instruções personalizados do projeto para padrões de codificação.

Esse fluxo de trabalho espelha como os engenheiros seniores planejam o trabalho antes do início da implementação, usando IA para ambos os estágios, mantendo o desenvolvedor no controle da transição.

Implementação → revisão de código

Depois que o código é gerado, seja por um desenvolvedor humano ou por um agente de IA, uma transferência pode ser feita para um agente de Revisão de Código. O agente de revisão avalia a qualidade do novo código, verificando se há bugs, problemas de segurança, violações de estilo e casos extremos ausentes. Em seguida, o agente de revisão pode fornecer comentários sobre correções manuais ou entregar a um agente "Fixer" que aplica correções, sujeito à aprovação do desenvolvedor.

Escrever testes falhos → Escrever código para passar

Aplique o Desenvolvimento Orientado por Testes (TDD) usando uma cadeia de dois agentes. Primeiro, um agente gerador de teste cria testes de unidade com falha para um requisito especificado. O desenvolvedor revisa os testes para confirmar que capturam o comportamento pretendido. Em seguida, a tarefa é transferida para um agente implementador que escreve o código mínimo necessário para que esses testes sejam aprovados. Essa cadeia impõe um ciclo de testes vermelho-verde com assistência de IA, produzindo tanto os testes quanto a implementação.

Depuração e aplicação de patch

Para cenários de correção de bugs, um agente de Depuração lê logs de erros, examina testes com falha e analisa o código relevante para hipotizar a causa do problema. Assim que o diagnóstico estiver concluído, o processo é transferido para um agente de aplicação de patches com permissões de edição para aplicar a correção. Uma entrega final pode invocar um agente de teste para executar o conjunto de testes e verificar se o problema foi resolvido.

Refatoração ou atualização

Use um agente de planejamento para analisar uma base de código existente e estruturar um plano de refatoração ou migração, por exemplo, atualizar um projeto C# de uma versão mais antiga do .NET para o .NET 8. O plano identifica quais arquivos, APIs e padrões precisam ser alterados. A transferência de responsabilidade é feita para um agente de atualização que executa as modificações de código nos arquivos de acordo com o plano. Uma entrega final para um agente de revisão verifica o código atualizado em busca de problemas introduzidos durante a migração.

Observação

Esses fluxos de trabalho refletem como as equipes de desenvolvimento podem delegar uma sequência de tarefas — planejar, codificar, testar, revisar — a diferentes auxiliares especializados de IA durante a supervisão de cada etapa. O resultado é um fluxo de trabalho mais eficiente em que tarefas repetitivas ou complexas são tratadas pela IA, liberando o desenvolvedor para se concentrar na tomada de decisões e na verificação.

Ambientes de execução do agente

Por padrão, agentes personalizados são executados no cliente (dentro do Visual Studio Code). No entanto, os agentes também podem ser configurados para serem executados na nuvem definindo target: cloud o frontmatter YAML do agente. Os agentes de nuvem são executados remotamente e são mais adequados para tarefas de execução longa, como a criação de um recurso inteiro ou a execução de um conjunto de testes abrangente, que, de outra forma, manteriam sua instância local do Visual Studio Code ocupada. Os agentes em segundo plano são um conceito relacionado: eles são executados independentemente sem bloquear a interface de chat, permitindo que você continue trabalhando enquanto o agente processa uma tarefa.

Ganchos do GitHub Copilot

Os ganchos do GitHub Copilot permitem executar comandos de shell personalizados em pontos estratégicos no fluxo de trabalho de um agente. Os ganchos são definidos nas configurações do Visual Studio Code (não nos arquivos do agente) e disparam antes ou depois de eventos específicos, como antes de o GitHub Copilot salvar um arquivo ou depois de executar um comando de terminal. Por exemplo, você pode configurar um gancho para executar um linter automaticamente depois que o GitHub Copilot edita um arquivo, garantindo que o código gerado por IA sempre atenda aos seus padrões de formatação antes de ser salvo.

Os hooks ampliam as capacidades de automação dos fluxos de trabalho multiagentes, adicionando ações baseadas no ciclo de vida que complementam as instruções e ferramentas do próprio agente.

Observação

Ganchos são um recurso de visualização e seu formato de configuração pode mudar. Eles são configurados nas configurações github.copilot.chat.hooks do Visual Studio Code e dão suporte a eventos como postSaveFile, preRunTerminalCommande postRunTerminalCommand.

Resumo

As transferências conectam vários agentes personalizados em fluxos de trabalho sequenciais guiados, permitindo tarefas de desenvolvimento com várias etapas, onde cada agente lida com uma fase específica. Ao configurar transferências no frontmatter YAML de arquivos de agente, você pode criar cadeias que fazem a transição do planejamento para a implementação, da implementação para a revisão ou qualquer outra sequência que corresponda ao processo de desenvolvimento da sua equipe. Cada entrega mantém o desenvolvedor no controle, com a opção de examinar e aprovar antes de prosseguir para a próxima etapa. Outros recursos, como agentes de nuvem, execução em segundo plano e ganchos do GitHub Copilot, estendem esses fluxos de trabalho com processamento remoto e automação do ciclo de vida.