Otimização de Prompt¶

Visão Geral¶

O sistema de otimização de prompt reduz o consumo de tokens nas conversas ao gerar uma versão compactada do SystemPrompt do agente. A otimização é feita via LLM no momento da criação/atualização do agente e armazenada na coluna OptimizedSystemPrompt.

Benefícios: - Redução de ~30-35% no consumo de tokens por conversa - Preservação da semântica e comportamento do agente - Processamento transparente (usuário não percebe diferença)

Arquitetura¶

┌─────────────────────────────────────────────────────────────────────────┐
│  Criação/Atualização do Agente                                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  CreateAgentHandler / UpdateAgentHandler                                │
│              │                                                          │
│              ▼                                                          │
│  ┌─────────────────────────────────────────┐                            │
│  │   IPromptOptimizationService            │                            │
│  │   .OptimizeAsync(systemPrompt)          │                            │
│  └───────────────────┬─────────────────────┘                            │
│                      │                                                  │
│         ┌────────────┴────────────┐                                     │
│         │                         │                                     │
│         ▼                         ▼                                     │
│  ┌─────────────┐           ┌─────────────┐                              │
│  │  Enabled?   │──false──▶ │ Return null │                              │
│  │  MinLength? │           │ (usa orig.) │                              │
│  └──────┬──────┘           └─────────────┘                              │
│         │ true                                                          │
│         ▼                                                               │
│  ┌─────────────────────────────────────────┐                            │
│  │   LLM Provider (Claude/OpenAI)          │                            │
│  │   - Carrega template de otimização      │                            │
│  │   - Envia prompt para otimização        │                            │
│  │   - Retorna versão otimizada            │                            │
│  └───────────────────┬─────────────────────┘                            │
│                      │                                                  │
│                      ▼                                                  │
│  ┌─────────────────────────────────────────┐                            │
│  │   Agent.OptimizedSystemPrompt = result  │                            │
│  └─────────────────────────────────────────┘                            │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Uso em Conversas¶

Durante o processamento de mensagens, o sistema usa o prompt otimizado com fallback para o original:

// ProcessMessageHandler.cs / PlaygroundHandler.cs
var basePrompt = agent.OptimizedSystemPrompt ?? agent.SystemPrompt;
var fullSystemPrompt = basePrompt;

if (knowledgeBlocks.Count > 0)
{
    var knowledgeSection = string.Join("\n\n---\n\n", knowledgeBlocks);
    fullSystemPrompt = $"{basePrompt}\n\n## Base de Conhecimento\n\n{knowledgeSection}";
}

Comportamento de Fallback: - Se OptimizedSystemPrompt é null → usa SystemPrompt original - Se otimização falhar → retorna null, usa original - Se feature desabilitada → retorna null, usa original

Configuração¶

appsettings.json¶

{
  "PromptOptimization": {
    "Enabled": true,
    "Provider": "anthropic",
    "Model": "claude-sonnet-4-5-20250929",
    "MaxOutputTokens": 4096,
    "MinPromptLength": 500
  }
}

Parâmetro	Tipo	Descrição
Enabled	bool	Habilita/desabilita a otimização
Provider	string	Provider LLM (`anthropic` ou `openai`)
Model	string	Modelo a usar para otimização
MaxOutputTokens	int	Limite de tokens na resposta
MinPromptLength	int	Tamanho mínimo do prompt para otimizar (chars)

docker-compose (Produção)¶

environment:
  - PromptOptimization__Enabled=true
  - PromptOptimization__Provider=anthropic
  - PromptOptimization__Model=claude-sonnet-4-5-20250929
  - PromptOptimization__MaxOutputTokens=4096
  - PromptOptimization__MinPromptLength=500

Regras de Otimização¶

O template de otimização (prompt-optimization.md) instrui o LLM a:

Remover redundâncias - Eliminar repetições e informações duplicadas
Compactar linguagem - Usar formas mais concisas sem perder clareza
Reorganizar estrutura - Agrupar informações relacionadas
Preservar semântica - Manter o comportamento e tom esperados
Manter exemplos - Preservar diálogos de exemplo (críticos para comportamento)
Preservar regras críticas - Nunca remover restrições de segurança (NUNCA, NÃO, proibido)

O que NÃO fazer: - Remover exemplos de diálogo - Alterar regras de segurança - Mudar o tom ou personalidade - Adicionar informações novas

Trigger de Otimização¶

CreateAgentHandler¶

Sempre otimiza ao criar um agente (se habilitado e prompt >= MinPromptLength).

UpdateAgentHandler¶

Otimiza quando: 1. SystemPrompt mudou (comparação de string) 2. OptimizedSystemPrompt é null (nunca foi otimizado)

var promptChanged = agent.SystemPrompt != request.SystemPrompt;
var needsOptimization = promptChanged || agent.OptimizedSystemPrompt is null;

if (needsOptimization)
{
    optimizedPrompt = await _promptOptimization.OptimizeAsync(request.SystemPrompt, ct);
}

Arquivos Relacionados¶

Arquivo	Descrição
`Infrastructure/Services/PromptOptimization/IPromptOptimizationService.cs`	Interface do serviço
`Infrastructure/Services/PromptOptimization/PromptOptimizationService.cs`	Implementação
`Infrastructure/Services/PromptOptimization/PromptOptimizationOptions.cs`	Configuração
`Infrastructure/Prompts/prompt-optimization.md`	Template de otimização
`Domain/Entities/Agent.cs`	Entidade com `OptimizedSystemPrompt`
`Api/Features/Agents/Create/CreateAgentHandler.cs`	Integração no create
`Api/Features/Agents/Update/UpdateAgentHandler.cs`	Integração no update

Métricas e Logs¶

Logs de Otimização¶

[INF] Prompt optimized: 4200 -> 2700 chars (35.7% reduction)
[INF] Agent {AgentId} updated: {AgentName}. PromptOptimized: True

Métricas Importantes¶

Redução média: ~30-35% (varia por prompt)
Tempo de otimização: 2-5s (síncrono no create/update)
Preservação de exemplos: Obrigatória (verificar manualmente)

Tratamento de Erros¶

Cenário	Comportamento
Otimização desabilitada	Retorna `null`, usa original
Prompt muito curto (< MinPromptLength)	Retorna `null`, usa original
LLM falha (timeout, erro API)	Loga erro, retorna `null`, usa original
`OptimizedSystemPrompt` é `null`	Fallback automático via `??`

Princípio: A aplicação nunca falha por causa da otimização. Graceful degradation sempre.

Escolha do Modelo¶

Baseado em análise comparativa:

Modelo	Redução	Preserva Exemplos	Recomendado
claude-sonnet-4-5	35.4%	Sim	Sim
claude-haiku-4-5	26.5%	Sim	Sim (custo menor)
gpt-4.1	21.5%	Sim	Não (menor redução)
gpt-4.1-mini	26.2%	Sim	Não
gpt-5.2	36.8%	Não	Não (remove exemplos)

Recomendação: Use claude-sonnet-4-5-20250929 para melhor equilíbrio entre redução e preservação.