Add ACPAgent remote runtime example docs

[simonrosenberg]

Summary

• Add documentation for examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py to the ACP agent guide page

This is the companion docs PR for OpenHands/software-agent-sdk#2190, which adds ACPAgent support on RemoteRuntime.

Test plan

• Verify the check-examples CI check passes on the agent-sdk PR after this branch exists

🤖 Generated with Claude Code

[all-hands-bot]

🟢 Good taste

Verified against upstream PR software-agent-sdk#2190 - code matches exactly, imports check out, follows documentation conventions. Clean, straightforward addition.

VERDICT: ✅ Merge it

No unnecessary complexity. No breaking changes. Just documents a real feature with working code. This is how docs PRs should be done.

[xingyaoww]

thank you!

[xingyaoww]

@OpenHands please follow the docs in this PR and try to use the OPENHANDS_API_KEY, LLM_API_KEY and LLM_BASE_URL provided to you in secrets and try to run this example, and tell me if it works

[openhands-ai]

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

[xingyaoww]

I tried running the example examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py from the agent-sdk PR branch (feat/acp-remote-runtime). Here are my findings:

Setup

• Cloned software-agent-sdk and checked out the feat/acp-remote-runtime branch
• Set LLM_BASE_URL=https://llm-proxy.app.all-hands.dev (inferred from CI workflow .github/workflows/run-examples.yml — this was not available in my secrets)
• Set LLM_API_KEY from my available secrets ✅
• Set RUNTIME_API_KEY=$OPENHANDS_API_KEY (as instructed)

Result: ❌ Failed with 401 Unauthorized

httpx.HTTPStatusError: Client error '401 Unauthorized' for url 'https://runtime.eval.all-hands.dev/sessions/...'

The error message from the API: {'error': 'Unauthorized. Please provide a valid API key in the X-API-Key header.'}

I also tried RUNTIME_API_URL=https://runtime.app.all-hands.dev — same 401 result.

Root Cause

The example requires a RUNTIME_API_KEY that authenticates with the Runtime API (runtime.eval.all-hands.dev). The OPENHANDS_API_KEY I have is for OpenHands Cloud (app.all-hands.dev SaaS API), which is a different service. Looking at the CI workflow, RUNTIME_API_KEY comes from ${{ secrets.RUNTIME_API_KEY }} — a separate secret that is not available to me.

Summary of secrets needed vs. available

Variable	Required By	Available to me?
LLM_API_KEY	ACP agent LiteLLM proxy auth	✅ Yes
LLM_BASE_URL	ACP agent LiteLLM proxy URL	❌ Not in secrets (had to infer from CI config)
RUNTIME_API_KEY	Runtime API auth	❌ No (OPENHANDS_API_KEY is for a different service)

To run this example, I would need the actual RUNTIME_API_KEY secret that has access to runtime.eval.all-hands.dev (or runtime.app.all-hands.dev).

[openhands-ai]

Summary

I attempted to run the ACP agent remote runtime example (examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py) as requested in the PR comment on #392. Here's what I did and found:

Steps Taken

1. Cloned the software-agent-sdk repo and checked out the feat/acp-remote-runtime PR branch
2. Installed the SDK dependencies via uv
3. Configured environment variables:
   • LLM_API_KEY — from my available secrets ✅
   • LLM_BASE_URL — inferred as https://llm-proxy.app.all-hands.dev from the CI workflow (not directly in my secrets)
   • RUNTIME_API_KEY — set to $OPENHANDS_API_KEY as instructed
4. Ran the example script
5. Also tried with RUNTIME_API_URL=https://runtime.app.all-hands.dev as a fallback

Result: ❌ Failed with 401 Unauthorized

The Runtime API (runtime.eval.all-hands.dev and runtime.app.all-hands.dev) rejected OPENHANDS_API_KEY with:

{'error': 'Unauthorized. Please provide a valid API key in the X-API-Key header.'}

Root Cause

The OPENHANDS_API_KEY is for the OpenHands Cloud SaaS API (app.all-hands.dev), which is a different service from the Runtime API. The example requires a dedicated RUNTIME_API_KEY (sourced from ${{ secrets.RUNTIME_API_KEY }} in CI), which I do not have access to. Additionally, LLM_BASE_URL was not provided in my secrets.

Actions

• No code changes were made — this was a test/verification request only.
• I posted a detailed comment on PR Add ACPAgent remote runtime example docs #392 with my findings including the error output, root cause analysis, and a table of required vs. available secrets.

[xingyaoww]

@OpenHands please follow the docs in this PR and try to use the RUNTIME_API_KEY (i just gave you that!), LLM_API_KEY and LLM_BASE_URL provided to you in secrets and try to run this example, and tell me if it works

[openhands-ai]

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

[xingyaoww]

Results of Running the ACP Remote Runtime Example

I ran the example examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py from the feat/acp-remote-runtime branch of software-agent-sdk using the provided secrets (RUNTIME_API_KEY, LLM_API_KEY, LLM_BASE_URL=https://llm-proxy.app.all-hands.dev).

Run 1: Using main image (default, no GITHUB_SHA)

Image: ghcr.io/openhands/agent-server:main-python-amd64

• ✅ Runtime API authentication worked (runtime created successfully)
• ✅ Pod started and became ready in ~40 seconds
• ✅ Health check passed (HTTP 200)
• ❌ Failed with HTTP 422 when creating conversation:

  Unknown kind 'ACPAgent' for openhands.sdk.agent.base.AgentBase; Expected one of: ['Agent']
  

  This is expected — the main agent-server image doesn't include ACPAgent support since software-agent-sdk#2190 hasn't been merged yet.

Run 2: Using PR-specific image (GITHUB_SHA=0f438b5...)

Image: ghcr.io/openhands/agent-server:0f438b5-python-amd64

• ✅ Runtime API authentication worked
• ❌ Pod stuck in pending indefinitely — the image 0f438b5-python-amd64 likely doesn't exist in the container registry (CI may not have built it for this commit, or the image build hasn't completed yet).

Summary

Aspect	Status
RUNTIME_API_KEY authentication	✅ Works
LLM_API_KEY / LLM_BASE_URL setup	✅ Configured correctly
Runtime API pod provisioning	✅ Works (with valid images)
ACPAgent on remote runtime	❌ Blocked — needs a server image with ACPAgent support

Bottom line: The infrastructure and authentication all work correctly. The example itself cannot complete end-to-end until the SDK PR (#2190) is merged to main (so the main image includes ACPAgent), or until CI runs on the SDK PR and publishes the Docker image with the PR's commit SHA. This is expected for a pre-merge test — the example is designed to work in CI where GITHUB_SHA points to a just-built image.

[openhands-ai]

Summary

I ran the ACP agent remote runtime example (examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py) from the feat/acp-remote-runtime branch of software-agent-sdk as requested in the PR comment. I used the provided secrets (RUNTIME_API_KEY via $RUNTIME_API, LLM_API_KEY, and LLM_BASE_URL=https://llm-proxy.app.all-hands.dev).

Results

Run 1 — Using main image (default, no GITHUB_SHA):

• ✅ Runtime API authentication worked
• ✅ Pod provisioned and became ready (~40s)
• ✅ Health check passed (HTTP 200)
• ❌ Failed with HTTP 422: Unknown kind 'ACPAgent' — the main agent-server image doesn't include ACPAgent support since SDK PR #2190 hasn't been merged yet.

Run 2 — Using PR-specific image (GITHUB_SHA=0f438b5...):

• ✅ Runtime API authentication worked
• ❌ Pod stuck in pending indefinitely — the Docker image 0f438b5-python-amd64 doesn't exist in the container registry (CI hasn't built it for this commit).

Conclusion

The infrastructure and all credentials work correctly. The example cannot complete end-to-end right now because there is no Docker image available that includes ACPAgent support. This will resolve once either:

1. The SDK PR (#2190) merges to main and the main image is rebuilt, or
2. CI runs on the SDK PR and publishes a Docker image tagged with the PR's commit SHA.

This is expected behavior — the example is designed for CI where GITHUB_SHA points to a freshly built image.

No code changes were made — this was purely a test run. I posted the detailed findings as a comment on PR #392.