feat(llm): add native Databricks Unity AI Gateway provider

openhands-sdk/openhands/sdk/__init__.py

@@ -117,6 +117,27 @@
 _print_banner(__version__)
 
 
+def create_llm(model: str = "", **kwargs) -> LLM:
+    """Factory function that routes to the correct LLM subclass.
+
+    Routes models with the "databricks/" prefix to DatabricksLLM (native FMAPI
+    provider, bypassing LiteLLM).  All other models use the base LLM class.
+
+    Uses lazy import for DatabricksLLM to avoid circular import and to keep
+    Databricks dependencies optional (install via: pip install openhands-sdk[databricks]).
+
+    Example:
+        llm = create_llm("databricks/databricks-meta-llama-3-3-70b-instruct",
+                         databricks_host="https://adb-xxx.azuredatabricks.net",
+                         api_key=SecretStr("dapi..."))
+        llm = create_llm("claude-sonnet-4-20250514", api_key=SecretStr("sk-ant-..."))
+    """
+    if model.startswith("databricks/"):
+        from openhands.sdk.llm.providers.databricks.llm import DatabricksLLM
+
+        return DatabricksLLM(model=model, **kwargs)
+    return LLM(model=model, **kwargs)
+
 __all__ = [
     "LLM",
     "LLM_PROFILE_SCHEMA_VERSION",
@@ -203,4 +224,5 @@
     "load_user_skills",
     "page_iterator",
     "__version__",
+    "create_llm",
 ]

openhands-sdk/openhands/sdk/agent/base.py

@@ -8,7 +8,7 @@
 from abc import ABC, abstractmethod
 from collections.abc import Generator, Iterable, Sequence
 from concurrent.futures import ThreadPoolExecutor
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Annotated, Any, Literal
 
 from pydantic import (
     BaseModel,
@@ -17,6 +17,7 @@
     PrivateAttr,
     SecretStr,
     SerializationInfo,
+    SerializeAsAny,
     ValidationInfo,
     model_serializer,
     model_validator,
@@ -110,7 +111,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         arbitrary_types_allowed=True,
     )
 
-    llm: LLM = Field(
+    llm: Annotated[LLM, SerializeAsAny()] = Field(
         ...,
         description="LLM configuration for the agent.",
         examples=[

openhands-sdk/openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -1,8 +1,9 @@
 import os
 from collections.abc import Sequence
 from enum import Enum
+from typing import Annotated
 
-from pydantic import Field, model_validator
+from pydantic import Field, SerializeAsAny, model_validator
 
 from openhands.sdk.context.condenser.base import (
     CondensationRequirement,
@@ -43,7 +44,7 @@ class LLMSummarizingCondenser(RollingCondenser):
     it is the same as the one defined in this condenser.
     """
 
-    llm: LLM
+    llm: Annotated[LLM, SerializeAsAny()]
     max_size: int = Field(default=240, gt=0)
     max_tokens: int | None = None
 

openhands-sdk/openhands/sdk/event/conversation_error.py

@@ -1,9 +1,78 @@
+import re
+
 from pydantic import Field
 from rich.text import Text
 
 from openhands.sdk.event.base import Event
 
 
+# ---------------------------------------------------------------------------
+# Hint rules: list of (pattern, hint_text) pairs.  The first matching pattern
+# wins.  Patterns are matched case-insensitively against ``detail``.
+# ---------------------------------------------------------------------------
+_HINT_RULES: list[tuple[re.Pattern[str], str]] = [
+    # Databricks AI Gateway: endpoint not found in workspace (404).
+    # Typically means cross-geography routing is disabled, or the endpoint
+    # has not been deployed in this workspace.
+    (
+        re.compile(
+            r"\[404\]\s*AI\s+Gateway\s+endpoint\s+['\"]?(\S+?)['\"]?\s+does\s+not\s+exist",
+            re.IGNORECASE,
+        ),
+        (
+            "This Databricks endpoint is not available in your workspace.\n"
+            "Possible reasons:\n"
+            "  • The model requires cross-geography routing, which is not\n"
+            "    enabled in your workspace (contact your admin).\n"
+            "  • The endpoint name is misspelled or not yet deployed.\n"
+            "Tip: Open Settings → click 'Refresh Models' to see the endpoints\n"
+            "that are actually available in your workspace, then save a\n"
+            "different model."
+        ),
+    ),
+    # Databricks: org-level access denied (403 Invalid access to Org).
+    # Gemini and other cross-geography models route through a Databricks
+    # global GCP org.  The 403 means that routing is not enabled for this
+    # workspace account.
+    (
+        re.compile(r"\[403\].*Invalid\s+access\s+to\s+Org", re.IGNORECASE),
+        (
+            "Your workspace does not have permission to access this model.\n"
+            "This error most commonly occurs with Gemini models, which require\n"
+            "cross-geography routing through a Databricks GCP organisation.\n"
+            "Action: ask your Databricks account admin to enable\n"
+            "  'Cross-geography model serving' for your account, or choose a\n"
+            "  different model (Claude / Llama / DBRX) that runs within your\n"
+            "  workspace region.\n"
+            "Tip: Open Settings → click '↻ Refresh Models' to see only the\n"
+            "endpoints available in your workspace, then pick a different model."
+        ),
+    ),
+    # Databricks: authentication failure (401 / token expired).
+    (
+        re.compile(r"\[401\].*databricks|databricks.*\[401\]|UNAUTHENTICATED", re.IGNORECASE),
+        (
+            "Databricks authentication failed.\n"
+            "Tip: Open Settings and re-authenticate (re-run the browser sign-in\n"
+            "for U2M, or verify your client credentials for M2M)."
+        ),
+    ),
+    # Generic LiteLLM / provider rate-limit.
+    (
+        re.compile(r"\[429\]|rate.?limit|too many requests", re.IGNORECASE),
+        "The model endpoint returned a rate-limit error.  Wait a moment and retry.",
+    ),
+]
+
+
+def _get_hint(detail: str) -> str | None:
+    """Return the first matching hint for the given error detail, or None."""
+    for pattern, hint in _HINT_RULES:
+        if pattern.search(detail):
+            return hint
+    return None
+
+
 class ConversationErrorEvent(Event):
     """
     Conversation-level failure that is NOT sent back to the LLM.
@@ -34,4 +103,10 @@ def visualize(self) -> Text:
         content.append(self.code)
         content.append("\n\nDetail:\n", style="bold")
         content.append(self.detail)
+
+        hint = _get_hint(self.detail)
+        if hint:
+            content.append("\n\nHint:\n", style="bold yellow")
+            content.append(hint, style="yellow")
+
         return content

openhands-sdk/openhands/sdk/llm/__init__.py

@@ -32,6 +32,16 @@
 )
 from openhands.sdk.llm.utils.verified_models import VERIFIED_MODELS
 
+# Eagerly import DatabricksLLM so it registers with LLM.__subclasses__() at
+# module-load time.  This ensures that LLM._dispatch_to_provider_subclass can
+# reconstruct a DatabricksLLM when deserializing persisted agent JSON that
+# carries provider="databricks" — even in processes (e.g. the agent server)
+# that never explicitly import the Databricks provider.
+try:
+    from openhands.sdk.llm.providers.databricks.llm import DatabricksLLM  # noqa: F401
+except Exception:  # pragma: no cover — optional dependency
+    pass
+
 
 __all__ = [
     # Auth

openhands-sdk/openhands/sdk/llm/llm.py

@@ -14,8 +14,10 @@
     BaseModel,
     ConfigDict,
     Field,
+    ModelWrapValidatorHandler,
     PrivateAttr,
     SecretStr,
+    ValidationInfo,
     field_serializer,
     field_validator,
     model_validator,
@@ -509,6 +511,38 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
     # =========================================================================
     # Validators
     # =========================================================================
+    @model_validator(mode="wrap")
+    @classmethod
+    def _dispatch_to_provider_subclass(
+        cls,
+        data: Any,
+        handler: ModelWrapValidatorHandler["LLM"],
+        info: ValidationInfo,
+    ) -> "LLM":
+        """Route persisted agent JSON to the matching LLM subclass.
+
+        When a saved agent is rehydrated the ``llm`` dict may carry a
+        ``provider`` key written by a subclass (e.g. ``"provider":
+        "databricks"``). Without this, ``LLM.model_validate(data)`` would
+        build a base ``LLM`` and silently drop the subclass-only fields.
+
+        Only fires when called directly on the base ``LLM`` class with a
+        plain dict — subclass validators and non-dict inputs pass through
+        unchanged.  Subclasses are discovered generically via
+        ``__subclasses__()`` keyed off their ``provider`` Literal annotation,
+        so no provider names are hardcoded here.
+        """
+        if cls is not LLM or not isinstance(data, dict):
+            return handler(data)
+        provider = data.get("provider")
+        if not provider:
+            return handler(data)
+        for sub in LLM.__subclasses__():
+            f = sub.model_fields.get("provider")
+            if f and provider in getattr(f.annotation, "__args__", ()):
+                return sub.model_validate(data, context=info.context)
+        return handler(data)
+
     @field_validator(
         "api_key", "aws_access_key_id", "aws_secret_access_key", "aws_session_token"
     )

openhands-sdk/openhands/sdk/llm/providers/__init__.py

@@ -0,0 +1,3 @@
+# Provider implementations for the OpenHands V1 SDK LLM layer.
+# Each provider subpackage contains a DatabricksLLM (or equivalent) subclass
+# that bypasses LiteLLM for direct, PWAF-compliant API communication.