> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Propostas e validação ## Visão geral Quando o ElevenAgents Architect conclui uma alteração, ele a entrega a você como uma **proposta**: uma branch que contém a alteração, testes que comprovam que ela funciona e uma [proposta de merge](/docs/pt/eleven-agents/operate/merge-proposals) solicitando que essa branch seja mesclada ao `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 com base no modelo existente de [versionamento](/docs/pt/eleven-agents/operate/versioning): | Parte | O que é | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Branch | Uma branch criada pelo Architect para a alteração, para que `main` e os usuários ao vivo não sejam afetados enquanto você trabalha. | | Rascunho | As edições do Architect, preparadas no seu rascunho não publicado nessa branch. | | Versão | Quando você publica o rascunho, ele se torna uma nova versão na branch. | | Testes | Os testes que o Architect escreveu para a alteração, vinculados ao agente e executados na branch. | | Proposta de merge | Uma solicitação para mesclar a branch em `main` (ou em outra branch que você escolher), com uma descrição da alteração, os testes executados e o que os revisores devem verificar. | A proposta de merge é uma proposta de merge padrão do ElevenAgents, do mesmo tipo que um colega abre manualmente. Não é um tipo de objeto separado. Uma proposta de merge abrange exatamente uma branch de origem e uma branch de destino, então 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](/docs/pt/eleven-agents/operate/experiments). > **Note** > > O Architect age 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 que ele corrija ou melhore algo, ou quando entrega 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](/docs/pt/eleven-agents/operate/architect/how-it-works#worked-example-improving-refund-resolutions). Em resumo: 1. O Architect investiga, cria uma branch e prepara a alteração no seu rascunho nessa branch. 2. O Architect escreve testes e simulações para a alteração e os executa na conversa antes de mostrar o resultado a você. 3. 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. 4. O Architect abre uma proposta de merge para `main`, escrevendo a descrição com base nos commits e nas execuções de teste reais da branch. 5. O Architect oferece enviar uma pequena parcela 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 automaticamente essa verificação de antes e depois 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 é **aprovado** 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 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](/docs/pt/eleven-agents/customization/agent-testing) para saber como cada tipo de teste é definido. ## Onde encontrar propostas Abra o agente e vá para **Controle de versão** > **Propostas**. A lista pode ser filtrada por status, autor (**Criado por**) e 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. ![Lista de propostas na página Branches](/docs/_fern-img/bfdb23ad1edb31c89c2ff2a137fa3028bf3f9fbcf31e236de142e207b5d54cd0.webp) ## 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 abas: #### Visão geral A descrição, uma linha do tempo de atividades 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 para executar ou uma conversa para experimentar). ![Aba Visão geral de uma proposta de merge](/docs/_fern-img/569eccd1750f90cd5ec8121411e8effd3a38e924e0f03f06f6216a9fcc160e08.webp) #### Alterações O diff de configuração: como ficará a branch de destino após o merge, em comparação com seu estado atual. Se as duas branches alteraram o mesmo campo, uma visualização de **Conflitos** lista cada conflito e qual lado prevalece. Após a proposta ser mesclada, esta aba mostra a branch de destino antes e depois do merge. ![Aba Alterações de uma proposta de merge](/docs/_fern-img/cd06c0f93240d7c973101b896599542290437a6dcbfa6d288a25db0c1bfcd566.webp) #### Execuções de teste A taxa de aprovação e o histórico de execuções de teste da branch de origem, incluindo as execuções iniciadas pelo Architect na conversa. Mude para a branch de destino para comparar sua taxa de aprovação. Selecione **Executar testes** para executar novamente todos os testes vinculados em qualquer branch, opcionalmente várias vezes cada um. As execuções de teste estão vinculadas à branch, não à proposta. O merge não exige que os testes sejam aprovados. Os revisores decidem com base no que a aba mostra. ![Aba Execuções de teste de uma proposta de merge](/docs/_fern-img/58e28b31cb3408fe5bf8e9193f4a4edb5e716e6023c56f29d5a4f924c70a0f7a.webp) #### Conversas Todas as conversas executadas na branch de origem, incluindo o tráfego ao vivo enviado para ela por uma divisão de tráfego. Selecione uma conversa para abrir sua transcrição. Enquanto uma branch estiver em uma implementação gradual, é aqui que você acompanha usuários reais utilizando a alteração. ![Aba Conversas de uma proposta de merge](/docs/_fern-img/f6345ff5beaee9a22732c7322995a7e889245cda7901682ab390790ef3849690.webp) ## Revisão e merge ### Status Uma proposta de merge tem um destes status: | Status | Significado | | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Aberta | Aguardando revisão ou merge. | | Mesclada | A branch foi mesclada ao destino. | | Fechada | Retirada pelo autor, rejeitada por outra pessoa ou fechada porque sua branch foi arquivada. Propostas fechadas não podem ser reabertas. | 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 exibidos na aba **Execuções de teste**. Revisões e comentários aparecem na linha do tempo de atividades da aba **Visão geral**, junto de cada nova versão confirmada na branch de origem. ![Linha do tempo de atividades de uma proposta de merge](/docs/_fern-img/522012341d0089ff418032a34bae6653d2b883934b64a0b6a12de887646b2f5f.webp) ### Quem pode aprovar e mesclar * Qualquer pessoa com acesso de editor ao agente pode revisar uma proposta, exceto o autor dela. Como o Architect age como você, você não pode aprovar uma proposta que ele abriu na sua conversa. Um colega precisa fazer isso. * Uma proposta pode ser mesclada depois de receber pelo menos uma aprovação de alguém que não seja o autor e desde que a revisão mais recente de nenhum revisor seja **Alterações solicitadas**. Administradores do workspace podem mesclar sem uma aprovação. * Fazer merge em uma [branch protegida](/docs/pt/eleven-agents/operate/versioning) exige 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](/docs/pt/eleven-agents/operate/merge-proposals) para ver as regras completas de revisão. > **Warning** > > O Architect pode mesclar uma branch diretamente, sem uma proposta, quando você pedir e sua função permitir > o merge. No modo **Aprovação necessária**, ele pergunta antes. No modo **Aprovação automática**, não. Use > proteção de branch em `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 ao vivo para qualquer parcela de tráfego que o destino receba. Quando o destino é `main` e nenhuma divisão de tráfego está definida, isso significa todos os usuários. 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 sua branch 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 de `main`, e pede aprovação antes de aplicá-la. Você também pode defini-la: em **Controle de versão** > **Branches**, selecione **Implantar** na branch. #### Acompanhe os resultados Abra a aba **Conversas** da proposta para ler as conversas na branch ou peça ao Architect para comparar os resultados da branch com os de `main`. #### Promova ou reverta Para promover, faça o merge da proposta. A parcela de tráfego da branch é movida com ela para `main`. Para reverter, peça ao Architect para definir a parcela da branch como 0% ou edite a implantação por conta própria. O tráfego ao vivo retorna a `main` imediatamente. 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](/docs/pt/eleven-agents/operate/versioning#traffic-deployment). ## Propostas proativas > **Note** > > O Architect produz propostas quando você pede ou quando entrega a ele um teste com falha, uma descoberta do Spotlight, > um alerta ou um ticket de triagem. Ele ainda não analisa seus agentes em uma programação nem abre > propostas por conta própria. O caminho proativo hoje é o [Spotlight](/docs/pt/eleven-agents/dashboard/spotlight), seguido de uma transferência. O Spotlight monitora continuamente as conversas do seu agente. Ele produz um resumo semanal com investigações sugeridas, gera alertas em tempo real e recomenda alterações de configuração. Para transformar uma descoberta do Spotlight em uma proposta: #### Abra o Spotlight Abra o agente. A página de visão geral dele é o Spotlight. #### Escolha uma descoberta Abra o resumo semanal e revise as **Próximas etapas sugeridas** ou abra um alerta em tempo real. #### Transfira 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 é afetada antes de sugerir uma alteração. #### Peça uma proposta Revise as descobertas do Architect. Se concordar com a causa raiz, peça que ele corrija o problema em uma branch, teste a correção e abra uma proposta. Tickets de triagem funcionam da mesma forma. Seu agente ao vivo pode [sinalizar problemas para revisão](/docs/pt/eleven-agents/customization/tools/system-tools/flag-issue-for-review) durante as conversas, e **Discutir com o Architect** em um ticket inicia uma investigação dele. Automações programadas, 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.