Use version tag for agent server image in version bump prs

[aivong-openhands]

Summary

• Fixes workflow by using python version 3.12
• Switches out update of SDK dependencies from a poetry lock command that was too loose with constraints to sed
• Updates agent server image in openhands to a version tag instead of commit hash
  • See prior version bump PR Bump SDK packages to v1.11.5 OpenHands#12966

Test run of workflow generated the following version bump PR: OpenHands/OpenHands#13394

Checklist

• If the PR is changing/adding functionality, are there tests to reflect this?
• If there is an example, have you run the example to make sure that it works?
• If there are instructions on how to run the code, have you followed the instructions and made sure that it works?
• If the feature is significant enough to require documentation, is there a PR open on the OpenHands/docs repository with the same branch name?
• Is the github CI passing?

---

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	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:59874b3-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

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

[github-actions]

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

[aivong-openhands]

Issue: poetry add --lock normalizes version constraints

When running poetry add --lock "openhands-sdk==$VERSION", Poetry normalizes the version constraint. For example, ==1.13.1 becomes "1.13" in pyproject.toml. This causes two problems:

1. Inconsistency between sections: As seen in the generated version bump PR, the [project].dependencies section (PEP 621 format) was correctly updated to ==1.13.1, but the [tool.poetry.dependencies] section only got "1.13" (normalized by Poetry)
2. Loose constraints: "1.13" means >=1.13.0,<1.14.0 rather than exactly 1.13.1

Solution

Replace poetry add --lock with sed commands to update both sections with exact version pins, then use poetry lock --no-update to regenerate the lock file.

Suggested changes for the workflow

Replace this section:

poetry add --lock "openhands-sdk==$VERSION" "openhands-tools==$VERSION" "openhands-agent-server==$VERSION"

With:

# 1. Update versions in pyproject.toml using sed for exact pinning
# Note: We use sed instead of `poetry add --lock` because Poetry normalizes
# version constraints (e.g., "==1.13.1" becomes "1.13") which causes
# inconsistencies between [tool.poetry.dependencies] and [project].dependencies
echo "📝 Updating pyproject.toml with exact version pins..."

# Update [tool.poetry.dependencies] section
# Matches: openhands-sdk = "1.13" or openhands-sdk = "1.13.0"
sed -i -E 's/^(openhands-sdk = )"[^"]*"/\1"'"$VERSION"'"/' pyproject.toml
sed -i -E 's/^(openhands-tools = )"[^"]*"/\1"'"$VERSION"'"/' pyproject.toml
sed -i -E 's/^(openhands-agent-server = )"[^"]*"/\1"'"$VERSION"'"/' pyproject.toml

# Update [project].dependencies section (PEP 621 format)
# Matches: "openhands-sdk==1.13.1", or "openhands-sdk==1.13",
sed -i -E 's/"openhands-sdk==[^"]*"/"openhands-sdk=='"$VERSION"'"/' pyproject.toml
sed -i -E 's/"openhands-tools==[^"]*"/"openhands-tools=='"$VERSION"'"/' pyproject.toml
sed -i -E 's/"openhands-agent-server==[^"]*"/"openhands-agent-server=='"$VERSION"'"/' pyproject.toml

echo "✅ Updated pyproject.toml"

# 2. Regenerate poetry.lock with the new versions
echo "📝 Regenerating poetry.lock..."
poetry lock --no-update

---

Note: I attempted to push this change directly but the GitHub token lacks workflow scope required to update workflow files. You'll need to apply this change manually or use a token with workflow permissions.

[aivong-openhands]

@OpenHands check why this workflow failed https://github.com/OpenHands/software-agent-sdk/actions/runs/23071803626/job/67023767599. Is the poetry version 2.2.1?

[openhands-ai]

I'm on it! aivong-openhands can track my progress at all-hands.dev

[aivong-openhands]

Investigation Results

Yes, the workflow is using Poetry version 2.2.1 (as shown in the logs: installed package poetry 2.2.1).

Root Cause

The workflow failed because it was using poetry lock --no-update, but the --no-update flag was removed in Poetry 2.x.

From the error message:

The option "--no-update" does not exist

The Fix

In Poetry 2.x, the default behavior of poetry lock is to not update packages already in the lock file, so the --no-update flag is no longer needed. I've updated the workflow to just use poetry lock without the flag.

Commit: ef98e81

[openhands-ai]

Final Summary

Answer to the Question

Yes, Poetry version 2.2.1 was being used in the failed workflow (confirmed from logs: installed package poetry 2.2.1).

Root Cause

The workflow failed because it used poetry lock --no-update, but the --no-update flag was removed in Poetry 2.x. The error was:

The option "--no-update" does not exist

Fix Applied

In Poetry 2.x, the default behavior of poetry lock is to not update packages already in the lock file, so the flag is no longer needed. I updated the workflow to use poetry lock without the flag.

Changes Made (already pushed)

Commit: ef98e81

-                  poetry lock --no-update
+                  # Note: In Poetry 2.x, the default behavior is to not update packages already
+                  # in the lock file (the --no-update flag was removed in Poetry 2.x)
+                  poetry lock

Also fixed step comment numbering (duplicate "# 2." → "# 3." and "# 4.").

Checklist

• ✅ Investigated the workflow failure
• ✅ Confirmed Poetry 2.2.1 was being used
• ✅ Identified root cause (--no-update flag removed in Poetry 2.x)
• ✅ Fixed the issue with minimal, focused changes
• ✅ Ran pre-commit (passed)
• ✅ Committed and pushed to the PR branch
• ✅ Replied to the PR comment with findings

[all-hands-bot]

🟡 Acceptable - Pragmatic simplification that solves a real problem. The sed approach is a reasonable workaround for Poetry's version normalization behavior, though it comes with inherent fragility. One important concern about missing validation.

[all-hands-bot]

🟠 Important: Missing validation that the version tag exists in the registry.

The old code validated the tag existed before proceeding:

SDK_COMMIT_HASH=$(git ls-remote ... "refs/tags/v$VERSION" | cut -c1-7)
if [ -z "$SDK_COMMIT_HASH" ]; then
  echo "⚠️ Could not find commit hash..."
fi

Consider adding validation that the agent-server image with this version tag is actually published before updating references. This would catch synchronization issues between SDK releases and agent-server image publishing.

Example:

# Validate version exists in GHCR
if ! docker manifest inspect "ghcr.io/openhands/agent-server:${VERSION}-python" > /dev/null 2>&1; then
  echo "❌ Image tag ${VERSION} not found in registry"
  exit 1
fi

However, if the release process guarantees the images are published before this workflow triggers, this validation may be unnecessary overhead.

[all-hands-bot]

🟡 Suggestion: The sed approach is fragile but pragmatic.

Six separate sed commands with regex patterns will break if pyproject.toml formatting changes. The comment explaining Poetry's normalization behavior is helpful.

This is an acceptable trade-off - you're working around a tool limitation. The explicit approach (vs. a loop) makes debugging easier when things break.

Consider adding a validation step after the sed commands to ensure all three packages were actually updated:

# Verify all packages were updated
for pkg in openhands-sdk openhands-tools openhands-agent-server; do
  if ! grep -q "\"$pkg.*$VERSION\"" pyproject.toml; then
    echo "❌ Failed to update $pkg to $VERSION"
    exit 1
  fi
done

[all-hands-bot]

🟢 Acceptable: Pinning Poetry to 2.2.1 is pragmatic for reproducibility.

Just remember to bump this when Poetry releases contain fixes you need. The lock file regeneration behavior mentioned in line 255 is specific to Poetry 2.x, so this pin ensures the workflow doesn't break with unexpected version changes.