Expose model switching (switch_profile) in agent-server REST API by VascoSch92 · Pull Request #2795 · OpenHands/software-agent-sdk

VascoSch92 · 2026-04-10T07:57:01Z

A human has tested these changes.

Summary

Add POST /{conversation_id}/switch_profile endpoint to conversation_router.py, allowing API clients to switch a conversation's LLM mid-session using named profiles from LLMProfileStore
Handle FileNotFoundError (unknown profile → 404) and ValueError (corrupted profile → 400) at the endpoint boundary
Add 3 tests: success path, conversation not found, and nonexistent profile

Issue Number

Closes #2794
Closes #416

How to Test

test_switch_conversation_profile_success — valid profile switches correctly, returns 200
test_switch_conversation_profile_not_found — missing conversation returns 404
test_switch_conversation_profile_nonexistent_profile — missing profile returns 404 with detail message

Type

Notes

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.13-nodejs22-slim`	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:91ce99a-python

Run

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

All tags pushed for this build

ghcr.io/openhands/agent-server:91ce99a-golang-amd64
ghcr.io/openhands/agent-server:91ce99a-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:91ce99a-golang-arm64
ghcr.io/openhands/agent-server:91ce99a-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:91ce99a-java-amd64
ghcr.io/openhands/agent-server:91ce99a-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:91ce99a-java-arm64
ghcr.io/openhands/agent-server:91ce99a-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:91ce99a-python-amd64
ghcr.io/openhands/agent-server:91ce99a-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-amd64
ghcr.io/openhands/agent-server:91ce99a-python-arm64
ghcr.io/openhands/agent-server:91ce99a-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-arm64
ghcr.io/openhands/agent-server:91ce99a-golang
ghcr.io/openhands/agent-server:91ce99a-java
ghcr.io/openhands/agent-server:91ce99a-python

About Multi-Architecture Support

Each variant tag (e.g., 91ce99a-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., 91ce99a-python-amd64) are also available if needed

github-actions · 2026-04-10T07:57:28Z

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

github-actions · 2026-04-10T07:57:43Z

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

github-actions · 2026-04-10T07:58:47Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-agent-server/openhands/agent_server
conversation_router.py	133	9	93%	286, 376–379, 391–394
TOTAL	22878	10402	54%

all-hands-bot

Taste Rating: 🟢 Good taste

What's Right:

Simple, direct solution: profile_name → switch_profile() with clean error mapping
No unnecessary complexity (2 levels max, single responsibility)
Appropriate error handling: FileNotFoundError→404, ValueError→400
Tests cover all code paths (router-layer mocking is correct here)
Solves real user problems (#2794, #416)

VERDICT: ✅ Approve

KEY INSIGHT: Straightforward REST wrapper exposing existing functionality - does exactly what it needs to do, nothing more.

all-hands-bot

QA Report: switch_profile Endpoint

Verdict: ✅ PASS

The switch_profile endpoint is working correctly. All tests pass, the implementation is solid, and the API behaves exactly as specified in all tested scenarios.

Environment Setup

✅ Success - Environment configured without issues

$ make build
# Dependencies installed successfully
# Pre-commit hooks configured

CI & Test Status

✅ All Checks Passed

Relevant CI checks:

✅ agent-server-tests - PASSED
✅ pre-commit - PASSED
✅ Python API breakage checks - PASSED
✅ REST API breakage checks - PASSED
✅ Check OpenAPI Schema - PASSED

Unit tests (local):

$ uv run pytest tests/agent_server/test_conversation_router.py -k "switch_conversation_profile" -v

tests/agent_server/test_conversation_router.py::test_switch_conversation_profile_success PASSED [25%]
tests/agent_server/test_conversation_router.py::test_switch_conversation_profile_not_found PASSED [50%]
tests/agent_server/test_conversation_router.py::test_switch_conversation_profile_nonexistent_profile PASSED [75%]
tests/agent_server/test_conversation_router.py::test_switch_conversation_profile_corrupted_profile PASSED [100%]

4 passed in 0.36s

Functional Verification

✅ All Scenarios Verified

I created and ran a comprehensive integration test that exercises the endpoint exactly as a real HTTP client would. All 5 scenarios work correctly:

Test 1: Successful Profile Switch ✅

POST /api/conversations/{id}/switch_profile
Payload: {"profile_name": "gpt-4o"}
Status: 200
Response: {"success": true}

✓ Endpoint accepts JSON with profile_name field
✓ Returns 200 on success
✓ Calls conversation.switch_profile() with the correct profile name

Test 2: Non-existent Conversation ✅

POST /api/conversations/{fake-id}/switch_profile
Payload: {"profile_name": "gpt"}
Status: 404
Response: {"detail": "Not Found"}

✓ Returns 404 when conversation doesn't exist

Test 3: Non-existent Profile ✅

POST /api/conversations/{id}/switch_profile
Payload: {"profile_name": "nonexistent"}
Status: 404
Response: {"detail": "Profile 'nonexistent' not found"}

✓ Returns 404 when profile doesn't exist (FileNotFoundError)
✓ Error message includes the profile name for clarity

Test 4: Corrupted Profile ✅

POST /api/conversations/{id}/switch_profile
Payload: {"profile_name": "corrupted"}
Status: 400
Response: {"detail": "Invalid profile format"}

✓ Returns 400 when profile is invalid (ValueError)
✓ Error message describes the issue

Test 5: Missing Required Parameter ✅

POST /api/conversations/{id}/switch_profile
Payload: {}
Status: 422

✓ Returns 422 when profile_name is missing

Code Quality Observations

✅ Implementation is clean and follows established patterns:

Error Handling - Properly maps Python exceptions to HTTP status codes:
- FileNotFoundError → 404 (profile not found)
- ValueError → 400 (corrupted profile)
- Missing conversation → 404
Consistency - Follows the same pattern as other conversation endpoints
Testing - Comprehensive test coverage with all 4 scenarios
API Design - Uses Body(..., embed=True) to require JSON body with named field, preventing ambiguity

Issues Found

None - No issues found during QA.

Verification Evidence

Full integration test output:

======================================================================
  Testing switch_profile Endpoint - Integration Test
======================================================================

[Test 1] Switching to 'gpt-4o' profile...
  POST /api/conversations/{id}/switch_profile
  Payload: {'profile_name': 'gpt-4o'}
  Status: 200
  Response: {'success': True}
  ✓ Successfully switched profile

[Test 2] Trying non-existent conversation...
  Status: 404
  ✓ Correctly returned 404 for non-existent conversation

[Test 3] Trying non-existent profile...
  Status: 404
  Response: {'detail': "Profile 'nonexistent' not found"}
  ✓ Correctly returned 404 with descriptive error

[Test 4] Trying corrupted profile...
  Status: 400
  Response: {'detail': 'Invalid profile format'}
  ✓ Correctly returned 400 with descriptive error

[Test 5] Missing profile_name parameter...
  Status: 422
  ✓ Correctly returned 422 for missing required parameter

======================================================================
  All Integration Tests Passed!
======================================================================

Summary

✅ PASS - The switch_profile endpoint is production-ready:

✅ Endpoint implementation is correct
✅ Error handling is comprehensive
✅ All unit tests pass
✅ Integration testing confirms real-world behavior
✅ CI checks all passing
✅ No regressions detected
✅ API design follows established patterns

Recommendation: This PR is ready to merge.

add switch_profile in agent-server REST API

8974a74

VascoSch92 linked an issue Apr 10, 2026 that may be closed by this pull request

Expose model switching (switch_profile) in agent-server REST API #2794

Open

VascoSch92 requested a review from all-hands-bot April 10, 2026 07:57

This comment was marked as duplicate.

Sign in to view

VascoSch92 linked an issue Apr 10, 2026 that may be closed by this pull request

Support switching LLM models in the middle of conversation #416

Open

VascoSch92 marked this pull request as ready for review April 10, 2026 08:00

VascoSch92 requested a review from neubig April 10, 2026 08:01

This comment was marked as outdated.

Sign in to view

This comment was marked as duplicate.

Sign in to view

address feedbacks

7c591fe

VascoSch92 requested a review from all-hands-bot April 10, 2026 08:33

all-hands-bot approved these changes Apr 10, 2026

View reviewed changes

all-hands-bot reviewed Apr 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Expose model switching (switch_profile) in agent-server REST API#2795

Expose model switching (switch_profile) in agent-server REST API#2795
VascoSch92 wants to merge 2 commits intomainfrom
2794-expose-model-switching-switch_profile-in-agent-server-rest-api

VascoSch92 commented Apr 10, 2026 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Apr 10, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 10, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 10, 2026 •

edited

Loading

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as duplicate.

Uh oh!

all-hands-bot left a comment

Uh oh!

all-hands-bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

VascoSch92 commented Apr 10, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Issue Number

How to Test

Type

Notes

Uh oh!

github-actions bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python API breakage checks — ✅ PASSED

Uh oh!

github-actions bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

REST API breakage checks (OpenAPI) — ✅ PASSED

Uh oh!

github-actions bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as duplicate.

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

QA Report: switch_profile Endpoint

Environment Setup

CI & Test Status

Functional Verification

Test 1: Successful Profile Switch ✅

Test 2: Non-existent Conversation ✅

Test 3: Non-existent Profile ✅

Test 4: Corrupted Profile ✅

Test 5: Missing Required Parameter ✅

Code Quality Observations

Issues Found

Verification Evidence

Summary

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

VascoSch92 commented Apr 10, 2026 •

edited by github-actions bot

Loading

github-actions bot commented Apr 10, 2026 •

edited

Loading

github-actions bot commented Apr 10, 2026 •

edited

Loading

github-actions bot commented Apr 10, 2026 •

edited

Loading