Skip to content

πŸ™Œ OpenHands: AI-Driven Development

refactor(settings): replace LLMAgentSettings with OpenHandsAgentSettings and drop compat shim (#14217)

simonrosenberg72ac92f4aa6e
diff --git a/openhands/app_server/app_conversation/app_conversation_models.py b/openhands/app_server/app_conversation/app_conversation_models.py
index f151ea8a7d..1d23294476 100644
--- a/openhands/app_server/app_conversation/app_conversation_models.py
+++ b/openhands/app_server/app_conversation/app_conversation_models.py
@@ -102,7 +102,7 @@ class AppConversationInfo(BaseModel):
trigger: ConversationTrigger | None = None
pr_number: list[int] = Field(default_factory=list)
llm_model: str | None = None
- agent_kind: str = 'llm'
+ agent_kind: str = 'openhands'
metrics: MetricsSnapshot | None = None
diff --git a/openhands/app_server/app_conversation/live_status_app_conversation_service.py b/openhands/app_server/app_conversation/live_status_app_conversation_service.py
index a907eb450a..e16528e70d 100644
--- a/openhands/app_server/app_conversation/live_status_app_conversation_service.py
+++ b/openhands/app_server/app_conversation/live_status_app_conversation_service.py
@@ -96,13 +96,13 @@ from openhands.app_server.utils.llm_metadata import (
get_llm_metadata,
should_set_litellm_extra_body,
)
-from openhands.app_server.utils.sdk_settings_compat import ACPAgentSettings
from openhands.sdk import Agent, AgentContext, LocalWorkspace
from openhands.sdk.agent.acp_agent import ACPAgent
from openhands.sdk.hooks import HookConfig
from openhands.sdk.llm import LLM
from openhands.sdk.plugin import PluginSource
from openhands.sdk.secret import LookupSecret, StaticSecret
+from openhands.sdk.settings import ACPAgentSettings
from openhands.sdk.utils.paging import page_iterator
from openhands.sdk.workspace.remote.async_remote_workspace import AsyncRemoteWorkspace
from openhands.server.types import AppMode
@@ -130,18 +130,18 @@ def _split_ids_by_kind(
conversation_ids: list[str],
conversation_kind_by_id: dict[str, str],
) -> tuple[list[str], list[str]]:
- """Split conversation IDs into (llm_ids, acp_ids) based on their agent_kind."""
- llm_ids = [
+ """Split conversation IDs into (openhands_ids, acp_ids) by agent_kind."""
+ openhands_ids = [
cid
for cid in conversation_ids
- if conversation_kind_by_id.get(cid, 'llm') != 'acp'
+ if conversation_kind_by_id.get(cid, 'openhands') != 'acp'
]
acp_ids = [
cid
for cid in conversation_ids
- if conversation_kind_by_id.get(cid, 'llm') == 'acp'
+ if conversation_kind_by_id.get(cid, 'openhands') == 'acp'
]
- return llm_ids, acp_ids
+ return openhands_ids, acp_ids
# Planning agent instruction to prevent "Ready to proceed?" behavior
@@ -381,7 +381,7 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
display_model = start_conversation_request.agent.acp_model
else:
info = ConversationInfo.model_validate(response.json())
- agent_kind = 'llm'
+ agent_kind = 'openhands'
display_model = start_conversation_request.agent.llm.model
# Store info...
@@ -518,7 +518,9 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
conversation_kind_by_id = conversation_kind_by_id or {}
- llm_ids, acp_ids = _split_ids_by_kind(conversation_ids, conversation_kind_by_id)
+ openhands_ids, acp_ids = _split_ids_by_kind(
+ conversation_ids, conversation_kind_by_id
+ )
agent_server_url = self._get_agent_server_url(sandbox)
headers: dict[str, str] = {}
@@ -527,12 +529,12 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
results: list[ConversationInfo | ACPConversationInfo] = []
- # Fetch LLM conversations
- if llm_ids:
+ # Fetch OpenHands conversations
+ if openhands_ids:
try:
url = f'{agent_server_url.rstrip("/")}/api/conversations'
response = await self.httpx_client.get(
- url, params={'ids': llm_ids}, headers=headers
+ url, params={'ids': openhands_ids}, headers=headers
)
response.raise_for_status()
data = response.json()
@@ -540,12 +542,12 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
results.extend(c for c in infos if c)
except httpx.HTTPStatusError:
_logger.warning(
- f'Error getting LLM conversation status from sandbox {sandbox.id}',
+ f'Error getting OpenHands conversation status from sandbox {sandbox.id}',
exc_info=True,
)
except Exception:
_logger.exception(
- f'Error getting LLM conversation status from sandbox {sandbox.id}',
+ f'Error getting OpenHands conversation status from sandbox {sandbox.id}',
stack_info=True,
)
diff --git a/openhands/app_server/app_conversation/sql_app_conversation_info_service.py b/openhands/app_server/app_conversation/sql_app_conversation_info_service.py
index 9a14e6b153..3a730b1e76 100644
--- a/openhands/app_server/app_conversation/sql_app_conversation_info_service.py
+++ b/openhands/app_server/app_conversation/sql_app_conversation_info_service.py
@@ -560,7 +560,7 @@ class SQLAppConversationInfoService(AppConversationInfoService):
trigger=ConversationTrigger(stored.trigger) if stored.trigger else None,
pr_number=stored.pr_number or [],
llm_model=stored.llm_model,
- agent_kind=stored.agent_kind or 'llm',
+ agent_kind=stored.agent_kind or 'openhands',
metrics=metrics,
parent_conversation_id=(
UUID(stored.parent_conversation_id)
diff --git a/openhands/app_server/settings/settings_models.py b/openhands/app_server/settings/settings_models.py
index 2814cf108d..1f80e89081 100644
--- a/openhands/app_server/settings/settings_models.py
+++ b/openhands/app_server/settings/settings_models.py
@@ -29,14 +29,14 @@ from openhands.app_server.integrations.provider import ProviderToken
from openhands.app_server.integrations.service_types import ProviderType
from openhands.app_server.settings.llm_profiles import LLMProfiles
from openhands.app_server.utils.jsonpatch_compat import deep_merge
-from openhands.app_server.utils.sdk_settings_compat import (
+from openhands.sdk.settings import (
ACPAgentSettings,
AgentSettingsConfig,
- LLMAgentSettings,
+ ConversationSettings,
+ OpenHandsAgentSettings,
default_agent_settings,
validate_agent_settings,
)
-from openhands.sdk.settings import ConversationSettings
def _coerce_value(value: Any) -> Any:
@@ -253,7 +253,7 @@ class Settings(BaseModel):
@field_serializer('agent_settings')
def agent_settings_serializer(
self,
- agent_settings: LLMAgentSettings | ACPAgentSettings,
+ agent_settings: OpenHandsAgentSettings | ACPAgentSettings,
info: SerializationInfo,
) -> dict[str, Any]:
context = info.context or {}
@@ -292,7 +292,7 @@ class Settings(BaseModel):
agent_settings = data.get('agent_settings')
if isinstance(agent_settings, dict):
data['agent_settings'] = _coerce_dict_secrets(agent_settings)
- elif isinstance(agent_settings, (LLMAgentSettings, ACPAgentSettings)):
+ elif isinstance(agent_settings, (OpenHandsAgentSettings, ACPAgentSettings)):
data['agent_settings'] = agent_settings.model_dump(
mode='json', context={'expose_secrets': True}
)
@@ -332,7 +332,7 @@ class Settings(BaseModel):
def secrets_store_serializer(self, secrets: Any, info: SerializationInfo):
return {'provider_tokens': {}}
- def to_agent_settings(self) -> LLMAgentSettings | ACPAgentSettings:
+ def to_agent_settings(self) -> OpenHandsAgentSettings | ACPAgentSettings:
return self.agent_settings
def get_agent_settings_display(self) -> dict[str, Any]:
diff --git a/openhands/app_server/settings/settings_router.py b/openhands/app_server/settings/settings_router.py
index 7b6f58c367..3422bdca5a 100644
--- a/openhands/app_server/settings/settings_router.py
+++ b/openhands/app_server/settings/settings_router.py
@@ -43,12 +43,12 @@ from openhands.app_server.utils.llm import (
resolve_llm_base_url,
)
from openhands.app_server.utils.logger import openhands_logger as logger
-from openhands.app_server.utils.sdk_settings_compat import (
- LLMAgentSettings,
+from openhands.sdk.llm import LLM
+from openhands.sdk.settings import (
+ ConversationSettings,
+ OpenHandsAgentSettings,
export_agent_settings_schema,
)
-from openhands.sdk.llm import LLM
-from openhands.sdk.settings import ConversationSettings
from openhands.server.shared import config
LITE_LLM_API_URL = os.environ.get(
@@ -70,7 +70,7 @@ def _post_merge_llm_fixups(settings: Settings) -> None:
rules to :func:`openhands.app_server.utils.llm.resolve_llm_base_url` so the
personal-save and enterprise org-defaults paths stay in lockstep.
"""
- if not isinstance(settings.agent_settings, LLMAgentSettings):
+ if not isinstance(settings.agent_settings, OpenHandsAgentSettings):
return
llm = settings.agent_settings.llm
llm.base_url = resolve_llm_base_url(
diff --git a/openhands/app_server/utils/sdk_settings_compat.py b/openhands/app_server/utils/sdk_settings_compat.py
deleted file mode 100644
index e896ce0510..0000000000
--- a/openhands/app_server/utils/sdk_settings_compat.py
+++ /dev/null
@@ -1,53 +0,0 @@
-"""SDK compatibility shim for the discriminated-union ``AgentSettings`` rework."""
-
-from typing import Any
-
-try:
- from openhands.sdk.settings import ( # type: ignore[attr-defined]
- ACPAgentSettings,
- AgentSettingsConfig,
- LLMAgentSettings,
- default_agent_settings,
- export_agent_settings_schema,
- validate_agent_settings,
- )
-
- _HAS_DISCRIMINATED_UNION = True
-except ImportError:
- _HAS_DISCRIMINATED_UNION = False
- from openhands.sdk.settings import AgentSettings
-
- LLMAgentSettings = AgentSettings # type: ignore[misc, assignment]
-
- class _ACPAgentSettingsStub:
- """Sentinel β€” older SDK builds cannot produce ACPAgentSettings instances."""
-
- ACPAgentSettings = _ACPAgentSettingsStub # type: ignore[misc, assignment]
- AgentSettingsConfig = AgentSettings # type: ignore[misc, assignment]
-
- def default_agent_settings() -> AgentSettings: # type: ignore[misc]
- return AgentSettings()
-
- def validate_agent_settings(data: dict[str, Any]) -> AgentSettings: # type: ignore[misc]
- if isinstance(data, dict) and data.get('kind') == 'acp':
- raise RuntimeError(
- "Stored settings contain kind='acp' but the installed "
- 'openhands-sdk does not support ACP agents. Upgrade to an '
- 'SDK release that includes the discriminated-union rework '
- '(OpenHands/software-agent-sdk#2861).'
- )
- return AgentSettings.model_validate(data)
-
- def export_agent_settings_schema(): # type: ignore[misc]
- return AgentSettings.export_schema()
-
-
-__all__ = [
- 'ACPAgentSettings',
- 'AgentSettingsConfig',
- 'LLMAgentSettings',
- '_HAS_DISCRIMINATED_UNION',
- 'default_agent_settings',
- 'export_agent_settings_schema',
- 'validate_agent_settings',
-]
diff --git a/tests/unit/app_server/test_live_status_app_conversation_service.py b/tests/unit/app_server/test_live_status_app_conversation_service.py
index cb0b4130b4..682ef01181 100644
--- a/tests/unit/app_server/test_live_status_app_conversation_service.py
+++ b/tests/unit/app_server/test_live_status_app_conversation_service.py
@@ -3312,7 +3312,7 @@ class TestAgentKindConversationUrl:
id=UUID('11111111-1111-1111-1111-111111111111'),
created_by_user_id=None,
sandbox_id='sandbox-a',
- agent_kind='llm',
+ agent_kind='openhands',
)
sandbox = SandboxInfo(
id='sandbox-a',
@@ -3371,20 +3371,26 @@ class TestAgentKindConversationUrl:
)
def test_agent_kind_to_router_path_known_kinds(self):
- """``'llm'`` β†’ ``'conversations'``, ``'acp'`` β†’ ``'acp/conversations'``."""
+ """``'openhands'`` routes to standard conversations; ``'acp'`` to ACP."""
from openhands.app_server.app_conversation.live_status_app_conversation_service import ( # noqa: E501
_agent_kind_to_router_path,
)
- assert _agent_kind_to_router_path('llm') == 'conversations'
+ assert _agent_kind_to_router_path('openhands') == 'conversations'
assert _agent_kind_to_router_path('acp') == 'acp/conversations'
def test_agent_kind_to_router_path_unknown_falls_back(self):
- """Unknown variants fall back to the LLM route."""
+ """Any value that is not 'acp' routes to 'conversations'.
+
+ This includes the legacy ``'llm'`` value that the old default emitted
+ before the rename, so rows stored with ``agent_kind='llm'`` continue to
+ route correctly without a migration.
+ """
from openhands.app_server.app_conversation.live_status_app_conversation_service import ( # noqa: E501
_agent_kind_to_router_path,
)
+ assert _agent_kind_to_router_path('llm') == 'conversations'
assert _agent_kind_to_router_path('future-variant') == 'conversations'
diff --git a/tests/unit/utils/test_sdk_settings_compat.py b/tests/unit/utils/test_sdk_settings_compat.py
deleted file mode 100644
index 585237ab91..0000000000
--- a/tests/unit/utils/test_sdk_settings_compat.py
+++ /dev/null
@@ -1,72 +0,0 @@
-"""Tests for SDK settings compatibility shim."""
-
-import pytest
-
-from openhands.app_server.utils.sdk_settings_compat import (
- _HAS_DISCRIMINATED_UNION,
- ACPAgentSettings,
- AgentSettingsConfig,
- LLMAgentSettings,
- default_agent_settings,
- export_agent_settings_schema,
- validate_agent_settings,
-)
-
-
-def test_has_discriminated_union_is_bool():
- assert isinstance(_HAS_DISCRIMINATED_UNION, bool)
-
-
-def test_default_agent_settings_returns_instance():
- settings = default_agent_settings()
- assert settings is not None
-
-
-def test_validate_agent_settings_with_llm_dict():
- """validate_agent_settings should accept a plain dict and return an agent settings object."""
- result = validate_agent_settings({})
- assert result is not None
-
-
-def test_validate_agent_settings_with_acp_kind_raises_or_returns():
- """validate_agent_settings with kind='acp' either returns ACP settings or raises RuntimeError."""
- data = {'kind': 'acp', 'agent_kind': 'acp'}
- if _HAS_DISCRIMINATED_UNION:
- # With SDK support, kind='acp' produces an ACPAgentSettings
- result = validate_agent_settings(data)
- assert isinstance(result, ACPAgentSettings)
- else:
- # Without SDK support, kind='acp' raises RuntimeError
- with pytest.raises(RuntimeError, match='kind=.acp.'):
- validate_agent_settings(data)
-
-
-def test_export_agent_settings_schema_returns_schema():
- schema = export_agent_settings_schema()
- assert schema is not None
- # Schema should have a model_dump method (Pydantic model)
- dumped = schema.model_dump(mode='json')
- assert isinstance(dumped, dict)
-
-
-def test_llm_agent_settings_is_usable():
- """LLMAgentSettings should be constructable."""
- settings = LLMAgentSettings()
- assert settings is not None
-
-
- not _HAS_DISCRIMINATED_UNION,
- reason='Discriminated union not available in installed SDK',
-)
-def test_acp_agent_settings_is_usable():
- """ACPAgentSettings should be constructable when SDK supports it."""
- settings = ACPAgentSettings()
- assert settings is not None
- assert hasattr(settings, 'agent_kind')
- assert settings.agent_kind == 'acp'
-
-
-def test_agent_settings_config_is_type():
- """AgentSettingsConfig should be a usable type."""
- assert AgentSettingsConfig is not None