Propostas e validação
Propostas e validação
Como as alterações do Architect são testadas, revisadas e implementadas no tráfego ao vivo.
Visão geral
Quando o Architect conclui uma alteração, ele a entrega a você como uma proposta: uma branch que contém a alteração, testes que mostram que ela funciona e uma proposta de merge solicitando que essa branch seja mesclada à main. Esta página explica como cada parte funciona, onde encontrá-la e como uma proposta passa de uma conversa para o tráfego ao vivo.
O que é uma proposta
Uma proposta é criada a partir do modelo de versionamento existente:
A proposta de merge é uma proposta de merge padrão do ElevenAgents, do mesmo tipo que um colega de equipe abre manualmente. Não é um tipo de objeto separado.
Uma proposta de merge abrange exatamente uma branch de origem e uma branch de destino, portanto uma proposta contém uma solução candidata. Para comparar alternativas, peça ao Architect para colocar cada uma em sua própria branch. Cada branch terá então sua própria proposta, e você poderá dividir o tráfego entre elas como um experimento.
O Architect age como você, então uma proposta de merge aberta por ele é registrada em seu nome como autor. Nenhum campo registra que o Architect a criou. Mencione isso na descrição da proposta se sua equipe quiser saber.
Como uma proposta é criada
O Architect cria uma proposta quando você pede que ele corrija ou melhore algo, ou quando você fornece a ele um teste com falha, uma descoberta do Spotlight ou um ticket de triagem. A sequência completa, com as ferramentas que o Architect chama em cada etapa, está no exemplo prático. Em resumo:
- O Architect investiga, cria uma branch e prepara a alteração no seu rascunho nessa branch.
- O Architect escreve testes e simulações para a alteração e os executa na conversa antes de mostrar o resultado a você.
- O Architect abre a caixa de diálogo de publicação. Você revisa o diff e seleciona Publicar, o que confirma a alteração como uma nova versão na branch.
- O Architect abre uma proposta de merge para a
main, escrevendo sua descrição com base nos commits e execuções de teste reais da branch. - O Architect oferece enviar uma pequena parte do tráfego ao vivo para a branch enquanto a proposta é revisada. Isso precisa da sua aprovação.
Você pode parar em qualquer etapa. Uma branch com uma versão publicada, mas sem proposta de merge, ainda é útil: você pode testá-la por conta própria ou abrir uma proposta mais tarde.
Validação na conversa
O Architect escreve e executa testes como parte da criação da alteração, não como uma etapa separada que você inicia depois. Para uma correção, um padrão útil é mostrar que os novos testes falham sem a alteração e passam com ela. O Architect pode executar os mesmos testes na branch original e no rascunho que contém a alteração.
O Architect não executa essa verificação de antes e depois automaticamente em todas as alterações. Peça isso quando for importante, por exemplo: “Mostre a nova simulação falhando na main e passando na branch, depois abra uma proposta.”
Um teste passa quando todas as condições de sucesso são atendidas. Em um teste de LLM, a resposta do agente atende aos critérios de sucesso. Em um teste de chamada de ferramenta, a ferramenta esperada é chamada com os parâmetros esperados. Em uma simulação, a conversa simulada atende às suas condições de sucesso. Para verificar resultados instáveis, peça ao Architect para executar os testes várias vezes. Ele pode repetir cada teste até 50 vezes e informar a taxa de aprovação.
Consulte Testes para saber como cada tipo de teste é definido.
Onde encontrar propostas
Abra o agente e depois vá para Controle de versão > Propostas. A lista pode ser filtrada por status, por autor (Criado por) e por revisor (Aguardando revisão de, Revisado por). Uma proposta que o Architect abriu na sua conversa é listada com você como autor.
O Architect também retorna um link para a proposta na conversa assim que a cria.
Anatomia de uma proposta
A página de uma proposta mostra as branches de origem e destino, seu status, se ela pode ser mesclada e o quanto a branch de origem está atrás ou à frente da branch de destino. Ela tem estas abas:
Visão geral
Alterações
Execuções de teste
Conversas
A descrição, uma linha do tempo de atividade dos commits na branch de origem, revisões e comentários, além de uma caixa de comentários. A barra lateral mostra revisores, revisores recomendados e qualquer ticket de triagem vinculado.
Uma descrição escrita pelo Architect sempre tem três seções: Resumo (cada alteração relevante e o motivo), Testes (quais testes foram executados e seus resultados, ou uma declaração de que nenhum foi executado) e Como revisar (em que se concentrar e um teste a executar ou uma conversa para experimentar).
Revisão e merge
Status
Uma proposta de merge tem um destes status:
Enquanto uma proposta estiver aberta, a revisão mais recente de cada revisor será Aprovada ou Alterações solicitadas. Não há status separados de “testado” ou “pronto para revisão”. Os resultados dos testes são exibidos na aba Execuções de teste.
Revisões e comentários aparecem na linha do tempo de atividade na aba Visão geral, junto de cada nova versão confirmada na branch de origem.
Quem pode aprovar e mesclar
- Qualquer pessoa com acesso de editor ao agente pode revisar uma proposta, exceto seu autor. Como o Architect age como você, você não pode aprovar uma proposta que o Architect abriu na sua conversa. Um colega de equipe precisa fazer isso.
- Uma proposta pode ser mesclada quando tiver pelo menos uma aprovação de alguém que não seja o autor e a revisão mais recente de nenhum revisor for Alterações solicitadas. Administradores do espaço de trabalho podem mesclar sem uma aprovação.
- Fazer merge em uma branch protegida requer permissões de administrador ou a aprovação de um administrador.
O Architect não pode aprovar, comentar, mesclar ou fechar uma proposta de merge. Essas etapas são sempre realizadas por pessoas. Consulte Propostas de merge para ver as regras completas de revisão.
O Architect pode mesclar uma branch diretamente, sem uma proposta, quando você pedir e sua função permitir
o merge. No modo Aprovação obrigatória, ele pergunta primeiro. No modo Aprovação automática, não pergunta. Use
proteção de branch na main se todas as alterações precisarem passar por uma proposta revisada.
O que acontece no merge
Não há uma etapa de publicação separada após um merge. O merge grava uma nova versão na branch de destino, e essa versão atende imediatamente o tráfego ao vivo para qualquer parcela de tráfego que o destino receba. Quando o destino é a main e não há divisão de tráfego configurada, isso significa todos os chamadores.
O merge também:
- Move para o destino qualquer parcela de tráfego ao vivo que a branch de origem tinha.
- Arquiva a branch de origem por padrão.
- Fecha qualquer outra proposta aberta da mesma branch.
- Resolve o ticket de triagem vinculado, se houver um.
Implementação gradual
Antes de uma proposta ser mesclada, você pode enviar uma parcela do tráfego ao vivo para a branch dela para que chamadores reais testem a alteração.
Inicie a divisão
Peça ao Architect, por exemplo: “Envie 5% do tráfego para esta branch.” O Architect informa a divisão
resultante completa, incluindo a parcela da main, e pede aprovação antes de aplicá-la. Você também pode
configurá-la: em Controle de versão > Branches, selecione Implantar na branch.
As parcelas de tráfego devem sempre totalizar 100%, e o roteamento é determinístico por conversa. Alterar a parcela de uma branch protegida, incluindo retirar tráfego de uma main protegida, requer um administrador. Consulte Implantação de tráfego.
Propostas proativas
O Architect produz propostas quando você pede ou quando fornece a ele um teste com falha, uma descoberta do Spotlight, um alerta ou um ticket de triagem. Ele ainda não verifica seus agentes em uma programação nem abre propostas por conta própria.
Hoje, o caminho proativo é Spotlight, seguido de um encaminhamento. O Spotlight monitora continuamente as conversas do seu agente. Ele produz um resumo semanal com investigações sugeridas, emite alertas em tempo real e recomenda alterações de configuração. Para transformar uma descoberta do Spotlight em uma proposta:
Escolha uma descoberta
Abra o resumo semanal e revise Próximas etapas sugeridas ou abra um alerta em tempo real.
Os tickets de triagem funcionam da mesma forma. Seu agente ao vivo pode sinalizar problemas para revisão durante as conversas, e Discutir com o Architect em um ticket inicia uma investigação sobre ele.
Automações agendadas, com relatórios entregues a uma caixa de entrada do Architect, estão em desenvolvimento. A aba Caixa de entrada na página do Architect é um espaço reservado para elas.