Document LLM profile migration design

[enyst]

Summary

• Adds a PR-scoped design assessment for Simplify LLM settings around profiles and remove raw LLM config from settings surfaces #3511.
• Maps the current raw LLM persistence/REST surfaces and existing profile infrastructure.
• Proposes a phased migration toward profile references at persistence/REST boundaries while keeping concrete LLM objects at runtime.

Validation

• uv run pre-commit run --files .pr/llm-profiles-design.md

This PR was created by an AI agent (OpenHands) on behalf of the user.

@enyst can click here to continue refining the PR

---

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:b67c700-python

Run

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

All tags pushed for this build

ghcr.io/openhands/agent-server:b67c700-golang-amd64
ghcr.io/openhands/agent-server:b67c700f238f34e3edcc34628c6a8bd6681d2e97-golang-amd64
ghcr.io/openhands/agent-server:design-llm-profiles-doc-golang-amd64
ghcr.io/openhands/agent-server:b67c700-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:b67c700-golang-arm64
ghcr.io/openhands/agent-server:b67c700f238f34e3edcc34628c6a8bd6681d2e97-golang-arm64
ghcr.io/openhands/agent-server:design-llm-profiles-doc-golang-arm64
ghcr.io/openhands/agent-server:b67c700-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:b67c700-java-amd64
ghcr.io/openhands/agent-server:b67c700f238f34e3edcc34628c6a8bd6681d2e97-java-amd64
ghcr.io/openhands/agent-server:design-llm-profiles-doc-java-amd64
ghcr.io/openhands/agent-server:b67c700-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:b67c700-java-arm64
ghcr.io/openhands/agent-server:b67c700f238f34e3edcc34628c6a8bd6681d2e97-java-arm64
ghcr.io/openhands/agent-server:design-llm-profiles-doc-java-arm64
ghcr.io/openhands/agent-server:b67c700-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:b67c700-python-amd64
ghcr.io/openhands/agent-server:b67c700f238f34e3edcc34628c6a8bd6681d2e97-python-amd64
ghcr.io/openhands/agent-server:design-llm-profiles-doc-python-amd64
ghcr.io/openhands/agent-server:b67c700-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-amd64
ghcr.io/openhands/agent-server:b67c700-python-arm64
ghcr.io/openhands/agent-server:b67c700f238f34e3edcc34628c6a8bd6681d2e97-python-arm64
ghcr.io/openhands/agent-server:design-llm-profiles-doc-python-arm64
ghcr.io/openhands/agent-server:b67c700-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-arm64
ghcr.io/openhands/agent-server:b67c700-golang
ghcr.io/openhands/agent-server:b67c700f238f34e3edcc34628c6a8bd6681d2e97-golang
ghcr.io/openhands/agent-server:design-llm-profiles-doc-golang
ghcr.io/openhands/agent-server:b67c700-golang_tag_1.21-bookworm
ghcr.io/openhands/agent-server:b67c700-java
ghcr.io/openhands/agent-server:b67c700f238f34e3edcc34628c6a8bd6681d2e97-java
ghcr.io/openhands/agent-server:design-llm-profiles-doc-java
ghcr.io/openhands/agent-server:b67c700-eclipse-temurin_tag_17-jdk
ghcr.io/openhands/agent-server:b67c700-python
ghcr.io/openhands/agent-server:b67c700f238f34e3edcc34628c6a8bd6681d2e97-python
ghcr.io/openhands/agent-server:design-llm-profiles-doc-python
ghcr.io/openhands/agent-server:b67c700-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim

About Multi-Architecture Support

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

[github-actions]

📁 PR Artifacts Notice

This PR contains a .pr/ directory with PR-specific documents. This directory will be automatically removed when the PR is approved.

For fork PRs: Manual removal is required before merging.

[github-actions]

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log