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.
Atenção
O Optimizer só reescreve o campo de instrução. Sub-agents, ferramentas, guardrails e demais configurações do Agent ficam intactos — o processo nunca altera nada além do texto da instrução.
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:
- 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).
- 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.
- 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).
- A variante com melhor taxa de aprovação vira a instrução vigente para a próxima rodada.
- 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.
Padrões
| Configuração | Padrão | Limite |
|---|---|---|
| Número de rodadas | 3 | até 10 |
| Variantes por rodada | 4 | até 8 |
| Orçamento de tokens | 200000 | — (teto de custo; o processo para ao estourar) |
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
Essa ação é feita pela tela do Agent Builder. Para times técnicos, também é possível via API:
bash
curl -X POST https://sua-instancia/api/ai-agents/{agent}/eval-sets/{set}/optimize \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"config": {
"rounds": 3,
"candidates": 4,
"budget_tokens": 200000
}
}'Todos os campos de configuração são opcionais — se omitidos, usam os padrões acima. A resposta devolve a otimização recém-criada com status "em andamento": o processamento roda em segundo plano, fora do processamento normal de uma requisição web — por isso, assim como o modo ao vivo do Eval, não tem um limite curto de tempo de execução.
Permissão requerida: gerenciar avaliações do Agent.
Acompanhando o progresso
Na tela de otimização, é possível ver ao vivo cada candidato sendo avaliado: a rodada, o índice do candidato, a taxa de aprovação do candidato, a melhor instrução encontrada até agora e os tokens já gastos. Sem precisar dar refresh na página, dá pra acompanhar a evolução rodada a rodada até o Optimizer convergir ou estourar o orçamento.
Para times técnicos, o mesmo pode ser consultado via API:
bash
curl https://sua-instancia/api/ai-agents/{agent}/optimize-runs/{optimizeRun} \
-H "Authorization: Bearer {token}"
curl https://sua-instancia/api/ai-agents/{agent}/optimize-runs/{optimizeRun}/candidates \
-H "Authorization: Bearer {token}"O primeiro endpoint devolve o resumo da otimização (status, configuração, instrução base, instrução vencedora); o segundo lista cada candidato gerado (rodada, índice, instrução testada, taxa de aprovação, média por critério).
Permissão requerida: visualizar avaliações do Agent.
Aplicando a instrução vencedora
Quando a otimização chega ao fim com uma instrução vencedora, a tela mostra um comparativo entre a instrução antiga e a nova para revisão antes de aplicar:
bash
curl -X POST https://sua-instancia/api/ai-agents/{agent}/optimize-runs/{optimizeRun}/apply \
-H "Authorization: Bearer {token}"Atenção
Aplicar a instrução vencedora grava no rascunho do Agent e publica imediatamente uma nova versão. Como só a versão publicada roda em produção, aplicar aqui já coloca a nova instrução em uso pelos canais reais — não é um rascunho para revisar depois.
Só é possível aplicar uma otimização que tenha terminado com uma instrução vencedora — tentar aplicar uma otimização ainda em andamento, sem instrução vencedora, retorna erro de validação.
Permissão requerida: gerenciar avaliações do Agent.
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
- Avaliação de Agents (Eval) — critérios de pontuação e como montar um conjunto de testes.
- Playground ao vivo — para testar um cenário pontual e salvá-lo como caso de teste antes de rodar uma otimização.
- Instruções e modelo — como a instrução é usada pelo Agent.