Intent Classification + Output Guardrails¶

Visão Geral¶

Sistema unificado de screening pré-IA e validação pós-IA que opera em 3 pipelines: MessageAggregation, Playground e DeferredAiResponse. Não se aplica ao AI Assistant.

Pré-IA: Classificação de Intent (1 chamada Haiku ~$0.0001)¶

Uma chamada LLM leve (Haiku) classifica a intenção do usuário antes da chamada principal:

Categoria	Ação	Modelo
`FaqSimple`	Override para Haiku (10x mais barato). Inclui saudações, info factual, links, capacidades, formas de pagamento.	Haiku
`ComplexQuery`	Sonnet normal (default). Requer raciocínio, comparação ou múltiplas informações.	Sonnet
`ActionRequest`	Sonnet normal (default). Usuário quer que o assistente execute uma ação agora (pedido com itens, reclamação formal, transferir para humano). Pedir link/info é FAQ, não action.	Sonnet
`OffTopic`	Resposta enlatada, pula IA	Nenhum
`Jailbreak`	Resposta enlatada, pula IA	Nenhum

Pós-IA: Output Guardrails (rule-based, sem LLM)¶

Validação regex/keyword na resposta da IA:

Verificação	Ação	Config
PII (CPF, CNPJ, cartão)	Mascara com `***`	`OutputGuardrailConfig.MaskPii`
Promessas não autorizadas	Log warning	`OutputGuardrailConfig.CheckUnauthorizedPromises`
Menção a concorrentes	Log warning (desabilitado)	`OutputGuardrailConfig.FilterCompetitorMentions`

Fluxo nos Pipelines¶

MessageAggregation (sub-pipeline dentro de GenerateAiResponseStep)¶

Init → PrepareHistory → ClassifyIntent → RewriteQuery → InvokeAi → ApplyDecisions → ValidateOutput

Playground¶

Load → Credits → Prepare → Build → ClassifyPlaygroundIntent → Generate → ValidatePlaygroundOutput → Consume → Track → Parse

Deferred¶

Validate → Hours → History → Credits → Cap → PrepareHistory → ClassifyDeferredIntent → InvokeAi → Consume → Increment → Decisions → ValidateDeferredOutput → Signature → Send → Persist → Notify

Model Override Chain¶

ClassifiedModelOverride ?? LlmConfig.DefaultModel

Sem override: Sonnet (default)
FAQ simple: Haiku (via classifier)
Jailbreak/off_topic: nenhum modelo (resposta enlatada, SkipLlmCall = true)

Regra de Desempate¶

Quando o classificador está incerto entre FaqSimple e ComplexQuery, prefere FaqSimple (Haiku). Racional: o custo de uma chamada Haiku desnecessária (~$0.0001) é negligível comparado ao custo de uma chamada Sonnet desnecessária (~$0.003).

Fallback¶

Se o classificador falhar (API indisponível, parsing erro), retorna ComplexQuery — o pipeline continua normalmente com Sonnet.

Respostas Enlatadas¶

Definidas como constantes no IntentClassifierService:

Jailbreak: "Desculpe, não posso ajudar com esse tipo de solicitação. Posso ajudar com algo relacionado aos nossos serviços?"
Off-topic: "Desculpe, essa pergunta está fora do escopo do meu atendimento. Posso ajudar com algo relacionado aos nossos serviços?"

Configuração¶

IntentClassifierConfig¶

Propriedade	Valor	Descrição
`Enabled`	`true`	Liga/desliga classificação
`Provider`	`"anthropic"`	Provider LLM
`Model`	`"claude-haiku-4-5-20251001"`	Modelo leve
`MaxOutputTokens`	`128`	Tokens de saída
`MaxHistoryMessages`	`4`	Mensagens de contexto
`Temperature`	`0.0`	Determinístico

OutputGuardrailConfig¶

Propriedade	Valor	Descrição
`Enabled`	`true`	Liga/desliga guardrails
`MaskPii`	`true`	Mascara CPF/CNPJ/cartão
`FilterCompetitorMentions`	`false`	Filtro de concorrentes
`CheckUnauthorizedPromises`	`true`	Detecta promessas

Arquivos¶

Arquivo	Descrição
`Domain/Enums/IntentCategory.cs`	Enum com categorias
`Infrastructure/Configuration/IntentClassifierConfig.cs`	Config do classificador
`Infrastructure/Configuration/OutputGuardrailConfig.cs`	Config dos guardrails
`Infrastructure/Services/Classification/IntentClassifierService.cs`	Serviço de classificação (Haiku)
`Infrastructure/Services/Guardrails/OutputGuardrailService.cs`	Serviço de guardrails (regex)
`Infrastructure/Prompts/intent-classifier.md`	Prompt do classificador
`Api/.../AiGeneration/ClassifyIntentStep.cs`	Step MessageAggregation
`Api/.../AiGeneration/ValidateOutputStep.cs`	Step MessageAggregation
`Api/.../Playground/Pipeline/ClassifyPlaygroundIntentStep.cs`	Step Playground
`Api/.../Playground/Pipeline/ValidatePlaygroundOutputStep.cs`	Step Playground
`Api/.../DeferredAiResponse/Pipeline/ClassifyDeferredIntentStep.cs`	Step Deferred
`Api/.../DeferredAiResponse/Pipeline/ValidateDeferredOutputStep.cs`	Step Deferred

Padrões Reutilizados¶

Padrão	Referência
Serviço LLM leve	`QueryRewriteService` — mesmo padrão de ILlmClientFactory + fallback
Config estática	`QueryRewriteConfig` — constantes com Provider/Model/MaxTokens
Prompt embedded resource	`PromptTemplateService` — Assembly.GetManifestResourceStream
Usage tracking	`ILlmUsageTracker.Track(LlmOperationType.IntentClassification, ...)`
Pipeline step pattern	`IPipelineStep<TContext>` com constructor injection
Context skip pattern	`context.SkipAiResponse` (pula tudo) + `context.SkipLlmCall` (pula LLM, envia canned response)