Experimental TypeScript API for the draft ACP v2 protocol.
Remarks
ACP v2 is still a draft. Its wire protocol and this API may change
incompatibly in any SDK release. The stable package entry point remains ACP
v1. The stable-feature set of the v2 draft is available through
@agentclientprotocol/sdk/experimental/v2; additional unstable protocol
features require @agentclientprotocol/sdk/experimental/v2/unstable.
Both entrypoints remain experimental.
Session state updates are aggregate snapshots, not per-prompt completions.
Apply repeated snapshots idempotently; a repeated idle stop reason is not a
new completion, cancellation, or usage report. Every successful
session/resume sends a current-state snapshot after replay and before its
response, including when replay was not requested. The response does not
imply idle. Agents may send live traffic after initialization even when no
client request is pending.
Top-level _meta on upsert updates patches stored metadata by key: omission
leaves it unchanged, null clears it, null-valued keys are removed, and other
values replace their key whole without nested merging. An empty object does
nothing. Replay uses the same rule. Metadata on chunks, content items,
snapshots, and plan_update is not an entity patch.
Experimental operations follow their advertised capabilities; local schema
selection does not establish peer support. When opting into unstable
lifecycle systemPrompt instructions, only send them when the agent
advertises session.systemPrompt, and only use override when its
mode.override capability is advertised.
Experimental TypeScript API for the draft ACP v2 protocol.
Remarks
ACP v2 is still a draft. Its wire protocol and this API may change incompatibly in any SDK release. The stable package entry point remains ACP v1. The stable-feature set of the v2 draft is available through
@agentclientprotocol/sdk/experimental/v2; additional unstable protocol features require@agentclientprotocol/sdk/experimental/v2/unstable. Both entrypoints remain experimental.Session state updates are aggregate snapshots, not per-prompt completions. Apply repeated snapshots idempotently; a repeated idle stop reason is not a new completion, cancellation, or usage report. Every successful
session/resumesends a current-state snapshot after replay and before its response, including when replay was not requested. The response does not imply idle. Agents may send live traffic after initialization even when no client request is pending.Top-level
_metaon upsert updates patches stored metadata by key: omission leaves it unchanged,nullclears it, null-valued keys are removed, and other values replace their key whole without nested merging. An empty object does nothing. Replay uses the same rule. Metadata on chunks, content items, snapshots, andplan_updateis not an entity patch.Experimental operations follow their advertised capabilities; local schema selection does not establish peer support. When opting into unstable lifecycle
systemPromptinstructions, only send them when the agent advertisessession.systemPrompt, and only useoverridewhen itsmode.overridecapability is advertised.