Ajustes conforme relatorio de testes 2026-08-27

config/mcp_parameter_mapping.yaml

@@ -25,8 +25,14 @@ mcp_parameter_mapping:
     consultar_status_solicitacao:
       map:
         customer_key: msisdn
-        interaction_key: protocol
         session_key: session_id
+      extract:
+        protocol:
+          from: message
+          type: string
+          strategy: llm
+          description: Extraia somente o número de protocolo explicitamente informado pelo cliente; não use message_id ou
+            interaction_key como protocolo.
     consultar_tracking:
       map:
         customer_key: msisdn
@@ -41,8 +47,7 @@ mcp_parameter_mapping:
           from: message
           type: string
           strategy: llm
-          description: Extraia somente o nome do serviço que o cliente quer cancelar.
-            Retorne null se não estiver claro.
+          description: Extraia somente o nome do serviço que o cliente quer cancelar. Retorne null se não estiver claro.
     tratar_vas_estrategico:
       map:
         customer_key: msisdn
@@ -52,8 +57,7 @@ mcp_parameter_mapping:
           from: message
           type: string
           strategy: llm
-          description: Extraia somente o nome do serviço estratégico ou incluso citado
-            pelo cliente.
+          description: Extraia somente o nome do serviço estratégico ou incluso citado pelo cliente.
     validar_contestacao:
       map:
         customer_key: msisdn
@@ -72,18 +76,22 @@ mcp_parameter_mapping:
           from: message
           type: number
           strategy: llm
-          description: Extraia o valor monetário explicitamente associado ao item.
-            Retorne null se não houver valor.
+          description: Extraia o valor monetário explicitamente associado ao item. Retorne null se não houver valor.
         motivo:
           from: message
           type: string
           strategy: llm
-          description: Extraia o motivo da contestação em frase curta; null se não
-            informado.
+          description: Extraia o motivo da contestação em frase curta; null se não informado.
     finalizar_atendimento:
       map:
         customer_key: msisdn
         session_key: session_id
+      extract:
+        status:
+          from: message
+          type: string
+          strategy: llm
+          description: Status explícito de finalização definido pelo fluxo de domínio; não inferir de identificadores técnicos.
     enviar_sms:
       map:
         customer_key: msisdn
@@ -103,6 +111,16 @@ mcp_parameter_mapping:
       map:
         customer_key: msisdn
         session_key: session_id
+    consultar_historico_descontos:
+      map:
+        customer_key: msisdn
+        session_key: session_id
+      extract:
+        nome_plano:
+          from: message
+          type: string
+          strategy: llm
+          description: Extraia o nome do plano somente se explicitamente citado; null se ausente.
     termino_desconto:
       map:
         customer_key: msisdn
@@ -120,3 +138,7 @@ mcp_parameter_mapping:
     retomar_workflow:
       map:
         session_key: session_id
+validar_vas_subject:
+  map:
+    customer_key: msisdn
+    session_key: session_id

config/prompts/billing.yaml

@@ -5,6 +5,10 @@ system: |
   Não implemente confirmação, stickiness, coleta transacional, memória, guardrails ou RAG no texto: essas responsabilidades são do agent_framework_oci.
   Se houver resultado de invoice_explanation, preserve nomes, valores e conclusões vindas da tool.
   Não prometa nem estime valores de faturas futuras.
+  Se a evidência não explicar a causa de uma cobrança, aumento, desconto ausente ou mudança de valor,
+  diga explicitamente que a causa não está disponível nos dados consultados. Não apresente hipóteses
+  como fim de promoção, perda de elegibilidade, alteração de consumo, reajuste tarifário ou mudança
+  de plano como explicação factual sem evidência explícita da tool/RAG do turno atual.
   Seja objetivo e mantenha o comportamento de negócio do Contas.
 
   Quando o cliente perguntar pelo plano contratado, use somente itens

config/prompts/contestation.yaml

@@ -33,7 +33,10 @@ system: |
   - preserve a categoria retornada;
   - não substitua o item por outro encontrado na fatura;
   - não declare sucesso quando a tool falhou ou bloqueou;
-  - não invente protocolo.
+  - não invente protocolo;
+  - nunca exponha códigos, nomes de guardrails, nomes de validator/tools, nomes de campos internos, status técnicos ou
+    estruturas de implementação como CVAL, JSON, BLOCKED, OUT_OF_SCOPE, validator_tool ou guardrail_code; traduza
+    somente o motivo de negócio autorizado para linguagem do cliente.
 
   Se a tool retornar OUT_OF_SCOPE, bloqueio ou categoria não tratável:
   - explique somente o motivo efetivamente retornado;

config/prompts/support.yaml

@@ -3,3 +3,7 @@ system: |
   Trate acompanhamento de solicitações, tracking, envio/recuperação de fatura e encerramento.
   Handoff humano e encerramento são estados do framework; não tente inferir confirmações de outras transações.
   Use respostas curtas, com o status efetivamente retornado pelas integrações.
+  Nunca anuncie transferência, encerramento, protocolo ou sucesso de uma operação sem que o estado/tool do turno atual confirme esse resultado.
+  Se uma integração retornar falha terminal, bloqueio, OUT_OF_SCOPE ou NOT_ALLOWED, explique somente o motivo retornado e encerre a resposta sem inventar alternativa.
+  Pedidos de atendimento humano e regras de retenção são políticas do domínio/orquestração; não simule handoff em texto livre.
+

config/routing.yaml

@@ -3,6 +3,35 @@ router:
   fallback_agent: faturas_agent
   confidence_threshold: 0.7
   allow_handoff: true
+  transaction_confirmation:
+    # Explicit yes/no stays deterministic. Only inconclusive replies use this LLM fallback.
+    semantic_fallback:
+      enabled: true
+      allowed_values: [SIM, NAO, CONTINUAR]
+      confirm_values: [SIM]
+      reject_values: [NAO]
+      continue_values: [CONTINUAR]
+      include_relevant_context: true
+      profile_name: router
+      prompt: |
+        Você classifica a resposta do cliente a uma confirmação transacional pendente.
+        Considere a pergunta pendente, somente o histórico recente relacionado ao mesmo tema e a fala atual.
+        Não execute a ação e não invente fatos.
+
+        Classes permitidas: {{ allowed_values }}
+        - SIM: confirmação/aceite inequívoco, inclusive equivalentes como "isso mesmo", "pode confirmar", "é isso" quando o contexto tornar o aceite claro.
+        - NAO: recusa/cancelamento inequívoco da ação pendente.
+        - CONTINUAR: qualquer resposta que não confirme nem rejeite inequivocamente, incluindo pergunta adicional, correção, novo dado, ambiguidade ou possível mudança de assunto.
+
+        Pergunta pendente:
+        {{ pending_prompt }}
+
+        Histórico relevante:
+        {{ relevant_conversation_context }}
+
+        Resposta atual do cliente:
+        {{ user_input }}
+
 state_policies:
 - state: WAITING_FATURAS_CONFIRMATION
   agent: faturas_agent
@@ -65,7 +94,6 @@ intents:
   - segunda via da fatura
   - obter fatura
   - baixar fatura
-  - minha conta
   - minhas faturas
   - fatura atual
   - última fatura
@@ -81,9 +109,8 @@ intents:
 - name: contas_invoice_explanation
   domain: telecom_contas
   agent: faturas_agent
-  priority: 130
-  description: Explicação, composição, diferença, aumento, variação ou dúvida sobre
-    valores/cobranças de uma fatura já conhecida.
+  priority: 150
+  description: Explicação, composição, diferença, aumento, variação, dúvida ou não reconhecimento informativo de valores/itens de uma fatura já conhecida. Use esta intent quando o cliente estiver tentando entender uma cobrança ou disser que não reconhece itens/valores, mas ainda não pedir explicitamente contestação, cancelamento, estorno, ajuste ou retirada.
   mcp_tools:
   - invoice_explanation
   keywords:
@@ -94,6 +121,14 @@ intents:
   - fatura veio alta
   - conta veio alta
   - veio mais cara
+  - conta subiu
+  - minha conta subiu
+  - fatura subiu
+  - minha fatura subiu
+  - conta aumentou
+  - minha conta aumentou
+  - fatura aumentou
+  - minha fatura aumentou
   - valor aumentou
   - diferença de valor
   - divergência na fatura
@@ -106,8 +141,18 @@ intents:
   - composicao da fatura
   - detalhar cobrança
   - detalhar cobranca
+  - não estou reconhecendo
+  - nao estou reconhecendo
+  - não reconheço esses itens
+  - nao reconheco esses itens
+  - itens que não reconheço
+  - itens que nao reconheco
+  - cobranças que não reconheço
+  - cobrancas que nao reconheco
   examples:
-  - Minha fatura veio mais alta
+  - Contratamos um plano, mas eu não estou reconhecendo esses itens eventuais.
+  - Tem cobranças que eu não reconheço e quero entender de onde vieram.
+  - Minha fatura veio mais alta e quero entender o que mudou.
   - Quero entender minha conta
   - Por que esse valor mudou?
   - Explique essas cobranças da minha fatura
@@ -115,41 +160,42 @@ intents:
 - name: contas_contestation
   domain: telecom_contas
   agent: contestacao_agent
-  priority: 150
-  description: Contestação, reclamação ou pedido de ajuste por cobrança que o cliente
-    considera indevida.
+  priority: 120
+  description: Pedido transacional de contestação, estorno, ajuste, retirada ou correção de uma cobrança. Na primeira fala de não reconhecimento sem alvo concreto, use contas_invoice_explanation. Porém, numa reentrada contextual após a explicação, se o pedido original era não reconhecimento e o cliente identificar inequivocamente a cobrança/item/valor que continua questionando, trate a solicitação como contestação daquele alvo; a execução continua sujeita a validação e confirmação transacional.
   mcp_tools:
   - consultar_faturas
   - invoice_explanation
   - contestar_cobranca
   keywords:
-  - contestar
-  - contestação
-  - contestacao
-  - cobrança indevida
-  - cobranca indevida
-  - não reconheço essa cobrança
-  - nao reconheco essa cobranca
-  - não concordo com a cobrança
-  - nao concordo com a cobranca
-  - ajuste na fatura
-  - estorno
-  - valor indevido
-  - não contratei
-  - nao contratei
-  - não reconheço a contratação
-  - nao reconheco a contratacao
-  - não contratei esse plano
-  - nao contratei esse plano
+  - quero contestar
+  - quero contestação
+  - quero contestacao
+  - contestar essa cobrança
+  - contestar essa cobranca
+  - abrir contestação
+  - abrir contestacao
+  - quero estorno
+  - pedir estorno
+  - quero ajuste na fatura
+  - ajustar essa cobrança
+  - ajustar essa cobranca
+  - retirar essa cobrança
+  - retirar essa cobranca
+  - tirar essa cobrança
+  - tirar essa cobranca
   examples:
+  - "Contexto anterior: cliente não reconhece uma cobrança; após a explicação identifica 'é a de quatorze e noventa e nove'."
+  - "Após a explicação da fatura, o cliente identifica pelo nome ou valor qual cobrança continua não reconhecendo."
   - Quero contestar essa cobrança
-  - Esse valor é indevido
-  - Não reconheço uma cobrança na minha fatura
+  - Quero abrir uma contestação para esse valor
+  - Quero um estorno dessa cobrança
+  - Não reconheço essa cobrança e quero contestar
+  - Esse valor está errado e quero um ajuste na fatura
 - name: contas_vas_cancel
   domain: telecom_contas
   agent: contestacao_agent
   priority: 145
-  description: Cancelamento ou retirada explicitamente solicitada de serviço/VAS. Não use para simples alegação de contratação não reconhecida; nesses casos use contestação.
+  description: Cancelamento ou retirada explicitamente solicitada de serviço/VAS. Não use para simples alegação de contratação ou cobrança não reconhecida sem pedido de ação; nesses casos use contas_invoice_explanation.
   mcp_tools:
   - consultar_vas
   - cancelar_vas_avulso

config/tool_policies.yaml

@@ -6,11 +6,18 @@ tool_policies:
   cancelar_vas_avulso:
     operation_type: transactional
     require_confirmation: true
-    requires: [subject]
+    requires:
+    - subject
+    pre_validation:
+      enabled: true
+      tool: validar_vas_subject
+      fail_open: false
   contestar_cobranca:
     operation_type: transactional
     require_confirmation: true
-    requires: [subject, valor]
+    requires:
+    - subject
+    - valor
     pre_validation:
       enabled: true
       tool: validar_contestacao
@@ -18,7 +25,12 @@ tool_policies:
   tratar_vas_estrategico:
     operation_type: conversational
     require_confirmation: false
-    requires: [subject]
+    requires:
+    - subject
+    pre_validation:
+      enabled: true
+      tool: validar_vas_subject
+      fail_open: false
   pro_rata:
     operation_type: conversational
     require_confirmation: false

config/tools.yaml

@@ -55,21 +55,17 @@ tools:
     - divergência
     - cobrança diferente
     - por que esse valor
-#  buscar_informacao:
-#    description: Conhecimento do Contas é atendido pelo RagService do agent_framework_oci, não pelo MCP.
-#    mcp_server: contas
-#    enabled: false
-#    args_schema:
-#      query:
-#        type: string
-#        description: Pergunta ou termo de busca em linguagem natural informado pelo cliente.
-#    selection_keywords:
-#    - o que é
-#    - o que significa
-#    - como funciona
-#    - como faço
-#    - informação
-#    - explique o conceito
+  buscar_informacao:
+    description: Preserva a capability de conhecimento do Contas e delega a recuperação ao RAG do framework.
+    mcp_server: contas
+    enabled: true
+    tool_type: internal
+    confirmation_required: false
+    args_schema:
+      queries:
+        type: array
+        description: Perguntas de conhecimento que devem ser recuperadas pelo RAG do framework.
+    selection_keywords: []
   consultar_vas:
     description: Consulta serviços VAS ativos.
     mcp_server: contas
@@ -115,8 +111,10 @@ tools:
     args_schema:
       subject:
         type: string
-        description: Nome do serviço, produto, item, cobrança ou benefício que é o objeto principal da operação solicitada
-          pelo cliente.
+        description: Referência a um serviço, produto ou benefício concreto e identificável nas evidências VAS/fatura do cliente.
+          Categorias ou referências genéricas não identificam uma entidade por si só; se o texto não permitir resolver univocamente
+          para um item real, mantenha subject ausente/null.
+        user_prompt: Qual serviço você deseja cancelar?
     selection_keywords:
     - cancelar serviço
     - cancelar servico
@@ -136,8 +134,10 @@ tools:
     args_schema:
       subject:
         type: string
-        description: Nome do serviço, produto, item, cobrança ou benefício que é o objeto principal da operação solicitada
-          pelo cliente.
+        description: Referência a um serviço, produto ou benefício concreto e identificável nas evidências VAS/fatura do cliente.
+          Categorias ou referências genéricas não identificam uma entidade por si só; se o texto não permitir resolver univocamente
+          para um item real, mantenha subject ausente/null.
+        user_prompt: Qual serviço ou benefício você deseja tratar?
     selection_keywords:
     - serviço estratégico
     - servico estrategico
@@ -149,6 +149,25 @@ tools:
     - netflix
     - globoplay
     - amazon prime
+  validar_vas_subject:
+    description: Pré-valida de forma side-effect-free se subject resolve para uma entidade VAS concreta antes de confirmação/execução.
+    mcp_server: contas
+    enabled: true
+    tool_type: internal
+    confirmation_required: false
+    requires:
+    - subject
+    args_schema:
+      subject:
+        type: string
+        description: Referência de entidade VAS a resolver contra evidência autorizada.
+      target_tool:
+        type: string
+        description: Tool de domínio que solicitou a pré-validação.
+      msisdn:
+        type: string
+        description: Linha autenticada do contexto operacional.
+    selection_keywords: []
   validar_contestacao:
     description: Pre-valida elegibilidade de uma contestação sem executar qualquer efeito transacional.
     mcp_server: contas
@@ -161,12 +180,15 @@ tools:
     args_schema:
       subject:
         type: string
-        description: Nome do serviço, produto, item, cobrança ou benefício que é o objeto principal da operação solicitada
-          pelo cliente.
+        description: Referência a um item concreto e identificável da fatura (serviço, produto, plano, cobrança específica
+          ou benefício). Uma referência genérica ao documento ou à cobrança como um todo não identifica o subject; quando
+          não houver entidade concreta suficiente para resolução contra a evidência da fatura, mantenha subject ausente/null.
+        user_prompt: Qual cobrança ou item você não reconhece?
       valor:
         type: number
         description: Valor monetário explicitamente associado pelo cliente ao item, cobrança ou operação. Se não houver valor
           explícito ou houver dúvida razoável, manter ausente/null.
+        user_prompt: Qual é o valor da cobrança?
       motivo:
         type: string
         description: Motivo informado pelo cliente para a solicitação ou contestação. Não inventar motivo quando não estiver
@@ -187,12 +209,15 @@ tools:
     args_schema:
       subject:
         type: string
-        description: Nome do serviço, produto, item, cobrança ou benefício que é o objeto principal da operação solicitada
-          pelo cliente.
+        description: Referência a um item concreto e identificável da fatura (serviço, produto, plano, cobrança específica
+          ou benefício). Uma referência genérica ao documento ou à cobrança como um todo não identifica o subject; quando
+          não houver entidade concreta suficiente para resolução contra a evidência da fatura, mantenha subject ausente/null.
+        user_prompt: Qual cobrança ou item você deseja contestar?
       valor:
         type: number
         description: Valor monetário explicitamente associado pelo cliente ao item, cobrança ou operação. Se não houver valor
           explícito ou houver dúvida razoável, manter ausente/null.
+        user_prompt: Qual é o valor da cobrança que você deseja contestar?
       motivo:
         type: string
         description: Motivo informado pelo cliente para a solicitação ou contestação. Não inventar motivo quando não estiver
@@ -212,6 +237,8 @@ tools:
     enabled: true
     tool_type: action
     confirmation_required: false
+    requires:
+    - status
     args_schema:
       status:
         type: string
@@ -284,8 +311,22 @@ tools:
     - cobrança proporcional
     - cobranca proporcional
     - troca de plano
+  consultar_historico_descontos:
+    description: Consulta histórico autoritativo de descontos com status, valores, datas e motivo explícito de término quando fornecido pelo sistema de origem.
+    mcp_server: contas
+    enabled: true
+    tool_type: internal
+    confirmation_required: false
+    args_schema:
+      msisdn:
+        type: string
+        description: Número da linha autenticada usada para consultar o histórico de descontos.
+      nome_plano:
+        type: string
+        description: Filtro opcional pelo nome do plano.
+
   termino_desconto:
-    description: Trata término de desconto identificado na fatura.
+    description: Analisa término/retirada de desconto somente com causa suportada por evidência autoritativa.
     mcp_server: contas
     enabled: true
     args_schema: