cortexhub 0.1.0__py3-none-any.whl

cortexhub/adapters/crewai.py

@@ -0,0 +1,297 @@
+"""CrewAI adapter for tool and LLM interception.
+
+Patches CrewAI at multiple levels:
+- CrewStructuredTool.invoke for all LLM-driven tool calls
+- BaseTool._run for direct tool usage
+- LiteLLM completion for LLM call governance (guardrails, PII detection)
+
+IMPORTANT: CrewAI has its own OpenTelemetry setup that may conflict with
+CortexHub's telemetry. To ensure proper telemetry capture, either:
+1. Call cortexhub.init() BEFORE importing crewai
+2. Set environment variable: CREWAI_TRACING_ENABLED=false
+
+Architectural rules:
+- Adapter is DUMB plumbing
+- SDK orchestrates everything via govern_execution()
+- Store original on class, not global
+"""
+
+from typing import Any
+
+import structlog
+
+from cortexhub.adapters.base import ToolAdapter
+from cortexhub.pipeline import govern_execution
+
+logger = structlog.get_logger(__name__)
+
+# Attribute names for storing originals on class
+_ORIGINAL_INVOKE_ATTR = "__cortexhub_original_invoke__"
+_ORIGINAL_RUN_ATTR = "__cortexhub_original_run__"
+_PATCHED_ATTR = "__cortexhub_patched__"
+_PATCHED_TOOL_ATTR = "__cortexhub_tool_patched__"
+_PATCHED_LLM_ATTR = "__cortexhub_llm_patched__"
+_ORIGINAL_COMPLETION_ATTR = "__cortexhub_original_completion__"
+_ORIGINAL_ACOMPLETION_ATTR = "__cortexhub_original_acompletion__"
+
+
+class CrewAIAdapter(ToolAdapter):
+    """Adapter for CrewAI framework.
+
+    Patches CrewStructuredTool.invoke - the method called by CrewAI's
+    agent executor when tools are invoked by the LLM.
+    
+    Key properties:
+    - Adapter is dumb plumbing
+    - Patches at class level so all tools are governed
+    - Works regardless of when tools are created
+    """
+
+    @property
+    def framework_name(self) -> str:
+        return "crewai"
+
+    def _get_framework_modules(self) -> list[str]:
+        return ["crewai", "crewai.tools"]
+
+    def patch(self) -> None:
+        """Patch CrewAI tool execution methods."""
+        try:
+            from crewai.tools.structured_tool import CrewStructuredTool
+            
+            cortex_hub = self.cortex_hub
+            tools = self._discover_tools()
+            if tools:
+                cortex_hub.backend.register_tool_inventory(
+                    agent_id=cortex_hub.agent_id,
+                    framework=self.framework_name,
+                    tools=tools,
+                )
+
+            # Patch CrewStructuredTool.invoke (primary execution path)
+            if not getattr(CrewStructuredTool, _PATCHED_ATTR, False):
+                if not hasattr(CrewStructuredTool, _ORIGINAL_INVOKE_ATTR):
+                    setattr(CrewStructuredTool, _ORIGINAL_INVOKE_ATTR, CrewStructuredTool.invoke)
+                
+                original_invoke = getattr(CrewStructuredTool, _ORIGINAL_INVOKE_ATTR)
+
+                def patched_invoke(self, input, config=None, **kwargs):
+                    """Governed CrewStructuredTool execution."""
+                    tool_name = getattr(self, 'name', 'unknown_tool')
+                    tool_description = getattr(self, 'description', None)
+                    
+                    tool_metadata = {
+                        "name": tool_name,
+                        "description": tool_description,
+                        "framework": "crewai",
+                    }
+
+                    governed_fn = govern_execution(
+                        tool_fn=lambda **_kw: original_invoke(self, input, config, **kwargs),
+                        tool_metadata=tool_metadata,
+                        cortex_hub=cortex_hub,
+                    )
+
+                    # Extract args from input
+                    if isinstance(input, dict):
+                        return governed_fn(**input)
+                    elif isinstance(input, str):
+                        return governed_fn(_raw=input)
+                    return governed_fn()
+
+                CrewStructuredTool.invoke = patched_invoke
+                setattr(CrewStructuredTool, _PATCHED_ATTR, True)
+                logger.info("CrewAI CrewStructuredTool.invoke patched")
+
+            # Also patch BaseTool._run for direct tool.run() calls
+            try:
+                from crewai.tools.base_tool import BaseTool
+                
+                if not getattr(BaseTool, _PATCHED_TOOL_ATTR, False):
+                    if not hasattr(BaseTool, _ORIGINAL_RUN_ATTR):
+                        setattr(BaseTool, _ORIGINAL_RUN_ATTR, BaseTool._run)
+                    
+                    original_run = getattr(BaseTool, _ORIGINAL_RUN_ATTR)
+
+                    def patched_run(self, *args, **kwargs):
+                        """Governed BaseTool execution."""
+                        tool_name = getattr(self, 'name', 'unknown_tool')
+                        tool_description = getattr(self, 'description', None)
+                        
+                        tool_metadata = {
+                            "name": tool_name,
+                            "description": tool_description,
+                            "framework": "crewai",
+                        }
+
+                        governed_fn = govern_execution(
+                            tool_fn=lambda **_kw: original_run(self, *args, **kwargs),
+                            tool_metadata=tool_metadata,
+                            cortex_hub=cortex_hub,
+                        )
+
+                        # Extract args
+                        if kwargs:
+                            return governed_fn(**kwargs)
+                        if len(args) == 1 and isinstance(args[0], dict):
+                            return governed_fn(**args[0])
+                        if args:
+                            return governed_fn(_raw=args[0])
+                        return governed_fn()
+
+                    BaseTool._run = patched_run
+                    setattr(BaseTool, _PATCHED_TOOL_ATTR, True)
+                    logger.info("CrewAI BaseTool._run patched")
+                    
+            except ImportError:
+                logger.debug("CrewAI BaseTool not available")
+
+            logger.info("CrewAI adapter patched successfully")
+            
+            # Patch LiteLLM for LLM call governance (guardrails, PII)
+            self._patch_litellm(cortex_hub)
+
+        except ImportError:
+            logger.debug("CrewAI not available, skipping adapter")
+            raise
+        except Exception as e:
+            logger.error("Failed to patch CrewAI", error=str(e))
+            raise
+
+    def _patch_litellm(self, cortex_hub) -> None:
+        """Patch LiteLLM completion for LLM call governance.
+        
+        CrewAI uses LiteLLM internally for all LLM calls.
+        We patch litellm.completion to intercept and run guardrails.
+        """
+        try:
+            import litellm
+            
+            if getattr(litellm, _PATCHED_LLM_ATTR, False):
+                logger.debug("LiteLLM already patched for CrewAI")
+                return
+            
+            # Store originals
+            if not hasattr(litellm, _ORIGINAL_COMPLETION_ATTR):
+                setattr(litellm, _ORIGINAL_COMPLETION_ATTR, litellm.completion)
+            original_completion = getattr(litellm, _ORIGINAL_COMPLETION_ATTR)
+            
+            def patched_completion(*args, **kwargs):
+                """Governed LiteLLM completion."""
+                model = kwargs.get("model") or (args[0] if args else "unknown")
+                messages = kwargs.get("messages") or (args[1] if len(args) > 1 else [])
+                
+                # Extract prompt from messages
+                prompt = messages
+                
+                def call_original(prompt_override):
+                    # Replace messages if overridden (for redaction)
+                    call_kwargs = kwargs.copy()
+                    if prompt_override is not None:
+                        call_kwargs["messages"] = prompt_override
+                    return original_completion(*args[:1] if args else [], **call_kwargs)
+                
+                llm_metadata = {
+                    "kind": "llm",
+                    "framework": "crewai",
+                    "model": model,
+                    "prompt": prompt,
+                    "call_original": call_original,
+                }
+                
+                governed = govern_execution(
+                    tool_fn=lambda *a, **kw: original_completion(*args, **kwargs),
+                    tool_metadata=llm_metadata,
+                    cortex_hub=cortex_hub,
+                )
+                return governed()
+            
+            litellm.completion = patched_completion
+            
+            # Patch async version too
+            if hasattr(litellm, "acompletion"):
+                if not hasattr(litellm, _ORIGINAL_ACOMPLETION_ATTR):
+                    setattr(litellm, _ORIGINAL_ACOMPLETION_ATTR, litellm.acompletion)
+                original_acompletion = getattr(litellm, _ORIGINAL_ACOMPLETION_ATTR)
+                
+                async def patched_acompletion(*args, **kwargs):
+                    """Governed async LiteLLM completion."""
+                    model = kwargs.get("model") or (args[0] if args else "unknown")
+                    messages = kwargs.get("messages") or (args[1] if len(args) > 1 else [])
+                    prompt = messages
+                    
+                    async def call_original(prompt_override):
+                        call_kwargs = kwargs.copy()
+                        if prompt_override is not None:
+                            call_kwargs["messages"] = prompt_override
+                        return await original_acompletion(*args[:1] if args else [], **call_kwargs)
+                    
+                    llm_metadata = {
+                        "kind": "llm",
+                        "framework": "crewai",
+                        "model": model,
+                        "prompt": prompt,
+                        "call_original": call_original,
+                    }
+                    
+                    governed = govern_execution(
+                        tool_fn=lambda *a, **kw: original_acompletion(*args, **kwargs),
+                        tool_metadata=llm_metadata,
+                        cortex_hub=cortex_hub,
+                    )
+                    return await governed()
+                
+                litellm.acompletion = patched_acompletion
+            
+            setattr(litellm, _PATCHED_LLM_ATTR, True)
+            logger.info("CrewAI LiteLLM interception patched successfully")
+            
+        except ImportError:
+            logger.debug("LiteLLM not available, skipping LLM interception for CrewAI")
+        except Exception as e:
+            logger.debug("CrewAI LiteLLM interception skipped", reason=str(e))
+
+    def unpatch(self) -> None:
+        """Restore original CrewAI methods."""
+        try:
+            from crewai.tools.structured_tool import CrewStructuredTool
+            
+            if hasattr(CrewStructuredTool, _ORIGINAL_INVOKE_ATTR):
+                original = getattr(CrewStructuredTool, _ORIGINAL_INVOKE_ATTR)
+                CrewStructuredTool.invoke = original
+                setattr(CrewStructuredTool, _PATCHED_ATTR, False)
+            
+            logger.info("CrewAI CrewStructuredTool unpatched")
+            
+            try:
+                from crewai.tools.base_tool import BaseTool
+                if hasattr(BaseTool, _ORIGINAL_RUN_ATTR):
+                    original = getattr(BaseTool, _ORIGINAL_RUN_ATTR)
+                    BaseTool._run = original
+                    setattr(BaseTool, _PATCHED_TOOL_ATTR, False)
+                logger.info("CrewAI BaseTool unpatched")
+            except ImportError:
+                pass
+            
+            # Restore LiteLLM
+            try:
+                import litellm
+                if hasattr(litellm, _ORIGINAL_COMPLETION_ATTR):
+                    litellm.completion = getattr(litellm, _ORIGINAL_COMPLETION_ATTR)
+                if hasattr(litellm, _ORIGINAL_ACOMPLETION_ATTR):
+                    litellm.acompletion = getattr(litellm, _ORIGINAL_ACOMPLETION_ATTR)
+                setattr(litellm, _PATCHED_LLM_ATTR, False)
+                logger.info("CrewAI LiteLLM unpatched")
+            except ImportError:
+                pass
+                
+        except ImportError:
+            pass
+
+    def intercept(self, tool_fn, tool_name, args, **kwargs):
+        """Not used - governance happens via SDK entrypoint."""
+        raise NotImplementedError("Use govern_execution via pipeline")
+
+    def _discover_tools(self) -> list[dict[str, Any]]:
+        """Discover tools from CrewAI (best-effort)."""
+        return []

cortexhub/adapters/langgraph.py

@@ -0,0 +1,386 @@
+"""LangGraph adapter for tool interception.
+
+Intercepts LangGraph tool execution via langchain_core.tools.BaseTool.
+
+LangGraph uses LangChain's tool infrastructure, so we patch BaseTool.invoke().
+For approval workflows, LangGraph provides native support via:
+- interrupt() for human-in-the-loop
+- Checkpointing for state persistence
+
+Architectural rules:
+- Adapter is DUMB plumbing
+- Adapter calls ONE SDK entrypoint: execute_governed_tool()
+- SDK orchestrates everything
+- No governance logic in adapter
+- For approval: Use LangGraph's native interrupt() mechanism
+"""
+
+from typing import Any
+import json
+
+import structlog
+
+from cortexhub.adapters.base import ToolAdapter
+from cortexhub.pipeline import govern_execution
+
+logger = structlog.get_logger(__name__)
+
+# Attribute names for storing originals on class
+_ORIGINAL_INVOKE_ATTR = "__cortexhub_original_invoke__"
+_PATCHED_ATTR = "__cortexhub_patched__"
+_ORIGINAL_CHAT_INVOKE_ATTR = "__cortexhub_original_chat_invoke__"
+_ORIGINAL_CHAT_AINVOKE_ATTR = "__cortexhub_original_chat_ainvoke__"
+_PATCHED_LLM_ATTR = "__cortexhub_llm_patched__"
+_ORIGINAL_TOOLNODE_INIT_ATTR = "__cortexhub_original_toolnode_init__"
+_PATCHED_TOOLNODE_ATTR = "__cortexhub_toolnode_patched__"
+
+
+class LangGraphAdapter(ToolAdapter):
+    """Adapter for LangGraph framework.
+
+    LangGraph uses LangChain's tool infrastructure, so we patch BaseTool.invoke().
+
+    For approval workflows (require_approval policy effect):
+    - We detect if checkpointer is configured
+    - If yes: Use LangGraph's native interrupt() mechanism
+    - If no: Raise clear error asking developer to add checkpointer
+
+    Key properties:
+    - Adapter is dumb plumbing
+    - Calls SDK entrypoint, doesn't implement governance
+    - Original stored on class, not global
+    - Leverages LangGraph's native human-in-the-loop support
+    """
+
+    @property
+    def framework_name(self) -> str:
+        return "langgraph"
+
+    def __init__(self, cortex_hub: Any):
+        super().__init__(cortex_hub)
+        self._discovered_tools: dict[str, dict[str, Any]] = {}
+
+    def _get_framework_modules(self) -> list[str]:
+        return ["langgraph", "langchain_core", "langchain_core.tools"]
+
+    def patch(self) -> None:
+        """Patch LangGraph/LangChain BaseTool.invoke method."""
+        try:
+            from langchain_core.tools import BaseTool
+
+            # Check if already patched
+            if getattr(BaseTool, _PATCHED_ATTR, False):
+                logger.info("LangGraph already patched")
+                return
+
+            # Store original on class
+            if not hasattr(BaseTool, _ORIGINAL_INVOKE_ATTR):
+                setattr(BaseTool, _ORIGINAL_INVOKE_ATTR, BaseTool.invoke)
+
+            tool_original_invoke = getattr(BaseTool, _ORIGINAL_INVOKE_ATTR)
+            cortex_hub = self.cortex_hub
+            adapter = self
+            tools = self._discover_tools()
+            if tools:
+                self._register_tools(tools)
+
+            def patched_invoke(self, input, config=None, **kwargs):
+                """Governed tool invocation."""
+                tool_name = getattr(self, "name", "unknown_tool")
+                tool_description = getattr(self, "description", None)
+
+                # Extract args - preserve structure without rewriting
+                if isinstance(input, dict):
+                    args = input
+                elif hasattr(input, "model_dump"):
+                    args = input.model_dump()
+                elif hasattr(input, "dict"):
+                    args = input.dict()
+                else:
+                    args = {"_raw": input}
+                policy_args = adapter._normalize_policy_args(self, args)
+
+                tool_metadata = {
+                    "name": tool_name,
+                    "description": tool_description,
+                    "framework": "langgraph",
+                }
+                governed_fn = govern_execution(
+                    tool_fn=lambda *a, **kw: tool_original_invoke(
+                        self, input, config=config, **kwargs
+                    ),
+                    tool_metadata=tool_metadata,
+                    cortex_hub=cortex_hub,
+                )
+                return governed_fn(**policy_args)
+
+            # Apply patch
+            BaseTool.invoke = patched_invoke
+            setattr(BaseTool, _PATCHED_ATTR, True)
+
+            logger.info("LangGraph adapter patched successfully")
+
+            # Patch ToolNode to discover tools (best-effort)
+            self._patch_tool_node()
+
+            # Patch LLM invoke for LLM call governance
+            self._patch_llm_invoke(cortex_hub)
+
+        except ImportError:
+            logger.debug("LangGraph/LangChain not available, skipping adapter")
+        except Exception as e:
+            logger.error("Failed to patch LangGraph", error=str(e))
+
+    def _patch_llm_invoke(self, cortex_hub) -> None:
+        """Patch LangChain chat model invoke for LLM call governance."""
+        try:
+            from langchain_core.language_models.chat_models import BaseChatModel
+
+            if getattr(BaseChatModel, _PATCHED_LLM_ATTR, False):
+                return
+
+            if not hasattr(BaseChatModel, _ORIGINAL_CHAT_INVOKE_ATTR):
+                setattr(BaseChatModel, _ORIGINAL_CHAT_INVOKE_ATTR, BaseChatModel.invoke)
+            chat_original_invoke = getattr(BaseChatModel, _ORIGINAL_CHAT_INVOKE_ATTR)
+
+            def patched_chat_invoke(self, input, config=None, **kwargs):
+                model_name = (
+                    getattr(self, "model_name", None) or getattr(self, "model", None) or "unknown"
+                )
+                prompt = input
+
+                def call_original(prompt_override):
+                    return chat_original_invoke(self, prompt_override, config=config, **kwargs)
+
+                llm_metadata = {
+                    "kind": "llm",
+                    "framework": "langgraph",
+                    "model": model_name,
+                    "prompt": prompt,
+                    "call_original": call_original,
+                }
+
+                governed = govern_execution(
+                    tool_fn=lambda *a, **kw: chat_original_invoke(
+                        self, input, config=config, **kwargs
+                    ),
+                    tool_metadata=llm_metadata,
+                    cortex_hub=cortex_hub,
+                )
+                return governed()
+
+            BaseChatModel.invoke = patched_chat_invoke
+
+            # Patch async version too
+            if hasattr(BaseChatModel, "ainvoke"):
+                if not hasattr(BaseChatModel, _ORIGINAL_CHAT_AINVOKE_ATTR):
+                    setattr(BaseChatModel, _ORIGINAL_CHAT_AINVOKE_ATTR, BaseChatModel.ainvoke)
+                chat_original_ainvoke = getattr(BaseChatModel, _ORIGINAL_CHAT_AINVOKE_ATTR)
+
+                async def patched_chat_ainvoke(self, input, config=None, **kwargs):
+                    model_name = (
+                        getattr(self, "model_name", None)
+                        or getattr(self, "model", None)
+                        or "unknown"
+                    )
+                    prompt = input
+
+                    async def call_original(prompt_override):
+                        return await chat_original_ainvoke(
+                            self, prompt_override, config=config, **kwargs
+                        )
+
+                    llm_metadata = {
+                        "kind": "llm",
+                        "framework": "langgraph",
+                        "model": model_name,
+                        "prompt": prompt,
+                        "call_original": call_original,
+                    }
+
+                    governed = govern_execution(
+                        tool_fn=lambda *a, **kw: chat_original_ainvoke(
+                            self, input, config=config, **kwargs
+                        ),
+                        tool_metadata=llm_metadata,
+                        cortex_hub=cortex_hub,
+                    )
+                    return await governed()
+
+                BaseChatModel.ainvoke = patched_chat_ainvoke
+
+            setattr(BaseChatModel, _PATCHED_LLM_ATTR, True)
+            logger.info("LangGraph LLM interception patched successfully")
+
+        except Exception as e:
+            logger.debug("LangGraph LLM interception skipped", reason=str(e))
+
+    def _patch_tool_node(self) -> None:
+        """Patch LangGraph ToolNode to capture tool inventory."""
+        try:
+            from langgraph.prebuilt import ToolNode
+
+            if getattr(ToolNode, _PATCHED_TOOLNODE_ATTR, False):
+                return
+
+            if not hasattr(ToolNode, _ORIGINAL_TOOLNODE_INIT_ATTR):
+                setattr(ToolNode, _ORIGINAL_TOOLNODE_INIT_ATTR, ToolNode.__init__)
+            original_init = getattr(ToolNode, _ORIGINAL_TOOLNODE_INIT_ATTR)
+            adapter = self
+
+            def patched_init(self, tools, *args, **kwargs):
+                original_init(self, tools, *args, **kwargs)
+                try:
+                    adapter._register_tools(adapter._normalize_tools(tools))
+                except Exception as e:
+                    logger.debug("ToolNode tool discovery failed", reason=str(e))
+
+            ToolNode.__init__ = patched_init
+            setattr(ToolNode, _PATCHED_TOOLNODE_ATTR, True)
+            logger.info("LangGraph ToolNode patched for tool discovery")
+        except Exception as e:
+            logger.debug("LangGraph ToolNode patch skipped", reason=str(e))
+
+    def unpatch(self) -> None:
+        """Restore original methods."""
+        try:
+            from langchain_core.tools import BaseTool
+
+            if hasattr(BaseTool, _ORIGINAL_INVOKE_ATTR):
+                BaseTool.invoke = getattr(BaseTool, _ORIGINAL_INVOKE_ATTR)
+                setattr(BaseTool, _PATCHED_ATTR, False)
+                logger.info("LangGraph adapter unpatched")
+
+            # Restore LLM interception
+            try:
+                from langchain_core.language_models.chat_models import BaseChatModel
+
+                if hasattr(BaseChatModel, _ORIGINAL_CHAT_INVOKE_ATTR):
+                    BaseChatModel.invoke = getattr(BaseChatModel, _ORIGINAL_CHAT_INVOKE_ATTR)
+                if hasattr(BaseChatModel, _ORIGINAL_CHAT_AINVOKE_ATTR):
+                    BaseChatModel.ainvoke = getattr(BaseChatModel, _ORIGINAL_CHAT_AINVOKE_ATTR)
+                setattr(BaseChatModel, _PATCHED_LLM_ATTR, False)
+            except ImportError:
+                pass
+
+            # Restore ToolNode init
+            try:
+                from langgraph.prebuilt import ToolNode
+
+                if hasattr(ToolNode, _ORIGINAL_TOOLNODE_INIT_ATTR):
+                    ToolNode.__init__ = getattr(ToolNode, _ORIGINAL_TOOLNODE_INIT_ATTR)
+                setattr(ToolNode, _PATCHED_TOOLNODE_ATTR, False)
+            except ImportError:
+                pass
+        except ImportError:
+            pass
+
+    def intercept(self, tool_fn, tool_name, args, **kwargs):
+        """Not used - governance happens via SDK entrypoint."""
+        raise NotImplementedError("Use execute_governed_tool via patched invoke")
+
+    def _discover_tools(self) -> list[dict[str, Any]]:
+        """Discover tools from LangGraph (best-effort)."""
+        return list(self._discovered_tools.values())
+
+    def _register_tools(self, tools: list[dict[str, Any]]) -> None:
+        """Register tools with backend, merging by name."""
+        if not tools:
+            return
+
+        for tool in tools:
+            name = tool.get("name") or "unknown_tool"
+            self._discovered_tools[name] = tool
+
+        self.cortex_hub.backend.register_tool_inventory(
+            agent_id=self.cortex_hub.agent_id,
+            framework=self.framework_name,
+            tools=list(self._discovered_tools.values()),
+        )
+
+    def _normalize_tools(self, tools: Any) -> list[dict[str, Any]]:
+        """Convert tool objects to inventory payloads."""
+        normalized: list[dict[str, Any]] = []
+
+        if not tools:
+            return normalized
+
+        tool_list = tools if isinstance(tools, list) else [tools]
+
+        for tool in tool_list:
+            name = getattr(tool, "name", None) or getattr(tool, "__name__", None) or "unknown_tool"
+            description = getattr(tool, "description", None) or getattr(tool, "__doc__", None)
+            parameters_schema = self._extract_parameters_schema(tool)
+
+            normalized.append(
+                {
+                    "name": name,
+                    "description": description.strip() if isinstance(description, str) else None,
+                    "parameters_schema": parameters_schema,
+                    "source": "framework",
+                }
+            )
+
+        return normalized
+
+    def _normalize_policy_args(self, tool: Any, raw_args: dict[str, Any]) -> dict[str, Any]:
+        """Best-effort normalize tool args for policy evaluation."""
+        args = raw_args
+        if isinstance(args, dict) and isinstance(args.get("args"), dict):
+            args = args["args"]
+
+        if isinstance(args, str):
+            try:
+                parsed = json.loads(args)
+                if isinstance(parsed, dict):
+                    args = parsed
+            except json.JSONDecodeError:
+                pass
+
+        args_schema = getattr(tool, "args_schema", None)
+        if args_schema and isinstance(args, dict):
+            try:
+                if hasattr(args_schema, "model_validate"):
+                    parsed = args_schema.model_validate(args)
+                elif hasattr(args_schema, "parse_obj"):
+                    parsed = args_schema.parse_obj(args)
+                else:
+                    parsed = None
+                if parsed is not None:
+                    if hasattr(parsed, "model_dump"):
+                        args = parsed.model_dump()
+                    elif hasattr(parsed, "dict"):
+                        args = parsed.dict()
+            except Exception:
+                pass
+
+        return args if isinstance(args, dict) else {"_raw": args}
+
+    def _extract_parameters_schema(self, tool: Any) -> dict[str, Any] | None:
+        """Best-effort JSON schema extraction for tool parameters."""
+        schema = None
+        args_schema = getattr(tool, "args_schema", None)
+
+        if args_schema is not None:
+            if hasattr(args_schema, "model_json_schema"):
+                schema = args_schema.model_json_schema()
+            elif hasattr(args_schema, "schema"):
+                schema = args_schema.schema()
+
+        if schema is None:
+            args = getattr(tool, "args", None)
+            if isinstance(args, dict):
+                schema = {
+                    "type": "object",
+                    "properties": args,
+                    "required": list(args.keys()),
+                }
+
+        if not isinstance(schema, dict):
+            return None
+
+        return {
+            "type": schema.get("type", "object"),
+            "properties": schema.get("properties", {}) or {},
+            "required": schema.get("required", []) or [],
+        }