feat: API design: launched agent profile provenance names#3788
Conversation
Python API breakage checks — ✅ PASSEDResult: ✅ PASSED |
REST API breakage checks (OpenAPI) — ✅ PASSEDResult: ✅ PASSED |
Coverage Report •
|
||||||||||||||||||||||||||||||
enyst
changed the title
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
⚠️ QA Report: PASS WITH ISSUES
Runtime verification confirms the PR delivers the explicit launched agent profile provenance names and keeps the short-lived legacy payload loadable; the only issue observed is an unrelated PR-description CI gate failure requiring human input.
Does this PR achieve its stated goal?
Yes. On main, the public model/export is still LaunchedProfile and conversation JSON reserializes provenance as launched_profile.profile_id; on the PR branch, the same runtime checks expose LaunchedAgentProfile, persist/return launched_agent_profile.agent_profile_id, and load the legacy launched_profile.profile_id payload before reserializing it to the explicit names. This directly verifies the PR goal of clarifying provenance names while preserving compatibility for conversations created with the short-lived merged payload shape.
| Phase | Result |
|---|---|
| Environment Setup | ✅ uv sync --dev completed successfully; no repo files modified. |
| CI Status | Validate PR description), 2 skipped, 3 in progress at snapshot time. |
| Functional Verification | ✅ Before/after runtime script exercised SDK imports, persistence JSON, legacy loading, and ConversationInfo response shape. |
Functional Verification
Test 1: Public provenance model name and serialized nested ID
Step 1 — Establish baseline on origin/main:
Ran OPENHANDS_SUPPRESS_BANNER=1 uv run python /tmp/qa_agent_profile_provenance.py after git checkout --detach origin/main:
commit 76e0e790
== Public profile provenance imports ==
LaunchedAgentProfile import/use: FAIL ImportError cannot import name 'LaunchedAgentProfile' from 'openhands.sdk.profiles'
LaunchedProfile import: OK
LaunchedProfile dump: {"profile_id": "55bc66e6-3b5f-440b-b606-2ed40587f318", "revision": 7}
This shows the baseline API still used the ambiguous LaunchedProfile name and profile_id JSON key.
Step 2 — Apply the PR's changes:
Checked out clarify-launched-agent-profile at 08e687c4.
Step 3 — Re-run with the PR branch:
Ran OPENHANDS_SUPPRESS_BANNER=1 uv run python /tmp/qa_agent_profile_provenance.py:
commit 08e687c4
== Public profile provenance imports ==
LaunchedAgentProfile import: OK
LaunchedAgentProfile dump: {"agent_profile_id": "e79df535-2672-476c-b78a-8fef172a1334", "revision": 7}
LaunchedProfile import/use: FAIL ImportError cannot import name 'LaunchedProfile' from 'openhands.sdk.profiles'
This confirms the public exported model and nested serialized ID now use the explicit agent-profile naming.
Test 2: StoredConversation persistence shape and legacy compatibility
Step 1 — Establish baseline on origin/main:
The same baseline run produced:
== StoredConversation new-shape persistence ==
new-shape kwarg accepted by model: True
dump has launched_agent_profile: False
dump has launched_profile: False
== Legacy short-lived payload compatibility ==
legacy payload loads: OK
reserialized keys: ['launched_profile']
reserialized provenance: {"launched_profile": {"profile_id": "55bc66e6-3b5f-440b-b606-2ed40587f318", "revision": 4}}
This shows main did not persist the new explicit field name and still reserialized the legacy payload using the old names.
Step 2 — Apply the PR's changes:
Checked out clarify-launched-agent-profile at 08e687c4.
Step 3 — Re-run with the PR branch:
The PR branch run produced:
== StoredConversation new-shape persistence ==
dump has launched_agent_profile: True
dump has launched_profile: False
dumped provenance: {"agent_profile_id": "e79df535-2672-476c-b78a-8fef172a1334", "revision": 7}
json reload agent_profile_id: e79df535-2672-476c-b78a-8fef172a1334
== Legacy short-lived payload compatibility ==
legacy payload loads: OK
reserialized keys: ['launched_agent_profile']
reserialized provenance: {"launched_agent_profile": {"agent_profile_id": "e79df535-2672-476c-b78a-8fef172a1334", "revision": 4}}
This confirms new persistence uses launched_agent_profile.agent_profile_id, JSON round-trip preserves it, and legacy launched_profile.profile_id still loads but reserializes to the explicit names.
Test 3: ConversationInfo response shape
Step 1 — Establish baseline on origin/main:
The baseline run produced:
== ConversationInfo response shape ==
response launched keys: ['launched_profile']
response provenance: {"launched_profile": {"profile_id": "55bc66e6-3b5f-440b-b606-2ed40587f318", "revision": 3}}
This shows user-facing conversation info responses previously exposed the ambiguous field names.
Step 2 — Apply the PR's changes:
Checked out clarify-launched-agent-profile at 08e687c4.
Step 3 — Re-run with the PR branch:
The PR branch run produced:
== ConversationInfo response shape ==
response launched keys: ['launched_agent_profile']
response provenance: {"launched_agent_profile": {"agent_profile_id": "e79df535-2672-476c-b78a-8fef172a1334", "revision": 3}}
This confirms the API response model now serializes the explicit provenance field/key pair.
Issues Found
- 🟡 Non-functional CI issue:
Validate PR descriptionis failing because the first visible PR description line is notHUMAN:and a human-written note is missing. Per repo guidance, I did not edit the human-only PR description fields. Remaining in-progress checks at snapshot time:Build & Push (java-amd64),Build & Push (java-arm64), andqa-changes.
This review was generated by an AI agent (OpenHands) on behalf of the user.
Rename the conversation-start provenance model and API field to explicitly reference agent profiles, while accepting the short-lived legacy payload names during validation. Co-authored-by: openhands <openhands@all-hands.dev>
enyst
force-pushed
the
clarify-launched-agent-profile
branch
from
08e687c to
acde9b2
Compare
3 participants
HUMAN:
We now have LLM profiles and Agent profiles: this PR proposes simply to keep the API clear on which is which.
AGENT:
Why
Follow-up to review feedback on #3784: the codebase now has both LLM profiles and agent profiles, so newly added public API names should make the profile kind explicit where the shorter
profilewording could be ambiguous.Summary
LaunchedProfiletoLaunchedAgentProfile.launched_profiletolaunched_agent_profile.profile_idtoagent_profile_id.Issue Number
Follow-up to #3784 / #3720.
How to Test
Validated locally with:
Result:
Also ran pre-commit on all changed files:
Result:
Video/Screenshots
No UI changes. The affected behavior is an agent-server/SDK response and persistence schema naming cleanup; targeted unit tests cover the updated serialization shape.
Type
Notes
I intentionally did not rename the existing legacy LLM-profile API surfaces such as
/api/profiles,active_profile, orswitch_profile; those are already established and documented as LLM-profile paths. This PR focuses on the new agent-profile provenance names introduced by #3784, where changing the names now is still small and targeted.Because #3784 only merged today and this change is intended to land before release, this PR does not carry compatibility aliases for the short-lived
launched_profile.profile_idshape.This PR description AGENT section was updated 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
eclipse-temurin:17-jdknikolaik/python-nodejs:python3.13-nodejs22-slimgolang:1.21-bookwormPull (multi-arch manifest)
# Each variant is a multi-arch manifest supporting both amd64 and arm64 docker pull ghcr.io/openhands/agent-server:acde9b2-pythonRun
All tags pushed for this build
About Multi-Architecture Support
acde9b2-python) is a multi-arch manifest supporting both amd64 and arm64acde9b2-python-amd64) are also available if needed