Switch LLM profiles

[enyst]

Summary

• add runtime LLM profile switching support for local conversations
• document the workflow and provide an example script
• enforce safe switching: only when conversation is idle (not RUNNING)

Testing

• unit tests via pre-commit hooks

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.12-nodejs22	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:3148251-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-3148251-python \
  ghcr.io/openhands/agent-server:3148251-python

All tags pushed for this build

ghcr.io/openhands/agent-server:3148251-golang-amd64
ghcr.io/openhands/agent-server:3148251-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:3148251-golang-arm64
ghcr.io/openhands/agent-server:3148251-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:3148251-java-amd64
ghcr.io/openhands/agent-server:3148251-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:3148251-java-arm64
ghcr.io/openhands/agent-server:3148251-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:3148251-python-amd64
ghcr.io/openhands/agent-server:3148251-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:3148251-python-arm64
ghcr.io/openhands/agent-server:3148251-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:3148251-golang
ghcr.io/openhands/agent-server:3148251-java
ghcr.io/openhands/agent-server:3148251-python

About Multi-Architecture Support

• Each variant tag (e.g., 3148251-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 3148251-python-amd64) are also available if needed

Docs PR (documents new examples for check-examples): OpenHands/docs#219

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/agent
base.py	180	22	87%	165, 171, 190, 239–240, 251–253, 266, 274–275, 309, 356, 363, 372–374, 384, 421–422, 432–433
openhands-sdk/openhands/sdk/conversation
state.py	185	41	77%	215–217, 219–220, 229, 254, 301–303, 319–320, 326, 332–335, 339, 345–348, 353–354, 358, 362, 364–370, 372–374, 401, 419, 428, 443, 449
openhands-sdk/openhands/sdk/conversation/impl
local_conversation.py	254	92	63%	150, 158, 164, 166–167, 205, 208–209, 222–223, 246, 251, 256–259, 306–307, 311–312, 365–366, 369, 376, 397, 400, 404–406, 413–415, 418, 427, 443, 445, 447, 451, 453–455, 457, 459, 465–466, 479–480, 482, 484, 488–491, 508–509, 515, 520, 523, 525, 535, 537–539, 557, 559, 563, 568, 573, 578–581, 587, 590, 594, 597, 599–601, 603, 621, 623, 637, 641, 649, 665–666, 670, 672, 674, 680–681
openhands-sdk/openhands/sdk/llm
llm_registry.py	122	70	42%	79–80, 86, 93, 98, 107–112, 115, 123, 128–129, 134–135, 137–140, 142–146, 150, 155–158, 169–173, 177–180, 182–183, 185–191, 196–203, 205–207, 214, 231–234, 248–249, 254, 257, 262
TOTAL	14612	6903	52%

[blacksmith-sh]

[Automatic Post]: It has been a while since there was any activity on this PR. @enyst, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

[github-actions]

[Automatic Post]: It has been a while since there was any activity on this PR. @enyst, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • [Optional] Docs example

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #1049 at branch `agent-sdk-26-llm-switch`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

[enyst]

Rebased onto updated agent-sdk-18-profile-manager (now includes latest upstream/main). Only remaining failing check is check-examples, pending OpenHands/docs#219.

[all-hands-bot]

[Automatic Post]: It has been a while since there was any activity on this PR. @enyst, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

[all-hands-bot]

[Automatic Post]: This PR seems to be currently waiting for review. @xingyaoww, could you please take a look when you have a chance?

[all-hands-bot]

[Automatic Post]: It has been a while since there was any activity on this PR. @enyst, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

[xingyaoww]

@enyst i guess this is not ready for review, until #795 is merged, right?