openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/mcp/tool.py

@@ -0,0 +1,270 @@
+"""Utility functions for MCP integration."""
+
+import re
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation import LocalConversation
+
+import mcp.types
+from litellm import ChatCompletionToolParam
+from pydantic import Field, ValidationError
+
+from openhands.sdk.logger import get_logger
+from openhands.sdk.mcp.client import MCPClient
+from openhands.sdk.mcp.definition import MCPToolAction, MCPToolObservation
+from openhands.sdk.observability.laminar import observe
+from openhands.sdk.tool import (
+    Action,
+    Observation,
+    ToolAnnotations,
+    ToolDefinition,
+    ToolExecutor,
+)
+from openhands.sdk.tool.schema import Schema
+from openhands.sdk.utils.models import DiscriminatedUnionMixin
+
+
+logger = get_logger(__name__)
+
+
+# NOTE: We don't define MCPToolAction because it
+# will be a pydantic BaseModel dynamically created from the MCP tool schema.
+# It will be available as "tool.action_type".
+
+
+def to_camel_case(s: str) -> str:
+    parts = re.split(r"[_\-\s]+", s)
+    return "".join(word.capitalize() for word in parts if word)
+
+
+class MCPToolExecutor(ToolExecutor):
+    """Executor for MCP tools."""
+
+    tool_name: str
+    client: MCPClient
+
+    def __init__(self, tool_name: str, client: MCPClient):
+        self.tool_name = tool_name
+        self.client = client
+
+    @observe(name="MCPToolExecutor.call_tool", span_type="TOOL")
+    async def call_tool(self, action: MCPToolAction) -> MCPToolObservation:
+        async with self.client:
+            assert self.client.is_connected(), "MCP client is not connected."
+            try:
+                logger.debug(
+                    f"Calling MCP tool {self.tool_name} "
+                    f"with args: {action.model_dump()}"
+                )
+                result: mcp.types.CallToolResult = await self.client.call_tool_mcp(
+                    name=self.tool_name, arguments=action.to_mcp_arguments()
+                )
+                return MCPToolObservation.from_call_tool_result(
+                    tool_name=self.tool_name, result=result
+                )
+            except Exception as e:
+                error_msg = f"Error calling MCP tool {self.tool_name}: {str(e)}"
+                logger.error(error_msg, exc_info=True)
+                return MCPToolObservation.from_text(
+                    text=error_msg,
+                    is_error=True,
+                    tool_name=self.tool_name,
+                )
+
+    def __call__(
+        self,
+        action: MCPToolAction,
+        conversation: "LocalConversation | None" = None,  # noqa: ARG002
+    ) -> MCPToolObservation:
+        """Execute an MCP tool call."""
+        return self.client.call_async_from_sync(
+            self.call_tool, action=action, timeout=300
+        )
+
+
+_mcp_dynamic_action_type: dict[str, type[Schema]] = {}
+
+
+def _create_mcp_action_type(action_type: mcp.types.Tool) -> type[Schema]:
+    """Dynamically create a Pydantic model for MCP tool action from schema.
+
+    We create from "Schema" instead of:
+    - "MCPToolAction" because MCPToolAction has a "data" field that
+      wraps all dynamic fields, which we don't want here.
+    - "Action" because Action inherits from DiscriminatedUnionMixin,
+      which includes `kind` field that is not needed here.
+
+    .from_mcp_schema simply defines a new Pydantic model class
+    that inherits from the given base class.
+    We may want to use the returned class to convert fields definitions
+    to openai tool schema.
+    """
+
+    # Tool.name should be unique, so we can cache the created types.
+    mcp_action_type = _mcp_dynamic_action_type.get(action_type.name)
+    if mcp_action_type:
+        return mcp_action_type
+
+    model_name = f"MCP{to_camel_case(action_type.name)}Action"
+    mcp_action_type = Schema.from_mcp_schema(model_name, action_type.inputSchema)
+    _mcp_dynamic_action_type[action_type.name] = mcp_action_type
+    return mcp_action_type
+
+
+class MCPToolDefinition(ToolDefinition[MCPToolAction, MCPToolObservation]):
+    """MCP Tool that wraps an MCP client and provides tool functionality."""
+
+    mcp_tool: mcp.types.Tool = Field(description="The MCP tool definition.")
+
+    @property
+    def name(self) -> str:  # type: ignore[override]
+        """Return the MCP tool name instead of the class name."""
+        return self.mcp_tool.name
+
+    def __call__(
+        self,
+        action: Action,
+        conversation: "LocalConversation | None" = None,  # noqa: ARG002
+    ) -> Observation:
+        """Execute the tool action using the MCP client.
+
+        We dynamically create a new MCPToolAction class with
+        the tool's input schema to validate the action.
+
+        Args:
+            action: The action to execute.
+
+        Returns:
+            The observation result from executing the action.
+        """
+        if not isinstance(action, MCPToolAction):
+            raise ValueError(
+                f"MCPTool can only execute MCPToolAction actions, got {type(action)}",
+            )
+        assert self.name == self.mcp_tool.name
+        mcp_action_type = _create_mcp_action_type(self.mcp_tool)
+        try:
+            mcp_action_type.model_validate(action.data)
+        except ValidationError as e:
+            # Surface validation errors as an observation instead of crashing
+            error_msg = f"Validation error for MCP tool '{self.name}' args: {e}"
+            logger.error(error_msg, exc_info=True)
+            return MCPToolObservation.from_text(
+                text=error_msg,
+                is_error=True,
+                tool_name=self.name,
+            )
+
+        return super().__call__(action, conversation)
+
+    def action_from_arguments(self, arguments: dict[str, Any]) -> MCPToolAction:
+        """Create an MCPToolAction from parsed arguments with early validation.
+
+        We validate the raw arguments against the MCP tool's input schema here so
+        Agent._get_action_event can catch ValidationError and surface an
+        AgentErrorEvent back to the model instead of crashing later during tool
+        execution. On success, we return MCPToolAction with sanitized arguments.
+
+        Args:
+            arguments: The parsed arguments from the tool call.
+
+        Returns:
+            The MCPToolAction instance with data populated from the arguments.
+
+        Raises:
+            ValidationError: If the arguments do not conform to the tool schema.
+        """
+        # Drop None-valued keys before validation to avoid type errors
+        # on optional fields
+        prefiltered_args = {k: v for k, v in (arguments or {}).items() if v is not None}
+        # Validate against the dynamically created action type (from MCP schema)
+        mcp_action_type = _create_mcp_action_type(self.mcp_tool)
+        validated = mcp_action_type.model_validate(prefiltered_args)
+        # Use exclude_none to avoid injecting nulls back to the call
+        # Exclude DiscriminatedUnionMixin fields (e.g., 'kind') as they're
+        # internal to OpenHands and not part of the MCP tool schema
+        exclude_fields = set(DiscriminatedUnionMixin.model_fields.keys())
+        sanitized = validated.model_dump(exclude_none=True, exclude=exclude_fields)
+        return MCPToolAction(data=sanitized)
+
+    @classmethod
+    def create(
+        cls,
+        mcp_tool: mcp.types.Tool,
+        mcp_client: MCPClient,
+    ) -> Sequence["MCPToolDefinition"]:
+        try:
+            annotations = (
+                ToolAnnotations.model_validate(
+                    mcp_tool.annotations.model_dump(exclude_none=True)
+                )
+                if mcp_tool.annotations
+                else None
+            )
+
+            tool_instance = cls(
+                description=mcp_tool.description or "No description provided",
+                action_type=MCPToolAction,
+                observation_type=MCPToolObservation,
+                annotations=annotations,
+                meta=mcp_tool.meta,
+                executor=MCPToolExecutor(tool_name=mcp_tool.name, client=mcp_client),
+                # pass-through fields (enabled by **extra in Tool.create)
+                mcp_tool=mcp_tool,
+            )
+            return [tool_instance]
+        except ValidationError as e:
+            logger.error(
+                f"Validation error creating MCPTool for {mcp_tool.name}: "
+                f"{e.json(indent=2)}",
+                exc_info=True,
+            )
+            raise e
+
+    def to_mcp_tool(
+        self,
+        input_schema: dict[str, Any] | None = None,
+        output_schema: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        if input_schema is not None or output_schema is not None:
+            raise ValueError("MCPTool.to_mcp_tool does not support overriding schemas")
+
+        return super().to_mcp_tool(
+            input_schema=self.mcp_tool.inputSchema,
+            output_schema=self.observation_type.to_mcp_schema()
+            if self.observation_type
+            else None,
+        )
+
+    def to_openai_tool(
+        self,
+        add_security_risk_prediction: bool = False,
+        action_type: type[Schema] | None = None,
+    ) -> ChatCompletionToolParam:
+        """Convert a Tool to an OpenAI tool.
+
+        For MCP, we dynamically create the action_type (type: Schema)
+        from the MCP tool input schema, and pass it to the parent method.
+        It will use the .model_fields from this pydantic model to
+        generate the OpenAI-compatible tool schema.
+
+        Args:
+            add_security_risk_prediction: Whether to add a `security_risk` field
+                to the action schema for LLM to predict. This is useful for
+                tools that may have safety risks, so the LLM can reason about
+                the risk level before calling the tool.
+        """
+        if action_type is not None:
+            raise ValueError(
+                "MCPTool.to_openai_tool does not support overriding action_type"
+            )
+
+        assert self.name == self.mcp_tool.name
+        mcp_action_type = _create_mcp_action_type(self.mcp_tool)
+        return super().to_openai_tool(
+            add_security_risk_prediction=add_security_risk_prediction,
+            action_type=mcp_action_type,
+        )

openhands/sdk/mcp/utils.py

@@ -0,0 +1,83 @@
+"""Utility functions for MCP integration."""
+
+import logging
+
+import mcp.types
+from fastmcp.client.logging import LogMessage
+from fastmcp.mcp_config import MCPConfig
+
+from openhands.sdk.logger import get_logger
+from openhands.sdk.mcp.client import MCPClient
+from openhands.sdk.mcp.exceptions import MCPTimeoutError
+from openhands.sdk.mcp.tool import MCPToolDefinition
+from openhands.sdk.tool.tool import ToolDefinition
+
+
+logger = get_logger(__name__)
+LOGGING_LEVEL_MAP = logging.getLevelNamesMapping()
+
+
+async def log_handler(message: LogMessage):
+    """
+    Handles incoming logs from the MCP server and forwards them
+    to the standard Python logging system.
+    """
+    msg = message.data.get("msg")
+    extra = message.data.get("extra")
+
+    # Convert the MCP log level to a Python log level
+    level = LOGGING_LEVEL_MAP.get(message.level.upper(), logging.INFO)
+
+    # Log the message using the standard logging library
+    logger.log(level, msg, extra=extra)
+
+
+async def _list_tools(client: MCPClient) -> list[ToolDefinition]:
+    """List tools from an MCP client."""
+    tools: list[ToolDefinition] = []
+
+    async with client:
+        assert client.is_connected(), "MCP client is not connected."
+        mcp_type_tools: list[mcp.types.Tool] = await client.list_tools()
+        for mcp_tool in mcp_type_tools:
+            tool_sequence = MCPToolDefinition.create(
+                mcp_tool=mcp_tool, mcp_client=client
+            )
+            tools.extend(tool_sequence)  # Flatten sequence into list
+    assert not client.is_connected(), (
+        "MCP client should be disconnected after listing tools."
+    )
+    return tools
+
+
+def create_mcp_tools(
+    config: dict | MCPConfig,
+    timeout: float = 30.0,
+) -> list[MCPToolDefinition]:
+    """Create MCP tools from MCP configuration."""
+    tools: list[MCPToolDefinition] = []
+    if isinstance(config, dict):
+        config = MCPConfig.model_validate(config)
+    client = MCPClient(config, log_handler=log_handler)
+
+    try:
+        tools = client.call_async_from_sync(_list_tools, timeout=timeout, client=client)
+    except TimeoutError as e:
+        # Extract server names from config for better error message
+        server_names = (
+            list(config.mcpServers.keys()) if config.mcpServers else ["unknown"]
+        )
+        error_msg = (
+            f"MCP tool listing timed out after {timeout} seconds.\n"
+            f"MCP servers configured: {', '.join(server_names)}\n\n"
+            "Possible solutions:\n"
+            "  1. Increase the timeout value (default is 30 seconds)\n"
+            "  2. Check if the MCP server is running and responding\n"
+            "  3. Verify network connectivity to the MCP server\n"
+        )
+        raise MCPTimeoutError(
+            error_msg, timeout=timeout, config=config.model_dump()
+        ) from e
+
+    logger.info(f"Created {len(tools)} MCP tools: {[t.name for t in tools]}")
+    return tools

openhands/sdk/observability/__init__.py

@@ -0,0 +1,4 @@
+from openhands.sdk.observability.laminar import maybe_init_laminar, observe
+
+
+__all__ = ["maybe_init_laminar", "observe"]

openhands/sdk/observability/laminar.py

@@ -0,0 +1,166 @@
+from collections.abc import Callable
+from typing import (
+    Any,
+    Literal,
+)
+
+import litellm
+from lmnr import (
+    Instruments,
+    Laminar,
+    LaminarLiteLLMCallback,
+    observe as laminar_observe,
+)
+from opentelemetry import trace
+
+from openhands.sdk.logger import get_logger
+from openhands.sdk.observability.utils import get_env
+
+
+logger = get_logger(__name__)
+
+
+def maybe_init_laminar():
+    """Initialize Laminar if the environment variables are set.
+
+    Example configuration:
+    OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4317/v1/traces
+
+    # comma separated, key=value url-encoded pairs
+    OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20<KEY>,X-Key=<CUSTOM_VALUE>"
+
+    # grpc is assumed if not specified
+    OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf # or grpc/protobuf
+    # or
+    OTEL_EXPORTER=otlp_http # or otlp_grpc
+    """
+    if should_enable_observability():
+        if _is_otel_backend_laminar():
+            Laminar.initialize()
+        else:
+            # Do not enable browser session replays for non-laminar backends
+            Laminar.initialize(
+                disabled_instruments=[
+                    Instruments.BROWSER_USE_SESSION,
+                    Instruments.PATCHRIGHT,
+                    Instruments.PLAYWRIGHT,
+                ],
+            )
+        litellm.callbacks.append(LaminarLiteLLMCallback())
+    else:
+        logger.debug(
+            "Observability/OTEL environment variables are not set. "
+            "Skipping Laminar initialization."
+        )
+
+
+def observe[**P, R](
+    *,
+    name: str | None = None,
+    session_id: str | None = None,
+    user_id: str | None = None,
+    ignore_input: bool = False,
+    ignore_output: bool = False,
+    span_type: Literal["DEFAULT", "LLM", "TOOL"] = "DEFAULT",
+    ignore_inputs: list[str] | None = None,
+    input_formatter: Callable[P, str] | None = None,
+    output_formatter: Callable[[R], str] | None = None,
+    metadata: dict[str, Any] | None = None,
+    tags: list[str] | None = None,
+    preserve_global_context: bool = False,
+    **kwargs: dict[str, Any],
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        return laminar_observe(
+            name=name,
+            session_id=session_id,
+            user_id=user_id,
+            ignore_input=ignore_input,
+            ignore_output=ignore_output,
+            span_type=span_type,
+            ignore_inputs=ignore_inputs,
+            input_formatter=input_formatter,
+            output_formatter=output_formatter,
+            metadata=metadata,
+            tags=tags,
+            preserve_global_context=preserve_global_context,
+            **kwargs,
+        )(func)
+
+    return decorator
+
+
+def should_enable_observability():
+    keys = [
+        "LMNR_PROJECT_API_KEY",
+        "OTEL_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_ENDPOINT",
+    ]
+    if any(get_env(key) for key in keys):
+        return True
+    if Laminar.is_initialized():
+        return True
+    return False
+
+
+def _is_otel_backend_laminar():
+    """Simple heuristic to check if the OTEL backend is Laminar.
+    Caveat: This will still be True if another backend uses the same
+    authentication scheme, and the user uses LMNR_PROJECT_API_KEY
+    instead of OTEL_HEADERS to authenticate.
+    """
+    key = get_env("LMNR_PROJECT_API_KEY")
+    return key is not None and key != ""
+
+
+class SpanManager:
+    """Manages a stack of active spans and their associated tokens."""
+
+    def __init__(self):
+        self._stack: list[trace.Span] = []
+
+    def start_active_span(self, name: str, session_id: str | None = None) -> None:
+        """Start a new active span and push it to the stack."""
+        span = Laminar.start_active_span(name)
+        if session_id:
+            Laminar.set_trace_session_id(session_id)
+        self._stack.append(span)
+
+    def end_active_span(self) -> None:
+        """End the most recent active span by popping it from the stack."""
+        if not self._stack:
+            logger.warning("Attempted to end active span, but stack is empty")
+            return
+
+        try:
+            span = self._stack.pop()
+            if span and span.is_recording():
+                span.end()
+        except IndexError:
+            logger.warning("Attempted to end active span, but stack is empty")
+            return
+
+
+_span_manager: SpanManager | None = None
+
+
+def _get_span_manager() -> SpanManager:
+    global _span_manager
+    if _span_manager is None:
+        _span_manager = SpanManager()
+    return _span_manager
+
+
+def start_active_span(name: str, session_id: str | None = None) -> None:
+    """Start a new active span using the global span manager."""
+    _get_span_manager().start_active_span(name, session_id)
+
+
+def end_active_span() -> None:
+    """End the most recent active span using the global span manager."""
+    try:
+        _get_span_manager().end_active_span()
+    except Exception:
+        logger.debug("Error ending active span")
+        pass

openhands/sdk/observability/utils.py

@@ -0,0 +1,20 @@
+import os
+
+from dotenv import dotenv_values
+
+from openhands.sdk.event import ActionEvent
+
+
+def get_env(key: str) -> str | None:
+    """Get an environment variable from the environment or the dotenv file."""
+    return os.getenv(key) or dotenv_values().get(key)
+
+
+def extract_action_name(action_event: ActionEvent) -> str:
+    try:
+        if action_event.action is not None and hasattr(action_event.action, "kind"):
+            return action_event.action.kind
+        else:
+            return action_event.tool_name
+    except Exception:
+        return "agent.execute_action"

openhands/sdk/secret/__init__.py

@@ -0,0 +1,19 @@
+"""Secret management module for handling sensitive data.
+
+This module provides classes and types for managing secrets in OpenHands.
+"""
+
+from openhands.sdk.secret.secrets import (
+    LookupSecret,
+    SecretSource,
+    SecretValue,
+    StaticSecret,
+)
+
+
+__all__ = [
+    "SecretSource",
+    "StaticSecret",
+    "LookupSecret",
+    "SecretValue",
+]

openhands/sdk/secret/secrets.py

@@ -0,0 +1,92 @@
+"""Secret sources and types for handling sensitive data."""
+
+from abc import ABC, abstractmethod
+
+import httpx
+from pydantic import Field, SecretStr, field_serializer, field_validator
+
+from openhands.sdk.utils.models import DiscriminatedUnionMixin
+from openhands.sdk.utils.pydantic_secrets import serialize_secret, validate_secret
+
+
+class SecretSource(DiscriminatedUnionMixin, ABC):
+    """Source for a named secret which may be obtained dynamically"""
+
+    description: str | None = Field(
+        default=None,
+        description="Optional description for this secret",
+    )
+
+    @abstractmethod
+    def get_value(self) -> str | None:
+        """Get the value of a secret in plain text"""
+
+
+class StaticSecret(SecretSource):
+    """A secret stored locally"""
+
+    value: SecretStr
+
+    def get_value(self):
+        return self.value.get_secret_value()
+
+    @field_validator("value")
+    @classmethod
+    def _validate_secrets(cls, v: SecretStr | None, info):
+        return validate_secret(v, info)
+
+    @field_serializer("value", when_used="always")
+    def _serialize_secrets(self, v: SecretStr | None, info):
+        return serialize_secret(v, info)
+
+
+class LookupSecret(SecretSource):
+    """A secret looked up from some external url"""
+
+    url: str
+    headers: dict[str, str] = Field(default_factory=dict)
+
+    def get_value(self):
+        response = httpx.get(self.url, headers=self.headers, timeout=30.0)
+        response.raise_for_status()
+        return response.text
+
+    @field_validator("headers")
+    @classmethod
+    def _validate_secrets(cls, headers: dict[str, str], info):
+        result = {}
+        for key, value in headers.items():
+            if _is_secret_header(key):
+                secret_value = validate_secret(SecretStr(value), info)
+                assert secret_value is not None
+                result[key] = secret_value.get_secret_value()
+            else:
+                result[key] = value
+        return result
+
+    @field_serializer("headers", when_used="always")
+    def _serialize_secrets(self, headers: dict[str, str], info):
+        result = {}
+        for key, value in headers.items():
+            if _is_secret_header(key):
+                secret_value = serialize_secret(SecretStr(value), info)
+                assert secret_value is not None
+                result[key] = secret_value
+            else:
+                result[key] = value
+        return result
+
+
+_SECRET_HEADERS = ["AUTHORIZATION", "KEY", "SECRET"]
+
+
+def _is_secret_header(key: str):
+    key = key.upper()
+    for secret in _SECRET_HEADERS:
+        if secret in key:
+            return True
+    return False
+
+
+# Type alias for secret values - can be a plain string or a SecretSource
+SecretValue = str | SecretSource

openhands/sdk/security/__init__.py

@@ -0,0 +1,6 @@
+from openhands.sdk.security.risk import SecurityRisk
+
+
+__all__ = [
+    "SecurityRisk",
+]