Atende Direito · Docs

Tema

Otimização de instruções (Optimizer) ​

O Optimizer reescreve automaticamente a instrução de um Agent, usando o Eval como régua: a cada rodada, ele olha os casos que falharam, pede a um modelo de IA algumas variantes da instrução e mantém a que performar melhor no conjunto de testes.

Pré-requisito: um bom conjunto de testes ​

O Optimizer não inventa critério de qualidade — ele usa o conjunto de testes que você indicar como gabarito em cada rodada. Isso quer dizer que a régua da otimização é o conjunto de testes: quanto mais representativos forem os casos (idealmente com a trajetória esperada e/ou a resposta final esperada definidas, não só a entrada), melhor a instrução final.

Um conjunto de testes pequeno, incompleto ou com poucos casos negativos tende a produzir uma instrução que só parece boa — porque só foi cobrada nos poucos cenários que o conjunto de testes testa. Antes de rodar o Optimizer, revise o conjunto de testes como se fosse revisar os requisitos de um projeto.

Como funciona ​

mermaid
flowchart TD
    A[Conjunto de testes com casos] --> B[Roda a avaliação com a instrução atual]
    B --> C{Algum caso falhou?}
    C -->|Sim| D[IA gera K variantes da instrução,<br/>focadas nos casos que falharam]
    D --> E[Cada variante roda o Agent em sandbox<br/>e é pontuada pelos mesmos critérios da avaliação]
    E --> F[Mantém a melhor variante da rodada]
    F --> G{Ainda há rodadas<br/>ou orçamento disponível?}
    G -->|Sim| B
    G -->|Não| H[Instrução vencedora]
    C -->|Não| H
    H --> I[Comparar antiga x nova e aplicar]
    I --> J[Grava no rascunho e PUBLICA<br/>uma nova versão do Agent]

A cada rodada:

  1. O Optimizer identifica os casos de teste que falharam com a instrução atual (a instrução vencedora da rodada anterior, ou a instrução base na primeira rodada).
  2. Pede a um modelo de IA gerador K variantes da instrução (candidatas), cada uma tentando corrigir as falhas identificadas sem perder o que já funcionava.
  3. Cada variante roda o Agent em sandbox (sem efeitos reais de CRM) contra todo o conjunto de testes e é pontuada pelos mesmos critérios usados no Eval (trajetória de ferramentas, resposta final, rubrica, segurança).
  4. A variante com melhor taxa de aprovação vira a instrução vigente para a próxima rodada.
  5. O processo repete por até N rodadas, respeitando um teto de orçamento de tokens (o "combustível" cobrado pelo uso de IA) — o que vier primeiro.

Ao final, a instrução da última rodada com o melhor resultado é a instrução vencedora da otimização.

Valores iniciais na tela ​

CampoValor inicial
Etapas (rodadas)3 (de 1 a 10)
Versões por etapa (variantes)4
Limite de uso (tokens)50000

O limite de uso é o teto de custo: o processo para ao estourar, mesmo que ainda faltem etapas.

Dica

Credenciais e modelo são determinados pelo sistema — o cliente não escolhe. Todas as chamadas de IA da otimização (o gerador de variantes e o juiz que pontua os candidatos) usam a credencial do próprio workspace (a chave do cliente, a mesma integração conectada que o Agent usa para rodar) — nunca uma chave global.

O juiz herda o provedor do próprio Agent — a mesma integração conectada que roda o Agent (OpenAI, Anthropic, Gemini, OpenRouter, etc.). Ele não exige uma integração OpenRouter separada: o provedor é derivado do modelo do Agent (ex.: gpt-4o → OpenAI, claude-sonnet-4 → Anthropic, gemini-2.5-flash → Gemini, qualquer modelo com / no identificador → OpenRouter) e usa a credencial daquele provedor.

O modelo do juiz é determinado pelo sistema por provedor — um modelo barato/leve por provedor (ex.: gpt-4.1-nano na OpenAI, um Haiku na Anthropic, um Flash Lite no Gemini). O gerador de variantes roda no modelo do próprio Agent sob otimização (o mesmo em que ele executa).

Cada workspace pode fixar um modelo ÚNICO de juiz (ex.: openai/gpt-4.1-nano ou gemini-2.5-flash-lite) que passa a valer para todas as avaliações. Quando definido, o juiz usa esse modelo para qualquer Agent, e provedor e credencial passam a vir do modelo escolhido (não mais do Agent). Vazio = padrão do sistema por provedor do Agent. Veja Modelo do juiz por workspace no guia de Eval.

Se o Agent não tiver um modelo definido ou o workspace não tiver a integração do provedor conectada, o disparo da otimização falha com um erro claro — configure a integração antes de otimizar.

Disparando uma otimização ​

  1. Abra as avaliações do Agent. Em Agentes, abra o Agent e clique em Avaliações. A aba Otimizar só aparece para quem tem permissão de gerenciar avaliações.

  2. Escolha o conjunto de testes. Na lista à esquerda, selecione o conjunto de testes que servirá de régua. O conjunto escolhido vale tanto para avaliar quanto para otimizar.

  3. Abra a aba Otimizar. À direita, clique em Otimizar. O painel Otimizar instruções do agente mostra três campos: Etapas, Versões por etapa e Limite de uso (tokens).

    Aba Otimizar das Avaliações, com Etapas, Versões por etapa, Limite de uso e o botão Otimizar agora.

    Aba Otimizar das Avaliações, com Etapas, Versões por etapa, Limite de uso e o botão Otimizar agora.

  4. Ajuste os valores e inicie. Mantenha os valores iniciais ou ajuste conforme a necessidade e clique em Otimizar agora. Uma mensagem confirma que a otimização foi iniciada e os campos ficam bloqueados enquanto ela roda.

O processamento roda em segundo plano, então não há um limite curto de tempo de execução — assim como no modo ao vivo do Eval.

Acompanhando o progresso ​

Logo abaixo do painel, a tela mostra o andamento ao vivo, sem precisar atualizar a página:

  • Etapas: a etapa atual sobre o total (por exemplo, 2/3), com uma barra de progresso.
  • Status: Na fila, Otimizando, Concluída ou Falhou.
  • Tokens gastos: o consumo acumulado em relação ao limite de uso.
  • Melhor versão até agora: a taxa de aprovação da melhor versão encontrada e de qual etapa e versão ela veio, com a Prévia do texto das instruções.
  • Versões testadas por etapa: um cartão por versão (Versão 1, Versão 2...) com a respectiva taxa de aprovação. A melhor fica destacada em verde.

Enquanto a tela estiver vazia, ela exibe Nenhuma otimização em andamento. Acompanhe a evolução etapa a etapa até a otimização convergir ou estourar o limite de uso.

Aplicando a instrução vencedora ​

Quando o status chega a Concluída, a tela exibe o comparativo Instruções — antes × depois, com Versão atual de um lado e Versão sugerida do outro. O que foi removido aparece riscado em vermelho e o que foi adicionado em verde.

  1. Revise o comparativo. Leia as diferenças entre a Versão atual e a Versão sugerida antes de decidir.

  2. Clique em Aplicar melhoria. O botão Aplicar melhoria aparece abaixo do comparativo, e só quando a otimização terminou com uma versão vencedora.

  3. Confirme em Aplicar e publicar. Na janela Aplicar melhoria, leia o aviso e clique em Aplicar e publicar (ou Cancelar para desistir). Uma mensagem confirma que uma nova versão foi criada e publicada.

Não é possível aplicar uma otimização que ainda esteja em andamento ou que tenha falhado sem uma instrução vencedora — o botão simplesmente não aparece.

Custos e limites ​

  • O custo escala com rodadas × variantes × casos do conjunto de testes × (1 execução do Agent + 1 julgamento de IA por critério) — um conjunto de testes com 10 casos, 3 rodadas e 4 variantes já significa até 120 execuções completas do Agent, cada uma seguida de avaliação por um juiz de IA. Comece pequeno (menos rodadas/variantes) e aumente conforme necessário.
  • Use o orçamento de tokens como teto de segurança: o processo para assim que o consumo estimado de tokens ultrapassa o valor configurado, mesmo que ainda faltem rodadas.
  • Conversas de múltiplas trocas não são suportadas no caso de teste usado pelo Optimizer — cada caso é avaliado a partir do turno inicial, sem considerar uma conversa de múltiplas trocas.
  • Assim como no eval, a qualidade da otimização depende diretamente da qualidade do conjunto de testes usado — veja Pré-requisito: um bom conjunto de testes acima.

Ver também ​