Ajustes conforme relatorio de testes 2026-08-27

agent_framework_oci/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflows/agent_graph.py

@@ -160,7 +160,7 @@ class AgentWorkflow:
         builder.add_conditional_edges(
             "input_guardrails",
             self._after_input_guardrails,
-            {"blocked": "persist", "continue": "load_long_term_memory"},
+            {"blocked": "output_guardrails", "continue": "load_long_term_memory"},
         )
         builder.add_edge("load_long_term_memory", "routing_decision")
         builder.add_conditional_edges(
@@ -197,6 +197,31 @@ class AgentWorkflow:
     def _after_input_guardrails(self, state):
         return "blocked" if state.get("blocked") else "continue"
 
+    @staticmethod
+    def _input_guardrail_user_message(decisions, state, sanitized_text):
+        # Keep the technical guardrail reason in telemetry, but expose only a
+        # safe, actionable message to the end user. The message is intentionally
+        # routed through output_guardrails before persistence/delivery.
+        blocked = [d for d in decisions if not getattr(d, "allowed", True)]
+        first = blocked[0] if blocked else None
+        code = str(getattr(first, "code", "") or "").upper()
+        if code == "COER":
+            return (
+                "Não consegui entender sua última mensagem porque ela parece "
+                "incompleta ou ambígua. Pode reformular ou completar o que você quis dizer?"
+            )
+        if code == "INPUT_SIZE":
+            return "Sua mensagem ficou muito longa para eu processar de uma vez. Pode resumir ou dividir em partes?"
+        if code == "DLEX_IN":
+            return "Não posso usar essa informação da forma solicitada. Reformule o pedido sem incluir dados ou conteúdo restrito."
+        if code == "PINJ":
+            return "Não posso seguir instruções que tentem alterar as regras do atendimento. Posso continuar ajudando com a sua solicitação."
+        if code == "TOX":
+            return "Não consegui prosseguir com essa mensagem. Pode reformular o pedido para continuarmos o atendimento?"
+        if code == "CMP":
+            return "Não posso prosseguir com essa solicitação dessa forma. Posso ajudar com uma alternativa permitida."
+        return "Não consegui processar essa mensagem. Pode reformular para eu continuar o atendimento?"
+
     async def input_guardrails(self, state):
         if state.get("session_ended") is True:
             answer = str(getattr(
@@ -281,12 +306,33 @@ class AgentWorkflow:
                 component="workflow.input_guardrails.final",
             )
             if any(not d.allowed for d in decisions):
+                # A blocking input guardrail stops the turn before routing/tools.
+                # Clear turn-local routing/tool state so stale data from a prior
+                # turn cannot appear as if it was executed after the block.
+                user_message = self._input_guardrail_user_message(decisions, state, sanitized)
                 return {
                     "sanitized_input": sanitized,
-                    "answer": "Não consegui seguir com essa mensagem por regra de segurança.",
-                    "final_answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "answer": user_message,
+                    "final_answer": None,
                     "guardrail_decisions": [d.model_dump() for d in decisions],
                     "route": "blocked",
+                    "intent": "input_guardrail_blocked",
+                    "route_decision": {
+                        "route": "blocked",
+                        "agent": None,
+                        "intent": "input_guardrail_blocked",
+                        "confidence": 1.0,
+                        "reason": "Entrada interrompida por guardrail antes do roteamento.",
+                        "method": "guardrail",
+                        "next_state": state.get("next_state"),
+                        "handoff": False,
+                        "metadata": {},
+                        "domain": state.get("domain"),
+                        "mcp_tools": [],
+                    },
+                    "mcp_tools": [],
+                    "mcp_results": [],
+                    "judge_results": [],
                     "blocked": True,
                 }
             return {

agent_framework_oci/Tuning-Performance/Authentication/agent_template_backend_authentication/config/routing.yaml

@@ -7,6 +7,35 @@ router:
   confidence_threshold: 0.65
   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_BILLING_CONFIRMATION
     agent: billing_agent

agent_framework_oci/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.

agent_framework_oci/Tuning-Performance/Deterministic_Transactional_Workflow/agent_template_backend/app/workflows/agent_graph.py

@@ -160,7 +160,7 @@ class AgentWorkflow:
         builder.add_conditional_edges(
             "input_guardrails",
             self._after_input_guardrails,
-            {"blocked": "persist", "continue": "load_long_term_memory"},
+            {"blocked": "output_guardrails", "continue": "load_long_term_memory"},
         )
         builder.add_edge("load_long_term_memory", "routing_decision")
         builder.add_conditional_edges(
@@ -197,6 +197,31 @@ class AgentWorkflow:
     def _after_input_guardrails(self, state):
         return "blocked" if state.get("blocked") else "continue"
 
+    @staticmethod
+    def _input_guardrail_user_message(decisions, state, sanitized_text):
+        # Keep the technical guardrail reason in telemetry, but expose only a
+        # safe, actionable message to the end user. The message is intentionally
+        # routed through output_guardrails before persistence/delivery.
+        blocked = [d for d in decisions if not getattr(d, "allowed", True)]
+        first = blocked[0] if blocked else None
+        code = str(getattr(first, "code", "") or "").upper()
+        if code == "COER":
+            return (
+                "Não consegui entender sua última mensagem porque ela parece "
+                "incompleta ou ambígua. Pode reformular ou completar o que você quis dizer?"
+            )
+        if code == "INPUT_SIZE":
+            return "Sua mensagem ficou muito longa para eu processar de uma vez. Pode resumir ou dividir em partes?"
+        if code == "DLEX_IN":
+            return "Não posso usar essa informação da forma solicitada. Reformule o pedido sem incluir dados ou conteúdo restrito."
+        if code == "PINJ":
+            return "Não posso seguir instruções que tentem alterar as regras do atendimento. Posso continuar ajudando com a sua solicitação."
+        if code == "TOX":
+            return "Não consegui prosseguir com essa mensagem. Pode reformular o pedido para continuarmos o atendimento?"
+        if code == "CMP":
+            return "Não posso prosseguir com essa solicitação dessa forma. Posso ajudar com uma alternativa permitida."
+        return "Não consegui processar essa mensagem. Pode reformular para eu continuar o atendimento?"
+
     async def input_guardrails(self, state):
         if state.get("session_ended") is True:
             answer = str(getattr(
@@ -281,12 +306,33 @@ class AgentWorkflow:
                 component="workflow.input_guardrails.final",
             )
             if any(not d.allowed for d in decisions):
+                # A blocking input guardrail stops the turn before routing/tools.
+                # Clear turn-local routing/tool state so stale data from a prior
+                # turn cannot appear as if it was executed after the block.
+                user_message = self._input_guardrail_user_message(decisions, state, sanitized)
                 return {
                     "sanitized_input": sanitized,
-                    "answer": "Não consegui seguir com essa mensagem por regra de segurança.",
-                    "final_answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "answer": user_message,
+                    "final_answer": None,
                     "guardrail_decisions": [d.model_dump() for d in decisions],
                     "route": "blocked",
+                    "intent": "input_guardrail_blocked",
+                    "route_decision": {
+                        "route": "blocked",
+                        "agent": None,
+                        "intent": "input_guardrail_blocked",
+                        "confidence": 1.0,
+                        "reason": "Entrada interrompida por guardrail antes do roteamento.",
+                        "method": "guardrail",
+                        "next_state": state.get("next_state"),
+                        "handoff": False,
+                        "metadata": {},
+                        "domain": state.get("domain"),
+                        "mcp_tools": [],
+                    },
+                    "mcp_tools": [],
+                    "mcp_results": [],
+                    "judge_results": [],
                     "blocked": True,
                 }
             return {

agent_framework_oci/Tuning-Performance/Deterministic_Transactional_Workflow/agent_template_backend/config/routing.yaml

@@ -7,6 +7,35 @@ router:
   confidence_threshold: 0.65
   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_BILLING_CONFIRMATION
     agent: billing_agent

agent_framework_oci/Tuning-Performance/Deterministic_Transactional_Workflow/agent_template_backend/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.

agent_framework_oci/Tuning-Performance/External_Guardrails_Judges/agent_template_backend/app/workflows/agent_graph.py

@@ -159,7 +159,7 @@ class AgentWorkflow:
         builder.add_conditional_edges(
             "input_guardrails",
             self._after_input_guardrails,
-            {"blocked": "persist", "continue": "routing_decision"},
+            {"blocked": "output_guardrails", "continue": "routing_decision"},
         )
         builder.add_conditional_edges(
             "routing_decision",
@@ -195,6 +195,31 @@ class AgentWorkflow:
     def _after_input_guardrails(self, state):
         return "blocked" if state.get("blocked") else "continue"
 
+    @staticmethod
+    def _input_guardrail_user_message(decisions, state, sanitized_text):
+        # Keep the technical guardrail reason in telemetry, but expose only a
+        # safe, actionable message to the end user. The message is intentionally
+        # routed through output_guardrails before persistence/delivery.
+        blocked = [d for d in decisions if not getattr(d, "allowed", True)]
+        first = blocked[0] if blocked else None
+        code = str(getattr(first, "code", "") or "").upper()
+        if code == "COER":
+            return (
+                "Não consegui entender sua última mensagem porque ela parece "
+                "incompleta ou ambígua. Pode reformular ou completar o que você quis dizer?"
+            )
+        if code == "INPUT_SIZE":
+            return "Sua mensagem ficou muito longa para eu processar de uma vez. Pode resumir ou dividir em partes?"
+        if code == "DLEX_IN":
+            return "Não posso usar essa informação da forma solicitada. Reformule o pedido sem incluir dados ou conteúdo restrito."
+        if code == "PINJ":
+            return "Não posso seguir instruções que tentem alterar as regras do atendimento. Posso continuar ajudando com a sua solicitação."
+        if code == "TOX":
+            return "Não consegui prosseguir com essa mensagem. Pode reformular o pedido para continuarmos o atendimento?"
+        if code == "CMP":
+            return "Não posso prosseguir com essa solicitação dessa forma. Posso ajudar com uma alternativa permitida."
+        return "Não consegui processar essa mensagem. Pode reformular para eu continuar o atendimento?"
+
     async def input_guardrails(self, state):
         if state.get("session_ended") is True:
             answer = str(getattr(
@@ -279,12 +304,33 @@ class AgentWorkflow:
                 component="workflow.input_guardrails.final",
             )
             if any(not d.allowed for d in decisions):
+                # A blocking input guardrail stops the turn before routing/tools.
+                # Clear turn-local routing/tool state so stale data from a prior
+                # turn cannot appear as if it was executed after the block.
+                user_message = self._input_guardrail_user_message(decisions, state, sanitized)
                 return {
                     "sanitized_input": sanitized,
-                    "answer": "Não consegui seguir com essa mensagem por regra de segurança.",
-                    "final_answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "answer": user_message,
+                    "final_answer": None,
                     "guardrail_decisions": [d.model_dump() for d in decisions],
                     "route": "blocked",
+                    "intent": "input_guardrail_blocked",
+                    "route_decision": {
+                        "route": "blocked",
+                        "agent": None,
+                        "intent": "input_guardrail_blocked",
+                        "confidence": 1.0,
+                        "reason": "Entrada interrompida por guardrail antes do roteamento.",
+                        "method": "guardrail",
+                        "next_state": state.get("next_state"),
+                        "handoff": False,
+                        "metadata": {},
+                        "domain": state.get("domain"),
+                        "mcp_tools": [],
+                    },
+                    "mcp_tools": [],
+                    "mcp_results": [],
+                    "judge_results": [],
                     "blocked": True,
                 }
             return {

agent_framework_oci/Tuning-Performance/External_Guardrails_Judges/agent_template_backend/config/routing.yaml

@@ -7,6 +7,35 @@ router:
   confidence_threshold: 0.65
   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_BILLING_CONFIRMATION
     agent: billing_agent

agent_framework_oci/Tuning-Performance/External_Guardrails_Judges/agent_template_backend/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.

agent_framework_oci/Tuning-Performance/Long_Term_Memory/templates/agent_template_backend/app/workflows/agent_graph.py

@@ -160,7 +160,7 @@ class AgentWorkflow:
         builder.add_conditional_edges(
             "input_guardrails",
             self._after_input_guardrails,
-            {"blocked": "persist", "continue": "load_long_term_memory"},
+            {"blocked": "output_guardrails", "continue": "load_long_term_memory"},
         )
         builder.add_edge("load_long_term_memory", "routing_decision")
         builder.add_conditional_edges(
@@ -197,6 +197,31 @@ class AgentWorkflow:
     def _after_input_guardrails(self, state):
         return "blocked" if state.get("blocked") else "continue"
 
+    @staticmethod
+    def _input_guardrail_user_message(decisions, state, sanitized_text):
+        # Keep the technical guardrail reason in telemetry, but expose only a
+        # safe, actionable message to the end user. The message is intentionally
+        # routed through output_guardrails before persistence/delivery.
+        blocked = [d for d in decisions if not getattr(d, "allowed", True)]
+        first = blocked[0] if blocked else None
+        code = str(getattr(first, "code", "") or "").upper()
+        if code == "COER":
+            return (
+                "Não consegui entender sua última mensagem porque ela parece "
+                "incompleta ou ambígua. Pode reformular ou completar o que você quis dizer?"
+            )
+        if code == "INPUT_SIZE":
+            return "Sua mensagem ficou muito longa para eu processar de uma vez. Pode resumir ou dividir em partes?"
+        if code == "DLEX_IN":
+            return "Não posso usar essa informação da forma solicitada. Reformule o pedido sem incluir dados ou conteúdo restrito."
+        if code == "PINJ":
+            return "Não posso seguir instruções que tentem alterar as regras do atendimento. Posso continuar ajudando com a sua solicitação."
+        if code == "TOX":
+            return "Não consegui prosseguir com essa mensagem. Pode reformular o pedido para continuarmos o atendimento?"
+        if code == "CMP":
+            return "Não posso prosseguir com essa solicitação dessa forma. Posso ajudar com uma alternativa permitida."
+        return "Não consegui processar essa mensagem. Pode reformular para eu continuar o atendimento?"
+
     async def input_guardrails(self, state):
         if state.get("session_ended") is True:
             answer = str(getattr(
@@ -281,12 +306,33 @@ class AgentWorkflow:
                 component="workflow.input_guardrails.final",
             )
             if any(not d.allowed for d in decisions):
+                # A blocking input guardrail stops the turn before routing/tools.
+                # Clear turn-local routing/tool state so stale data from a prior
+                # turn cannot appear as if it was executed after the block.
+                user_message = self._input_guardrail_user_message(decisions, state, sanitized)
                 return {
                     "sanitized_input": sanitized,
-                    "answer": "Não consegui seguir com essa mensagem por regra de segurança.",
-                    "final_answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "answer": user_message,
+                    "final_answer": None,
                     "guardrail_decisions": [d.model_dump() for d in decisions],
                     "route": "blocked",
+                    "intent": "input_guardrail_blocked",
+                    "route_decision": {
+                        "route": "blocked",
+                        "agent": None,
+                        "intent": "input_guardrail_blocked",
+                        "confidence": 1.0,
+                        "reason": "Entrada interrompida por guardrail antes do roteamento.",
+                        "method": "guardrail",
+                        "next_state": state.get("next_state"),
+                        "handoff": False,
+                        "metadata": {},
+                        "domain": state.get("domain"),
+                        "mcp_tools": [],
+                    },
+                    "mcp_tools": [],
+                    "mcp_results": [],
+                    "judge_results": [],
                     "blocked": True,
                 }
             return {

agent_framework_oci/Tuning-Performance/Long_Term_Memory/templates/agent_template_backend/config/routing.yaml

@@ -7,6 +7,35 @@ router:
   confidence_threshold: 0.65
   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_BILLING_CONFIRMATION
     agent: billing_agent

agent_framework_oci/Tuning-Performance/Long_Term_Memory/templates/agent_template_backend/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.

agent_framework_oci/Tuning-Performance/Normal/templates/agent_template_backend/app/workflows/agent_graph.py

@@ -159,7 +159,7 @@ class AgentWorkflow:
         builder.add_conditional_edges(
             "input_guardrails",
             self._after_input_guardrails,
-            {"blocked": "persist", "continue": "routing_decision"},
+            {"blocked": "output_guardrails", "continue": "routing_decision"},
         )
         builder.add_conditional_edges(
             "routing_decision",
@@ -195,6 +195,31 @@ class AgentWorkflow:
     def _after_input_guardrails(self, state):
         return "blocked" if state.get("blocked") else "continue"
 
+    @staticmethod
+    def _input_guardrail_user_message(decisions, state, sanitized_text):
+        # Keep the technical guardrail reason in telemetry, but expose only a
+        # safe, actionable message to the end user. The message is intentionally
+        # routed through output_guardrails before persistence/delivery.
+        blocked = [d for d in decisions if not getattr(d, "allowed", True)]
+        first = blocked[0] if blocked else None
+        code = str(getattr(first, "code", "") or "").upper()
+        if code == "COER":
+            return (
+                "Não consegui entender sua última mensagem porque ela parece "
+                "incompleta ou ambígua. Pode reformular ou completar o que você quis dizer?"
+            )
+        if code == "INPUT_SIZE":
+            return "Sua mensagem ficou muito longa para eu processar de uma vez. Pode resumir ou dividir em partes?"
+        if code == "DLEX_IN":
+            return "Não posso usar essa informação da forma solicitada. Reformule o pedido sem incluir dados ou conteúdo restrito."
+        if code == "PINJ":
+            return "Não posso seguir instruções que tentem alterar as regras do atendimento. Posso continuar ajudando com a sua solicitação."
+        if code == "TOX":
+            return "Não consegui prosseguir com essa mensagem. Pode reformular o pedido para continuarmos o atendimento?"
+        if code == "CMP":
+            return "Não posso prosseguir com essa solicitação dessa forma. Posso ajudar com uma alternativa permitida."
+        return "Não consegui processar essa mensagem. Pode reformular para eu continuar o atendimento?"
+
     async def input_guardrails(self, state):
         if state.get("session_ended") is True:
             answer = str(getattr(
@@ -279,12 +304,33 @@ class AgentWorkflow:
                 component="workflow.input_guardrails.final",
             )
             if any(not d.allowed for d in decisions):
+                # A blocking input guardrail stops the turn before routing/tools.
+                # Clear turn-local routing/tool state so stale data from a prior
+                # turn cannot appear as if it was executed after the block.
+                user_message = self._input_guardrail_user_message(decisions, state, sanitized)
                 return {
                     "sanitized_input": sanitized,
-                    "answer": "Não consegui seguir com essa mensagem por regra de segurança.",
-                    "final_answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "answer": user_message,
+                    "final_answer": None,
                     "guardrail_decisions": [d.model_dump() for d in decisions],
                     "route": "blocked",
+                    "intent": "input_guardrail_blocked",
+                    "route_decision": {
+                        "route": "blocked",
+                        "agent": None,
+                        "intent": "input_guardrail_blocked",
+                        "confidence": 1.0,
+                        "reason": "Entrada interrompida por guardrail antes do roteamento.",
+                        "method": "guardrail",
+                        "next_state": state.get("next_state"),
+                        "handoff": False,
+                        "metadata": {},
+                        "domain": state.get("domain"),
+                        "mcp_tools": [],
+                    },
+                    "mcp_tools": [],
+                    "mcp_results": [],
+                    "judge_results": [],
                     "blocked": True,
                 }
             return {

agent_framework_oci/Tuning-Performance/Normal/templates/agent_template_backend/config/routing.yaml

@@ -7,6 +7,35 @@ router:
   confidence_threshold: 0.65
   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_BILLING_CONFIRMATION
     agent: billing_agent

agent_framework_oci/Tuning-Performance/Normal/templates/agent_template_backend/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.

agent_framework_oci/Tuning-Performance/Normal/templates/agent_template_backend_day_zero/app/workflows/agent_graph.py

@@ -159,7 +159,7 @@ class AgentWorkflow:
         builder.add_conditional_edges(
             "input_guardrails",
             self._after_input_guardrails,
-            {"blocked": "persist", "continue": "routing_decision"},
+            {"blocked": "output_guardrails", "continue": "routing_decision"},
         )
         builder.add_conditional_edges(
             "routing_decision",
@@ -195,6 +195,31 @@ class AgentWorkflow:
     def _after_input_guardrails(self, state):
         return "blocked" if state.get("blocked") else "continue"
 
+    @staticmethod
+    def _input_guardrail_user_message(decisions, state, sanitized_text):
+        # Keep the technical guardrail reason in telemetry, but expose only a
+        # safe, actionable message to the end user. The message is intentionally
+        # routed through output_guardrails before persistence/delivery.
+        blocked = [d for d in decisions if not getattr(d, "allowed", True)]
+        first = blocked[0] if blocked else None
+        code = str(getattr(first, "code", "") or "").upper()
+        if code == "COER":
+            return (
+                "Não consegui entender sua última mensagem porque ela parece "
+                "incompleta ou ambígua. Pode reformular ou completar o que você quis dizer?"
+            )
+        if code == "INPUT_SIZE":
+            return "Sua mensagem ficou muito longa para eu processar de uma vez. Pode resumir ou dividir em partes?"
+        if code == "DLEX_IN":
+            return "Não posso usar essa informação da forma solicitada. Reformule o pedido sem incluir dados ou conteúdo restrito."
+        if code == "PINJ":
+            return "Não posso seguir instruções que tentem alterar as regras do atendimento. Posso continuar ajudando com a sua solicitação."
+        if code == "TOX":
+            return "Não consegui prosseguir com essa mensagem. Pode reformular o pedido para continuarmos o atendimento?"
+        if code == "CMP":
+            return "Não posso prosseguir com essa solicitação dessa forma. Posso ajudar com uma alternativa permitida."
+        return "Não consegui processar essa mensagem. Pode reformular para eu continuar o atendimento?"
+
     async def input_guardrails(self, state):
         if state.get("session_ended") is True:
             answer = str(getattr(
@@ -279,12 +304,33 @@ class AgentWorkflow:
                 component="workflow.input_guardrails.final",
             )
             if any(not d.allowed for d in decisions):
+                # A blocking input guardrail stops the turn before routing/tools.
+                # Clear turn-local routing/tool state so stale data from a prior
+                # turn cannot appear as if it was executed after the block.
+                user_message = self._input_guardrail_user_message(decisions, state, sanitized)
                 return {
                     "sanitized_input": sanitized,
-                    "answer": "Não consegui seguir com essa mensagem por regra de segurança.",
-                    "final_answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "answer": user_message,
+                    "final_answer": None,
                     "guardrail_decisions": [d.model_dump() for d in decisions],
                     "route": "blocked",
+                    "intent": "input_guardrail_blocked",
+                    "route_decision": {
+                        "route": "blocked",
+                        "agent": None,
+                        "intent": "input_guardrail_blocked",
+                        "confidence": 1.0,
+                        "reason": "Entrada interrompida por guardrail antes do roteamento.",
+                        "method": "guardrail",
+                        "next_state": state.get("next_state"),
+                        "handoff": False,
+                        "metadata": {},
+                        "domain": state.get("domain"),
+                        "mcp_tools": [],
+                    },
+                    "mcp_tools": [],
+                    "mcp_results": [],
+                    "judge_results": [],
                     "blocked": True,
                 }
             return {

agent_framework_oci/Tuning-Performance/Normal/templates/agent_template_backend_day_zero/config/routing.yaml

@@ -7,6 +7,35 @@ router:
   confidence_threshold: 0.65
   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_BILLING_CONFIRMATION
     agent: billing_agent

agent_framework_oci/Tuning-Performance/Normal/templates/agent_template_backend_day_zero/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.

agent_framework_oci/Tuning-Performance/Pause_Resume_Workflow/IMPLEMENTACAO_PAUSE_RESUME_LANGGRAPH.md

@@ -13,3 +13,46 @@ O `WorkflowRuntime` também preserva o último snapshot persistido do LangGraph
 Isso é necessário para workflows transacionais: por exemplo, se um protocolo foi criado e uma chamada posterior falha, o chamador ainda recebe o `protocol_number` persistido e pode executar recuperação/idempotência sem repetir o primeiro side effect.
 
 O runtime não transforma falha em sucesso e não reexecuta automaticamente a action; ele apenas preserva a evidência durável já existente no checkpointer.
+
+## Tratamento genérico de entrada fora das opções (`unmatched`)
+
+`expected_input` mantém compatibilidade com o comportamento anterior.
+Sem `semantic_classifier`, qualquer entrada que não pertença literalmente a
+`allowed_values` permanece no workflow e recebe o `reprompt`.
+
+Quando o agente precisa aceitar linguagem natural, ele declara um prompt
+classificatório cujo resultado deve ser uma das próprias opções dinâmicas:
+
+```yaml
+expected_input:
+  key: resposta_usuario
+  allowed_values: [SIM, NAO]
+  normalize: upper_strip
+  reprompt: "Não entendi. Responda sim ou não."
+  semantic_classifier:
+    enabled: true
+    prompt: |
+      Classifique a fala em exatamente uma opção de {{ allowed_values }}.
+      Pergunta pendente: {{ pending_prompt }}
+      Fala do usuário: {{ user_input }}
+      Retorne somente uma opção de {{ allowed_values }}.
+```
+
+O framework não possui classes fixas. `allowed_values` pode conter duas, três ou
+mais opções; o prompt do agente define a semântica de cada uma. O framework
+renderiza os placeholders, chama a LLM e rejeita qualquer saída que não pertença
+à allowlist, usando `reprompt` nesse caso. O texto original do usuário é mantido
+nos metadados da decisão para auditoria.
+
+Nesse modo, `COER` delega a interpretação semântica ao classificador configurado.
+Rails de segurança independentes — por exemplo PINJ, toxicidade, PII e limites
+de tamanho — continuam podendo bloquear o turno normalmente.
+
+O exemplo executável está em `agent_template_backend/` e, por compatibilidade
+com a estrutura histórica desta feature, também em
+`agent_template_backend_pause_resume/`.
+
+
+### Reentrada contextual por opção
+
+Uma opção do `semantic_classifier` pode declarar `option_actions.<OPCAO>.action: contextual_reentry`. Nesse caso o workflow pausado não é retomado: o framework libera a pausa e reexecuta o roteamento usando somente o contexto conversacional ancorado que originou a decisão mais a fala atual. A fala original é preservada para auditoria e o contexto reconstruído não vira evidência de negócio; parâmetros candidatos continuam sujeitos a validação e confirmação normais.

agent_framework_oci/Tuning-Performance/Pause_Resume_Workflow/README.md

@@ -32,3 +32,49 @@ O exemplo usa `MemorySaver` apenas para ser autocontido. Em aplicações reais u
 ## Regra arquitetural
 
 Código de domínio não deve importar `langgraph.graph.StateGraph`. Para grafos de agentes use `FrameworkStateGraph`; para workflows determinísticos de negócio use `WorkflowRuntime`.
+
+## Entrada enumerada, reprompt e `semantic_classifier`
+
+O contrato `expected_input` pode declarar qualquer conjunto de opções em
+`allowed_values`. O match literal continua determinístico; quando a resposta não
+coincide literalmente com uma opção, o agente pode habilitar um classificador
+semântico com prompt próprio.
+
+```yaml
+expected_input:
+  key: resposta_usuario
+  allowed_values: [SIM, NAO]
+  normalize: upper_strip
+  reprompt: "Não entendi. Responda sim ou não."
+  semantic_classifier:
+    enabled: true
+    prompt: |
+      Classifique {{ user_input }} em exatamente uma opção de {{ allowed_values }}.
+      Para este workflow, aceitação/entendimento => SIM; negação, nova pergunta
+      ou hipótese factual a validar => NAO.
+      Retorne somente uma opção de {{ allowed_values }}.
+```
+
+O framework não conhece o significado de `SIM`, `NAO` nem de nenhuma outra
+opção. Ele apenas injeta `allowed_values`, `pending_prompt` e `user_input`, chama
+a LLM e valida estritamente se a saída pertence à lista declarada. Uma saída
+fora da lista usa o `reprompt`.
+
+O mesmo mecanismo funciona sem alteração do framework para, por exemplo,
+`[CONFIRMAR, ALTERAR, CANCELAR]` ou qualquer outra lista configurada pelo agente.
+O rail `COER` delega a semântica ao `semantic_classifier` nesse modo; PINJ,
+toxicidade, PII e os demais rails de segurança continuam independentes.
+
+Há dois diretórios equivalentes para facilitar comparação com os demais
+cenários de Tuning-Performance:
+
+- `agent_template_backend/` — nome padrão de template;
+- `agent_template_backend_pause_resume/` — nome histórico deste exemplo.
+
+Ambos contêm o mesmo workflow `confirmacao.v1.yaml`.
+
+
+
+### Reentrada contextual por opção
+
+Uma opção do `semantic_classifier` pode declarar `option_actions.<OPCAO>.action: contextual_reentry`. Nesse caso o workflow pausado não é retomado: o framework libera a pausa e reexecuta o roteamento usando somente o contexto conversacional ancorado que originou a decisão mais a fala atual. A fala original é preservada para auditoria e o contexto reconstruído não vira evidência de negócio; parâmetros candidatos continuam sujeitos a validação e confirmação normais.

agent_framework_oci/Tuning-Performance/Pause_Resume_Workflow/agent_template_backend/README.md

@@ -0,0 +1,26 @@
+# Agent Template Backend — Pause/Resume Workflow
+
+Exemplo autocontido de um agente que usa o motor genérico de workflows do
+`agent_framework_oci`.
+
+O arquivo `workflows/confirmacao.v1.yaml` demonstra:
+
+- `pause`;
+- `expected_input`;
+- `allowed_values`;
+- `normalize`;
+- `reprompt`;
+- `semantic_classifier`;
+- `resume_from`.
+
+O framework não conhece `SIM`, `NAO` nem a regra de negócio. O agente declara
+os valores e o prompt no YAML. Quando a fala não corresponde literalmente a uma
+opção, `semantic_classifier` classifica usando o prompt do agente e o framework
+aceita somente uma saída presente em `allowed_values`; qualquer outra saída usa
+o `reprompt`. O mesmo mecanismo funciona com qualquer quantidade de opções.
+
+Execute os testes a partir desta pasta:
+
+```bash
+pytest -q
+```

agent_framework_oci/Tuning-Performance/Pause_Resume_Workflow/agent_template_backend/app/demo.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from agent_framework.workflows import FileWorkflowRepository, WorkflowActionRegistry, WorkflowRuntime
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def build_runtime(*, offline_test_fallback: bool = False) -> WorkflowRuntime:
+    actions = WorkflowActionRegistry()
+
+    async def preparar(params, state):
+        return {"assunto": params.get("assunto") or "operação"}
+
+    async def perguntar(params, state):
+        return {"mensagem": f"Deseja confirmar {params['assunto']}?"}
+
+    async def decidir(params, state):
+        return {
+            "mensagem": "Operação confirmada." if params["resposta"] == "SIM" else "Operação cancelada.",
+            "confirmado": params["resposta"] == "SIM",
+        }
+
+    actions.register("preparar_operacao", preparar)
+    actions.register("montar_pergunta", perguntar)
+    actions.register("registrar_decisao", decidir)
+
+    checkpointer = None
+    if not offline_test_fallback:
+        # Produção/exemplo real continua usando LangGraph + checkpointer. O import
+        # fica aqui para que a regressão offline do repositório não dependa de rede.
+        from langgraph.checkpoint.memory import MemorySaver
+        checkpointer = MemorySaver()
+
+    return WorkflowRuntime(
+        FileWorkflowRepository(ROOT / "workflows"),
+        actions=actions,
+        checkpointer=checkpointer,
+        allow_deterministic_fallback=offline_test_fallback,
+    )
+
+
+async def main() -> None:
+    runtime = build_runtime()
+    first = await runtime.arun("confirmacao", {"assunto": "a alteração do plano"})
+    print(first.model_dump(mode="json"))
+    assert first.status == "PAUSED"
+    resumed = await runtime.aresume("confirmacao", first.execution_id, {"resposta_usuario": "sim"})
+    print(resumed.model_dump(mode="json"))
+    assert resumed.status == "COMPLETED"
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent_framework_oci/Tuning-Performance/Pause_Resume_Workflow/agent_template_backend/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.

agent_framework_oci/Tuning-Performance/Pause_Resume_Workflow/agent_template_backend/tests/test_pause_resume.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import pytest
+
+from app.demo import build_runtime
+
+
+@pytest.mark.asyncio
+async def test_pause_resume_does_not_repeat_previous_action():
+    # Regressão offline: exercita a mesma DSL/WorkflowRuntime sem exigir download
+    # de LangGraph no builder. Produção continua usando build_runtime() default.
+    runtime = build_runtime(offline_test_fallback=True)
+    first = await runtime.arun("confirmacao", {"assunto": "o cancelamento"})
+    assert first.status == "PAUSED"
+    assert first.pause["expected_input"]["key"] == "resposta_usuario"
+    before = [item for item in first.trace if item.get("action") == "preparar_operacao"]
+    assert len(before) == 1
+    resumed = await runtime.aresume("confirmacao", first.execution_id, {"resposta_usuario": "SIM"})
+    assert resumed.status == "COMPLETED"
+    after = [item for item in resumed.trace if item.get("action") == "preparar_operacao"]
+    assert len(after) == 1
+    assert resumed.state["vars"]["decidir"]["confirmado"] is True
+
+
+def test_pause_resume_example_documents_semantic_classifier():
+    from pathlib import Path
+    import yaml
+
+    project = Path(__file__).resolve().parents[1]
+    data = yaml.safe_load((project / "workflows" / "confirmacao.v1.yaml").read_text(encoding="utf-8"))
+    perguntar = next(node for node in data["nodes"] if node["id"] == "perguntar")
+    expected = perguntar["pause"]["expected_input"]
+    assert expected["reprompt"] == "Não entendi. Responda sim ou não."
+    assert expected["semantic_classifier"]["enabled"] is True
+    assert "{{ allowed_values }}" in expected["semantic_classifier"]["prompt"]

agent_framework_oci/Tuning-Performance/Pause_Resume_Workflow/agent_template_backend/workflows/confirmacao.active.yaml

@@ -0,0 +1 @@
+version: 1

agent_framework_oci/Tuning-Performance/Pause_Resume_Workflow/agent_template_backend/workflows/confirmacao.v1.yaml

@@ -0,0 +1,45 @@
+name: confirmacao
+version: 1
+start: preparar
+nodes:
+  - id: preparar
+    action: preparar_operacao
+    input:
+      assunto: $.input.assunto
+  - id: perguntar
+    action: montar_pergunta
+    input:
+      assunto: $.vars.preparar.assunto
+    pause:
+      enabled: true
+      return_from: $.output.mensagem
+      expected_input:
+        key: resposta_usuario
+        allowed_values: [SIM, NAO]
+        normalize: upper_strip
+        reprompt: "Não entendi. Responda sim ou não."
+        semantic_classifier:
+          include_relevant_context: true
+          enabled: true
+          prompt: |
+            Classifique a resposta em exatamente uma opção de {{ allowed_values }}.
+            Pergunta pendente: {{ pending_prompt }}
+            Contexto relevante:
+            {{ relevant_conversation_context }}
+            Resposta do usuário: {{ user_input }}
+            Neste exemplo, concordância/aceitação corresponde a SIM e recusa, dúvida
+            adicional ou nova condição corresponde a NAO.
+            Retorne somente uma opção de {{ allowed_values }}.
+      resume_from: decidir
+  - id: decidir
+    action: registrar_decisao
+    input:
+      resposta: $.input.resposta_usuario
+      assunto: $.vars.preparar.assunto
+edges:
+  - from: preparar
+    to: perguntar
+  - from: perguntar
+    to: END
+  - from: decidir
+    to: END

agent_framework_oci/Tuning-Performance/Pause_Resume_Workflow/agent_template_backend_pause_resume/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.

agent_framework_oci/Tuning-Performance/Pause_Resume_Workflow/agent_template_backend_pause_resume/tests/test_pause_resume.py

@@ -20,3 +20,16 @@ async def test_pause_resume_does_not_repeat_previous_action():
     after = [item for item in resumed.trace if item.get("action") == "preparar_operacao"]
     assert len(after) == 1
     assert resumed.state["vars"]["decidir"]["confirmado"] is True
+
+
+def test_pause_resume_example_documents_semantic_classifier():
+    from pathlib import Path
+    import yaml
+
+    project = Path(__file__).resolve().parents[1]
+    data = yaml.safe_load((project / "workflows" / "confirmacao.v1.yaml").read_text(encoding="utf-8"))
+    perguntar = next(node for node in data["nodes"] if node["id"] == "perguntar")
+    expected = perguntar["pause"]["expected_input"]
+    assert expected["reprompt"] == "Não entendi. Responda sim ou não."
+    assert expected["semantic_classifier"]["enabled"] is True
+    assert "{{ allowed_values }}" in expected["semantic_classifier"]["prompt"]

agent_framework_oci/Tuning-Performance/Pause_Resume_Workflow/agent_template_backend_pause_resume/workflows/confirmacao.v1.yaml

@@ -17,6 +17,19 @@ nodes:
         key: resposta_usuario
         allowed_values: [SIM, NAO]
         normalize: upper_strip
+        reprompt: "Não entendi. Responda sim ou não."
+        semantic_classifier:
+          include_relevant_context: true
+          enabled: true
+          prompt: |
+            Classifique a resposta em exatamente uma opção de {{ allowed_values }}.
+            Pergunta pendente: {{ pending_prompt }}
+            Contexto relevante:
+            {{ relevant_conversation_context }}
+            Resposta do usuário: {{ user_input }}
+            Neste exemplo, concordância/aceitação corresponde a SIM e recusa, dúvida
+            adicional ou nova condição corresponde a NAO.
+            Retorne somente uma opção de {{ allowed_values }}.
       resume_from: decidir
   - id: decidir
     action: registrar_decisao

agent_framework_oci/Tuning-Performance/Route_Stickness/templates/agent_template_backend/app/workflows/agent_graph.py

@@ -159,7 +159,7 @@ class AgentWorkflow:
         builder.add_conditional_edges(
             "input_guardrails",
             self._after_input_guardrails,
-            {"blocked": "persist", "continue": "routing_decision"},
+            {"blocked": "output_guardrails", "continue": "routing_decision"},
         )
         builder.add_conditional_edges(
             "routing_decision",
@@ -195,6 +195,31 @@ class AgentWorkflow:
     def _after_input_guardrails(self, state):
         return "blocked" if state.get("blocked") else "continue"
 
+    @staticmethod
+    def _input_guardrail_user_message(decisions, state, sanitized_text):
+        # Keep the technical guardrail reason in telemetry, but expose only a
+        # safe, actionable message to the end user. The message is intentionally
+        # routed through output_guardrails before persistence/delivery.
+        blocked = [d for d in decisions if not getattr(d, "allowed", True)]
+        first = blocked[0] if blocked else None
+        code = str(getattr(first, "code", "") or "").upper()
+        if code == "COER":
+            return (
+                "Não consegui entender sua última mensagem porque ela parece "
+                "incompleta ou ambígua. Pode reformular ou completar o que você quis dizer?"
+            )
+        if code == "INPUT_SIZE":
+            return "Sua mensagem ficou muito longa para eu processar de uma vez. Pode resumir ou dividir em partes?"
+        if code == "DLEX_IN":
+            return "Não posso usar essa informação da forma solicitada. Reformule o pedido sem incluir dados ou conteúdo restrito."
+        if code == "PINJ":
+            return "Não posso seguir instruções que tentem alterar as regras do atendimento. Posso continuar ajudando com a sua solicitação."
+        if code == "TOX":
+            return "Não consegui prosseguir com essa mensagem. Pode reformular o pedido para continuarmos o atendimento?"
+        if code == "CMP":
+            return "Não posso prosseguir com essa solicitação dessa forma. Posso ajudar com uma alternativa permitida."
+        return "Não consegui processar essa mensagem. Pode reformular para eu continuar o atendimento?"
+
     async def input_guardrails(self, state):
         if state.get("session_ended") is True:
             answer = str(getattr(
@@ -279,12 +304,33 @@ class AgentWorkflow:
                 component="workflow.input_guardrails.final",
             )
             if any(not d.allowed for d in decisions):
+                # A blocking input guardrail stops the turn before routing/tools.
+                # Clear turn-local routing/tool state so stale data from a prior
+                # turn cannot appear as if it was executed after the block.
+                user_message = self._input_guardrail_user_message(decisions, state, sanitized)
                 return {
                     "sanitized_input": sanitized,
-                    "answer": "Não consegui seguir com essa mensagem por regra de segurança.",
-                    "final_answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "answer": user_message,
+                    "final_answer": None,
                     "guardrail_decisions": [d.model_dump() for d in decisions],
                     "route": "blocked",
+                    "intent": "input_guardrail_blocked",
+                    "route_decision": {
+                        "route": "blocked",
+                        "agent": None,
+                        "intent": "input_guardrail_blocked",
+                        "confidence": 1.0,
+                        "reason": "Entrada interrompida por guardrail antes do roteamento.",
+                        "method": "guardrail",
+                        "next_state": state.get("next_state"),
+                        "handoff": False,
+                        "metadata": {},
+                        "domain": state.get("domain"),
+                        "mcp_tools": [],
+                    },
+                    "mcp_tools": [],
+                    "mcp_results": [],
+                    "judge_results": [],
                     "blocked": True,
                 }
             return {

agent_framework_oci/Tuning-Performance/Route_Stickness/templates/agent_template_backend/config/routing.yaml

@@ -7,6 +7,35 @@ router:
   confidence_threshold: 0.65
   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_BILLING_CONFIRMATION
     agent: billing_agent

agent_framework_oci/Tuning-Performance/Route_Stickness/templates/agent_template_backend/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.

agent_framework_oci/Tuning-Performance/Route_Stickness/templates/agent_template_backend_day_zero/app/workflows/agent_graph.py

@@ -159,7 +159,7 @@ class AgentWorkflow:
         builder.add_conditional_edges(
             "input_guardrails",
             self._after_input_guardrails,
-            {"blocked": "persist", "continue": "routing_decision"},
+            {"blocked": "output_guardrails", "continue": "routing_decision"},
         )
         builder.add_conditional_edges(
             "routing_decision",
@@ -195,6 +195,31 @@ class AgentWorkflow:
     def _after_input_guardrails(self, state):
         return "blocked" if state.get("blocked") else "continue"
 
+    @staticmethod
+    def _input_guardrail_user_message(decisions, state, sanitized_text):
+        # Keep the technical guardrail reason in telemetry, but expose only a
+        # safe, actionable message to the end user. The message is intentionally
+        # routed through output_guardrails before persistence/delivery.
+        blocked = [d for d in decisions if not getattr(d, "allowed", True)]
+        first = blocked[0] if blocked else None
+        code = str(getattr(first, "code", "") or "").upper()
+        if code == "COER":
+            return (
+                "Não consegui entender sua última mensagem porque ela parece "
+                "incompleta ou ambígua. Pode reformular ou completar o que você quis dizer?"
+            )
+        if code == "INPUT_SIZE":
+            return "Sua mensagem ficou muito longa para eu processar de uma vez. Pode resumir ou dividir em partes?"
+        if code == "DLEX_IN":
+            return "Não posso usar essa informação da forma solicitada. Reformule o pedido sem incluir dados ou conteúdo restrito."
+        if code == "PINJ":
+            return "Não posso seguir instruções que tentem alterar as regras do atendimento. Posso continuar ajudando com a sua solicitação."
+        if code == "TOX":
+            return "Não consegui prosseguir com essa mensagem. Pode reformular o pedido para continuarmos o atendimento?"
+        if code == "CMP":
+            return "Não posso prosseguir com essa solicitação dessa forma. Posso ajudar com uma alternativa permitida."
+        return "Não consegui processar essa mensagem. Pode reformular para eu continuar o atendimento?"
+
     async def input_guardrails(self, state):
         if state.get("session_ended") is True:
             answer = str(getattr(
@@ -279,12 +304,33 @@ class AgentWorkflow:
                 component="workflow.input_guardrails.final",
             )
             if any(not d.allowed for d in decisions):
+                # A blocking input guardrail stops the turn before routing/tools.
+                # Clear turn-local routing/tool state so stale data from a prior
+                # turn cannot appear as if it was executed after the block.
+                user_message = self._input_guardrail_user_message(decisions, state, sanitized)
                 return {
                     "sanitized_input": sanitized,
-                    "answer": "Não consegui seguir com essa mensagem por regra de segurança.",
-                    "final_answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "answer": user_message,
+                    "final_answer": None,
                     "guardrail_decisions": [d.model_dump() for d in decisions],
                     "route": "blocked",
+                    "intent": "input_guardrail_blocked",
+                    "route_decision": {
+                        "route": "blocked",
+                        "agent": None,
+                        "intent": "input_guardrail_blocked",
+                        "confidence": 1.0,
+                        "reason": "Entrada interrompida por guardrail antes do roteamento.",
+                        "method": "guardrail",
+                        "next_state": state.get("next_state"),
+                        "handoff": False,
+                        "metadata": {},
+                        "domain": state.get("domain"),
+                        "mcp_tools": [],
+                    },
+                    "mcp_tools": [],
+                    "mcp_results": [],
+                    "judge_results": [],
                     "blocked": True,
                 }
             return {

agent_framework_oci/Tuning-Performance/Route_Stickness/templates/agent_template_backend_day_zero/config/routing.yaml

@@ -7,6 +7,35 @@ router:
   confidence_threshold: 0.65
   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_BILLING_CONFIRMATION
     agent: billing_agent

agent_framework_oci/Tuning-Performance/Route_Stickness/templates/agent_template_backend_day_zero/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.

agent_framework_oci/Tuning-Performance/Transaction_Evidence/agent_template_backend/.env.example

@@ -14,45 +14,38 @@ CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
 # LLM - OCI Generative AI como provider principal
 ###############################################################################
 # Opções: mock, oci_openai, oci_sdk, openai_compatible
-LLM_PROVIDER=oci_sdk
+LLM_PROVIDER=oci_openai
 LLM_TEMPERATURE=0.2
 LLM_MAX_TOKENS=2048
 LLM_TIMEOUT_SECONDS=120
 
 # OCI OpenAI-compatible endpoint
-OCI_GENAI_BASE_URL=https://inference.generativeai.us-chicago-1.oci.oraclecloud.com
+OCI_GENAI_BASE_URL=https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1
 OCI_GENAI_MODEL=openai.gpt-4.1
-OCI_GENAI_API_KEY=sk-ph3FgX6iP3fxAQCXb9IpPIDTadkeeYAWntUWhzcWysIM6zsS
+OCI_GENAI_API_KEY=sk-ph3FgX6ph3FgX6ph3FgX6ph3FgX6ph3FgX6ph3FgX6
 OCI_GENAI_PROJECT_OCID=
 
-#OCI_GENAI_BASE_URL=https://pegruagntaiatenddev.pe.inference.generativeai.sa-saopaulo-1.oci.oraclecloud.com
-#OCI_GENAI_MODEL=openai.gpt-4.1
-#OCI_GENAI_API_KEY=
-#OCI_GENAI_PROJECT_OCID=
-
-
-# OCI_AUTH_MODE=config_file|instance_principal|resource_principal
-OCI_AUTH_MODE=config_file
 # OCI SDK / signer / profiles
 OCI_CONFIG_FILE=~/.oci/config
-OCI_PROFILE=LATINOAMERICA-Chicago
-OCI_COMPARTMENT_ID=ocid1.compartment.oc1..aaaaaaaaexpiw4a7dio64mkfv2t273s2hgdl6mgfvvyv7tycalnjlvpvfl3q
+OCI_PROFILE=DEFAULT
+OCI_COMPARTMENT_ID=ocid1.compartment.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
 OCI_REGION=us-chicago-1
 
 ###############################################################################
 # Persistência
 ###############################################################################
 # Opções: memory, autonomous, mongodb
-SESSION_REPOSITORY_PROVIDER=autonomous
-MEMORY_REPOSITORY_PROVIDER=autonomous
-CHECKPOINT_REPOSITORY_PROVIDER=autonomous
+SESSION_REPOSITORY_PROVIDER=sqlite
+MEMORY_REPOSITORY_PROVIDER=sqlite
+CHECKPOINT_REPOSITORY_PROVIDER=sqlite
+SQLITE_DB_PATH=./data/agent_framework.db
 
 # Autonomous Database
 ADB_USER=admin
-ADB_PASSWORD=Moniquinha19721972
-ADB_DSN=oradb23ai_high
-ADB_WALLET_LOCATION=/mnt/d/Dropbox/ORACLE/LatinoAmerica/Wallet_ORADB23ai
-ADB_WALLET_PASSWORD=Moniquinha1972
+ADB_PASSWORD=fjhsdf04954hf
+ADB_DSN=oradb23aidev_high
+ADB_WALLET_LOCATION=/ORACLE/DEFAULT/Wallet_ORADB23aiDev
+ADB_WALLET_PASSWORD=fjhsdf04954hf
 ADB_TABLE_PREFIX=AGENTFW
 
 # MongoDB - também pode representar Autonomous usando API compatível com Mongo, se habilitada no ambiente
@@ -66,10 +59,10 @@ ENABLE_REDIS_CACHE=false
 ###############################################################################
 # RAG / Vector / Graph
 ###############################################################################
-VECTOR_STORE_PROVIDER=autonomous
-GRAPH_STORE_PROVIDER=autonomous
+VECTOR_STORE_PROVIDER=sqlite
+GRAPH_STORE_PROVIDER=sqlite
 RAG_TOP_K=5
-EMBEDDING_PROVIDER=oci
+EMBEDDING_PROVIDER=mock
 OCI_EMBEDDING_MODEL=cohere.embed-multilingual-v3.0
 RAG_FILE_GLOBS=*.md,*.txt,*.yaml,*.yml,*.json
 
@@ -77,21 +70,14 @@ RAG_FILE_GLOBS=*.md,*.txt,*.yaml,*.yml,*.json
 # Observabilidade
 ###############################################################################
 ENABLE_LANGFUSE=true
- # Opcional: verbose, compact
-LANGFUSE_TRACE_MODE=compact
-# Nome customizado do trace pai, ex.: backoffice.checklist.workflow ou backoffice.emulador.workflow
-LANGFUSE_COMPACT_VISIBLE_EVENT_PREFIXES=AGA.,NOC., IC.
-LANGFUSE_COMPACT_SUPPRESSED_PREFIXES=llm.chat_completion
-LANGFUSE_IGNORE_HEALTHCHECKS=true
-LANGFUSE_IGNORED_PATHS=/health,/ready,/metrics
-LANGFUSE_PUBLIC_KEY=pk-lf-4a1e3921-5158-4fd3-a16d-7a77549fb312
-LANGFUSE_SECRET_KEY=sk-lf-efc6fd59-c5ec-4858-b6ec-4aa129734915
+LANGFUSE_TRACE_MODE=compact # Opcional: verbose, compact
+LANGFUSE_PUBLIC_KEY=pk-lf-2f9da109-5b0f-4c78-b61d-9598ed787eba
+LANGFUSE_SECRET_KEY=sk-lf-a4cb0cdd-f2ea-4468-9911-cebeb91ba944
 LANGFUSE_HOST=http://localhost:3005
 ENABLE_OTEL=false
 OTEL_EXPORTER_OTLP_ENDPOINT=
 OTEL_SERVICE_NAME=ai-agent-template
 ENABLE_LANGFUSE_OPENAI_AUTO_INSTRUMENTATION=true
-ENABLE_LANGFUSE_ANALYTICS_PUBLISHER=false
 
 ###############################################################################
 # Analytics / Observer corporativo
@@ -99,7 +85,7 @@ ENABLE_LANGFUSE_ANALYTICS_PUBLISHER=false
 # Quando true, AgentObserver publica eventos IC.*, NOC.* e GRL.* nos providers abaixo.
 ENABLE_ANALYTICS=false
 # Providers aceitos: oci_streaming,pubsub,noop
-ANALYTICS_PROVIDERS=oci_streaming
+ANALYTICS_PROVIDERS=pubsub
 # Compatibilidade FIRST/TIM: pode informar AGENT_PUBSUB_TOPIC diretamente.
 AGENT_PUBSUB_TOPIC=
 GCP_PUBSUB_TOPIC_PATH=
@@ -162,6 +148,7 @@ ROUTE_STICKINESS_HISTORY_TURNS=2
 ROUTE_STICKINESS_MAX_TOKENS=80
 HUMAN_HANDOFF_MESSAGE=Vou encaminhar seu atendimento para uma pessoa.
 END_SESSION_MESSAGE=Atendimento encerrado. Obrigado pelo contato.
+SESSION_ALREADY_ENDED_MESSAGE=Este atendimento já foi encerrado. Inicie uma nova sessão para continuar.
 
 ###############################################################################
 # MCP / Tools
@@ -169,13 +156,14 @@ END_SESSION_MESSAGE=Atendimento encerrado. Obrigado pelo contato.
 ENABLE_MCP_TOOLS=true
 MCP_SERVERS_CONFIG_PATH=./config/mcp_servers.yaml
 TOOLS_CONFIG_PATH=./config/tools.yaml
+TOOL_POLICIES_PATH=./config/tool_policies.yaml
 MCP_TOOL_TIMEOUT_SECONDS=30
 
 # router = EnterpriseRouter seleciona um agente; supervisor = pode acionar múltiplos agentes
 ROUTING_MODE=router
 
 # Usage/cost accounting
-USAGE_REPOSITORY_PROVIDER=autonomous
+USAGE_REPOSITORY_PROVIDER=sqlite
 IDENTITY_CONFIG_PATH=./config/identity.yaml
 MCP_PARAMETER_MAPPING_PATH=./config/mcp_parameter_mapping.yaml
 
@@ -192,6 +180,18 @@ MEMORY_SUMMARY_USE_LLM=true
 MEMORY_INJECT_RECENT_MESSAGES=true
 MEMORY_INJECT_SUMMARY=true
 
+###############################################################################
+# MCP Gateway
+###############################################################################
+# true = framework routes tool calls to the dedicated MCP Gateway.
+# false = framework calls MCP servers directly from mcp_servers.yaml.
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+# MCP_GATEWAY_TOKEN=
+MCP_GATEWAY_AGENT_ID=telecom_contas
+MCP_GATEWAY_TENANT_ID=default
+
 ###############################################################################
 # LONG-TERM MEMORY
 ###############################################################################

agent_framework_oci/Tuning-Performance/Transaction_Evidence/agent_template_backend/app/workflows/agent_graph.py

@@ -160,7 +160,7 @@ class AgentWorkflow:
         builder.add_conditional_edges(
             "input_guardrails",
             self._after_input_guardrails,
-            {"blocked": "persist", "continue": "load_long_term_memory"},
+            {"blocked": "output_guardrails", "continue": "load_long_term_memory"},
         )
         builder.add_edge("load_long_term_memory", "routing_decision")
         builder.add_conditional_edges(
@@ -197,6 +197,31 @@ class AgentWorkflow:
     def _after_input_guardrails(self, state):
         return "blocked" if state.get("blocked") else "continue"
 
+    @staticmethod
+    def _input_guardrail_user_message(decisions, state, sanitized_text):
+        # Keep the technical guardrail reason in telemetry, but expose only a
+        # safe, actionable message to the end user. The message is intentionally
+        # routed through output_guardrails before persistence/delivery.
+        blocked = [d for d in decisions if not getattr(d, "allowed", True)]
+        first = blocked[0] if blocked else None
+        code = str(getattr(first, "code", "") or "").upper()
+        if code == "COER":
+            return (
+                "Não consegui entender sua última mensagem porque ela parece "
+                "incompleta ou ambígua. Pode reformular ou completar o que você quis dizer?"
+            )
+        if code == "INPUT_SIZE":
+            return "Sua mensagem ficou muito longa para eu processar de uma vez. Pode resumir ou dividir em partes?"
+        if code == "DLEX_IN":
+            return "Não posso usar essa informação da forma solicitada. Reformule o pedido sem incluir dados ou conteúdo restrito."
+        if code == "PINJ":
+            return "Não posso seguir instruções que tentem alterar as regras do atendimento. Posso continuar ajudando com a sua solicitação."
+        if code == "TOX":
+            return "Não consegui prosseguir com essa mensagem. Pode reformular o pedido para continuarmos o atendimento?"
+        if code == "CMP":
+            return "Não posso prosseguir com essa solicitação dessa forma. Posso ajudar com uma alternativa permitida."
+        return "Não consegui processar essa mensagem. Pode reformular para eu continuar o atendimento?"
+
     async def input_guardrails(self, state):
         if state.get("session_ended") is True:
             answer = str(getattr(
@@ -281,12 +306,33 @@ class AgentWorkflow:
                 component="workflow.input_guardrails.final",
             )
             if any(not d.allowed for d in decisions):
+                # A blocking input guardrail stops the turn before routing/tools.
+                # Clear turn-local routing/tool state so stale data from a prior
+                # turn cannot appear as if it was executed after the block.
+                user_message = self._input_guardrail_user_message(decisions, state, sanitized)
                 return {
                     "sanitized_input": sanitized,
-                    "answer": "Não consegui seguir com essa mensagem por regra de segurança.",
-                    "final_answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "answer": user_message,
+                    "final_answer": None,
                     "guardrail_decisions": [d.model_dump() for d in decisions],
                     "route": "blocked",
+                    "intent": "input_guardrail_blocked",
+                    "route_decision": {
+                        "route": "blocked",
+                        "agent": None,
+                        "intent": "input_guardrail_blocked",
+                        "confidence": 1.0,
+                        "reason": "Entrada interrompida por guardrail antes do roteamento.",
+                        "method": "guardrail",
+                        "next_state": state.get("next_state"),
+                        "handoff": False,
+                        "metadata": {},
+                        "domain": state.get("domain"),
+                        "mcp_tools": [],
+                    },
+                    "mcp_tools": [],
+                    "mcp_results": [],
+                    "judge_results": [],
                     "blocked": True,
                 }
             return {

agent_framework_oci/Tuning-Performance/Transaction_Evidence/agent_template_backend/config/routing.yaml

@@ -7,6 +7,35 @@ router:
   confidence_threshold: 0.65
   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_BILLING_CONFIRMATION
     agent: billing_agent

agent_framework_oci/Tuning-Performance/Transaction_Evidence/agent_template_backend/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.

agent_framework_oci/Tuning-Performance/Transaction_Pre_Validation/agent_template_backend/app/workflows/agent_graph.py

@@ -160,7 +160,7 @@ class AgentWorkflow:
         builder.add_conditional_edges(
             "input_guardrails",
             self._after_input_guardrails,
-            {"blocked": "persist", "continue": "load_long_term_memory"},
+            {"blocked": "output_guardrails", "continue": "load_long_term_memory"},
         )
         builder.add_edge("load_long_term_memory", "routing_decision")
         builder.add_conditional_edges(
@@ -197,6 +197,31 @@ class AgentWorkflow:
     def _after_input_guardrails(self, state):
         return "blocked" if state.get("blocked") else "continue"
 
+    @staticmethod
+    def _input_guardrail_user_message(decisions, state, sanitized_text):
+        # Keep the technical guardrail reason in telemetry, but expose only a
+        # safe, actionable message to the end user. The message is intentionally
+        # routed through output_guardrails before persistence/delivery.
+        blocked = [d for d in decisions if not getattr(d, "allowed", True)]
+        first = blocked[0] if blocked else None
+        code = str(getattr(first, "code", "") or "").upper()
+        if code == "COER":
+            return (
+                "Não consegui entender sua última mensagem porque ela parece "
+                "incompleta ou ambígua. Pode reformular ou completar o que você quis dizer?"
+            )
+        if code == "INPUT_SIZE":
+            return "Sua mensagem ficou muito longa para eu processar de uma vez. Pode resumir ou dividir em partes?"
+        if code == "DLEX_IN":
+            return "Não posso usar essa informação da forma solicitada. Reformule o pedido sem incluir dados ou conteúdo restrito."
+        if code == "PINJ":
+            return "Não posso seguir instruções que tentem alterar as regras do atendimento. Posso continuar ajudando com a sua solicitação."
+        if code == "TOX":
+            return "Não consegui prosseguir com essa mensagem. Pode reformular o pedido para continuarmos o atendimento?"
+        if code == "CMP":
+            return "Não posso prosseguir com essa solicitação dessa forma. Posso ajudar com uma alternativa permitida."
+        return "Não consegui processar essa mensagem. Pode reformular para eu continuar o atendimento?"
+
     async def input_guardrails(self, state):
         if state.get("session_ended") is True:
             answer = str(getattr(
@@ -281,12 +306,33 @@ class AgentWorkflow:
                 component="workflow.input_guardrails.final",
             )
             if any(not d.allowed for d in decisions):
+                # A blocking input guardrail stops the turn before routing/tools.
+                # Clear turn-local routing/tool state so stale data from a prior
+                # turn cannot appear as if it was executed after the block.
+                user_message = self._input_guardrail_user_message(decisions, state, sanitized)
                 return {
                     "sanitized_input": sanitized,
-                    "answer": "Não consegui seguir com essa mensagem por regra de segurança.",
-                    "final_answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "answer": user_message,
+                    "final_answer": None,
                     "guardrail_decisions": [d.model_dump() for d in decisions],
                     "route": "blocked",
+                    "intent": "input_guardrail_blocked",
+                    "route_decision": {
+                        "route": "blocked",
+                        "agent": None,
+                        "intent": "input_guardrail_blocked",
+                        "confidence": 1.0,
+                        "reason": "Entrada interrompida por guardrail antes do roteamento.",
+                        "method": "guardrail",
+                        "next_state": state.get("next_state"),
+                        "handoff": False,
+                        "metadata": {},
+                        "domain": state.get("domain"),
+                        "mcp_tools": [],
+                    },
+                    "mcp_tools": [],
+                    "mcp_results": [],
+                    "judge_results": [],
                     "blocked": True,
                 }
             return {

agent_framework_oci/Tuning-Performance/Transaction_Pre_Validation/agent_template_backend/config/routing.yaml

@@ -7,6 +7,35 @@ router:
   confidence_threshold: 0.65
   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_BILLING_CONFIRMATION
     agent: billing_agent

agent_framework_oci/Tuning-Performance/Transaction_Pre_Validation/agent_template_backend/docs/TRANSACTION_SEMANTIC_CONFIRMATION.md

@@ -0,0 +1,11 @@
+# Confirmação Transacional Semântica
+
+Este template suporta confirmação transacional em duas camadas: primeiro um parser determinístico para `sim`/`não` e equivalentes explícitos; somente quando ele não consegue decidir, o framework usa um classificador semântico configurado em `config/routing.yaml`.
+
+A configuração `router.transaction_confirmation.semantic_fallback` usa três classes: `SIM`, `NAO` e `CONTINUAR`. O prompt pode usar `{{ pending_prompt }}`, `{{ relevant_conversation_context }}`, `{{ user_input }}` e `{{ allowed_values }}`. O histórico injetado é apenas contexto de interpretação; não substitui validação de negócio ou evidência MCP.
+
+Exemplo: após `Você confirma o cancelamento do serviço Tamboro Mensal?`, a frase `isso mesmo, pode confirmar` pode ser classificada como `SIM`. Já `mas qual é o valor?` deve ser `CONTINUAR`, portanto não executa a ação por confirmação.
+
+Entradas explícitas já suportadas continuam no caminho determinístico e não geram custo adicional de LLM. Em observabilidade, o fallback usa `transaction.confirmation.semantic_classifier` e o `route_decision.metadata` informa `transaction_confirmation_source: semantic`.
+
+Consulte `docs/developer/pt/03_transaction_workflows_and_state.md` do framework para o contrato completo e exemplos.