Simplify image resolution logic in remote agent server example after runtime-api image pull policy support

[xingyaoww]

Description

The example 04_convo_with_api_sandboxed_server.py currently contains complex logic for determining which agent-server Docker image to use. This includes:

1. A get_latest_commit_sha() function that queries the GitHub API to fetch the latest commit SHA
2. Logic to conditionally use GITHUB_SHA environment variable (for CI) or fetch from main branch
3. Manual construction of the image tag with specific architecture

Current code location: examples/02_remote_agent_server/04_convo_with_api_sandboxed_server.py, lines 49-79

def get_latest_commit_sha(
    repo: str = "OpenHands/software-agent-sdk", branch: str = "main"
) -> str:
    """
    Return the full SHA of the latest commit on `branch` for the given GitHub repo.
    Respects an optional GITHUB_TOKEN to avoid rate limits.
    """
    url = f"https://api.github.com/repos/{repo}/commits/{branch}"
    headers = {}
    token = os.getenv("GITHUB_TOKEN") or os.getenv("GH_TOKEN")
    if token:
        headers["Authorization"] = f"Bearer {token}"

    resp = requests.get(url, headers=headers, timeout=20)
    if resp.status_code != 200:
        raise RuntimeError(f"GitHub API error {resp.status_code}: {resp.text}")
    data = resp.json()
    sha = data.get("sha")
    if not sha:
        raise RuntimeError("Could not find commit SHA in GitHub response")
    logger.info(f"Latest commit on {repo} branch={branch} is {sha}")
    return sha


# If GITHUB_SHA is set (e.g. running in CI of a PR), use that to ensure consistency
# Otherwise, get the latest commit SHA from main branch (images are built on main)
server_image_sha = os.getenv("GITHUB_SHA") or get_latest_commit_sha(
    "OpenHands/software-agent-sdk", "main"
)
server_image = f"ghcr.io/openhands/agent-server:{server_image_sha[:7]}-python-amd64"

Proposed Simplification

Once the Runtime API supports customizable image pull policies (tracked in https://github.com/OpenHands/runtime-api/pull/356), we can simplify this example significantly.

The simplified version could:

1. Remove the get_latest_commit_sha() helper function
2. Use a simpler, stable image tag (e.g., latest or version-based tags)
3. Let the Runtime API handle image pulling with appropriate policies
4. Reduce cognitive load for developers trying to understand the example

This would make the example more focused on demonstrating the core functionality rather than workaround logic for image availability.

References

• Runtime API PR: https://github.com/OpenHands/runtime-api/pull/356
• Related PR where this was identified: Fix Remote Runtime API Authentication #1090
• Comment thread: Fix Remote Runtime API Authentication #1090 (comment)

Tasks

• Wait for runtime-api#356 to be merged
• Update Runtime API client to support image pull policy configuration
• Simplify the example to remove complex image resolution logic
• Consider moving any remaining image utility functions to a shared utility module if needed by multiple examples

[xingyaoww]

done in #1127