--- title: Otimização de instruções (Optimizer) description: Melhore automaticamente a instrução de um Agent com um ciclo guiado por avaliações — a IA gera variantes, reavalia contra o conjunto de testes e mantém a melhor. --- # Otimização de instruções (Optimizer) O Optimizer reescreve automaticamente a **instrução** de um Agent, usando o [Eval](/guia/agents/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. 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](/guia/agents/eval) 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,
focadas nos casos que falharam] D --> E[Cada variante roda o Agent em sandbox
e é pontuada pelos mesmos critérios da avaliação] E --> F[Mantém a melhor variante da rodada] F --> G{Ainda há rodadas
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
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](/guia/agents/eval#criterios-disponiveis) (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. ### 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) | **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](/guia/agents/eval#modelo-do-juiz-por-workspace-override) 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](/guia/agents/eval#modo-ao-vivo-live), 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}" ``` 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](#pre-requisito-um-bom-conjunto-de-testes) acima. ## Ver também - [Avaliação de Agents (Eval)](/guia/agents/eval) — critérios de pontuação e como montar um conjunto de testes. - [Playground ao vivo](/guia/agents/playground) — para testar um cenário pontual e salvá-lo como caso de teste antes de rodar uma otimização. - [Instruções e modelo](/guia/agents/instrucoes-modelo) — como a instrução é usada pelo Agent.