Clarify launched agent profile provenance

Rename the conversation-start provenance model and API field to explicitly reference agent profiles, while accepting the short-lived legacy payload names during validation.

Co-authored-by: openhands <openhands@all-hands.dev>

Author: enyst

openhands-agent-server/openhands/agent_server/conversation_service.py

@@ -21,7 +21,7 @@
     ConversationInfo,
     ConversationPage,
     ConversationSortOrder,
-    LaunchedProfile,
+    LaunchedAgentProfile,
     StartConversationRequest,
     StoredConversation,
     UpdateConversationRequest,
@@ -245,7 +245,7 @@ def _resolve_agent_from_profile(
     profile_id: "UUID",
     cipher: "Cipher | None",
     mcp_config: "Any",
-) -> "tuple[AgentBase, LaunchedProfile]":
+) -> "tuple[AgentBase, LaunchedAgentProfile]":
     """Load and resolve an agent profile by id, returning the built agent + provenance.
 
     Runs synchronously (call via ``asyncio.to_thread`` from async context).
@@ -290,7 +290,10 @@ def _resolve_agent_from_profile(
         raise ValueError(f"Profile '{profile_name}' failed to resolve: {exc}") from exc
 
     agent = settings_config.create_agent()
-    launched = LaunchedProfile(profile_id=profile.id, revision=profile.revision)
+    launched = LaunchedAgentProfile(
+        agent_profile_id=profile.id,
+        revision=profile.revision,
+    )
     return agent, launched
 
 
@@ -363,7 +366,7 @@ def _compose_conversation_info(
         available_models=available_models,
         supports_runtime_model_switch=supports_runtime_model_switch,
         client_tools=stored.client_tools,
-        launched_profile=stored.launched_profile,
+        launched_agent_profile=stored.launched_agent_profile,
     )
 
 
@@ -670,7 +673,7 @@ async def _start_conversation(
         # Profile resolution must happen before _prepare_request_workspace (which
         # asserts request.agent is not None) and before model_dump so the resolved
         # agent is captured in request_data.
-        launched_profile: LaunchedProfile | None = None
+        launched_agent_profile: LaunchedAgentProfile | None = None
         if request.agent_profile_id is not None:
             # get_settings_store() is safe here: get_instance() initialises the
             # singleton with the server cipher before any conversation can start.
@@ -681,7 +684,7 @@ async def _start_conversation(
 
             settings = get_settings_store().load() or PersistedSettings()
             mcp_config = settings.agent_settings.mcp_config
-            resolved_agent, launched_profile = await asyncio.to_thread(
+            resolved_agent, launched_agent_profile = await asyncio.to_thread(
                 _resolve_agent_from_profile,
                 request.agent_profile_id,
                 self.cipher,
@@ -751,7 +754,7 @@ async def _start_conversation(
         # serialize to plain strings. Pass expose_secrets=True so StaticSecret values
         # are preserved through the round-trip; the dict is only used in-process to
         # construct StoredConversation, not sent over the network.
-        # agent_profile_id is excluded: it was resolved into `launched_profile`
+        # agent_profile_id is excluded: it was resolved into `launched_agent_profile`
         # above and must not re-trigger the mutual-exclusivity validator.
         request_data = request.model_dump(
             mode="json",
@@ -772,9 +775,9 @@ async def _start_conversation(
                 {
                     "id": conversation_id,
                     **request_data,
-                    "launched_profile": (
-                        launched_profile.model_dump(mode="json")
-                        if launched_profile is not None
+                    "launched_agent_profile": (
+                        launched_agent_profile.model_dump(mode="json")
+                        if launched_agent_profile is not None
                         else None
                     ),
                 },
@@ -783,7 +786,7 @@ async def _start_conversation(
         else:
             stored = StoredConversation(
                 id=conversation_id,
-                launched_profile=launched_profile,
+                launched_agent_profile=launched_agent_profile,
                 **request_data,
             )
         event_service = await self._start_event_service(stored)

openhands-agent-server/openhands/agent_server/models.py

@@ -6,7 +6,7 @@
 from typing import Any, TypeAlias
 from uuid import UUID, uuid4
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import AliasChoices, BaseModel, Field, field_validator
 
 from openhands.sdk import LLM
 from openhands.sdk.agent.acp_models import ACPModelInfo
@@ -28,7 +28,9 @@
     TextContent as TextContent,
 )
 from openhands.sdk.llm.utils.metrics import MetricsSnapshot
-from openhands.sdk.profiles.agent_profile import LaunchedProfile as LaunchedProfile
+from openhands.sdk.profiles.agent_profile import (
+    LaunchedAgentProfile as LaunchedAgentProfile,
+)
 from openhands.sdk.secret import SecretSource
 from openhands.sdk.security.analyzer import SecurityAnalyzerBase
 from openhands.sdk.security.confirmation_policy import (
@@ -79,7 +81,7 @@ class StoredConversation(StartConversationRequest):
     Extends StartConversationRequest with server-assigned fields.
     """
 
-    # agent_profile_id is resolved into launched_profile at creation; exclude from
+    # agent_profile_id is resolved into launched_agent_profile at creation; exclude from
     # the persistence payload so it does not re-appear in meta.json.
     agent_profile_id: UUID | None = Field(default=None, exclude=True)
 
@@ -90,8 +92,9 @@ class StoredConversation(StartConversationRequest):
     metrics: MetricsSnapshot | None = None
     created_at: datetime = Field(default_factory=utc_now)
     updated_at: datetime = Field(default_factory=utc_now)
-    launched_profile: LaunchedProfile | None = Field(
+    launched_agent_profile: LaunchedAgentProfile | None = Field(
         default=None,
+        validation_alias=AliasChoices("launched_agent_profile", "launched_profile"),
         description=(
             "Provenance snapshot of the agent profile that launched this "
             "conversation. Set at creation when `agent_profile_id` is supplied; "
@@ -248,14 +251,15 @@ class _ConversationInfoBase(BaseModel):
             "and before the conversation has started a session."
         ),
     )
-    launched_profile: LaunchedProfile | None = Field(
+    launched_agent_profile: LaunchedAgentProfile | None = Field(
         default=None,
+        validation_alias=AliasChoices("launched_agent_profile", "launched_profile"),
         description=(
             "Provenance snapshot of the agent profile that launched this "
             "conversation. Set at creation when the conversation was started via "
             "``agent_profile_id``; ``None`` for conversations started directly "
             "with ``agent`` or ``agent_settings``. Clients use this to identify "
-            "which profile is current without fragile settings-comparison."
+            "which agent profile is current without fragile settings-comparison."
         ),
     )
 

openhands-sdk/openhands/sdk/profiles/__init__.py

@@ -5,7 +5,7 @@
     ACPAgentProfile,
     AgentProfile,
     AgentProfileBase,
-    LaunchedProfile,
+    LaunchedAgentProfile,
     OpenHandsAgentProfile,
     ProfileVerificationSettings,
     validate_agent_profile,
@@ -38,7 +38,7 @@
     "AgentProfileDiagnostics",
     "AgentProfileStore",
     "DanglingMcpServerRef",
-    "LaunchedProfile",
+    "LaunchedAgentProfile",
     "OpenHandsAgentProfile",
     "ProfileLimitExceeded",
     "ProfileNotFound",

openhands-sdk/openhands/sdk/profiles/agent_profile.py

@@ -14,6 +14,7 @@
 from uuid import UUID, uuid4
 
 from pydantic import (
+    AliasChoices,
     BaseModel,
     ConfigDict,
     Discriminator,
@@ -209,20 +210,21 @@ class ACPAgentProfile(AgentProfileBase):
     )
 
 
-class LaunchedProfile(BaseModel):
-    """Provenance snapshot recorded when a profile launches a conversation.
+class LaunchedAgentProfile(BaseModel):
+    """Provenance snapshot recorded when an agent profile launches a conversation.
 
     Stored on ``StoredConversation`` and projected onto ``ConversationInfo`` so
-    ts-client ``deriveSwitchPlan`` can identify which profile is current without
-    fragile settings-comparison. See #3720.
+    ts-client ``deriveSwitchPlan`` can identify which agent profile is current
+    without fragile settings-comparison. See #3720.
     """
 
-    profile_id: UUID = Field(
-        description="Stable id of the profile that launched the conversation."
+    agent_profile_id: UUID = Field(
+        validation_alias=AliasChoices("agent_profile_id", "profile_id"),
+        description="Stable id of the agent profile that launched the conversation.",
     )
     revision: int = Field(
         ge=0,
-        description="Revision of the profile at launch time.",
+        description="Revision of the agent profile at launch time.",
     )