Background
The discriminated union introduced in v1.17 uses agent_kind: 'llm' | 'acp' to distinguish agent types. Both names are misleading:
'llm' describes the mechanism (uses an LLM), not the agent type. The correct semantic is 'openhands' — the built-in OpenHands agent, as opposed to an external ACP agent.
LLMAgentSettings has the same problem — it should be OpenHandsAgentSettings.
Changes needed
AgentKind = Literal["llm", "acp"] → Literal["openhands", "acp"]
LLMAgentSettings.agent_kind: Literal["llm"] → Literal["openhands"]
- All
variant="llm" section/field metadata → variant="openhands"
Tag("llm") in AgentSettingsConfig union → Tag("openhands")
_agent_settings_discriminator default fallback → "openhands"
class LLMAgentSettings → class OpenHandsAgentSettings (keep LLMAgentSettings as a deprecated alias)
- Update
AgentSettings deprecation notice to point to OpenHandsAgentSettings
Notes
- Requires a minor version bump (breaking change to the
agent_kind field default and type).
- Backwards-compat: add
"llm" → "openhands" coercion in _agent_settings_discriminator for one release cycle to allow stored settings to migrate gracefully.
Background
The discriminated union introduced in v1.17 uses
agent_kind: 'llm' | 'acp'to distinguish agent types. Both names are misleading:'llm'describes the mechanism (uses an LLM), not the agent type. The correct semantic is'openhands'— the built-in OpenHands agent, as opposed to an external ACP agent.LLMAgentSettingshas the same problem — it should beOpenHandsAgentSettings.Changes needed
AgentKind = Literal["llm", "acp"]→Literal["openhands", "acp"]LLMAgentSettings.agent_kind: Literal["llm"]→Literal["openhands"]variant="llm"section/field metadata →variant="openhands"Tag("llm")inAgentSettingsConfigunion →Tag("openhands")_agent_settings_discriminatordefault fallback →"openhands"class LLMAgentSettings→class OpenHandsAgentSettings(keepLLMAgentSettingsas a deprecated alias)AgentSettingsdeprecation notice to point toOpenHandsAgentSettingsNotes
agent_kindfield default and type)."llm"→"openhands"coercion in_agent_settings_discriminatorfor one release cycle to allow stored settings to migrate gracefully.