Merge branch 'main' into feat/enable-multitenancy-support-for-agent-memory

Author: cassiofariasmachado

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sap-cloud-sdk"
-version = "0.33.1"
+version = "0.35.0"
 description = "SAP Cloud SDK for Python"
 readme = "README.md"
 license = "Apache-2.0"
@@ -33,6 +33,7 @@ dependencies = [
 extensibility = ["a2a-sdk>=0.2.0"]
 starlette = ["starlette>=0.40.0"]
 langchain = ["langchain-core>=1.2.7"]
+langgraph = ["langgraph>=1.0.0"]
 
 [build-system]
 requires = ["hatchling"]

src/sap_cloud_sdk/agent_memory/factory/__init__.py

@@ -0,0 +1,14 @@
+"""Factory subpackage for SAP Agent Memory framework adapters.
+
+Each module in this package provides a factory function that creates the
+appropriate framework-specific implementation for the current environment.
+
+Available factories:
+
+- :func:`sap_cloud_sdk.agent_memory.factory.langgraph_checkpoint.create_checkpointer`
+  — returns a LangGraph ``BaseCheckpointSaver`` (short-term memory)
+
+Usage:
+
+    from sap_cloud_sdk.agent_memory.factory.langgraph_checkpoint import create_checkpointer
+"""

src/sap_cloud_sdk/agent_memory/factory/_timed_memory.py

@@ -0,0 +1,111 @@
+"""TimedInMemorySaver — InMemorySaver with background TTL-based thread eviction.
+
+Not intended for direct use. Use ``create_checkpointer(ttl_seconds=...)`` instead.
+"""
+
+import logging
+import threading
+import time
+from typing import Any
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import ChannelVersions, Checkpoint, CheckpointMetadata
+from langgraph.checkpoint.memory import InMemorySaver
+
+logger = logging.getLogger(__name__)
+
+_SWEEP_INTERVAL_SECONDS = 60
+
+
+class TimedInMemorySaver(InMemorySaver):
+    """InMemorySaver with background TTL-based thread eviction.
+
+    Tracks last-active time per thread and evicts inactive threads via a
+    daemon background sweep. The sweep is fully decoupled from the read/write
+    path — ``put()`` only updates the activity timestamp.
+
+    This approximates server-side TTL semantics for in-process storage:
+    - ``put()`` records last-active timestamp (hot path stays clean)
+    - A daemon sweep thread evicts inactive threads every 60 seconds
+    - Eviction is best-effort — a thread may live up to
+      ``ttl_seconds + 60`` seconds before deletion
+    - State does not survive process restarts (inherent to InMemorySaver)
+
+    Args:
+        ttl_seconds: Inactivity threshold in seconds. Threads inactive for
+                     longer than this are evicted. Default: 3600 (1 hour).
+
+    Example::
+
+        from sap_cloud_sdk.agent_memory.factory.langgraph_checkpoint import (
+            create_checkpointer,
+        )
+
+        checkpointer = create_checkpointer(ttl_seconds=3600)
+    """
+
+    def __init__(self, *, ttl_seconds: int = 3600, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.ttl_seconds = ttl_seconds
+        self._last_active: dict[str, float] = {}
+        self._lock = threading.Lock()
+        self._sweeper = threading.Thread(
+            target=self._sweep_loop,
+            daemon=True,
+            name="TimedInMemorySaver-sweeper",
+        )
+        self._sweeper.start()
+        logger.debug(
+            "TimedInMemorySaver started with ttl_seconds=%d, sweep_interval=%ds",
+            ttl_seconds,
+            _SWEEP_INTERVAL_SECONDS,
+        )
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Save checkpoint and refresh thread activity timestamp."""
+        thread_id: str = config["configurable"]["thread_id"]
+        with self._lock:
+            self._last_active[thread_id] = time.monotonic()
+        return super().put(config, checkpoint, metadata, new_versions)
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Async version of put — refreshes thread activity timestamp."""
+        thread_id: str = config["configurable"]["thread_id"]
+        with self._lock:
+            self._last_active[thread_id] = time.monotonic()
+        return await super().aput(config, checkpoint, metadata, new_versions)
+
+    def _sweep_loop(self) -> None:
+        while True:
+            time.sleep(_SWEEP_INTERVAL_SECONDS)
+            self._evict_expired()
+
+    def _evict_expired(self) -> None:
+        now = time.monotonic()
+        with self._lock:
+            expired = [
+                tid
+                for tid, ts in self._last_active.items()
+                if now - ts > self.ttl_seconds
+            ]
+        for tid in expired:
+            self.delete_thread(tid)
+            with self._lock:
+                self._last_active.pop(tid, None)
+            logger.info(
+                "TimedInMemorySaver: evicted inactive thread '%s' (inactive for >%ds)",
+                tid,
+                self.ttl_seconds,
+            )

src/sap_cloud_sdk/agent_memory/factory/langgraph_checkpoint.py

@@ -0,0 +1,75 @@
+"""LangGraph checkpointer factory for SAP Agent Memory.
+
+Usage::
+
+    from sap_cloud_sdk.agent_memory.factory.langgraph_checkpoint import create_checkpointer
+
+    # No TTL — plain InMemorySaver
+    checkpointer = create_checkpointer()
+
+    # With TTL — TimedInMemorySaver evicts inactive threads automatically
+    checkpointer = create_checkpointer(ttl_seconds=3600)
+
+    app = workflow.compile(checkpointer=checkpointer)
+
+    # Or with LangChain create_agent:
+    from langchain.agents import create_agent
+    agent = create_agent(model="...", tools=[...], checkpointer=checkpointer)
+"""
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+def create_checkpointer(*, ttl_seconds: Optional[int] = None):
+    """Create a LangGraph checkpointer for the current environment.
+
+    Returns LangGraph's ``InMemorySaver`` (no TTL) or ``TimedInMemorySaver``
+    (with TTL-based thread eviction). State is held in-process and does not
+    survive restarts.
+
+    Args:
+        ttl_seconds: Evict threads inactive for this many seconds.
+                     ``None`` (default) disables eviction.
+
+    Returns:
+        BaseCheckpointSaver instance.
+
+    Raises:
+        ImportError: If langgraph is not installed.
+
+    Example — no TTL::
+
+        checkpointer = create_checkpointer()
+        app = workflow.compile(checkpointer=checkpointer)
+
+    Example — evict threads inactive for 1 hour::
+
+        checkpointer = create_checkpointer(ttl_seconds=3600)
+        app = workflow.compile(checkpointer=checkpointer)
+    """
+    try:
+        from langgraph.checkpoint.memory import InMemorySaver
+    except ImportError:
+        raise ImportError(
+            "langgraph is required for create_checkpointer(). "
+            "Install it with: pip install sap-cloud-sdk[langgraph] or pip install langgraph"
+        )
+
+    if ttl_seconds is not None:
+        from sap_cloud_sdk.agent_memory.factory._timed_memory import TimedInMemorySaver
+
+        logger.warning(
+            "create_checkpointer(): using TimedInMemorySaver(ttl_seconds=%d) — "
+            "session state is in-process only and will be lost on process exit.",
+            ttl_seconds,
+        )
+        return TimedInMemorySaver(ttl_seconds=ttl_seconds)
+
+    logger.warning(
+        "create_checkpointer(): using InMemorySaver — "
+        "session state is in-process only and will be lost on process exit."
+    )
+    return InMemorySaver()

src/sap_cloud_sdk/agent_memory/user-guide.md

@@ -66,6 +66,12 @@ plain text, and the service makes it searchable by meaning.
       - [Mounted Secrets (Kubernetes)](#mounted-secrets-kubernetes)
       - [Environment Variables](#environment-variables)
       - [UAA JSON Schema](#uaa-json-schema)
+  - [LangGraph Checkpointer](#langgraph-checkpointer)
+    - [Prerequisites](#prerequisites)
+    - [Import](#import-1)
+    - [Usage with LangGraph StateGraph](#usage-with-langgraph-stategraph)
+    - [Usage with LangChain create\_agent](#usage-with-langchain-create_agent)
+    - [Thread TTL](#thread-ttl)
 
 ## Installation
 
@@ -898,3 +904,116 @@ The `uaa` key must contain a JSON string with the XSUAA credentials:
   "url": "https://subdomain.authentication.region.hana.ondemand.com"
 }
 ```
+
+## LangGraph Checkpointer
+
+> This section covers the LangGraph-specific
+> factory for short-term memory (checkpointing). It is only relevant if your agent
+> is built with LangGraph or LangChain's `create_agent()`. The core
+> `AgentMemoryClient` and `create_client()` above are framework-agnostic and work
+> independently of this section.
+
+For LangGraph agents, the `agent_memory` module provides a `create_checkpointer()`
+factory in the `factory` subpackage. It returns a `BaseCheckpointSaver` that
+manages short-term session memory — conversation state, thread continuity, and
+HITL support — natively within LangGraph.
+
+> [!NOTE]
+> The current implementation uses LangGraph's `InMemorySaver` or
+> `TimedInMemorySaver` (when `ttl_seconds` is set). State is held in-process
+> and does not survive restarts. Persistent checkpointing backed by the
+> Agent Memory Service is not yet supported.
+
+### Prerequisites
+
+`langgraph` is an optional dependency. Install it via the SDK extra or directly:
+
+```bash
+# Via SDK optional extra (recommended)
+pip install "sap-cloud-sdk[langgraph]"
+
+# Or install langgraph directly
+pip install langgraph
+```
+
+### Import
+
+```python
+from sap_cloud_sdk.agent_memory.factory.langgraph_checkpoint import create_checkpointer
+```
+
+### Usage with LangGraph StateGraph
+
+```python
+from sap_cloud_sdk.agent_memory.factory.langgraph_checkpoint import create_checkpointer
+
+checkpointer = create_checkpointer()
+app = workflow.compile(checkpointer=checkpointer)
+
+result = app.invoke(
+    {"messages": [{"role": "user", "content": "hello"}]},
+    {"configurable": {"thread_id": "session-1"}},
+)
+```
+
+### Usage with LangChain create_agent
+
+```python
+from langchain.agents import create_agent
+from sap_cloud_sdk.agent_memory.factory.langgraph_checkpoint import create_checkpointer
+
+agent = create_agent(
+    model="...",
+    tools=[...],
+    checkpointer=create_checkpointer(),
+)
+```
+
+### Thread TTL
+
+Pass `ttl_seconds` to evict threads that have been inactive for the given
+period. This prevents unbounded memory growth in long-running processes.
+
+```python
+# Evict threads inactive for more than 1 hour
+checkpointer = create_checkpointer(ttl_seconds=3600)
+```
+
+When `ttl_seconds` is set, the factory returns a `TimedInMemorySaver` that
+tracks last-active time per thread and evicts inactive threads via a
+background daemon sweep. Eviction is best-effort — a thread may live up to
+`ttl_seconds + 60` seconds before deletion.
+
+#### Exposing TTL as a configurable parameter with `@agent_config`
+
+Use `@agent_config` from `sap_cloud_sdk.agent_decorators` to expose
+`ttl_seconds` as an operator-adjustable configuration field. The key
+`config.checkpointer.ttl_seconds` groups it with other checkpointer settings
+so external tooling can surface it in the low-code UI alongside model
+selection and temperature.
+
+```python
+from sap_cloud_sdk.agent_decorators import agent_config
+from sap_cloud_sdk.agent_memory.factory.langgraph_checkpoint import create_checkpointer
+
+
+@agent_config(
+    key="config.checkpointer.ttl_seconds",
+    label="Thread TTL (seconds)",
+    description="Evict inactive conversation threads after this period of "
+                "inactivity. Set to 0 to disable eviction.",
+)
+def thread_ttl_seconds() -> int:
+    return 3600 # 1 hour
+
+
+class MyAgent:
+    def __init__(self):
+        ttl = thread_ttl_seconds()
+        self._checkpointer = create_checkpointer(ttl_seconds=ttl or None)
+```
+
+> [!NOTE]
+> `TimedInMemorySaver` state does not survive process restarts — the TTL
+> applies to in-process memory only. Persistent TTL enforcement will be
+> available when the Agent Memory Service checkpointer ships.

src/sap_cloud_sdk/agentgateway/_fragments.py

@@ -16,6 +16,7 @@
 )
 
 from sap_cloud_sdk.agentgateway.exceptions import MCPServerNotFoundError
+from sap_cloud_sdk.core.telemetry import Module
 
 logger = logging.getLogger(__name__)
 
@@ -35,7 +36,10 @@ class FragmentLabel(str, Enum):
 
 
 def _list_fragments_by_label(label: FragmentLabel, tenant_subdomain: str) -> list:
-    client = create_fragment_client(instance=_DESTINATION_INSTANCE)
+    client = create_fragment_client(
+        instance=_DESTINATION_INSTANCE,
+        _telemetry_source=Module.AGENTGATEWAY,
+    )
     return client.list_instance_fragments(
         filter=ListOptions(filter_labels=[Label(key=LABEL_KEY, values=[label.value])]),
         tenant=tenant_subdomain,