feat(llm): add LLM profiles

.github/scripts/check_documented_examples.py

@@ -29,7 +29,12 @@ def find_documented_examples(docs_path: Path) -> set[str]:
     """
     documented_examples: set[str] = set()
 
-    # Pattern to match example file references with arbitrary nesting depth.
+    # Pattern to match example file references.
+    #
+    # The agent-sdk examples tree includes nested modules (e.g.
+    # examples/02_remote_agent_server/05_custom_tool/custom_tools/log_data.py),
+    # so we intentionally support *arbitrary* nesting depth under examples/.
+    #
     # Matches: examples/<dir>/.../<file>.py
     pattern = r"examples/(?:[-\w]+/)+[-\w]+\.py"
 
@@ -81,8 +86,9 @@ def find_agent_sdk_examples(agent_sdk_path: Path) -> set[str]:
                 if relative_path_str.startswith("examples/03_github_workflows/"):
                     continue
 
-                # Skip LLM-specific tools examples: these are intentionally not
-                # enforced by the docs check. See discussion in PR #1486.
+                # Skip LLM-specific tools examples: these depend on external
+                # model/provider availability and are intentionally excluded from
+                # docs example enforcement.
                 if relative_path_str.startswith("examples/04_llm_specific_tools/"):
                     continue
 

examples/01_standalone_sdk/34_llm_profiles.py

@@ -0,0 +1,124 @@
+"""Create and use an LLM profile with :class:`LLMRegistry`.
+
+Run with::
+
+    uv run python examples/01_standalone_sdk/34_llm_profiles.py
+
+Profiles are stored under ``~/.openhands/llm-profiles/<name>.json`` by default.
+Set ``LLM_PROFILE_NAME`` to pick a profile.
+
+Notes on credentials:
+- New profiles include API keys by default when saved
+- To omit secrets on disk, pass include_secrets=False to LLMRegistry.save_profile
+"""
+
+import json
+import os
+from pathlib import Path
+
+from pydantic import SecretStr
+
+from openhands.sdk import (
+    LLM,
+    Agent,
+    Conversation,
+    LLMRegistry,
+    Tool,
+)
+from openhands.tools.terminal import TerminalTool
+
+
+PROFILE_NAME = os.getenv("LLM_PROFILE_NAME", "gpt-5-mini")
+
+
+def ensure_profile_exists(registry: LLMRegistry, name: str) -> None:
+    """Create a starter profile in the default directory when missing."""
+
+    if name in registry.list_profiles():
+        return
+
+    model = os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929")
+    base_url = os.getenv("LLM_BASE_URL")
+    api_key = os.getenv("LLM_API_KEY")
+
+    profile_defaults = LLM(
+        usage_id="agent",
+        model=model,
+        base_url=base_url,
+        api_key=SecretStr(api_key) if api_key else None,
+        temperature=0.2,
+        max_output_tokens=4096,
+    )
+    path = registry.save_profile(name, profile_defaults)
+    print(f"Created profile '{name}' at {path}")
+
+
+def load_profile(registry: LLMRegistry, name: str) -> LLM:
+    llm = registry.load_profile(name)
+    # If profile was saved without secrets, allow providing API key via env var
+    if llm.api_key is None:
+        api_key = os.getenv("LLM_API_KEY")
+        if api_key:
+            llm = llm.model_copy(update={"api_key": SecretStr(api_key)})
+    return llm
+
+
+if __name__ == "__main__":  # pragma: no cover
+    registry = LLMRegistry()
+    ensure_profile_exists(registry, PROFILE_NAME)
+
+    llm = load_profile(registry, PROFILE_NAME)
+
+    tools = [Tool(name=TerminalTool.name)]
+    agent = Agent(llm=llm, tools=tools)
+
+    workspace_dir = Path(os.getcwd())
+    summary_path = workspace_dir / "summary_readme.md"
+    if summary_path.exists():
+        summary_path.unlink()
+
+    persistence_root = workspace_dir / ".conversations_llm_profiles"
+    conversation = Conversation(
+        agent=agent,
+        workspace=str(workspace_dir),
+        persistence_dir=str(persistence_root),
+        visualizer=None,
+    )
+
+    conversation.send_message(
+        "Read README.md in this workspace, create a concise summary in "
+        "summary_readme.md (overwrite it if it exists), and respond with "
+        "SUMMARY_READY when the file is written."
+    )
+    conversation.run()
+
+    if summary_path.exists():
+        print(f"summary_readme.md written to {summary_path}")
+    else:
+        print("summary_readme.md not found after first run")
+
+    conversation.send_message(
+        "Thanks! Delete summary_readme.md from the workspace and respond with "
+        "SUMMARY_REMOVED once it is gone."
+    )
+    conversation.run()
+
+    if summary_path.exists():
+        print("summary_readme.md still present after deletion request")
+    else:
+        print("summary_readme.md removed")
+
+    persistence_dir = conversation.state.persistence_dir
+    if persistence_dir is None:
+        raise RuntimeError("Conversation did not persist base state to disk")
+
+    base_state_path = Path(persistence_dir) / "base_state.json"
+    state_payload = json.loads(base_state_path.read_text())
+    llm_entry = state_payload.get("agent", {}).get("llm", {})
+    profile_in_state = llm_entry.get("profile_id")
+    print(f"Profile recorded in base_state.json: {profile_in_state}")
+    if profile_in_state != PROFILE_NAME:
+        print(
+            "Warning: profile_id in base_state.json does not match the profile "
+            "used at runtime."
+        )

examples/llm-profiles/gpt-5-mini.json

@@ -0,0 +1,7 @@
+{
+  "model": "litellm_proxy/openai/gpt-5-mini",
+  "base_url": "https://llm-proxy.eval.all-hands.dev",
+  "temperature": 0.2,
+  "max_output_tokens": 4096,
+  "usage_id": "agent"
+}

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

@@ -414,6 +414,7 @@ def model_dump_succint(self, **kwargs):
         """Like model_dump, but excludes None fields by default."""
         if "exclude_none" not in kwargs:
             kwargs["exclude_none"] = True
+
         dumped = super().model_dump(**kwargs)
         # remove tool schema details for brevity
         if "tools" in dumped and isinstance(dumped["tools"], dict):

openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py

@@ -106,6 +106,9 @@ def __init__(
                       'monologue', 'alternating_pattern'. Values are integers
                       representing the number of repetitions before triggering.
         """
+        # Initialize the registry early so profile references resolve during resume.
+        self.llm_registry = LLMRegistry()
+
         super().__init__()  # Initialize with span tracking
         # Mark cleanup as initiated as early as possible to avoid races or partially
         # initialized instances during interpreter shutdown.
@@ -134,6 +137,7 @@ def __init__(
             else None,
             max_iterations=max_iteration_per_run,
             stuck_detection=stuck_detection,
+            llm_registry=self.llm_registry,
         )
 
         # Default callback: persist every event to state
@@ -209,7 +213,6 @@ def _default_callback(e):
             self.agent.init_state(self._state, on_event=self._on_event)
 
         # Register existing llms in agent
-        self.llm_registry = LLMRegistry()
         self.llm_registry.subscribe(self._state.stats.register_llm)
         for llm in list(self.agent.get_all_llms()):
             self.llm_registry.add(llm)
@@ -254,6 +257,7 @@ def send_message(self, message: str | Message, sender: str | None = None) -> Non
 
         Args:
             message: Either a string (which will be converted to a user message)
+
                     or a Message object
             sender: Optional identifier of the sender. Can be used to track
                    message origin in multi-agent scenarios. For example, when

openhands-sdk/openhands/sdk/conversation/state.py

@@ -3,7 +3,7 @@
 from collections.abc import Sequence
 from enum import Enum
 from pathlib import Path
-from typing import Any, Self
+from typing import TYPE_CHECKING, Any, Self
 
 from pydantic import Field, PrivateAttr, model_validator
 
@@ -18,6 +18,12 @@
 from openhands.sdk.event.base import Event
 from openhands.sdk.io import FileStore, InMemoryFileStore, LocalFileStore
 from openhands.sdk.logger import get_logger
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.llm.llm_registry import LLMRegistry
+
+
 from openhands.sdk.security.analyzer import SecurityAnalyzerBase
 from openhands.sdk.security.confirmation_policy import (
     ConfirmationPolicyBase,
@@ -180,6 +186,7 @@ def create(
         persistence_dir: str | None = None,
         max_iterations: int = 500,
         stuck_detection: bool = True,
+        llm_registry: "LLMRegistry | None" = None,
     ) -> "ConversationState":
         """Create a new conversation state or resume from persistence.
 
@@ -196,13 +203,19 @@ def create(
         history), but all other configuration can be freely changed: LLM,
         agent_context, condenser, system prompts, etc.
 
+        When conversation state is persisted with LLM profile references (instead
+        of inlined credentials), pass an ``llm_registry`` so profile IDs can be
+        expanded during restore.
+
         Args:
             id: Unique conversation identifier
             agent: The Agent to use (tools must match persisted on restore)
             workspace: Working directory for agent operations
             persistence_dir: Directory for persisting state and events
             max_iterations: Maximum iterations per run
             stuck_detection: Whether to enable stuck detection
+            llm_registry: Optional registry used to expand profile references when
+                conversations persist profile IDs instead of inline credentials.
 
         Returns:
             ConversationState ready for use
@@ -222,32 +235,59 @@ def create(
         except FileNotFoundError:
             base_text = None
 
+        context: dict[str, object] = {}
+        registry = llm_registry
+        if registry is None:
+            from openhands.sdk.llm.llm_registry import LLMRegistry
+
+            registry = LLMRegistry()
+        context["llm_registry"] = registry
+
+        # Ensure that any runtime-provided LLM without an explicit profile is
+        # persisted as a stable "default" profile, so conversation state can
+        # safely store only a profile reference.
+        agent = agent.model_copy(
+            update={"llm": registry.ensure_default_profile(agent.llm)}
+        )
+
         # ---- Resume path ----
         if base_text:
-            state = cls.model_validate(json.loads(base_text))
+            base_payload = json.loads(base_text)
 
-            # Restore the conversation with the same id
-            if state.id != id:
+            persisted_id = ConversationID(base_payload.get("id"))
+            if persisted_id != id:
                 raise ValueError(
                     f"Conversation ID mismatch: provided {id}, "
-                    f"but persisted state has {state.id}"
+                    f"but persisted state has {persisted_id}"
                 )
 
+            persisted_agent_payload = base_payload.get("agent")
+            if persisted_agent_payload is None:
+                raise ValueError("Persisted conversation is missing agent state")
+
             # Attach event log early so we can read history for tool verification
-            state._fs = file_store
-            state._events = EventLog(file_store, dir_path=EVENTS_DIR)
+            event_log = EventLog(file_store, dir_path=EVENTS_DIR)
 
-            # Verify compatibility (agent class + tools)
-            agent.verify(state.agent, events=state._events)
+            persisted_agent = AgentBase.model_validate(
+                persisted_agent_payload,
+                context={"llm_registry": registry},
+            )
+            agent.verify(persisted_agent, events=event_log)
 
-            # Commit runtime-provided values (may autosave)
-            state._autosave_enabled = True
-            state.agent = agent
-            state.workspace = workspace
-            state.max_iterations = max_iterations
+            # Use runtime-provided Agent directly (PR #1542 / issue #1451)
+            base_payload["agent"] = agent.model_dump(
+                mode="json",
+                exclude_none=True,
+                context={"expose_secrets": True},
+            )
+            base_payload["workspace"] = workspace.model_dump(mode="json")
+            base_payload["max_iterations"] = max_iterations
+
+            state = cls.model_validate(base_payload, context=context)
+            state._fs = file_store
+            state._events = event_log
 
-            # Note: stats are already deserialized from base_state.json above.
-            # Do NOT reset stats here - this would lose accumulated metrics.
+            state._autosave_enabled = True
 
             logger.info(
                 f"Resumed conversation {state.id} from persistent storage.\n"