New features: Route Stickness, Handoff, Clarification, Read-Only/Transactional, Long Term Memory

libs/agent_framework/config/llm_profiles.yaml

@@ -15,6 +15,17 @@ profiles:
     temperature: 0
     max_tokens: 700
 
+
+  # Lightweight semantic continuity classifier. Choose the smallest/fastest
+  # model approved for the environment. The framework references this profile
+  # through ROUTE_STICKINESS_LLM_PROFILE.
+  route_continuity:
+    provider: oci_openai
+    model: openai.gpt-4.1-mini
+    temperature: 0
+    max_tokens: 80
+    timeout_seconds: 5
+
   router:
     provider: oci_openai
     model: openai.gpt-4.1

libs/agent_framework/config/mcp_parameter_mapping.yaml

@@ -8,17 +8,16 @@ mcp_parameter_mapping:
         contract_key: invoice_id
         interaction_key: ura_call_id
         session_key: session_id
-
       extract:
         parametro_externo:
           from: message
           type: string
           strategy: llm
-          description: >
-            Extraia da mensagem do usuário o valor necessário para o parâmetro
-            parametro_externo. Retorne null quando a informação não estiver
-            presente no texto.
+          description: 'Extraia da mensagem do usuário o valor necessário para o parâmetro
+            parametro_externo. Retorne null quando a informação não estiver presente
+            no texto.
 
+            '
     consultar_pagamentos:
       map:
         customer_key: msisdn
@@ -37,24 +36,52 @@ mcp_parameter_mapping:
     consultar_pedido:
       map:
         customer_key: customer_id
-        contract_key: order_id
         session_key: session_id
+      extract:
+        order_id:
+          from: message
+          type: string
+          strategy: llm
+          description: Extraia somente o identificador do pedido informado explicitamente
+            pelo usuário. Retorne null quando não houver identificador de pedido na
+            mensagem.
     consultar_entrega:
       map:
-        contract_key: order_id
         session_key: session_id
+      extract:
+        order_id:
+          from: message
+          type: string
+          strategy: llm
+          description: Extraia somente o identificador do pedido informado explicitamente
+            pelo usuário. Retorne null quando não houver identificador de pedido na
+            mensagem.
     solicitar_troca:
       map:
-        contract_key: order_id
         session_key: session_id
       defaults:
         reason: Solicitação aberta pelo atendimento conversacional.
+      extract:
+        order_id:
+          from: message
+          type: string
+          strategy: llm
+          description: Extraia somente o identificador do pedido informado explicitamente
+            pelo usuário. Retorne null quando não houver identificador de pedido na
+            mensagem.
     solicitar_devolucao:
       map:
-        contract_key: order_id
         session_key: session_id
       defaults:
         reason: Solicitação aberta pelo atendimento conversacional.
+      extract:
+        order_id:
+          from: message
+          type: string
+          strategy: llm
+          description: Extraia somente o identificador do pedido informado explicitamente
+            pelo usuário. Retorne null quando não houver identificador de pedido na
+            mensagem.
     consultar_titulo_financeiro:
       map:
         customer_key: customer_id

libs/agent_framework/config/tools.yaml

@@ -68,7 +68,7 @@ tools:
     enabled: true
     tool_type: action
     requires: [order_id, reason]
-    confirmation_required: false
+    confirmation_required: true
     cache:
       enabled: false
     args_schema:
@@ -81,7 +81,7 @@ tools:
     enabled: true
     tool_type: action
     requires: [order_id, reason]
-    confirmation_required: false
+    confirmation_required: true
     cache:
       enabled: false
     args_schema:

libs/agent_framework/docs/MCP_CACHE.md

@@ -202,3 +202,6 @@ IC.TOOL_CALLED cached=true
 ```
 
 Quando houver `IC.MCP_CACHE_HIT`, não deve aparecer `IC.MCP_TOOL_EXECUTING` nem `IC.MCP_TOOL_EXECUTED`, porque o MCP Server não foi chamado.
+# Relação com políticas de execução
+
+Cache e política operacional são independentes. Classifique consultas e transações no arquivo opcional `config/tool_policies.yaml` do backend; mantenha `cache` no catálogo `tools.yaml`. Operações transacionais não devem ser cacheadas. Se o arquivo novo não existir, os campos legados de execução em `tools.yaml` continuam válidos.

libs/agent_framework/docs/MCP_PARAMETER_EXTRACTION.md

@@ -173,3 +173,39 @@ O framework deve executar extração somente quando:
 ```
 
 Sem `extract` declarado, nada é extraído.
+
+## Precedência dos valores
+
+A partir desta correção, a precedência efetiva é:
+
+```text
+1. argumento explícito já presente na tool call;
+2. valor extraído da mensagem pelo bloco extract;
+3. valor proveniente do Business Context via map;
+4. defaults globais ou específicos da tool.
+```
+
+O Business Context nunca sobrescreve um argumento explícito ou extraído. Para
+identificadores que obrigatoriamente vêm da mensagem, como `order_id`, não
+configure `contract_key: order_id`.
+
+Exemplo recomendado:
+
+```yaml
+consultar_pedido:
+  map:
+    customer_key: customer_id
+    session_key: session_id
+  extract:
+    order_id:
+      from: message
+      type: string
+      strategy: llm
+      description: >
+        Extraia somente o identificador do pedido informado explicitamente pelo
+        usuário. Retorne null quando não houver identificador.
+```
+
+A extração usa a generation `llm.mcp_parameter_extraction` e o profile
+`mcp_parameter_extraction`. Identificadores devem preferencialmente usar
+`type: string` para preservar zeros à esquerda, hífens e prefixos.

libs/agent_framework/src/agent_framework/config/settings.py

@@ -102,6 +102,7 @@ class Settings(BaseSettings):
     ORACLE_GRAPH_NAME: str = 'AGENTFW_GRAPH'
     ORACLE_GRAPH_AUTO_CREATE: bool = False
     RAG_TOP_K: int = 5
+    SKIP_RAG_WHEN_MCP_SUFFICIENT: bool = True
     ENABLE_RAG_QUERY_REWRITE: bool = False
     ENABLE_RAG_CONTEXT_COMPRESSION: bool = False
     ENABLE_RAG_GENERATION: bool = False
@@ -173,6 +174,15 @@ class Settings(BaseSettings):
     ROUTING_CONFIG_PATH: str = './config/routing.yaml'
     ENABLE_LLM_ROUTER: bool = False
     ROUTING_MODE: Literal['router','supervisor'] = 'router'
+    # Semantic route stickiness. Uses an LLM profile; no regex or language rules.
+    ENABLE_ROUTE_STICKINESS: bool = False
+    ROUTE_STICKINESS_LLM_PROFILE: str = 'route_continuity'
+    ROUTE_STICKINESS_CONFIDENCE_THRESHOLD: float = 0.90
+    ROUTE_STICKINESS_HISTORY_TURNS: int = 2
+    ROUTE_STICKINESS_MAX_TOKENS: int = 80
+    HUMAN_HANDOFF_MESSAGE: str = 'Vou encaminhar seu atendimento para uma pessoa.'
+    END_SESSION_MESSAGE: str = 'Atendimento encerrado. Obrigado pelo contato.'
+    SESSION_ALREADY_ENDED_MESSAGE: str = 'Este atendimento já foi encerrado. Inicie uma nova sessão para continuar.'
 
     # MCP / Tooling
     ENABLE_MCP_TOOLS: bool = True
@@ -180,6 +190,8 @@ class Settings(BaseSettings):
     MCP_CACHE_TTL_SECONDS: int = 300
     MCP_SERVERS_CONFIG_PATH: str = './config/mcp_servers.yaml'
     TOOLS_CONFIG_PATH: str = './config/tools.yaml'
+    # Opcional. Se ausente, permanecem válidas as políticas legadas de tools.yaml.
+    TOOL_POLICIES_PATH: str | None = './config/tool_policies.yaml'
     IDENTITY_CONFIG_PATH: str = './config/identity.yaml'
     MCP_PARAMETER_MAPPING_PATH: str = './config/mcp_parameter_mapping.yaml'
     MCP_TOOL_TIMEOUT_SECONDS: int = 30