From ba5e5e5e5b53d9e165a58ed9acbd180197788e44 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 10 Mar 2026 10:41:31 +0000 Subject: [PATCH 1/3] docs(sdk): add conversation model switching example Co-authored-by: openhands --- sdk/guides/llm-profile-store.mdx | 65 ++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/sdk/guides/llm-profile-store.mdx b/sdk/guides/llm-profile-store.mdx index e6ac7e18..8c5a019b 100644 --- a/sdk/guides/llm-profile-store.mdx +++ b/sdk/guides/llm-profile-store.mdx @@ -170,6 +170,71 @@ print("EXAMPLE_COST: 0") +## Mid-Conversation Model Switching + +You can use a saved profile to switch the active model on a running conversation between turns. This is useful when you want to start with one model, then swap to another for later user messages while keeping a single conversation state and combined usage metrics. + + +This example is available on GitHub: [examples/01_standalone_sdk/44_model_switching_in_convo.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/44_model_switching_in_convo.py) + + +```python icon="python" expandable examples/01_standalone_sdk/44_model_switching_in_convo.py +"""Mid-conversation model switching. + +Usage: + uv run examples/01_standalone_sdk/44_model_switching_in_convo.py +""" + +import os + +from openhands.sdk import LLM, Agent, LocalConversation, Tool +from openhands.sdk.llm.llm_profile_store import LLMProfileStore +from openhands.tools.terminal import TerminalTool + + +LLM_API_KEY = os.getenv("LLM_API_KEY") +store = LLMProfileStore() + +store.save( + "gpt", + LLM(model="openhands/gpt-5.2", api_key=LLM_API_KEY), + include_secrets=True, +) + +agent = Agent( + llm=LLM( + model=os.getenv("LLM_MODEL", "openhands/claude-sonnet-4-5-20250929"), + api_key=LLM_API_KEY, + ), + tools=[Tool(name=TerminalTool.name)], +) +conversation = LocalConversation(agent=agent, workspace=os.getcwd()) + +# Send a message with the default model +conversation.send_message("Say hello in one sentence.") +conversation.run() + +# Switch to a different model and send another message +conversation.switch_profile("gpt") +print(f"Switched to: {conversation.agent.llm.model}") + +conversation.send_message("Say goodbye in one sentence.") +conversation.run() + +# Print metrics per model +for usage_id, metrics in conversation.state.stats.usage_to_metrics.items(): + print(f" [{usage_id}] cost=${metrics.accumulated_cost:.6f}") + +combined = conversation.state.stats.get_combined_metrics() +print(f"Total cost: ${combined.accumulated_cost:.6f}") +print(f"EXAMPLE_COST: {combined.accumulated_cost}") + +store.delete("gpt") +``` + + + + ## Next Steps - **[LLM Registry](/sdk/guides/llm-registry)** - Manage multiple LLMs in memory at runtime From eb6f764e15531f0ae24817fac6f5f2e9604d158f Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Tue, 10 Mar 2026 11:43:54 +0100 Subject: [PATCH 2/3] Apply suggestion from @enyst --- sdk/guides/llm-profile-store.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/guides/llm-profile-store.mdx b/sdk/guides/llm-profile-store.mdx index 8c5a019b..3970bfd3 100644 --- a/sdk/guides/llm-profile-store.mdx +++ b/sdk/guides/llm-profile-store.mdx @@ -172,7 +172,7 @@ print("EXAMPLE_COST: 0") ## Mid-Conversation Model Switching -You can use a saved profile to switch the active model on a running conversation between turns. This is useful when you want to start with one model, then swap to another for later user messages while keeping a single conversation state and combined usage metrics. +You can use a saved profile to switch the active model on a running conversation between turns. This is useful when you want to start with one model, then switch to another for later user messages while keeping the same conversation history and combined usage metrics. This example is available on GitHub: [examples/01_standalone_sdk/44_model_switching_in_convo.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/44_model_switching_in_convo.py) From e9a214140f336f8b344f5a129663f5002a976c96 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Tue, 10 Mar 2026 11:44:42 +0100 Subject: [PATCH 3/3] Apply suggestion from @enyst --- sdk/guides/llm-profile-store.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/sdk/guides/llm-profile-store.mdx b/sdk/guides/llm-profile-store.mdx index 3970bfd3..f86ff635 100644 --- a/sdk/guides/llm-profile-store.mdx +++ b/sdk/guides/llm-profile-store.mdx @@ -234,7 +234,6 @@ store.delete("gpt") - ## Next Steps - **[LLM Registry](/sdk/guides/llm-registry)** - Manage multiple LLMs in memory at runtime