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

Documentacao/README_SEMANTIC_ROUTE_STICKINESS.md

@@ -0,0 +1,86 @@
+# Semantic Route Stickiness and Global Session Control in Agent Framework OCI
+
+## Purpose
+
+This optional capability uses a lightweight LLM profile and no regex, phrase lists, or domain-specific language rules. It classifies each turn as:
+
+- `CONTINUE`: keep the active agent;
+- `ROUTE`: run the regular Enterprise Router;
+- `HUMAN_HANDOFF`: request human assistance;
+- `END_SESSION`: finish the automated session.
+
+The classifier does not answer the user, execute tools, or implement domain rules. Human handoff and session ending are handled by global graph nodes.
+
+## Flow
+
+```text
+Incoming turn
+  -> lightweight semantic classifier
+       CONTINUE + active agent -> active agent
+       ROUTE / low confidence / error -> Enterprise Router
+       HUMAN_HANDOFF -> human_handoff node
+       END_SESSION -> end_session node
+```
+
+`CONTINUE` is converted to `ROUTE` when there is no active agent. Global session actions can be detected on the first turn.
+
+## Configuration
+
+```dotenv
+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=I will transfer your request to a person.
+END_SESSION_MESSAGE=The session has ended. Thank you for contacting us.
+```
+
+```yaml
+profiles:
+  route_continuity:
+    provider: oci_openai
+    model: openai.gpt-4.1-mini
+    temperature: 0
+    max_tokens: 80
+    timeout_seconds: 5
+```
+
+Use the smallest approved model available in the target OCI environment.
+
+## Human handoff contract
+
+The router returns route `human_handoff`, intent `human_handoff`, `handoff=true`, and metadata `session_control=HUMAN_HANDOFF`. The graph node sets:
+
+- `human_handoff_requested=true`;
+- `session_ended=false`;
+- `next_state=HUMAN_HANDOFF_REQUESTED`.
+
+It emits `session.human_handoff.requested`. The customer integration remains responsible for choosing the human queue and protocol.
+
+## End-session contract
+
+The router returns route `end_session`, intent `end_session`, and metadata `session_control=END_SESSION`. The graph node sets:
+
+- `session_ended=true`;
+- `human_handoff_requested=false`;
+- `next_state=SESSION_ENDED`.
+
+It emits `session.end.requested`. Channel-specific session expiration or connection closing remains an integration responsibility.
+
+## Safety behavior
+
+- Only decisions above the configured confidence threshold are accepted.
+- Invalid JSON, timeout, low confidence, or errors fall back to the Enterprise Router.
+- Human handoff and session ending do not execute domain agents or MCP tools.
+- The classifier never selects a human queue and never physically closes a channel connection.
+
+## Tests
+
+Run:
+
+```bash
+PYTHONPATH=libs/agent_framework/src pytest -q tests/unit/test_semantic_route_stickiness.py
+```
+
+The suite covers CONTINUE, ROUTE, low confidence, invalid output, HUMAN_HANDOFF, END_SESSION, first-turn global actions, and CONTINUE without an active agent.