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

tests/test_judge_transaction_sampling.py

@@ -0,0 +1,60 @@
+import asyncio
+from types import SimpleNamespace
+
+from agent_framework.judges.judge import JudgePipeline, JudgeResult
+
+
+class DummyJudge:
+    async def evaluate(self, question, answer, context):
+        return JudgeResult(name="dummy", score=1.0, passed=True, reason="ran")
+
+
+def pipeline(*, sample_rate=0.0, always=True):
+    obj = object.__new__(JudgePipeline)
+    obj.enabled = True
+    obj.judges = [DummyJudge()]
+    obj.sample_rate = sample_rate
+    obj.always_run_for_transactional = always
+    return obj
+
+
+def test_awaiting_confirmation_bypasses_sampling():
+    p = pipeline(sample_rate=0.0, always=True)
+    results = asyncio.run(p.evaluate_all("devolver", "confirma?", {
+        "transaction_status": "AWAITING_CONFIRMATION",
+        "mcp_results": [{
+            "tool_name": "solicitar_devolucao",
+            "awaiting_confirmation": True,
+            "transaction_status": "AWAITING_CONFIRMATION",
+            "metadata": {"operation_type": "transactional"},
+        }],
+    }))
+    assert len(results) == 1
+
+
+def test_completed_transaction_bypasses_sampling_from_mcp_result():
+    p = pipeline(sample_rate=0.0, always=True)
+    results = asyncio.run(p.evaluate_all("sim", "protocolo DEV-1", {
+        "mcp_results": [{
+            "tool_name": "solicitar_devolucao",
+            "ok": True,
+            "metadata": {"operation_type": "transactional"},
+        }],
+    }))
+    assert len(results) == 1
+
+
+def test_non_transactional_turn_respects_zero_sample_rate():
+    p = pipeline(sample_rate=0.0, always=True)
+    results = asyncio.run(p.evaluate_all("pedido 123", "entregue", {
+        "mcp_results": [{"tool_name": "consultar_pedido", "ok": True}],
+    }))
+    assert results == []
+
+
+def test_transactional_detection_from_tool_policy():
+    p = pipeline(sample_rate=0.0, always=True)
+    results = asyncio.run(p.evaluate_all("sim", "feito", {
+        "tool_policy_result": {"operation_type": "transactional"},
+    }))
+    assert len(results) == 1

tests/test_mcp_parameter_extraction_runtime.py

@@ -0,0 +1,61 @@
+import pytest
+from agent_framework.identity.mcp_mapper import MCPParameterMapper
+from agent_framework.runtime.agent_runtime import AgentRuntimeMixin
+
+
+def test_explicit_order_id_has_precedence_over_contract_key():
+    mapper = MCPParameterMapper({
+        "mcp_parameter_mapping": {
+            "tools": {
+                "consultar_pedido": {
+                    "map": {"contract_key": "order_id", "customer_key": "customer_id"},
+                    "extract": {"order_id": {"from": "message", "strategy": "llm", "type": "string"}},
+                }
+            }
+        }
+    })
+    mapped = mapper.map(
+        "consultar_pedido",
+        {"contract_key": "3000131180", "customer_key": "11999999999"},
+        extra_args={"order_id": "123"},
+    )
+    assert mapped["order_id"] == "123"
+    assert mapped["customer_id"] == "11999999999"
+    assert "extract" not in mapped
+
+
+class _FakeLLM:
+    async def ainvoke(self, messages, **kwargs):
+        assert "consultar pedido 123" in messages[0]["content"]
+        assert kwargs["generation_name"] == "llm.mcp_parameter_extraction"
+        return {"content": '{"order_id": "123"}'}
+
+
+class _FakeRouter:
+    def parameter_extract_rules(self, tool_name):
+        return {
+            "order_id": {
+                "from": "message",
+                "strategy": "llm",
+                "type": "string",
+                "description": "Extraia o identificador do pedido.",
+            }
+        }
+
+
+class _Runtime(AgentRuntimeMixin):
+    def __init__(self):
+        self.tool_router = _FakeRouter()
+        self.llm = _FakeLLM()
+
+
+@pytest.mark.asyncio
+async def test_runtime_extracts_order_id_from_current_message():
+    runtime = _Runtime()
+    result = await runtime._extract_mcp_parameters(
+        "consultar_pedido",
+        {"contract_key": "3000131180"},
+        {"user_text": "consultar pedido 123", "sanitized_input": "consultar pedido 123"},
+    )
+    assert result["order_id"] == "123"
+    assert result["contract_key"] == "3000131180"

tests/test_performance_optimizations.py

@@ -0,0 +1,50 @@
+import asyncio
+from types import SimpleNamespace
+from agent_framework.runtime.agent_runtime import AgentRuntimeMixin
+
+class Registry:
+    def __init__(self):
+        self.items={
+            'consultar_pedido': SimpleNamespace(selection_keywords=['pedido','status do pedido']),
+            'consultar_entrega': SimpleNamespace(selection_keywords=['entrega','rastreio']),
+        }
+    def get_tool(self,name): return self.items.get(name)
+
+class Router:
+    registry=Registry()
+    def parameter_extract_rules(self, tool):
+        return {'order_id': {'from':'message','type':'string','strategy':'hybrid','pattern':r'(?i)\bpedido\s+([A-Z0-9-]+)\b','group':1}}
+
+class Runtime(AgentRuntimeMixin):
+    tool_router=Router()
+    llm=None
+    settings=SimpleNamespace(SKIP_RAG_WHEN_MCP_SUFFICIENT=True)
+
+
+def test_selects_only_relevant_read_only_tool():
+    r=Runtime()
+    assert r._select_read_only_tools(['consultar_pedido','consultar_entrega'],'consultar pedido 123') == ['consultar_pedido']
+    assert r._select_read_only_tools(['consultar_pedido','consultar_entrega'],'rastreio da entrega 123') == ['consultar_entrega']
+
+
+def test_hybrid_regex_does_not_require_llm():
+    r=Runtime()
+    state={'user_text':'consultar pedido 123','sanitized_input':'consultar pedido 123','context':{},'business_context':{}}
+    out=asyncio.run(r._extract_mcp_parameters('consultar_pedido',{},state))
+    assert out['order_id']=='123'
+
+
+def test_direct_answer_is_blocked_for_transactional_request():
+    runtime = object.__new__(AgentRuntimeMixin)
+    registry = SimpleNamespace(
+        tools={"consultar_pedido": object(), "solicitar_devolucao": object()},
+        get_tool=lambda name: {
+            "consultar_pedido": SimpleNamespace(selection_keywords=["pedido"]),
+            "solicitar_devolucao": SimpleNamespace(selection_keywords=["devolver pedido", "devolver", "devolução"]),
+        }.get(name),
+    )
+    runtime.tool_router = SimpleNamespace(registry=registry)
+    runtime._resolve_tool_execution_policy = lambda name, args=None: {"operation_type": "transactional" if name == "solicitar_devolucao" else "read_only"}
+    state = {"user_text": "Quero devolver o pedido 123"}
+    results = [{"ok": True, "tool_name": "consultar_pedido", "result": {"order_id": "123", "status": "ENTREGUE"}}]
+    assert runtime.build_direct_mcp_answer(state, results, agent_label="OrdersAgent") is None

tests/test_route_stickiness_transaction_shift.py

@@ -0,0 +1,14 @@
+from types import SimpleNamespace
+
+from agent_framework.routing.enterprise_router import EnterpriseRouter
+from agent_framework.routing.models import RouteDecision
+
+
+def test_explicit_keyword_shift_preempts_stickiness():
+    d = RouteDecision(route="support_agent", agent="support_agent", intent="retail_support_exchange_return", method="keyword", metadata={"matched_keyword": "devolver pedido"})
+    assert EnterpriseRouter._is_explicit_intent_shift(d) is True
+
+
+def test_short_generic_keyword_does_not_preempt():
+    d = RouteDecision(route="x", agent="x", intent="x", method="keyword", metadata={"matched_keyword": "id"})
+    assert EnterpriseRouter._is_explicit_intent_shift(d) is False

tests/test_transactional_tool_flow.py

@@ -0,0 +1,90 @@
+from pathlib import Path
+
+from agent_framework.mcp.tool_policy import ToolPolicyRegistry
+
+
+def test_tool_policy_registry_reads_transactional_confirmation(tmp_path: Path):
+    config = tmp_path / "tool_policies.yaml"
+    config.write_text("""version: 1
+defaults:
+  operation_type: read_only
+  require_confirmation: false
+tool_policies:
+  solicitar_devolucao:
+    operation_type: transactional
+    require_confirmation: true
+""", encoding="utf-8")
+    policy = ToolPolicyRegistry(str(config)).get("solicitar_devolucao")
+    assert policy is not None
+    assert policy.operation_type == "transactional"
+    assert policy.require_confirmation is True
+
+
+def test_runtime_source_contains_persisted_confirmation_contract():
+    source = Path("libs/agent_framework/src/agent_framework/runtime/agent_runtime.py").read_text(encoding="utf-8")
+    assert "pending_tool_call" in source
+    assert "AWAITING_CONFIRMATION" in source
+    assert "executed_after_confirmation" in source
+
+import pytest
+from agent_framework.runtime.agent_runtime import AgentRuntimeMixin
+
+
+class _PolicyRouter:
+    def __init__(self):
+        from types import SimpleNamespace
+        self.registry = SimpleNamespace(
+            tools={"consultar_pedido": object(), "solicitar_devolucao": object()},
+            get_tool=lambda name: {
+                "consultar_pedido": SimpleNamespace(selection_keywords=["consultar pedido", "pedido"]),
+                "solicitar_devolucao": SimpleNamespace(selection_keywords=["devolver pedido", "devolver", "devolução", "arrependimento"]),
+            }.get(name),
+        )
+
+    def resolve_execution_policy(self, tool_name, arguments=None):
+        if tool_name == "solicitar_devolucao":
+            return {"operation_type": "transactional", "require_confirmation": True, "policy_source": "test"}
+        return {"operation_type": "read_only", "require_confirmation": False, "policy_source": "test"}
+
+    def validate_execution_policy(self, tool_name, arguments=None):
+        policy = self.resolve_execution_policy(tool_name, arguments)
+        if policy["require_confirmation"] and not (arguments or {}).get("confirmed"):
+            return False, "Tool exige confirmação explícita antes da execução", policy
+        return True, None, policy
+
+
+class _Runtime(AgentRuntimeMixin):
+    def __init__(self):
+        self.tool_router = _PolicyRouter()
+        self.calls = []
+
+    async def _call_mcp_tool(self, tool_name, arguments, state):
+        self.calls.append((tool_name, dict(arguments)))
+        return {"ok": True, "tool_name": tool_name, "result": {"status": "ABERTO"}}
+
+
+@pytest.mark.asyncio
+async def test_transaction_waits_then_executes_after_confirmation():
+    runtime = _Runtime()
+    state = {
+        "user_text": "Quero devolver o pedido 123 porque me arrependi",
+        "sanitized_input": "Quero devolver o pedido 123 porque me arrependi",
+        "mcp_tools": ["consultar_pedido", "solicitar_devolucao"],
+        "route": "support_agent",
+        "intent": "retail_support_exchange_return",
+    }
+    first = await runtime.execute_tools_for_intent(state)
+    assert state["transaction_status"] == "AWAITING_CONFIRMATION"
+    assert state["pending_tool_call"]["tool_name"] == "solicitar_devolucao"
+    assert state["pending_tool_call"]["arguments"]["order_id"] == "123"
+    assert not any(name == "solicitar_devolucao" for name, _ in runtime.calls)
+    assert first[-1]["awaiting_confirmation"] is True
+
+    state["user_text"] = "Sim, confirmo a devolução."
+    state["sanitized_input"] = state["user_text"]
+    second = await runtime.execute_tools_for_intent(state)
+    assert state["transaction_status"] == "COMPLETED"
+    assert state["pending_tool_call"] == {}
+    assert runtime.calls[-1][0] == "solicitar_devolucao"
+    assert runtime.calls[-1][1]["confirmed"] is True
+    assert second[-1]["ok"] is True

tests/unit/test_semantic_route_stickiness.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from agent_framework.routing.continuity import SemanticRouteContinuity
+from agent_framework.routing.models import IntentDefinition
+
+
+class FakeLLM:
+    def __init__(self, response: dict | str):
+        self.response = response
+        self.calls = []
+
+    async def ainvoke(self, messages, **kwargs):
+        self.calls.append((messages, kwargs))
+        if isinstance(self.response, str):
+            return self.response
+        return json.dumps(self.response)
+
+
+class FakeTelemetry:
+    def __init__(self):
+        self.events = []
+
+    async def event(self, name, payload):
+        self.events.append((name, payload))
+
+
+def settings(**overrides):
+    values = {
+        "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,
+    }
+    values.update(overrides)
+    return SimpleNamespace(**values)
+
+
+def intents():
+    return [
+        IntentDefinition(
+            name="product_services_information",
+            agent="product_agent",
+            description="Planos, serviços, benefícios e mudança de plano.",
+        ),
+        IntentDefinition(
+            name="billing_invoice_explanation",
+            agent="billing_agent",
+            description="Faturas, pagamentos, cobranças e contestação.",
+        ),
+    ]
+
+
+def state(message="o que está incluso?"):
+    return {
+        "session_id": "s1",
+        "active_agent": "product_agent",
+        "intent": "product_services_information",
+        "domain": "telecom",
+        "route_decision": {
+            "intent": "product_services_information",
+            "domain": "telecom",
+            "mcp_tools": ["consultar_plano"],
+        },
+        "history": [
+            {"role": "user", "content": "qual é o meu plano?"},
+            {"role": "assistant", "content": "Seu plano atual é Controle 50GB."},
+        ],
+        "user_text": message,
+        "sanitized_input": message,
+    }
+
+
+@pytest.mark.asyncio
+async def test_continue_bypasses_router_without_regex_rules():
+    llm = FakeLLM({"decision": "CONTINUE", "confidence": 0.97, "reason": "Continua o assunto do plano."})
+    telemetry = FakeTelemetry()
+    policy = SemanticRouteContinuity(settings(), llm, telemetry)
+
+    decision = await policy.evaluate(state(), intents=intents())
+
+    assert decision is not None
+    assert decision.agent == "product_agent"
+    assert decision.method == "continuity"
+    assert decision.metadata["route_bypassed"] is True
+    assert llm.calls[0][1]["profile_name"] == "route_continuity"
+    prompt = json.loads(llm.calls[0][0][1]["content"])
+    assert prompt["current_message"] == "o que está incluso?"
+    assert "product_agent" not in prompt["other_agents"]
+    assert telemetry.events[-1][1]["route_bypassed"] is True
+
+
+@pytest.mark.asyncio
+async def test_route_result_falls_back_to_enterprise_router():
+    llm = FakeLLM({"decision": "ROUTE", "confidence": 0.98, "reason": "Novo assunto de cobrança."})
+    policy = SemanticRouteContinuity(settings(), llm)
+
+    decision = await policy.evaluate(
+        state("agora quero contestar uma cobrança"), intents=intents()
+    )
+
+    assert decision is None
+
+
+@pytest.mark.asyncio
+async def test_low_confidence_continue_falls_back_safely():
+    llm = FakeLLM({"decision": "CONTINUE", "confidence": 0.70, "reason": "Possível continuidade."})
+    policy = SemanticRouteContinuity(settings(), llm)
+
+    assert await policy.evaluate(state(), intents=intents()) is None
+
+
+@pytest.mark.asyncio
+async def test_invalid_output_falls_back_safely():
+    llm = FakeLLM("not-json")
+    policy = SemanticRouteContinuity(settings(), llm)
+
+    assert await policy.evaluate(state(), intents=intents()) is None
+
+
+@pytest.mark.asyncio
+async def test_no_active_agent_still_classifies_global_session_actions():
+    llm = FakeLLM({"decision": "ROUTE", "confidence": 1.0})
+    policy = SemanticRouteContinuity(settings(), llm)
+    current = state()
+    current.pop("active_agent")
+
+    assert await policy.evaluate(current, intents=intents()) is None
+    assert len(llm.calls) == 1
+
+@pytest.mark.asyncio
+async def test_human_handoff_is_returned_as_global_route():
+    llm = FakeLLM({
+        "decision": "HUMAN_HANDOFF",
+        "confidence": 0.99,
+        "reason": "O usuário pediu atendimento humano.",
+    })
+    policy = SemanticRouteContinuity(settings(), llm)
+
+    decision = await policy.evaluate(
+        state("quero falar com um atendente"), intents=intents()
+    )
+
+    assert decision is not None
+    assert decision.route == "human_handoff"
+    assert decision.agent == "human_handoff"
+    assert decision.intent == "human_handoff"
+    assert decision.handoff is True
+    assert decision.metadata["session_control"] == "HUMAN_HANDOFF"
+    assert decision.metadata["route_bypassed"] is True
+
+
+@pytest.mark.asyncio
+async def test_end_session_is_returned_as_global_route():
+    llm = FakeLLM({
+        "decision": "END_SESSION",
+        "confidence": 0.98,
+        "reason": "O usuário informou que não precisa continuar.",
+    })
+    policy = SemanticRouteContinuity(settings(), llm)
+
+    decision = await policy.evaluate(state("obrigado, era só isso"), intents=intents())
+
+    assert decision is not None
+    assert decision.route == "end_session"
+    assert decision.agent == "end_session"
+    assert decision.intent == "end_session"
+    assert decision.handoff is False
+    assert decision.metadata["session_control"] == "END_SESSION"
+    assert decision.metadata["route_bypassed"] is True
+
+
+@pytest.mark.asyncio
+async def test_global_session_actions_work_without_active_agent():
+    llm = FakeLLM({
+        "decision": "HUMAN_HANDOFF",
+        "confidence": 0.97,
+        "reason": "Solicitação explícita de pessoa.",
+    })
+    policy = SemanticRouteContinuity(settings(), llm)
+    current = state("quero uma pessoa")
+    current.pop("active_agent")
+
+    decision = await policy.evaluate(current, intents=intents())
+
+    assert decision is not None
+    assert decision.route == "human_handoff"
+    assert len(llm.calls) == 1
+
+
+@pytest.mark.asyncio
+async def test_continue_without_active_agent_falls_back_to_router():
+    llm = FakeLLM({"decision": "CONTINUE", "confidence": 0.99})
+    policy = SemanticRouteContinuity(settings(), llm)
+    current = state()
+    current.pop("active_agent")
+
+    assert await policy.evaluate(current, intents=intents()) is None
+    assert len(llm.calls) == 1

tests/unit/test_tool_policies.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from agent_framework.mcp.tool_policy import ToolPolicyRegistry
+from agent_framework.mcp.tool_router import MCPToolRouter
+
+
+class _Registry:
+    def __init__(self, tool=None):
+        self.tool = tool
+
+    def get_tool(self, _name):
+        return self.tool
+
+
+def _router(policy_registry, legacy=None):
+    router = MCPToolRouter.__new__(MCPToolRouter)
+    router.tool_policies = policy_registry
+    router.registry = _Registry(legacy)
+    return router
+
+
+def test_missing_policy_file_preserves_legacy_behavior(tmp_path):
+    policies = ToolPolicyRegistry(str(tmp_path / "missing.yaml"))
+    legacy = SimpleNamespace(
+        tool_type="action",
+        requires=["order_id"],
+        confirmation_required=True,
+        execution_policy={},
+    )
+    router = _router(policies, legacy)
+
+    allowed, reason, metadata = router.validate_execution_policy("alterar", {"order_id": "42"})
+
+    assert allowed is False
+    assert "confirmação" in reason
+    assert metadata["operation_type"] == "transactional"
+    assert metadata["policy_source"] == "tools.yaml"
+
+
+def test_read_only_policy_executes_without_confirmation(tmp_path):
+    path = tmp_path / "tool_policies.yaml"
+    path.write_text(
+        "tool_policies:\n  consultar:\n    operation_type: read_only\n",
+        encoding="utf-8",
+    )
+    router = _router(ToolPolicyRegistry(str(path)))
+
+    allowed, reason, metadata = router.validate_execution_policy("consultar", {})
+
+    assert allowed is True
+    assert reason is None
+    assert metadata["operation_type"] == "read_only"
+
+
+def test_transactional_policy_requires_literal_boolean_confirmation(tmp_path):
+    path = tmp_path / "tool_policies.yaml"
+    path.write_text(
+        "tool_policies:\n  cancelar:\n    operation_type: transactional\n    require_confirmation: true\n",
+        encoding="utf-8",
+    )
+    router = _router(ToolPolicyRegistry(str(path)))
+
+    denied, _, _ = router.validate_execution_policy("cancelar", {"confirmed": "true"})
+    allowed, reason, metadata = router.validate_execution_policy("cancelar", {"confirmed": True})
+
+    assert denied is False
+    assert allowed is True
+    assert reason is None
+    assert metadata["policy_source"] == "tool_policies.yaml"
+
+
+def test_requires_confirmation_alias_is_supported(tmp_path):
+    path = tmp_path / "tool_policies.yaml"
+    path.write_text(
+        "tool_policies:\n  alterar:\n    type: transactional\n    requires_confirmation: true\n",
+        encoding="utf-8",
+    )
+
+    policy = ToolPolicyRegistry(str(path)).get("alterar")
+
+    assert policy.operation_type == "transactional"
+    assert policy.require_confirmation is True