docs(sdk): add ACP Agent guide by simonrosenberg · Pull Request #351 · OpenHands/docs

simonrosenberg · 2026-02-20T11:37:22Z

Summary

Adds sdk/guides/agent-acp.mdx documenting ACPAgent usage, configuration, metrics, and cleanup
References examples/01_standalone_sdk/40_acp_agent_example.py from software-agent-sdk#2133
Adds the new page to the "Agent Features" navigation group in docs.json

Context

This branch is needed by the check-documented-examples CI job on software-agent-sdk PR #2133, which checks out a matching docs branch (feat/acp-agent) to verify that new examples are documented.

🤖 Generated with Claude Code

Documents ACPAgent usage, configuration, metrics, and cleanup with a ready-to-run example referencing examples/01_standalone_sdk/40_acp_agent_example.py. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

all-hands-bot

🟡 Acceptable - Documentation is clear and practical, but has organizational issues and unverified syntax.

Key Issue: Important information about ACP delegation model is scattered. The fact that this replaces direct LLM calls (no API key needed, server manages everything) should be front and center, not discovered at line 143.

sdk/guides/agent-acp.mdx

docs.json

simonrosenberg · 2026-02-20T13:08:28Z

@OpenHands read the PR and apply all suggestions

openhands-ai · 2026-02-20T13:08:49Z

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

- Replace 'wrap focus={5-7}' with 'highlight={5-7}' per Mintlify standards - Remove 'wrap' attribute from other code blocks - Add Note callout explaining key differentiator (no LLM_API_KEY needed) - Move 'What ACPAgent Does Not Support' section after Basic Usage - Expand permission auto-approval explanation with security context Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-02-20T13:11:14Z

Summary

I've successfully applied all review suggestions from PR #351. The changes have already been committed and pushed to the feat/acp-agent branch.

Checklist of Review Suggestions Applied:

✅ Fixed code block syntax - Changed wrap focus={5-7} to highlight={5-7} per Mintlify standards (and removed wrap from 3 other code blocks)
✅ Added key differentiator callout - Added <Note> component after Basic Usage explaining that ACPAgent doesn't need an LLM_API_KEY (addresses the "buried at line 143" feedback)
✅ Moved constraints section earlier - Relocated "What ACPAgent Does Not Support" to right after Basic Usage so developers understand limitations upfront
✅ Expanded permission auto-approval explanation - Added security context: "this means the SDK automatically grants any tool execution or file access the server requests, so ensure you trust the ACP server you're running"
✅ docs.json placement - Already correct (reviewer confirmed ✅)

Commit Details:

Commit: 718ed57
Branch: feat/acp-agent
Files changed: sdk/guides/agent-acp.mdx (+21 lines, -17 lines)

The changes are concise and focused solely on addressing the review feedback. No extraneous modifications were made.

all-hands-bot

🟡 Acceptable - Good improvements from previous feedback, but missing the "how to run" instructions that users need.

Key Issue: You import RunExampleCode but never use it, and provide no alternative bash block. Users reading this will see example code but no clear command to execute it.

sdk/guides/agent-acp.mdx

simonrosenberg · 2026-02-24T20:35:10Z

@OpenHands please read the reviews and fix them

openhands-ai · 2026-02-24T20:35:31Z

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

all-hands-bot

🟡 Acceptable - Docs are functional but still have unresolved usability issues from previous rounds.

sdk/guides/agent-acp.mdx

- Remove unused RunExampleCode import - Fix highlight range from {5-7} to {5,7-9} to skip blank line - Add bash code block with 'Running the Example' instructions Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-02-24T20:37:16Z

Summary

I've successfully addressed the two outstanding review comments on PR #351:

Changes Made:

Review Feedback	Fix Applied
`highlight={5-7}` includes blank line (line 6)	Changed to `highlight={5,7-9}` to skip the blank line
Imported `RunExampleCode` but never used it	Removed the unused import
Users need runnable instructions	Added bash code block with "Running the Example" instructions

Checklist:

✅ Fixed highlight range to skip blank line (used {5,7-9} as suggested)
✅ Removed unused RunExampleCode import
✅ Added bash code block following the suggested pattern (includes authentication note about Claude Code CLI)
✅ Changes are minimal and focused only on review feedback
✅ Changes committed and pushed to feat/acp-agent branch

Commit: bb768a9 - "fix: address review feedback for ACP Agent guide"

all-hands-bot

🟡 Acceptable - Previous issues have been addressed. Document is functional and practical, but could be more concise.

all-hands-bot · 2026-02-24T20:41:58Z

sdk/guides/agent-acp.mdx

+4. The server processes the request using its own LLM and tools, streaming session updates (text chunks, thought chunks, tool calls) back to the SDK
+5. The SDK accumulates the response and emits it as a `MessageEvent`
+6. Permission requests from the server are auto-approved — this means the SDK automatically grants any tool execution or file access the server requests, so ensure you trust the ACP server you're running
+7. Token usage and cost metrics from the ACP server are captured into the agent's `LLM.metrics`


🟡 Suggestion: This 7-step procedural breakdown is verbose for a usage guide. Users don't need to know that the SDK calls conn.prompt() internally or that it emits a MessageEvent.

Condense to 3-4 key architectural points:

Subprocess delegation: ACPAgent spawns the ACP server and communicates via JSON-RPC

Server-managed execution: The ACP server handles its own LLM calls, tools, and context

Auto-approval: Permission requests are auto-approved (trust your ACP server)

Metrics collection: Token usage and costs are captured automatically

The current version reads like implementation docs rather than user-facing guidance. Keep it at the conceptual level — users care about what happens (delegation model), not how the SDK implements it (method names, event types).

Interesting nit. I tend to agree with the agent, FWIW though, I was thinking about this on other issues: sometimes we really seem to need some docs for the agent, and some other doc for the human.

I'm looking into a custom llms.txt for this... Maybe. Or shadow docs. Or invisible comments 😅

simonrosenberg · 2026-02-24T20:44:21Z

@OpenHands please apply all the PR reviews and suggestions

openhands-ai · 2026-02-24T20:44:45Z

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

Address review feedback to reduce verbosity in the 'How It Works' section. Changed 7-step procedural breakdown to 4 concise bullet points focusing on: - Subprocess delegation - Server-managed execution - Auto-approval - Metrics collection This keeps content at the conceptual level users care about, rather than implementation details (method names, event types). Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-02-24T20:46:32Z

Summary

I've successfully applied the outstanding PR review suggestion for PR #351.

Change Made:

Review Feedback	Fix Applied
"This 7-step procedural breakdown is verbose for a usage guide... Condense to 3-4 key architectural points"	Condensed "How It Works" from 7 numbered steps to 4 concise bullet points

The Change:

Before: A 7-step numbered list with implementation details like conn.prompt(), MessageEvent, session initialization, etc.

After: 4 key architectural bullet points:

Subprocess delegation: ACPAgent spawns the ACP server and communicates via JSON-RPC over stdin/stdout
Server-managed execution: The ACP server handles its own LLM calls, tools, and context — your code just sends messages
Auto-approval: Permission requests from the server are automatically granted, so ensure you trust the ACP server you're running
Metrics collection: Token usage and costs from the server are captured into the agent's LLM.metrics

Checklist:

✅ Addressed the review feedback about verbose procedural breakdown
✅ Kept content at the conceptual level users care about (not implementation details)
✅ Preserved the security warning about auto-approval
✅ Changes are minimal and focused only on the review feedback
✅ Changes committed and pushed to feat/acp-agent branch

Commit:

Hash: 4f2ee5b
Message: "refactor: condense How It Works section to key architectural points"
Files changed: sdk/guides/agent-acp.mdx (-7 lines, +4 lines)

enyst

Thank you!

docs(sdk): add ACP Agent guide

c0a393c

Documents ACPAgent usage, configuration, metrics, and cleanup with a ready-to-run example referencing examples/01_standalone_sdk/40_acp_agent_example.py. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

simonrosenberg requested review from enyst and xingyaoww as code owners February 20, 2026 11:37

mintlify bot deployed to staging February 20, 2026 11:38 View deployment

all-hands-bot reviewed Feb 20, 2026

View reviewed changes

sdk/guides/agent-acp.mdx Show resolved Hide resolved

sdk/guides/agent-acp.mdx Outdated Show resolved Hide resolved

sdk/guides/agent-acp.mdx Show resolved Hide resolved

sdk/guides/agent-acp.mdx Outdated Show resolved Hide resolved

docs.json Show resolved Hide resolved

mintlify bot deployed to staging February 20, 2026 13:11 View deployment

Merge branch 'main' into feat/acp-agent

8b53e4b

mintlify bot deployed to staging February 23, 2026 17:51 View deployment

simonrosenberg requested a review from all-hands-bot February 23, 2026 17:52

all-hands-bot reviewed Feb 23, 2026

View reviewed changes

sdk/guides/agent-acp.mdx Outdated Show resolved Hide resolved

sdk/guides/agent-acp.mdx Show resolved Hide resolved

simonrosenberg requested a review from all-hands-bot February 24, 2026 20:34

Merge branch 'main' into feat/acp-agent

5b6d365

mintlify bot deployed to staging February 24, 2026 20:36 View deployment

all-hands-bot reviewed Feb 24, 2026

View reviewed changes

sdk/guides/agent-acp.mdx Outdated Show resolved Hide resolved

sdk/guides/agent-acp.mdx Outdated Show resolved Hide resolved

sdk/guides/agent-acp.mdx Show resolved Hide resolved

fix: address review feedback for ACP Agent guide

bb768a9

- Remove unused RunExampleCode import - Fix highlight range from {5-7} to {5,7-9} to skip blank line - Add bash code block with 'Running the Example' instructions Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging February 24, 2026 20:37 View deployment

simonrosenberg requested a review from all-hands-bot February 24, 2026 20:39

all-hands-bot reviewed Feb 24, 2026

View reviewed changes

mintlify bot deployed to staging February 24, 2026 20:48 View deployment

enyst approved these changes Feb 24, 2026

View reviewed changes

simonrosenberg merged commit 4b1f779 into main Feb 24, 2026
5 checks passed

simonrosenberg deleted the feat/acp-agent branch February 24, 2026 20:52

Conversation

simonrosenberg commented Feb 20, 2026

Summary

Context

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

simonrosenberg commented Feb 20, 2026

Uh oh!

openhands-ai bot commented Feb 20, 2026

Uh oh!

openhands-ai bot commented Feb 20, 2026

Summary

Checklist of Review Suggestions Applied:

Commit Details:

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

simonrosenberg commented Feb 24, 2026

Uh oh!

openhands-ai bot commented Feb 24, 2026

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

openhands-ai bot commented Feb 24, 2026

Summary

Changes Made:

Checklist:

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

all-hands-bot Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

enyst Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

simonrosenberg commented Feb 24, 2026

Uh oh!

openhands-ai bot commented Feb 24, 2026

Uh oh!

openhands-ai bot commented Feb 24, 2026

Summary

Change Made:

The Change:

Checklist:

Commit:

Uh oh!

enyst left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants