new feature: mcp pre-validation

templates/agent_template_backend/.env

@@ -0,0 +1,207 @@
+###############################################################################
+# AI AGENT PLATFORM - CONFIGURAÇÃO ÚNICA
+# Este arquivo é lido por Pydantic Settings no framework e no backend template.
+###############################################################################
+
+APP_NAME=ai-agent-template
+APP_ENV=local
+LOG_LEVEL=INFO
+API_HOST=0.0.0.0
+API_PORT=8000
+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_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_MODEL=openai.gpt-4.1
+OCI_GENAI_API_KEY=sk-ph3FgX6iP3fxAQCXb9IpPIDTadkeeYAWntUWhzcWysIM6zsS
+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_REGION=us-chicago-1
+
+###############################################################################
+# Persistência
+###############################################################################
+# Opções: memory, autonomous, mongodb
+SESSION_REPOSITORY_PROVIDER=autonomous
+MEMORY_REPOSITORY_PROVIDER=autonomous
+CHECKPOINT_REPOSITORY_PROVIDER=autonomous
+
+# 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_TABLE_PREFIX=AGENTFW
+
+# MongoDB - também pode representar Autonomous usando API compatível com Mongo, se habilitada no ambiente
+MONGODB_URI=mongodb://mongo:mongopassword@localhost:27017
+MONGODB_DATABASE=agent_platform
+
+# Redis
+REDIS_URL=redis://localhost:6379/0
+ENABLE_REDIS_CACHE=false
+
+###############################################################################
+# RAG / Vector / Graph
+###############################################################################
+VECTOR_STORE_PROVIDER=autonomous
+GRAPH_STORE_PROVIDER=autonomous
+RAG_TOP_K=5
+EMBEDDING_PROVIDER=oci
+OCI_EMBEDDING_MODEL=cohere.embed-multilingual-v3.0
+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_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
+###############################################################################
+# 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
+# Compatibilidade FIRST/TIM: pode informar AGENT_PUBSUB_TOPIC diretamente.
+AGENT_PUBSUB_TOPIC=
+GCP_PUBSUB_TOPIC_PATH=
+GCP_PROJECT_ID=
+GCP_PUBSUB_TOPIC=
+GCP_PUBSUB_TIMEOUT_SECONDS=30
+# Credencial GCP segue padrão Google:
+# GOOGLE_APPLICATION_CREDENTIALS=/secrets/gcp-service-account.json
+
+###############################################################################
+# OCI Streaming
+###############################################################################
+ENABLE_OCI_STREAMING=false
+OCI_STREAM_ENDPOINT=
+OCI_STREAM_OCID=
+OCI_STREAM_PARTITION_KEY=agent-events
+
+###############################################################################
+# Guardrails, Judges, Supervisor
+###############################################################################
+ENABLE_INPUT_GUARDRAILS=true
+ENABLE_OUTPUT_GUARDRAILS=true
+ENABLE_JUDGES=true
+ENABLE_SUPERVISOR=true
+ENABLE_OUTPUT_SUPERVISOR=true
+ENABLE_PARALLEL_GUARDRAILS=true
+GUARDRAILS_FAIL_FAST=true
+OUTPUT_SUPERVISOR_MAX_RETRIES=3
+GUARDRAILS_CONFIG_PATH=./config/guardrails.yaml
+JUDGES_CONFIG_PATH=./config/judges.yaml
+PROMPT_POLICY_PATH=./config/prompt_policy.yaml
+
+###############################################################################
+# Gateway de canais
+###############################################################################
+DEFAULT_CHANNEL=web
+# embedded = backend may parse simple/native channel payloads.
+# external = backend only accepts GatewayRequest normalized by an external Channel Gateway.
+FRAMEWORK_CHANNEL_INPUT_MODE=embedded
+ENABLE_VOICE_ADAPTER=true
+ENABLE_WHATSAPP_ADAPTER=true
+ENABLE_TEXT_ADAPTER=true
+
+#################################################
+# ENTERPRISE ROUTING
+#################################################
+# Arquivo YAML com intents, keywords, políticas de estado e fallback.
+ROUTING_CONFIG_PATH=./config/routing.yaml
+# true = usa LLM para classificar quando keywords/estado não resolverem.
+# Em produção, costuma ser útil; em desenvolvimento, false evita custo e latência.
+ENABLE_LLM_ROUTER=true
+
+# Semantic route stickiness (optional).
+# Uses a lightweight LLM profile to decide only CONTINUE vs ROUTE.
+# There are no regexes or deterministic language rules.
+ENABLE_ROUTE_STICKINESS=true
+ROUTE_STICKINESS_LLM_PROFILE=route_continuity
+ROUTE_STICKINESS_CONFIDENCE_THRESHOLD=0.90
+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.
+
+###############################################################################
+# MCP / Tools
+###############################################################################
+ENABLE_MCP_TOOLS=true
+MCP_SERVERS_CONFIG_PATH=./config/mcp_servers.yaml
+TOOLS_CONFIG_PATH=./config/tools.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
+IDENTITY_CONFIG_PATH=./config/identity.yaml
+MCP_PARAMETER_MAPPING_PATH=./config/mcp_parameter_mapping.yaml
+
+# -----------------------------------------------------------------------------
+# ConversationSummaryMemory / compressão de contexto conversacional
+# -----------------------------------------------------------------------------
+ENABLE_CONVERSATION_SUMMARY_MEMORY=true
+MEMORY_CONTEXT_STRATEGY=summary
+MEMORY_HISTORY_LIMIT=80
+MEMORY_RECENT_MESSAGES_LIMIT=8
+MEMORY_SUMMARY_TRIGGER_MESSAGES=20
+MEMORY_MAX_SUMMARY_CHARS=6000
+MEMORY_SUMMARY_USE_LLM=true
+MEMORY_INJECT_RECENT_MESSAGES=true
+MEMORY_INJECT_SUMMARY=true
+
+###############################################################################
+# LONG-TERM MEMORY
+###############################################################################
+ENABLE_LONG_TERM_MEMORY=true
+LONG_TERM_MEMORY_PROVIDER=sqlite
+LONG_TERM_MEMORY_SQLITE_PATH=./data/agent_framework.db
+LONG_TERM_MEMORY_TABLE=agentfw_long_term_memory
+# For Autonomous/Oracle, defaults to ${ADB_TABLE_PREFIX}_LONG_TERM_MEMORY
+# LONG_TERM_MEMORY_ORACLE_TABLE=AGENTFW_LONG_TERM_MEMORY
+LONG_TERM_MEMORY_MAX_CONTEXT_ITEMS=20
+LONG_TERM_MEMORY_MIN_CONFIDENCE=0.70
+LONG_TERM_MEMORY_AUTO_EXTRACT=true
+LONG_TERM_MEMORY_INJECT_CONTEXT=true

templates/agent_template_backend/app/main.py

@@ -461,6 +461,7 @@ async def _process_gateway_message(req: GatewayRequest, emit_sse: bool = False)
                     "mcp_tools": result.get("mcp_tools"),
                     "mcp_results": result.get("mcp_results"),
                     "transaction_evidence": result.get("relevant_transaction_evidence", []),
+                    "transaction_pre_validation": result.get("transaction_pre_validation"),
                     "business_context": business_context.model_dump(),
                     "identity_missing": missing_identity_keys,
                     "judges": result.get("judge_results"),

templates/agent_template_backend/app/state.py

@@ -27,6 +27,7 @@ class AgentState(TypedDict, total=False):
     selected_tool_call: dict[str, Any]
     pending_tool_call: dict[str, Any]
     transaction_status: str
+    transaction_pre_validation: dict[str, Any]
     transaction_evidence: list[dict[str, Any]]
     last_transaction_evidence: dict[str, Any]
     relevant_transaction_evidence: list[dict[str, Any]]

templates/agent_template_backend/config/mcp_parameter_mapping.yaml

@@ -60,6 +60,10 @@ mcp_parameter_mapping:
             mensagem.
           pattern: (?i)\\b(?:pedido|order)\\s*[:#-]?\\s*([A-Z0-9-]+)\\b
           group: 1
+    validar_cancelamento_pedido:
+      map:
+        resource_key: order_id
+
     cancelar_pedido:
       map:
         session_key: session_id

templates/agent_template_backend/config/tool_policies.yaml

@@ -11,6 +11,10 @@ tool_policies:
     operation_type: transactional
     require_confirmation: true
     requires: [order_id]
+    pre_validation:
+      enabled: true
+      tool: validar_cancelamento_pedido
+      fail_open: false
 
 
   solicitar_troca:

templates/agent_template_backend/config/tools.yaml

@@ -73,6 +73,18 @@ tools:
     response:
       mode: renderer
       renderer: retail.delivery
+  validar_cancelamento_pedido:
+    description: Pre-valida cancelamento do pedido sem executar efeitos transacionais.
+    mcp_server: retail
+    enabled: true
+    tool_type: internal
+    confirmation_required: false
+    requires: [order_id]
+    args_schema:
+      order_id: string
+      target_tool: string
+    selection_keywords: []
+
   cancelar_pedido:
     description: Simula o cancelamento de um pedido de varejo.
     mcp_server: retail

templates/agent_template_backend_day_zero/app/state.py

@@ -27,6 +27,7 @@ class AgentState(TypedDict, total=False):
     selected_tool_call: dict[str, Any]
     pending_tool_call: dict[str, Any]
     transaction_status: str
+    transaction_pre_validation: dict[str, Any]
     confirmation_required: bool
     confirmation_received: bool
     tool_policy_result: dict[str, Any]

templates/agent_template_backend_day_zero/config/mcp_parameter_mapping.yaml

@@ -60,6 +60,10 @@ mcp_parameter_mapping:
             mensagem.
           pattern: (?i)\\b(?:pedido|order)\\s*[:#-]?\\s*([A-Z0-9-]+)\\b
           group: 1
+    validar_cancelamento_pedido:
+      map:
+        resource_key: order_id
+
     cancelar_pedido:
       map:
         session_key: session_id

templates/agent_template_backend_day_zero/config/tool_policies.yaml

@@ -11,6 +11,10 @@ tool_policies:
     operation_type: transactional
     require_confirmation: true
     requires: [order_id]
+    pre_validation:
+      enabled: true
+      tool: validar_cancelamento_pedido
+      fail_open: false
 
 
   solicitar_troca:

templates/agent_template_backend_day_zero/config/tools.yaml

@@ -61,6 +61,18 @@ tools:
     - rastreamento
     - transportadora
     - previsão
+  validar_cancelamento_pedido:
+    description: Pre-valida cancelamento do pedido sem executar efeitos transacionais.
+    mcp_server: retail
+    enabled: true
+    tool_type: internal
+    confirmation_required: false
+    requires: [order_id]
+    args_schema:
+      order_id: string
+      target_tool: string
+    selection_keywords: []
+
   cancelar_pedido:
     description: Simula o cancelamento de um pedido de varejo.
     mcp_server: retail