Skip to content

docs(sdk): explain ACP session resume failure recovery #803

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
LiZhengliang wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(sdk): explain ACP session resume failure recovery #803

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions sdk/guides/agent-acp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,38 @@ When the ACP server advertises authentication methods, `ACPAgent` automatically

If no supported credential source is found, the server may proceed without authentication (some servers don't require it).

## Session Recovery

`ACPAgent` persists the provider's session ID in the conversation state and uses
`session/load` to resume it after a process restart. The provider's own session
files must also remain available. Saving the OpenHands event history alone does
not preserve the provider's native context.

If `session/load` fails, the conversation enters an error state and retains its
previous session ID. It does not automatically call `session/new` or send the
pending message to an empty session. The error includes the provider's failure
details and asks you to retry or explicitly start a new conversation.

To recover:

1. Resolve the reported provider error. For example, restore missing credentials
or session files, or shut down a confirmed stale process that owns the session.
2. Retry the same conversation using the same working directory and provider data
directory. The SDK attempts to load the original session again.
3. If the original session cannot be recovered, explicitly create a new
conversation and provide the context it needs.

`acp_resume_session_id` can supply an explicit provider session ID when it was
stored separately from OpenHands conversation state. A failed load of this ID
also raises an error instead of falling back to a fresh session. Treat this ID as
a secret.

<Note>
This recovery behavior applies to `session/load` failures. Moving a persisted
conversation to a different working directory still follows the existing
working-directory mismatch behavior, which can start a fresh session.
</Note>

## Metrics

Token usage and cost data are automatically captured from the ACP server's responses. You can inspect them through the standard `LLM.metrics` interface:
Expand Down