Propostas e validação
Como as alterações do ElevenAgents Architect são testadas, revisadas e implementadas no tráfego ativo.
Visão geral
Quando o ElevenAgents Architect conclui uma alteração, ele entrega a você 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 em produção.
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 abre manualmente. Ela não é um tipo de objeto separado.
Uma proposta de merge abrange exatamente uma branch de origem e uma branch de destino, portanto cada 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 atua como você, portanto 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 para ele corrigir ou melhorar algo, ou quando fornece a ele um teste com falha, uma descoberta do Spotlight ou um problema. A sequência completa, com as ferramentas que o Architect chama em cada etapa, está no exemplo detalhado. Em resumo:
- O Architect investiga, cria uma branch e prepara a alteração no seu rascunho nessa branch.
- O Architect cria 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 nas execuções de teste reais da branch. - O Architect oferece enviar uma pequena parcela do tráfego em produção para a branch enquanto a proposta é revisada. Isso requer sua aprovação.
Você pode parar em qualquer etapa. Uma branch com uma versão publicada, mas sem proposta de merge, continua sendo útil: você pode testá-la por conta própria ou abrir uma proposta mais tarde.
Validação dentro da conversa
O Architect cria e executa testes como parte da implementação da alteração, e 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 para 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 condições de sucesso. Para verificar resultados inconsistentes, 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 acesse 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 aparece 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 de destino. Ela tem estas guias:
Visão geral
Alterações
Execuções de teste
Conversas
A descrição, uma linha do tempo de atividades com 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 problema 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 a informação de que nenhum foi executado) e Como revisar (no que focar e um teste para executar ou uma conversa para experimentar).
Revisão e merge
Statuses
Uma proposta de merge tem um destes status:
Enquanto uma proposta está aberta, a revisão mais recente de cada revisor é Aprovada ou Alterações solicitadas. Não há status separados de “testado” ou “pronto para revisão”. Os resultados dos testes são mostrados na guia Execuções de teste.
As revisões e os comentários aparecem na linha do tempo de atividades na guia Visão geral, ao lado 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 o autor. Como o Architect atua como você, não é possível aprovar uma proposta que ele abriu na sua conversa. Um colega 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 aprovação.
- O merge em uma branch protegida exige permissões de administrador ou a aprovação de um administrador.
O Architect não pode aprovar, comentar, mesclar nem fechar uma proposta de merge. Essas etapas são sempre realizadas por pessoas. Consulte Propostas de merge para conhecer as regras completas de revisão.
O Architect pode mesclar uma branch diretamente, sem uma proposta, quando você pede isso e sua função permite
o merge. No modo Aprovação necessária, ele pergunta primeiro. No modo Aprovação automática, não pergunta. Use
a 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 cria uma nova versão na branch de destino, e essa versão atende imediatamente ao tráfego em produção correspondente à parcela de tráfego recebida pelo destino. Quando o destino é a main e não há divisão de tráfego configurada, isso significa todos os usuários.
O merge também:
- Move para o destino qualquer parcela de tráfego em produção que a branch de origem tinha.
- Arquiva a branch de origem por padrão.
- Fecha qualquer outra proposta aberta da mesma branch.
- Resolve o problema vinculado, se houver um.
Lançamento gradual
Antes que uma proposta seja mesclada, você pode enviar uma parcela do tráfego em produção para a branch dela, para que usuários 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, exige 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 problema. 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 as Próximas etapas sugeridas ou abra um alerta em tempo real.
Encaminhe para o ElevenAgents Architect
Selecione Abrir no Architect em uma sugestão, Analisar com o Architect no resumo ou Investigar com o Architect em um alerta. O Architect recebe a descoberta e é instruído a verificá-la em conversas reais e identificar qual branch foi afetada antes de sugerir uma alteração.
Os problemas funcionam da mesma forma. Seu agente em produção pode sinalizar problemas para revisão durante as conversas, e Conversar com o Architect em um problema inicia uma investigação.
Automações agendadas, com relatórios entregues a uma caixa de entrada do Architect, estão em desenvolvimento. A guia Caixa de entrada na página do Architect é um espaço reservado para elas.