Testes A/B de agentes

Uma mudança no agente pode passar nas avaliações e ainda assim se comportar de outro jeito em conversas reais. Um experimento manda parte das novas conversas para uma candidata e mantém o resto no controle publicado. Ele fixa as duas versões exatas, mede as duas com as mesmas regras e deixa a decisão de publicar com você.

Nada é publicado automaticamente.

Antes de começar

Você precisa de:

• Um agente publicado. A versão publicada dele vira o controle.
• Uma branch candidata com a mudança que você quer testar. Você pode criar uma no assistente de configuração.
• Acesso de editor ou administrador à aplicação.
• Opcionalmente, um Insight de conversa booleano ou numérico como métrica principal. Você pode rodar um experimento só com limites de segurança, sem métrica.

Os experimentos de agentes vêm ativados por padrão. Se a aba Experimentos ou a API não estiverem disponíveis, uma configuração da aplicação ou da empresa pode ter desativado agentBranchingEnabled explicitamente. A configuração da aplicação tem prioridade sobre a da empresa, que tem prioridade sobre o padrão da plataforma. AGENT_BRANCHING_ENABLED=false muda só esse padrão da plataforma. Uma configuração explícita da aplicação ou da empresa continua tendo prioridade.

Execução de código e Habilidades seguem o mesmo padrão: ativadas por padrão, com substituição por escopo. A recuperação da saída da execução de código e a indexação de arquivos gerados são recursos separados e ficam desligados até serem configurados.

Configure um experimento

Abra a aba Experimentos do agente e escolha Iniciar experimento. O assistente tem cinco etapas: Candidata, Público, Limites de segurança, Métrica e Revisão. Público é opcional e começa em "Todos". Uma etapa condicional Nós do Insight aparece depois de Métrica quando uma métrica baseada em nó precisa de um mapeamento braço a braço.

Uma branch candidata salva cada edição automaticamente, e você não pode publicá-la diretamente. Ela chega aos clientes por um experimento, por Publicar variante testada ou pela promoção da branch.

1. Escolha a candidata e os limites

Dê um nome ao experimento, escolha a branch candidata e defina a fatia das novas conversas que ela recebe. Cada conversa é atribuída uma vez e fica naquele braço. Conversas que começaram antes do experimento ficam fora dele.

Escolha a candidata e quanto do novo tráfego ela recebe. Dados de teste sintéticos.

A mesma etapa tem os limites de parada. Você pode limitar o tempo decorrido, o total de conversas atribuídas ou os dois. O primeiro limite atingido encerra o experimento. Configurações de medição abre a janela de inatividade, que decide quando uma conversa não arquivada está pronta para ser medida.

Os limites de tempo e de conversas são condições de parada independentes. Dados de teste sintéticos.

2. Escolha quem participa (opcional)

Pule esta etapa e qualquer nova conversa pode entrar. Escolha Personalizar para:

• mandar suas próprias conversas para a variante antes que os clientes a vejam,
• rodar o experimento só para alguns clientes, como uma cidade ou uma lista de empresas,
• manter todas as conversas do mesmo cliente ou atendimento na mesma versão.

Público de experimentos tem tutoriais passo a passo para cada caso.

3. Defina os limites de segurança

Os limites de segurança são uma rede de proteção. Se a candidata se mostrar claramente pior que o controle, por exemplo muito mais lenta ou falhando com mais frequência, o limite encerra o experimento automaticamente e todo mundo volta para a versão publicada. Você não precisa ficar acompanhando.

Cada limite de segurança tem um valor máximo e uma quantidade mínima de conversas atribuídas por braço. Até os dois braços chegarem a esse mínimo, ele fica Pendente, para que uma única conversa lenta não pare o experimento.

Use o controle deslizante para um limite rápido e o campo de porcentagem para um valor exato. Escolha Verificar momento da avaliação para definir o mínimo de conversas atribuídas daquele limite.

Limite de segurança	Comparação	Limite padrão
Custo por conversa	Variação relativa em relação à referência do controle	A candidata pode aumentar até 25%
Tempo de resposta (p95)	Tempo de resposta por turno no percentil 95	A candidata pode aumentar até 50%
Erros	Fração das execuções com erro ou falha terminal	A candidata pode aumentar até 25%
Conversas sem resposta	Fração que termina com uma mensagem do usuário sem resposta	A candidata pode aumentar até 25%

A comparação de custo mostrada ao cliente usa porcentagens com sinal: o controle é a Referência, a candidata aparece como uma variação, como +8%, e o limite configurado como +25%. Se a referência do controle for zero ou não estiver disponível, o Docana mostra a comparação como indisponível em vez de inventar uma proporção. O status do limite de segurança continua vindo do limite configurado, independentemente de a candidata estar melhor ou pior que o controle no momento.

4. Escolha o que medir

Escolha um Insight booleano ou numérico e se valores maiores ou menores são melhores. Insights de texto não podem ser métrica principal. Escolha Apenas limites de segurança quando quiser monitorar a segurança sem uma recomendação. Esta etapa também define o tempo mínimo decorrido e o número mínimo de conversas medidas por braço antes de o Docana fazer uma recomendação.

Para um evento determinístico do fluxo, use nodeReached com um Insight booleano ou nodeExecutionCount com um Insight numérico. O controle e a candidata podem ter IDs de nó diferentes para o mesmo evento, então confirme o significado em cada versão revisada. O assistente mostra o caminho do fluxo e os nós vizinhos para ajudar na comparação. Um Insight subAgentCalled ou subAgentCallCount aponta para um subagente em vez de um nó, então ele significa a mesma coisa nas duas versões e o assistente pula a etapa de mapeamento de nós.

Confirme os eventos equivalentes nas duas versões exatas. Dados de teste sintéticos.

Se um braço não tiver nó equivalente, marque-o como indisponível. Um mapeamento indisponível nunca vira falso nem zero. Escolha outra métrica ou continue só com limites de segurança. O Docana registra a exclusão junto com o experimento.

A resposta da configuração inclui uma impressão digital da definição. O Docana confere essa impressão digital e as duas versões de artefato revisadas quando o experimento começa. Isso impede que uma candidata alterada, um Insight editado ou um mapeamento de nós diferente entre na comparação depois da revisão.

5. Revise e inicie

Revise os nomes do controle e da candidata, os IDs de artefato, as versões, a distribuição de tráfego, a direção da métrica, os mapeamentos de nós, os limites de segurança, os mínimos de evidência e os limites de parada. Iniciar manda tráfego real.

O par revisado registra as versões exatas e o mapeamento de nós que o início vai fixar. Dados de teste sintéticos.

Editar a candidata depois do início não muda a variante fixada: o experimento continua rodando a versão exata que você revisou. Para testar edições mais novas, pare o experimento e inicie um novo. Publicar uma nova versão do agente encerra a comparação em andamento, porque o controle publicado mudou. Só um experimento pode rodar por agente.

Leia o resultado

A lista de experimentos é uma visão geral compacta. Ela mostra os valores mais recentes de cada braço e a diferença observada, a recomendação, o progresso em direção aos limites de parada de tempo e de conversas atribuídas, o status dos limites de segurança e as ações do ciclo de vida. As barras de progresso descrevem condições de parada, não prontidão estatística. Pausar a entrada não pausa o tempo decorrido.

A visão geral compacta deixa fácil ver a comparação observada e a próxima ação. Dados de teste sintéticos do CI.

Para ver qual versão respondeu uma conversa específica, abra a aba Logs do agente. Cada execução mostra a origem: A · Controle, B · Candidata, Teste direcionado para conversas que uma regra de direcionamento mandou para um braço, ou Fora de experimento.

Abra Ver resultado para ver as evidências em detalhe. O cartão Configurações mostra tudo com que o experimento começou: as versões, o tráfego, os limites, as regras de público, os limites de segurança e a métrica. A comparação principal mantém o controle publicado e a candidata visíveis como dois cartões de braço com nome, com as versões fixadas, a distribuição testada, a estimativa da métrica, as contagens de medidas e atribuídas e o número de amostras da métrica. À frente no momento descreve só a estimativa observada na direção escolhida. Não significa que o Docana já tenha evidência suficiente para recomendar aquele braço.

A candidata está à frente no momento, mas o experimento ainda precisa de mais evidência. O cartão e o medidor usam a mesma cor de indicador. Dados de teste sintéticos.

Leia os números separadamente:

• Atribuídas conta as conversas direcionadas a um braço que não ficaram mistas depois.
• Medidas conta as conversas atribuídas cujo snapshot elegível mais recente tem um valor legível para a métrica principal.
• Amostras da métrica são as observações usadas na estimativa exibida. Os limites de segurança têm suas próprias contagens de amostras por braço e seus próprios mínimos.
• Chance de a nova versão ser melhor usa a direção escolhida (maior ou menor). A recomendação continua sendo Ainda é cedo para recomendar, Resultado inconclusivo, Variante recomendada ou Controle recomendado, de acordo com as regras de evidência mínima e de probabilidade.

As contagens de medidas podem ficar atrás das atribuídas enquanto as conversas continuam abertas. Um histórico podado, um mapeamento excluído, um snapshot ausente ou um valor indisponível fica fora da estimativa, em vez de contar como zero.

A página de detalhes mantém a probabilidade e a recomendação separadas da vantagem observada. Ela também mostra a perda esperada, as unidades, as definições de medição congeladas, o momento do encerramento e as versões de artefato fixadas. Os valores numéricos seguem o idioma atual, então 9.3333 aparece como 9.3 em inglês e 9,3 em português. As contagens usam o separador de milhar do idioma.

Os limites de segurança comparam cada braço com o limite configurado. Um indicador vermelho na candidata significa que o custo ou o tempo de resposta observado está pior que o do controle. Isso, sozinho, não quer dizer que o limite foi excedido. Pendente, Dentro do limite e Excedido continuam sendo os estados que valem.

O custo usa porcentagens. Vermelho marca uma piora, e Pendente significa que o limite ainda não chegou ao mínimo de amostras. Dados de teste sintéticos.

Pause, retome, pare ou publique

Essas ações têm consequências diferentes:

• Pausar entrada manda as novas conversas para a versão principal publicada. As conversas já atribuídas ao experimento mantêm as versões fixadas e continuam sendo medidas. Os limites de tempo e as verificações dos limites de segurança continuam.
• Retomar entrada aceita as conversas criadas a partir desse momento. As conversas criadas durante a pausa ficam fora do experimento.
• Parar experimento é definitivo. O novo tráfego volta para a versão publicada, as conversas do experimento que estavam abertas ficam mistas e são excluídas, e o resultado fica no histórico.
• Publicar variante testada é uma decisão explícita. Ela publica a candidata exata revisada como a versão principal em produção e encerra o experimento. A ação continua disponível para experimentos em andamento ou encerrados, mesmo quando o resultado é precoce, inconclusivo, favorável ao controle ou tem um limite de segurança excedido, então revise as evidências antes de confirmar.

Publicar exige as quatro versões fixadas revisadas: ID e versão do artefato do controle, mais ID e versão do artefato da candidata. Se alguma estiver desatualizada, ou se outro experimento estiver rodando quando você tentar publicar um resultado antigo, o servidor retorna um conflito e pede uma nova revisão. Ele nunca trata a ponta de uma branch que mudou como consentimento.

A promoção comum de branch é diferente. Ela move a candidata para o rascunho principal e não publica. O tráfego, a métrica, os mapeamentos de nós, os limites de segurança, os mínimos de evidência e os limites de parada de um experimento em andamento não podem ser alterados. Pare o experimento e inicie um novo para mudá-los.

O histórico de experimentos é mantido. Não existe operação para excluir um experimento.

API, MCP e CLI

A API REST, o servidor MCP e a CLI cobrem toda a configuração e o ciclo de vida. Os nomes das ferramentas MCP abaixo levam à referência da API, com campos da requisição, respostas e exemplos.

Prepare os Insights e uma candidata

Tarefa	Referência da API / ferramenta MCP	CLI
Ler a configuração atual de Insights	getAgent	docana agents insights get --agent-id <agent>
Substituir, ativar, desativar ou limpar os Insights	updateAgentInsights	docana agents insights set / clear
Descobrir os nós do fluxo que podem ser medidos	listAgentInsightSourceNodes	docana agents insights nodes
Preencher o histórico de Insights determinísticos de nós	backfillAgentInsights	docana agents insights backfill
Ler os agregados de Insights de conversa	getAgentAnalyticsInsights	docana api com o método e o caminho documentados
Criar e gerenciar versões candidatas	Operações de branch e updateAgentSpec com branchId	docana agents branches list/create/show/discard/preview/promote. docana agents push FILE --branch BRANCH_ID grava uma nova versão. Use docana api para renomear

O preenchimento de histórico aceita só pontos determinísticos de nó. Ele não refaz a extração por IA. Atualizar os Insights substitui a configuração inteira, então comece por insights get --json e envie todos os pontos que você quer manter. pollAgentInsights pertence aos Insights de documentos. Use getAgentAnalyticsInsights para agregados de conversas.

Rode e gerencie o experimento

Tarefa	Referência da API / ferramenta MCP	Comando da CLI
Revisar a configuração exata	getAgentExperimentSetup	experiments setup
Iniciar	startAgentExperiment	experiments start
Listar o histórico	listAgentExperiments	experiments list
Ler um resultado	getAgentExperiment	experiments show
Pausar a entrada	pauseAgentExperiment	experiments pause
Retomar a entrada	resumeAgentExperiment	experiments resume
Parar	endAgentExperiment	experiments stop
Publicar a candidata revisada	publishAgentExperimentVariant	experiments publish

Use os IDs retornados pelas respostas de configuração e de listagem em vez de copiar IDs da URL do navegador. O exemplo abaixo supõe que response-delivered já está configurado. Confira com insights get. Para um ponto baseado em nó, use insights nodes --json e insights set como descrito em Insights de conversa. Troque todos os identificadores de artefato e de nó do exemplo pelos valores das suas respostas reais de configuração e de nós.

Este fluxo da CLI revisa e inicia um experimento com métrica principal:

export DOCANA_API_URL=https://platform.docana.com
docana whoami

docana agents branches create AGENT_ID \
  --name "Concise replies" --from published --json

# Edit the candidate's spec locally, then save it as the branch's next version
docana agents push candidate.json --branch BRANCH_ID --agent-id AGENT_ID

docana agents experiments setup AGENT_ID \
  --branch BRANCH_ID --json > setup.json

Copie control, variant e definitionFingerprint de setup.json para start-review.json. Adicione nodeMappings só para métricas baseadas em nó. Registre os mapeamentos indisponíveis em excludedDataPointIds.

{
  "reviewed": {
    "control": { "artifactId": "CONTROL_ARTIFACT_ID", "version": 2 },
    "variant": { "artifactId": "VARIANT_ARTIFACT_ID", "version": 1 },
    "definitionFingerprint": "FINGERPRINT_FROM_SETUP"
  },
  "nodeMappings": [
    {
      "dataPointId": "response-delivered",
      "control": { "nodeId": "understand-request" },
      "variant": { "nodeId": "understand-request" }
    }
  ],
  "excludedDataPointIds": []
}

Depois inicie e guarde o experimentId retornado:

docana agents experiments start AGENT_ID \
  --branch BRANCH_ID \
  --name "Concise replies" \
  --traffic 50 \
  --win-metric response-delivered \
  --direction higher \
  --review-file start-review.json \
  --guardrail cost:0.25:30 \
  --guardrail latency:0.5:30 \
  --min-hours 48 \
  --min-measured 30 \
  --max-hours 336 \
  --max-threads 2000 \
  --idle-hours 24 \
  --json

docana agents experiments list AGENT_ID --json
docana agents experiments show AGENT_ID EXPERIMENT_ID --json
docana agents experiments pause AGENT_ID EXPERIMENT_ID
docana agents experiments resume AGENT_ID EXPERIMENT_ID

Para um experimento só com limites de segurança, omita --win-metric, --direction, --min-hours e --min-measured.

Para publicar, leia o experimento de novo e copie os valores exatos de controlArtifactId, controlVersion, variantArtifactId e variantVersion para um arquivo de revisão separado:

{
  "expectedControlArtifactId": "CONTROL_ARTIFACT_ID",
  "expectedControlVersion": 2,
  "expectedVariantArtifactId": "VARIANT_ARTIFACT_ID",
  "expectedVariantVersion": 1
}

docana agents experiments publish AGENT_ID EXPERIMENT_ID \
  --review-file publish-review.json --json

Quem chama a API REST envia o mesmo arquivo para a rota versionada:

docana api POST \
  /api/v1/agents/AGENT_ID/experiments/EXPERIMENT_ID/publish/ \
  -d @publish-review.json

Um cliente MCP chama publishAgentExperimentVariant com os mesmos valores revisados dentro de body:

{
  "agentId": "AGENT_ID",
  "experimentId": "EXPERIMENT_ID",
  "body": {
    "expectedControlArtifactId": "CONTROL_ARTIFACT_ID",
    "expectedControlVersion": 2,
    "expectedVariantArtifactId": "VARIANT_ARTIFACT_ID",
    "expectedVariantVersion": 1
  }
}

O servidor rejeita versões fixadas desatualizadas com 409. Busque e revise o resultado de novo em vez de usar a versão mais recente da branch no lugar.

Quando nenhum comando específico da CLI cobre uma operação, use o acesso direto e autenticado à API com um caminho HTTP, não com um ID de operação:

docana api PATCH \
  /api/v1/agents/AGENT_ID/branches/BRANCH_ID/ \
  -d '{"name":"Concise support replies"}'

docana api GET \
  /api/v1/agents/AGENT_ID/analytics/insights/ \
  applicationId=APPLICATION_ID

Rode docana api schema search agent experiments ou docana api schema search conversation insights na sua implantação para ver os parâmetros e as respostas atuais.

Próximos passos

• Público de experimentos: teste no seu próprio celular, direcione para uma cidade ou uma lista de clientes e meça por atendimento
• Insights de conversa: defina os pontos de dados que um experimento pode medir
• Testes de agentes: pegue regressões com avaliações antes de usar tráfego real

No perfil do funcionário

Para um funcionário, abra Desempenho para ver o experimento atual, as versões testadas, as conversas atribuídas e a recomendação mais recente. O cartão leva ao resultado completo e diferencia entrada pausada de medição pausada. Depois que o teste termina, ele leva ao resultado registrado. Sem experimento, ele oferece Configurar um experimento.

A comparação usa só as conversas atribuídas àquele experimento. Publicar a versão testada continua sendo uma decisão explícita na página de resultado.