fractal-graph-react-agent 0.0.0__py3-none-any.whl

fractal_graph_react_agent-0.0.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: fractal-graph-react-agent
+Version: 0.0.0
+Summary: Portable ReAct agent graph with MCP tools and RAG — part of the fractal-agent-graphs catalog
+Author: l4b4r4b4b4
+License: MIT
+Project-URL: Homepage, https://github.com/l4b4r4b4b4/fractal-agents-runtime
+Project-URL: Repository, https://github.com/l4b4r4b4b4/fractal-agents-runtime
+Project-URL: Issues, https://github.com/l4b4r4b4b4/fractal-agents-runtime/issues
+Keywords: langgraph,langchain,mcp,agent,rag,react,fractal
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.13,>=3.11.0
+Description-Content-Type: text/markdown
+Requires-Dist: langgraph>=1.0.8
+Requires-Dist: langchain-core>=1.2.11
+Requires-Dist: langchain>=1.2.10
+Requires-Dist: langchain-openai>=1.1.9
+Requires-Dist: langchain-mcp-adapters>=0.2.1
+Requires-Dist: pydantic<3,>=2.11.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: mcp>=1.9.1
+Requires-Dist: fractal-agent-infra
+
+# fractal-graph-react-agent
+
+ReAct agent with MCP tools — part of the [fractal-agents-runtime](https://github.com/l4b4r4b4b4/fractal-agents-runtime) graph catalog.
+
+## Overview
+
+This package provides a portable, self-contained ReAct agent graph built on LangGraph with:
+
+- **MCP tool integration** — connects to Model Context Protocol servers for extensible tool use
+- **RAG tool factory** — creates retrieval-augmented generation tools from document collections
+- **OAuth token exchange** — handles MCP server authentication with token caching
+- **Multi-provider LLM support** — OpenAI, Anthropic, Google, and custom OpenAI-compatible endpoints
+
+## Installation
+
+```bash
+uv add fractal-graph-react-agent
+```
+
+## Usage
+
+The graph is a portable factory function that accepts a `RunnableConfig` and optional persistence components via dependency injection:
+
+```python
+from react_agent import graph
+from langchain_core.runnables import RunnableConfig
+
+# Build the agent graph — runtime injects persistence
+config = RunnableConfig(configurable={"model_name": "openai:gpt-4o"})
+agent = await graph(config, checkpointer=my_checkpointer, store=my_store)
+
+# Invoke
+result = await agent.ainvoke({"messages": [{"role": "user", "content": "Hello!"}]})
+```
+
+### Dependency Injection
+
+The `graph()` factory uses dependency injection for persistence — it never imports from any specific runtime:
+
+```python
+# The runtime (e.g., Robyn server) creates and injects these:
+from my_runtime.database import get_checkpointer, get_store
+
+agent = await graph(
+    config,
+    checkpointer=get_checkpointer(),  # Thread-level conversation memory
+    store=get_store(),                  # Cross-thread long-term memory
+)
+```
+
+When `checkpointer` and `store` are `None` (the default), the agent runs without persistence — useful for testing or stateless invocations.
+
+## Configuration
+
+The graph is configured via `RunnableConfig.configurable`:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `model_name` | `str` | `"openai:gpt-4o"` | LLM provider and model |
+| `temperature` | `float` | `0.7` | Sampling temperature |
+| `max_tokens` | `int` | `4000` | Maximum generation tokens |
+| `system_prompt` | `str` | Generic helpful assistant | System prompt |
+| `mcp_config` | `dict` | `None` | MCP server configuration |
+| `rag` | `dict` | `None` | RAG collection configuration |
+| `base_url` | `str` | `None` | Custom OpenAI-compatible endpoint |
+
+## Architecture
+
+This package is part of the 3-layer architecture:
+
+```
+apps/          → Thin HTTP wrappers (Robyn, FastAPI, etc.)
+  ↓ depends on
+graphs/        → Portable agent architectures (this package)
+  ↓ depends on
+infra/         → Shared runtime infrastructure (tracing, auth, store namespace)
+```
+
+Graphs have **zero coupling** to any runtime — they can be deployed to LangGraph Platform, embedded in any server framework, or run standalone.
+
+## License
+
+MIT

fractal_graph_react_agent-0.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+react_agent/__init__.py,sha256=qM8ayb4rkSKjA1X3EGfwhchj4utroFGtsCbsAUQ_3PQ,851
+react_agent/agent.py,sha256=OwbVC3Z9xxVpm4WDzPg8R9wAtpFsqiJJ4rcztcn5MOE,17411
+react_agent/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+react_agent/utils/mcp_interceptors.py,sha256=Z4VUWtHAvmVdG75pF_52eSu1zYcEENJYDDfRsujjMS8,4382
+react_agent/utils/token.py,sha256=moyNmOCYb_xrygtdrP2ugHO40FMfO4tUFIn4viiD0zw,7413
+react_agent/utils/tools.py,sha256=JNWodIj_HUA7vEmWk88sAWvGJHkWqEi2lfScQHFPnF0,3583
+fractal_graph_react_agent-0.0.0.dist-info/METADATA,sha256=zqBmTkRq6nTF1j8-SFgetLk_HdDg1K974iEJRMRfx6c,4195
+fractal_graph_react_agent-0.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+fractal_graph_react_agent-0.0.0.dist-info/top_level.txt,sha256=2wR6hO9F5NSWFpBOQjDUfSa5BlChaekPUxuyTi-gG9M,12
+fractal_graph_react_agent-0.0.0.dist-info/RECORD,,

fractal_graph_react_agent-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fractal_graph_react_agent-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+react_agent

react_agent/__init__.py

@@ -0,0 +1,28 @@
+"""ReAct agent with MCP tools — portable graph architecture.
+
+This package provides a self-contained ReAct agent graph built on LangGraph
+with MCP tool integration, RAG tool factory, and multi-provider LLM support.
+
+The graph factory uses dependency injection for persistence — it never
+imports from any specific runtime.
+
+Usage::
+
+    from react_agent import graph
+
+    # Build the agent — runtime injects persistence
+    agent = await graph(config, checkpointer=my_checkpointer, store=my_store)
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from react_agent.agent import graph
+
+__all__ = ["graph"]
+
+try:
+    __version__ = version("fractal-graph-react-agent")
+except PackageNotFoundError:
+    # Package is not installed (running from source / editable install
+    # before first ``uv sync``).
+    __version__ = "0.0.0-dev"

react_agent/agent.py

@@ -0,0 +1,470 @@
+import logging
+import os
+
+from langchain.agents import create_agent
+from langchain.chat_models import init_chat_model
+from langchain_core.runnables import RunnableConfig
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_openai import ChatOpenAI
+from pydantic import BaseModel, Field
+
+from react_agent.utils.mcp_interceptors import (
+    handle_interaction_required,
+)
+from react_agent.utils.token import fetch_tokens
+from react_agent.utils.tools import create_rag_tool
+
+logger = logging.getLogger(__name__)
+
+
+def _safe_present_configurable_keys(config: RunnableConfig) -> list[str]:
+    """Return a stable, non-sensitive view of the configurable keys present.
+
+    This intentionally does not log values to avoid leaking secrets.
+    """
+    configurable: dict = config.get("configurable", {}) or {}
+    return sorted(str(key) for key in configurable)
+
+
+def _safe_mask_url(url: str | None) -> str | None:
+    """Mask potentially sensitive URL parts (query strings, userinfo).
+
+    This keeps the scheme/host/path which is enough to confirm routing.
+    """
+    if not url:
+        return url
+    # Avoid importing urllib just for logging; keep it conservative.
+    # Drop query fragments if present.
+    return url.split("?", 1)[0].split("#", 1)[0]
+
+
+def _merge_assistant_configurable_into_run_config(
+    config: RunnableConfig,
+) -> RunnableConfig:
+    """Merge assistant-level configurable settings into the run config.
+
+    LangGraph runtime-inmem passes per-run metadata in `configurable`, but in some
+    versions it may not automatically inject assistant `configurable` fields into
+    `graph(config)`. This merge reads the assistant settings (if present) and
+    overlays them onto the run config so fields such as `base_url` reach the agent.
+
+    Notes:
+        - Values are not logged here to avoid leaking secrets.
+        - Run-level keys take precedence over assistant-level keys.
+
+    Returns:
+        A new RunnableConfig with merged `configurable`.
+    """
+    original_configurable: dict = config.get("configurable", {}) or {}
+
+    # Common places LangGraph API may attach assistant settings:
+    # - "assistant" (object)
+    # - "assistant_config" (object)
+    # - "assistant_configurable" (already flattened)
+    assistant_configurable: dict = {}
+
+    assistant_container = original_configurable.get("assistant")
+    if isinstance(assistant_container, dict):
+        assistant_cfg = assistant_container.get("configurable")
+        if isinstance(assistant_cfg, dict):
+            assistant_configurable.update(assistant_cfg)
+
+    assistant_config_container = original_configurable.get("assistant_config")
+    if isinstance(assistant_config_container, dict):
+        assistant_cfg = assistant_config_container.get("configurable")
+        if isinstance(assistant_cfg, dict):
+            assistant_configurable.update(assistant_cfg)
+
+    assistant_config_flat = original_configurable.get("assistant_configurable")
+    if isinstance(assistant_config_flat, dict):
+        assistant_configurable.update(assistant_config_flat)
+
+    if not assistant_configurable:
+        return config
+
+    merged_configurable = {**assistant_configurable, **original_configurable}
+    return {**config, "configurable": merged_configurable}
+
+
+UNEDITABLE_SYSTEM_PROMPT = (
+    "\nIf the tool throws an error requiring authentication, provide the user"
+    " with a Markdown link to the authentication page and prompt them to"
+    " authenticate."
+)
+
+DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant that has access to a variety of tools."
+
+
+class RagConfig(BaseModel):
+    rag_url: str | None = None
+    """The URL of the rag server"""
+    collections: list[str] | None = None
+    """The collections to use for rag"""
+
+
+class MCPServerConfig(BaseModel):
+    """Configuration for a single MCP server.
+
+    Attributes:
+        name: Stable identifier for this server entry. Used as the key when
+            creating the MultiServerMCPClient config dict.
+        url: Base URL for the MCP server (may or may not end with /mcp).
+        tools: Optional list of tool names to expose from this server.
+            If omitted/None, all tools from the server are exposed.
+        auth_required: Whether this server requires auth token exchange.
+    """
+
+    name: str = Field(
+        default="default",
+        optional=True,
+    )
+    url: str
+    tools: list[str] | None = Field(
+        default=None,
+        optional=True,
+    )
+    auth_required: bool = Field(
+        default=False,
+        optional=True,
+    )
+
+
+class MCPConfig(BaseModel):
+    """Multi-server MCP configuration (no backward compatibility)."""
+
+    servers: list[MCPServerConfig] = Field(default_factory=list)
+
+
+class GraphConfigPydantic(BaseModel):
+    model_name: str | None = Field(
+        default="openai:gpt-4o",
+        metadata={
+            "x_oap_ui_config": {
+                "type": "select",
+                "default": "openai:gpt-4o",
+                "description": "The model to use in all generations",
+                "options": [
+                    {
+                        "label": "Claude Sonnet 4",
+                        "value": "anthropic:claude-sonnet-4-0",
+                    },
+                    {
+                        "label": "Claude 3.7 Sonnet",
+                        "value": "anthropic:claude-3-7-sonnet-latest",
+                    },
+                    {
+                        "label": "Claude 3.5 Sonnet",
+                        "value": "anthropic:claude-3-5-sonnet-latest",
+                    },
+                    {
+                        "label": "Claude 3.5 Haiku",
+                        "value": "anthropic:claude-3-5-haiku-latest",
+                    },
+                    {"label": "o4 mini", "value": "openai:o4-mini"},
+                    {"label": "o3", "value": "openai:o3"},
+                    {"label": "o3 mini", "value": "openai:o3-mini"},
+                    {"label": "GPT 4o", "value": "openai:gpt-4o"},
+                    {"label": "GPT 4o mini", "value": "openai:gpt-4o-mini"},
+                    {"label": "GPT 4.1", "value": "openai:gpt-4.1"},
+                    {"label": "GPT 4.1 mini", "value": "openai:gpt-4.1-mini"},
+                    {
+                        "label": "Custom OpenAI-compatible endpoint",
+                        "value": "custom:",
+                    },
+                ],
+            }
+        },
+    )
+    temperature: float | None = Field(
+        default=0.7,
+        metadata={
+            "x_oap_ui_config": {
+                "type": "slider",
+                "default": 0.7,
+                "min": 0,
+                "max": 2,
+                "step": 0.1,
+                "description": "Controls randomness (0 = deterministic, 2 = creative)",
+            }
+        },
+    )
+    max_tokens: int | None = Field(
+        default=4000,
+        metadata={
+            "x_oap_ui_config": {
+                "type": "number",
+                "default": 4000,
+                "min": 1,
+                "description": "The maximum number of tokens to generate",
+            }
+        },
+    )
+    system_prompt: str | None = Field(
+        default=DEFAULT_SYSTEM_PROMPT,
+        metadata={
+            "x_oap_ui_config": {
+                "type": "textarea",
+                "placeholder": "Enter a system prompt...",
+                "description": (
+                    "The system prompt to use in all generations."
+                    " The following prompt will always be included"
+                    " at the end of the system prompt:\n---"
+                    f"{UNEDITABLE_SYSTEM_PROMPT}\n---"
+                ),
+                "default": DEFAULT_SYSTEM_PROMPT,
+            }
+        },
+    )
+    mcp_config: MCPConfig | None = Field(
+        default=None,
+        optional=True,
+        metadata={
+            "x_oap_ui_config": {
+                "type": "mcp",
+            }
+        },
+    )
+    rag: RagConfig | None = Field(
+        default=None,
+        optional=True,
+        metadata={
+            "x_oap_ui_config": {
+                "type": "rag",
+                # Here is where you would set the default collection. Use collection IDs
+                # "default": {
+                #     "collections": [
+                #         "fd4fac19-886c-4ac8-8a59-fff37d2b847f",
+                #         "659abb76-fdeb-428a-ac8f-03b111183e25",
+                #     ]
+                # },
+            }
+        },
+    )
+    # Custom endpoint configuration
+    base_url: str | None = Field(
+        default=None,
+        optional=True,
+        metadata={
+            "x_oap_ui_config": {
+                "type": "text",
+                "placeholder": "http://localhost:7374/v1",
+                "description": "Base URL for custom OpenAI-compatible API",
+                "visible_when": {"model_name": "custom:"},
+            }
+        },
+    )
+    custom_model_name: str | None = Field(
+        default=None,
+        optional=True,
+        metadata={
+            "x_oap_ui_config": {
+                "type": "text",
+                "placeholder": "mistralai/ministral-3b-instruct",
+                "description": "Model name for custom endpoint",
+                "visible_when": {"model_name": "custom:"},
+            }
+        },
+    )
+    custom_api_key: str | None = Field(
+        default=None,
+        optional=True,
+        metadata={
+            "x_oap_ui_config": {
+                "type": "password",
+                "placeholder": "Leave empty for local vLLM",
+                "description": "API key for custom endpoint (optional)",
+                "visible_when": {"model_name": "custom:"},
+            }
+        },
+    )
+
+
+def get_api_key_for_model(model_name: str, config: RunnableConfig):
+    model_name = model_name.lower()
+
+    # Handle custom endpoints
+    if model_name.startswith("custom:"):
+        # First check config for custom_api_key
+        custom_key = config.get("configurable", {}).get("custom_api_key")
+        if custom_key:
+            return custom_key
+        # Fallback to environment variable
+        return os.getenv("CUSTOM_API_KEY")
+
+    # Existing logic for standard providers
+    model_to_key = {
+        "openai:": "OPENAI_API_KEY",
+        "anthropic:": "ANTHROPIC_API_KEY",
+        "google": "GOOGLE_API_KEY",
+    }
+    key_name = next(
+        (key for prefix, key in model_to_key.items() if model_name.startswith(prefix)),
+        None,
+    )
+    if not key_name:
+        return None
+    api_keys = config.get("configurable", {}).get("apiKeys", {})
+    if api_keys and api_keys.get(key_name) and len(api_keys[key_name]) > 0:
+        return api_keys[key_name]
+    # Fallback to environment variable
+    return os.getenv(key_name)
+
+
+async def graph(config: RunnableConfig, *, checkpointer=None, store=None):
+    config = _merge_assistant_configurable_into_run_config(config)
+
+    # INFO-level, runtime-safe logging to confirm config propagation.
+    # Do NOT log values that may contain secrets.
+    logger.info(
+        "graph() invoked; configurable_keys=%s",
+        _safe_present_configurable_keys(config),
+    )
+
+    cfg = GraphConfigPydantic(**(config.get("configurable", {}) or {}))
+
+    logger.info(
+        "graph() parsed_config; model_name=%s base_url_present=%s"
+        " custom_model_name_present=%s custom_api_key_present=%s",
+        cfg.model_name,
+        bool(cfg.base_url),
+        bool(cfg.custom_model_name),
+        bool(cfg.custom_api_key),
+    )
+
+    tools = []
+
+    supabase_token = config.get("configurable", {}).get("x-supabase-access-token")
+    if cfg.rag and cfg.rag.rag_url and cfg.rag.collections and supabase_token:
+        for collection in cfg.rag.collections:
+            rag_tool = await create_rag_tool(cfg.rag.rag_url, collection, supabase_token)
+            tools.append(rag_tool)
+
+    if cfg.mcp_config and cfg.mcp_config.servers:
+        mcp_server_entries: dict[str, dict] = {}
+        server_tool_filters: dict[str, set[str] | None] = {}
+        any_auth_required = any(server.auth_required for server in cfg.mcp_config.servers)
+
+        if any_auth_required:
+            mcp_tokens = await fetch_tokens(config)
+        else:
+            mcp_tokens = None
+
+        for server in cfg.mcp_config.servers:
+            # Append /mcp only if the URL doesn't already end with it.
+            raw_url = server.url.rstrip("/")
+            server_url = raw_url if raw_url.endswith("/mcp") else raw_url + "/mcp"
+
+            headers: dict[str, str] = {}
+            if server.auth_required:
+                if not mcp_tokens:
+                    # Auth required but token exchange failed / not available.
+                    # Skip connecting to this server.
+                    logger.warning(
+                        "MCP server skipped (auth required but no tokens): name=%s url=%s",
+                        server.name,
+                        _safe_mask_url(server_url),
+                    )
+                    continue
+                headers["Authorization"] = f"Bearer {mcp_tokens['access_token']}"
+
+            # Ensure unique keys for MultiServerMCPClient config
+            server_key = server.name or "default"
+            if server_key in mcp_server_entries:
+                # Deterministic de-dupe by suffixing with an index.
+                index = 2
+                while f"{server_key}-{index}" in mcp_server_entries:
+                    index += 1
+                server_key = f"{server_key}-{index}"
+
+            mcp_server_entries[server_key] = {
+                "transport": "http",
+                "url": server_url,
+                "headers": headers,
+            }
+            server_tool_filters[server_key] = set(server.tools) if server.tools else None
+
+        if mcp_server_entries:
+            try:
+                mcp_client = MultiServerMCPClient(
+                    mcp_server_entries,
+                    tool_interceptors=[handle_interaction_required],
+                )
+                mcp_tools = await mcp_client.get_tools()
+
+                # Apply per-server filtering when requested.
+                filtered_tools = []
+                for tool in mcp_tools:
+                    tool_origin = getattr(tool, "server_name", None)
+                    if tool_origin and tool_origin in server_tool_filters:
+                        requested = server_tool_filters[tool_origin]
+                        if requested is None or tool.name in requested:
+                            filtered_tools.append(tool)
+                    else:
+                        # If origin is unknown, include it (conservative).
+                        filtered_tools.append(tool)
+
+                tools.extend(filtered_tools)
+                logger.info(
+                    "MCP tools loaded: count=%d servers=%s",
+                    len(filtered_tools),
+                    [_safe_mask_url(entry["url"]) for entry in mcp_server_entries.values()],
+                )
+            except Exception as e:
+                logger.warning("Failed to fetch MCP tools: %s", str(e))
+
+    # Initialize model based on configuration
+    if cfg.base_url:
+        # Custom endpoint - use ChatOpenAI with OpenAI-compatible base URL.
+        # LangChain's vLLM integration docs recommend `openai_api_base` + `openai_api_key="EMPTY"`.
+        masked_base_url = _safe_mask_url(cfg.base_url)
+        logger.info("LLM routing: custom endpoint enabled; base_url=%s", masked_base_url)
+
+        # Get API key for custom endpoint (do not log the key)
+        api_key = get_api_key_for_model("custom:", config)
+        if not api_key:
+            # Use "EMPTY" for local vLLM that doesn't require authentication
+            api_key = "EMPTY"
+            logger.info("LLM auth: no custom API key provided; using EMPTY")
+        else:
+            logger.info("LLM auth: custom API key provided (masked)")
+
+        # Use custom model name if provided, otherwise use the configured model_name
+        model_name = cfg.custom_model_name or cfg.model_name
+        logger.info("LLM model: %s", model_name)
+
+        # Prefer the vLLM-recommended parameters. Avoid passing multiple aliases
+        # for the same setting to reduce ambiguity across versions.
+        model = ChatOpenAI(
+            openai_api_base=cfg.base_url,
+            openai_api_key=api_key,
+            model=model_name,
+            temperature=cfg.temperature,
+            max_tokens=cfg.max_tokens,
+        )
+    else:
+        # Standard provider - use init_chat_model
+        logger.info("LLM routing: standard provider enabled; model_name=%s", cfg.model_name)
+        api_key = get_api_key_for_model(cfg.model_name, config)
+        logger.info("LLM auth: standard provider api key present=%s", bool(api_key))
+
+        model = init_chat_model(
+            cfg.model_name,
+            temperature=cfg.temperature,
+            max_tokens=cfg.max_tokens,
+            api_key=api_key or "No token found",
+        )
+
+    # Persistence components are injected by the runtime caller.
+    # When None (the default), the agent runs without persistence.
+    if checkpointer is not None:
+        logger.info("graph() using injected checkpointer for thread persistence")
+    if store is not None:
+        logger.info("graph() using injected store for cross-thread memory")
+
+    return create_agent(
+        model=model,
+        tools=tools,
+        system_prompt=cfg.system_prompt + UNEDITABLE_SYSTEM_PROMPT,
+        checkpointer=checkpointer,
+        store=store,
+    )

react_agent/utils/mcp_interceptors.py

@@ -0,0 +1,126 @@
+"""MCP tool interceptors for langchain-mcp-adapters.
+
+Provides middleware-like interceptors that wrap MCP tool calls to handle
+cross-cutting concerns like authentication errors, logging, and retries.
+
+These interceptors are passed to ``MultiServerMCPClient`` via the
+``tool_interceptors`` parameter and execute in "onion" order (first
+interceptor in the list is the outermost layer).
+
+Usage::
+
+    from langchain_mcp_adapters.client import MultiServerMCPClient
+    from react_agent.utils.mcp_interceptors import handle_interaction_required
+
+    client = MultiServerMCPClient(
+        {...},
+        tool_interceptors=[handle_interaction_required],
+    )
+"""
+
+import logging
+from typing import Any
+
+from langchain_core.tools import ToolException
+from langchain_mcp_adapters.interceptors import MCPToolCallRequest
+from mcp import McpError
+
+logger = logging.getLogger(__name__)
+
+
+def _find_first_mcp_error_nested(exception: BaseException) -> McpError | None:
+    """Walk a (possibly nested) exception tree to find the first ``McpError``.
+
+    The MCP SDK can raise ``McpError`` directly or wrap it inside an
+    ``ExceptionGroup`` when multiple tasks fail concurrently.  This helper
+    recurses into ``ExceptionGroup.exceptions`` to locate the root MCP error.
+
+    Args:
+        exception: The caught exception (may be an ``ExceptionGroup``).
+
+    Returns:
+        The first ``McpError`` found, or ``None``.
+    """
+    if isinstance(exception, McpError):
+        return exception
+    if isinstance(exception, ExceptionGroup):
+        for sub_exception in exception.exceptions:
+            if found := _find_first_mcp_error_nested(sub_exception):
+                return found
+    return None
+
+
+def _extract_interaction_message(error_data: dict[str, Any]) -> str:
+    """Build a user-facing message from an ``interaction_required`` error payload.
+
+    The MCP ``interaction_required`` error (code -32003) may carry a nested
+    ``message`` dict with a ``text`` field and/or a ``url`` for the user to
+    visit.  This helper extracts both into a single string that the LLM can
+    present to the user (e.g. as a clickable link).
+
+    Args:
+        error_data: The ``data`` dict from the MCP error response.
+
+    Returns:
+        A human-readable error message, optionally including the URL.
+    """
+    message_payload = error_data.get("message", {})
+    error_message_text = "Required interaction"
+    if isinstance(message_payload, dict):
+        error_message_text = message_payload.get("text") or error_message_text
+
+    if url := error_data.get("url"):
+        error_message_text = f"{error_message_text} {url}"
+
+    return error_message_text
+
+
+async def handle_interaction_required(
+    request: MCPToolCallRequest,
+    handler: Any,
+) -> Any:
+    """Intercept ``interaction_required`` MCP errors and raise ``ToolException``.
+
+    When an MCP server responds with error code ``-32003``
+    (``interaction_required``), the raw ``McpError`` is caught and converted
+    into a LangChain ``ToolException`` with a clean, user-facing message.
+    This prevents noisy stack traces from cluttering the logs and gives the
+    LLM a structured error it can relay to the user.
+
+    All other exceptions are re-raised unmodified.
+
+    Args:
+        request: The incoming MCP tool call request (contains tool name, args,
+            runtime context).
+        handler: The next handler in the interceptor chain.  Call
+            ``await handler(request)`` to proceed with the actual tool
+            invocation.
+
+    Returns:
+        The tool call result if the call succeeds.
+
+    Raises:
+        ToolException: If the MCP server returns ``interaction_required``.
+    """
+    try:
+        return await handler(request)
+    except BaseException as exception:
+        mcp_error = _find_first_mcp_error_nested(exception)
+
+        if not mcp_error:
+            raise
+
+        error_details = mcp_error.error
+        is_interaction_required = getattr(error_details, "code", None) == -32003
+        error_data = getattr(error_details, "data", None) or {}
+
+        if is_interaction_required:
+            error_message = _extract_interaction_message(error_data)
+            logger.info(
+                "MCP interaction_required for tool=%s: %s",
+                request.name,
+                error_message,
+            )
+            raise ToolException(error_message) from exception
+
+        raise

react_agent/utils/token.py

@@ -0,0 +1,240 @@
+"""MCP token exchange and caching utilities.
+
+Handles OAuth2 token exchange with MCP servers and caches tokens in the
+LangGraph Store using the canonical org-scoped namespace convention::
+
+    (org_id, user_id, assistant_id, "tokens")
+
+See :mod:`fractal_agent_infra.store_namespace` for the namespace contract.
+"""
+
+import contextlib
+import logging
+from datetime import UTC
+from typing import Any
+
+import aiohttp
+from fractal_agent_infra.store_namespace import (
+    CATEGORY_TOKENS,
+    build_namespace,
+    extract_namespace_components,
+)
+from langchain_core.runnables import RunnableConfig
+from langgraph.config import get_store
+
+logger = logging.getLogger(__name__)
+
+# Store key for the cached token data within the namespace.
+_TOKEN_STORE_KEY = "data"
+
+
+async def get_mcp_access_token(
+    supabase_token: str,
+    base_mcp_url: str,
+) -> dict[str, Any] | None:
+    """
+    Exchange a Supabase token for an MCP access token.
+
+    Args:
+        supabase_token: The Supabase token to exchange
+        base_mcp_url: The base URL for the MCP server
+
+    Returns:
+        The token data as a dictionary if successful, None otherwise
+    """
+    try:
+        # Exchange Supabase token for MCP access token
+        form_data = {
+            "client_id": "mcp_default",
+            "subject_token": supabase_token,
+            "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+            "resource": base_mcp_url.rstrip("/") + "/mcp",
+            "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
+        }
+
+        async with (
+            aiohttp.ClientSession() as session,
+            session.post(
+                base_mcp_url.rstrip("/") + "/oauth/token",
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                data=form_data,
+            ) as token_response,
+        ):
+            if token_response.status != 200:
+                response_text = await token_response.text()
+                logger.error("Token exchange failed: %s", response_text)
+                return None
+
+            token_data = await token_response.json()
+            return token_data if isinstance(token_data, dict) else None
+    except Exception:
+        logger.exception("Error during token exchange")
+
+    return None
+
+
+def _build_token_namespace(
+    config: RunnableConfig,
+) -> tuple[str, str, str, str] | None:
+    """Build the store namespace tuple for token caching.
+
+    Extracts ``(org_id, user_id, assistant_id)`` from the config and appends
+    the ``"tokens"`` category.
+
+    Returns:
+        A 4-tuple namespace, or ``None`` if required components are missing.
+    """
+    components = extract_namespace_components(config)
+    if components is None:
+        return None
+
+    return build_namespace(
+        components.org_id,
+        components.user_id,
+        components.assistant_id,
+        CATEGORY_TOKENS,
+    )
+
+
+async def get_tokens(config: RunnableConfig) -> dict[str, Any] | None:
+    """Return cached MCP tokens from the LangGraph store if present and valid.
+
+    Uses the org-scoped namespace ``(org_id, user_id, assistant_id, "tokens")``.
+
+    This function is deliberately defensive:
+    - Store may be unavailable (returns None).
+    - Namespace components may be missing (returns None).
+    - Token objects may have unexpected shapes.
+    - Missing/invalid expiration metadata results in cache eviction + None.
+    """
+    store = get_store()
+    if store is None:
+        return None
+
+    namespace = _build_token_namespace(config)
+    if namespace is None:
+        return None
+
+    try:
+        token_record = await store.aget(namespace, _TOKEN_STORE_KEY)
+    except Exception:
+        logger.debug("get_tokens: store.aget failed", exc_info=True)
+        return None
+
+    if not token_record:
+        return None
+
+    tokens_value = getattr(token_record, "value", None)
+    if not isinstance(tokens_value, dict):
+        return None
+
+    created_at = getattr(token_record, "created_at", None)
+    if created_at is None:
+        # Without created_at, we cannot safely evaluate expiry.
+        with contextlib.suppress(Exception):
+            await store.adelete(namespace, _TOKEN_STORE_KEY)
+        return None
+
+    expires_in_raw = tokens_value.get("expires_in")
+    expires_in_seconds: float | None = None
+    if expires_in_raw is not None:
+        with contextlib.suppress(TypeError, ValueError):
+            expires_in_seconds = float(expires_in_raw)
+
+    if expires_in_seconds is None:
+        with contextlib.suppress(Exception):
+            await store.adelete(namespace, _TOKEN_STORE_KEY)
+        return None
+
+    # At this point expires_in_seconds is guaranteed to be a float.
+    validated_expires: float = expires_in_seconds
+
+    from datetime import datetime, timedelta
+
+    current_time = datetime.now(UTC)
+    expiration_time = created_at + timedelta(seconds=validated_expires)
+
+    if current_time > expiration_time:
+        with contextlib.suppress(Exception):
+            await store.adelete(namespace, _TOKEN_STORE_KEY)
+        return None
+
+    return tokens_value
+
+
+async def set_tokens(config: RunnableConfig, tokens: dict[str, Any] | None) -> None:
+    """Persist MCP tokens to the LangGraph store (best-effort).
+
+    Uses the org-scoped namespace ``(org_id, user_id, assistant_id, "tokens")``.
+    """
+    if tokens is None:
+        return
+
+    store = get_store()
+    if store is None:
+        return
+
+    namespace = _build_token_namespace(config)
+    if namespace is None:
+        return
+
+    try:
+        await store.aput(namespace, _TOKEN_STORE_KEY, tokens)
+    except Exception:
+        # Best-effort cache; ignore storage failures.
+        logger.debug("set_tokens: store.aput failed", exc_info=True)
+        return
+
+
+async def fetch_tokens(config: RunnableConfig) -> dict[str, Any] | None:
+    """Fetch MCP access token if it doesn't already exist in the store.
+
+    Supports the multi-server MCP config shape::
+
+        configurable.mcp_config.servers = [
+            {"name": "...", "url": "...", "auth_required": bool, ...},
+            ...
+        ]
+
+    Returns a token dict that can be reused for one or more auth-required
+    MCP servers, or ``None`` when tokens are unavailable.
+    """
+    current_tokens = await get_tokens(config)
+    if isinstance(current_tokens, dict) and current_tokens:
+        return current_tokens
+
+    configurable = config.get("configurable", {}) or {}
+
+    supabase_token = configurable.get("x-supabase-access-token")
+    if not supabase_token:
+        return None
+
+    mcp_config = configurable.get("mcp_config")
+    if not isinstance(mcp_config, dict):
+        return None
+
+    servers = mcp_config.get("servers")
+    if not isinstance(servers, list) or not servers:
+        return None
+
+    # Find the first auth-required server with a usable URL.
+    base_mcp_url: str | None = None
+    for server in servers:
+        if not isinstance(server, dict):
+            continue
+        if not server.get("auth_required"):
+            continue
+        url_value = server.get("url")
+        if isinstance(url_value, str) and url_value.strip():
+            base_mcp_url = url_value.strip()
+            break
+
+    if not base_mcp_url:
+        return None
+
+    mcp_tokens: dict[str, Any] | None = await get_mcp_access_token(supabase_token, base_mcp_url)
+    if mcp_tokens is None:
+        return None
+
+    await set_tokens(config, mcp_tokens)
+    return mcp_tokens

react_agent/utils/tools.py

@@ -0,0 +1,94 @@
+import re
+from typing import Annotated
+
+import aiohttp
+from langchain_core.tools import tool
+
+
+async def create_rag_tool(rag_url: str, collection_id: str, access_token: str):
+    """Create a RAG tool for a specific collection.
+
+    Args:
+        rag_url: The base URL for the RAG API server
+        collection_id: The ID of the collection to query
+        access_token: The access token for authentication
+
+    Returns:
+        A structured tool that can be used to query the RAG collection
+    """
+    rag_url = rag_url.removesuffix("/")
+
+    collection_endpoint = f"{rag_url}/collections/{collection_id}"
+    try:
+        async with (
+            aiohttp.ClientSession() as session,
+            session.get(
+                collection_endpoint, headers={"Authorization": f"Bearer {access_token}"}
+            ) as response,
+        ):
+            response.raise_for_status()
+            collection_data = await response.json()
+
+        # Get the collection name and sanitize it to match the required regex pattern
+        raw_collection_name = collection_data.get("name", f"collection_{collection_id}")
+
+        # Sanitize the name to only include alphanumeric characters, underscores, and hyphens
+        # Replace any other characters with underscores
+        sanitized_name = re.sub(r"[^a-zA-Z0-9_-]", "_", raw_collection_name)
+
+        # Ensure the name is not empty and doesn't exceed 64 characters
+        if not sanitized_name:
+            sanitized_name = f"collection_{collection_id}"
+        collection_name = sanitized_name[:64]
+
+        raw_description = collection_data.get("metadata", {}).get("description")
+
+        base_description = (
+            "Search your collection of documents for results"
+            " semantically similar to the input query"
+        )
+        if not raw_description:
+            collection_description = base_description
+        else:
+            collection_description = (
+                f"{base_description}. Collection description: {raw_description}"
+            )
+
+        @tool(name_or_callable=collection_name, description=collection_description)
+        async def get_documents(
+            query: Annotated[str, "The search query to find relevant documents"],
+        ) -> str:
+            """Search for documents in the collection based on the query"""
+
+            search_endpoint = f"{rag_url}/collections/{collection_id}/documents/search"
+            payload = {"query": query, "limit": 10}
+
+            try:
+                async with (
+                    aiohttp.ClientSession() as session,
+                    session.post(
+                        search_endpoint,
+                        json=payload,
+                        headers={"Authorization": f"Bearer {access_token}"},
+                    ) as search_response,
+                ):
+                    search_response.raise_for_status()
+                    documents = await search_response.json()
+
+                formatted_docs = "<all-documents>\n"
+
+                for doc in documents:
+                    doc_id = doc.get("id", "unknown")
+                    content = doc.get("page_content", "")
+                    formatted_docs += f'  <document id="{doc_id}">\n    {content}\n  </document>\n'
+
+                formatted_docs += "</all-documents>"
+                return formatted_docs
+            except Exception as e:
+                return f"<all-documents>\n  <error>{e!s}</error>\n</all-documents>"
+
+        return get_documents
+
+    except Exception as e:
+        msg = f"Failed to create RAG tool: {e!s}"
+        raise RuntimeError(msg) from e