feat: Add ACPAgent for Agent Client Protocol integration by simonrosenberg · Pull Request #2133 · OpenHands/software-agent-sdk

simonrosenberg · 2026-02-19T20:37:14Z

Summary

Add ACPAgent, an AgentBase subclass that delegates to ACP-compatible servers (Claude Code, Gemini CLI, etc.) instead of direct LLM calls
The ACP server manages its own LLM, tools, and execution lifecycle; ACPAgent simply relays user messages and collects responses
Includes LLM telemetry: per-turn token usage from PromptResponse.usage, incremental cost from UsageUpdate notifications, and stats callback for GUI updates
Includes stdout filtering for claude-code-acp v0.1.x which emits non-JSON-RPC log lines to stdout
Optional dependency: pip install 'openhands-sdk[acp]' (requires agent-client-protocol>=0.8.1)

Changes

File	Description
`openhands-sdk/openhands/sdk/agent/acp_agent.py`	Main implementation: `_OpenHandsACPClient`, `_filter_jsonrpc_lines`, `ACPAgent` with telemetry
`openhands-sdk/openhands/sdk/agent/__init__.py`	Lazy import for `ACPAgent` to avoid requiring `agent-client-protocol` at import time
`openhands-sdk/pyproject.toml`	Add `acp` optional dependency
`tests/sdk/agent/test_acp_agent.py`	47 unit tests covering instantiation, serialization, validation, step, cleanup, JSON-RPC filtering, and telemetry
`examples/01_standalone_sdk/36_acp_agent_example.py`	Minimal integration example with try/finally cleanup

Test plan

47 unit tests pass (uv run pytest tests/sdk/agent/test_acp_agent.py -v)
Ruff lint passes on all modified/created files
Integration example runs end-to-end with real claude-code-acp server

Closes #590

🤖 Generated with Claude Code

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.12-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:7154df8-python

Run

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

All tags pushed for this build

ghcr.io/openhands/agent-server:7154df8-golang-amd64
ghcr.io/openhands/agent-server:7154df8-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:7154df8-golang-arm64
ghcr.io/openhands/agent-server:7154df8-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:7154df8-java-amd64
ghcr.io/openhands/agent-server:7154df8-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:7154df8-java-arm64
ghcr.io/openhands/agent-server:7154df8-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:7154df8-python-amd64
ghcr.io/openhands/agent-server:7154df8-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:7154df8-python-arm64
ghcr.io/openhands/agent-server:7154df8-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:7154df8-golang
ghcr.io/openhands/agent-server:7154df8-java
ghcr.io/openhands/agent-server:7154df8-python

About Multi-Architecture Support

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

Documentation

Docs PR: docs: align ACP agent example docs#384

Add ACPAgent, an AgentBase subclass that delegates to ACP-compatible servers (Claude Code, Gemini CLI, etc.) instead of direct LLM calls. The ACP server manages its own LLM, tools, and execution lifecycle. Closes #590 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Record per-turn token usage from PromptResponse.usage in step() - Record incremental cost from UsageUpdate notifications in session_update() - Yield sentinel LLM from get_all_llms() for telemetry pipeline - Wire _llm_ref on client for dynamic metrics/telemetry access - Trigger stats callback after each step for GUI updates - Extract notification drain delay to configurable constant - Add audit logging for auto-approved permission requests - Add debug logging in cleanup for process/executor errors - Wrap example in try/finally for robust cleanup - Add 8 telemetry tests in TestACPAgentTelemetry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

all-hands-bot

🟢 Good taste - Clean integration with pragmatic workarounds for ecosystem quirks. Solid testing and good defensive error handling.

openhands-sdk/openhands/sdk/agent/acp_agent.py

…ition Add ACP_NOTIFICATION_DRAIN_DELAY env var override, yield to the event loop before the timed sleep, and add a TODO for protocol-level fix. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-02-19T20:48:23Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/agent
__init__.py	10	4	60%	17–18, 20–21
acp_agent.py	234	57	75%	100–102, 136–143, 145–146, 156–157, 159, 170–171, 176, 243, 309, 319, 324, 335–338, 351–353, 356–358, 360–361, 363, 365, 370, 378–379, 383–384, 388, 395, 398–399, 401, 403–404, 439, 446–448, 474–475, 544–545
TOTAL	19385	5297	72%

- Fix RequestPermissionResponse constructor (outcome, not result) - Add proper signatures to Client protocol stub methods - Narrow content[0] type in tests with isinstance checks - Pass required args in fs/terminal stub tests Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Renumber example 36 -> 40 to avoid conflict with 36_event_json_to_openai_messages.py - Add type: ignore[reportMissingImports] to all acp imports (optional dep) - Add TYPE_CHECKING import in __init__.py to satisfy pyright __all__ check - Add @requires_acp skip marker for tests needing the acp package Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Move acp from optional to required deps, removing: - Lazy import guard in init_state - type: ignore[reportMissingImports] comments - @requires_acp skip markers on tests - test_missing_acp_sdk_raises_import_error test The __getattr__ in __init__.py is kept to avoid a circular import. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

neubig

I think overall it looks good, I left a few comments. I assume that this has been tested, in which case we can probably merge it in and then iterate.

openhands-sdk/openhands/sdk/agent/__init__.py

openhands-sdk/openhands/sdk/agent/acp_agent.py

Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

- Rename _make_sentinel_llm → _make_dummy_llm - Move inline acp imports to top-level - Add GitHub issue link to TODO comment - Simplify _filter_jsonrpc_lines exception handling - Add debug logging for on_token and stats callback failures - Remove chatty Example from class docstring - Remove critic validation check (ACP server manages its own evaluation) - Add comment explaining lazy import in __init__.py (avoids circular dependency) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

openhands-sdk/openhands/sdk/agent/__init__.py

xingyaoww · 2026-02-20T22:17:38Z

@simonrosenberg btw, this workflow is broken. We should also add a docs for this script on OpenHands/docs repo:

https://github.com/OpenHands/software-agent-sdk/actions/runs/22243244271/job/64351561891?pr=2160

Resolve conflicts between TCP transport feature and upstream changes (ACPAgent refactoring from #2133, ask_agent from #2145). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

jpshackelford · 2026-03-06T12:12:29Z

CLI Compatibility Note

This PR introduced breaking changes to the Agent class that are incompatible with the current OpenHands-CLI:

New abstract methods required: set_config_option, fork_session, etc.
Method signature changes in new_session() and load_session()
Import changes in acp.schema (StdioMcpServer → McpServerStdio, removed SessionUpdate2-6)
agent-client-protocol bumped from <0.8.0 to >=0.8.1

CLI fix PR: OpenHands/OpenHands-CLI#548

Question: Are subsequent SDK fixes/features intended for CLI use now blocked until the CLI PR #548 is merged? For example, we're trying to test #2334 (terminal escape filter fix) with the CLI, but it fails because it's based on post-breaking-change main.

cc @enyst

enyst · 2026-03-06T12:27:37Z

@OpenHands We see this error. Check if that example is still undocumented, and if so, do what it says below. Verify in the sync workflows on the docs/ repo in the same org to understand CI on this, so you know:

❌ Found 1 undocumented example(s):

examples/01_standalone_sdk/40_acp_agent_example.py

⚠️ Please add documentation for these examples in the docs repo.

📚 How to Document Examples:

Clone the docs repository:
git clone https://github.com/OpenHands/docs.git
Create a new .mdx file in sdk/guides/ directory
(e.g., sdk/guides/my-feature.mdx)
Add the example code block with this format:
```
<code will be auto-synced>
```
See the format documentation at:
https://github.com/OpenHands/docs/blob/main/.github/scripts/README.md
Example documentation files can be found in:
https://github.com/OpenHands/docs/tree/main/sdk/guides
After creating the PR in docs repo, reference it in your
agent-sdk PR description.
============================================================
Error: Process completed with exit code 1.

openhands-ai · 2026-03-06T12:27:56Z

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

enyst · 2026-03-06T12:35:03Z

@OpenHands Read this comment #2133 (comment) and verify each link.

Look at our workflow with griffe on api breakage. Did that happen in this PR? If not, why not? Were these methods referenced in the public api? (if not, do you think they should be, wdyt?)

Then. We just made a release of the SDK, find the release PR.

Clone yourself the CLI repo and verify on which SDK version it is. If we upgrade it, will the comment still apply?

Make a new investigation issue in the sdk repo, and answer my questions there, plus any results of your investigation. Answer the questions in the comment linked, too.

openhands-ai · 2026-03-06T12:35:24Z

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

openhands-ai · 2026-03-06T12:41:03Z

Final summary of work:

Verified the PR comment links: OpenHands‑CLI PR Refactor: Move state persistence from callback to direct agent.py calls #548 is open/draft and SDK PR fix(terminal): filter terminal query sequences from captured output #2334 is open but mergeable_state reported as blocked.
Checked the Griffe API breakage workflow: it ran for PR feat: Add ACPAgent for Agent Client Protocol integration #2133 and succeeded; no public API breakage detected because the methods cited are not part of the SDK’s public __all__ surface. Suggested keeping them non‑public unless we want to formalize them on AgentBase.
Found the latest SDK release PR (Release v1.12.0 #2302 – Release v1.12.0, merged 2026‑03‑05).
Cloned OpenHands‑CLI and confirmed main pins openhands‑sdk==1.11.5 (tools 1.11.5, workspace 1.11.1), meaning post‑breaking‑change SDK fixes are blocked for CLI until it updates. If CLI upgrades to 1.12.0 or merges PR Refactor: Move state persistence from callback to direct agent.py calls #548, the compatibility note should no longer apply.
Created investigation issue Investigation: CLI compatibility and API breakage check for PR #2133 #2343 with all findings.

No code changes were made; therefore there is nothing to push.

simonrosenberg and others added 2 commits February 19, 2026 16:45

all-hands-bot approved these changes Feb 19, 2026

View reviewed changes

openhands-sdk/openhands/sdk/agent/acp_agent.py Outdated Show resolved Hide resolved

Make notification drain delay configurable and document the race cond…

364fca1

…ition Add ACP_NOTIFICATION_DRAIN_DELAY env var override, yield to the event loop before the timed sleep, and add a TODO for protocol-level fix. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

simonrosenberg and others added 3 commits February 19, 2026 19:53

simonrosenberg mentioned this pull request Feb 20, 2026

docs(sdk): add ACP Agent guide OpenHands/docs#351

Merged

simonrosenberg self-assigned this Feb 20, 2026

neubig reviewed Feb 20, 2026

View reviewed changes

enyst reviewed Feb 20, 2026

View reviewed changes

openhands-sdk/openhands/sdk/agent/acp_agent.py Outdated Show resolved Hide resolved

enyst reviewed Feb 20, 2026

View reviewed changes

openhands-sdk/openhands/sdk/agent/acp_agent.py Outdated Show resolved Hide resolved

enyst reviewed Feb 20, 2026

View reviewed changes

openhands-sdk/openhands/sdk/agent/acp_agent.py Outdated Show resolved Hide resolved

simonrosenberg and others added 2 commits February 20, 2026 15:19

Update openhands-sdk/openhands/sdk/agent/acp_agent.py

f04ca71

Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

Update openhands-sdk/openhands/sdk/agent/acp_agent.py

2ae9b9b

Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

simonrosenberg force-pushed the feat/acp-agent branch 4 times, most recently from 934a9d8 to d5c43b1 Compare February 20, 2026 19:24

simonrosenberg force-pushed the feat/acp-agent branch from d5c43b1 to 506a50a Compare February 20, 2026 19:28

Merge branch 'main' into feat/acp-agent

d49438a

simonrosenberg commented Feb 20, 2026

View reviewed changes

openhands-sdk/openhands/sdk/agent/__init__.py Outdated Show resolved Hide resolved

Apply suggestion from @simonrosenberg

6e97751

simonrosenberg merged commit fc84a48 into main Feb 20, 2026
27 of 28 checks passed

simonrosenberg deleted the feat/acp-agent branch February 20, 2026 22:06

This was referenced Mar 6, 2026

feat: implement Ctrl+C pause/interrupt flow and update SDK hash OpenHands/OpenHands-CLI#548

Draft

fix(terminal): filter terminal query sequences from captured output #2334

Open

enyst mentioned this pull request Mar 6, 2026

docs: align ACP agent example OpenHands/docs#384

Closed

This comment was marked as duplicate.

Sign in to view

enyst mentioned this pull request Mar 6, 2026

Investigation: CLI compatibility and API breakage check for PR #2133 #2343

Closed

Conversation

simonrosenberg commented Feb 19, 2026 • edited by enyst Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Test plan

Documentation

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

neubig left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xingyaoww commented Feb 20, 2026

Uh oh!

jpshackelford commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CLI Compatibility Note

Uh oh!

enyst commented Mar 6, 2026

❌ Found 1 undocumented example(s):

⚠️ Please add documentation for these examples in the docs repo.

📚 How to Document Examples:

Uh oh!

openhands-ai bot commented Mar 6, 2026

Uh oh!

This comment was marked as duplicate.

enyst commented Mar 6, 2026

Uh oh!

openhands-ai bot commented Mar 6, 2026

Uh oh!

openhands-ai bot commented Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

simonrosenberg commented Feb 19, 2026 •

edited by enyst

Loading

github-actions bot commented Feb 19, 2026 •

edited

Loading

jpshackelford commented Mar 6, 2026 •

edited

Loading