Skip to main content
Author(s): @benbrandt

​
Elevator pitch

What are you proposing to change?
Add a fire-and-forget notice session update to ACP v1 and v2 for advisory information that should be visible to the user without becoming conversation history or a durable protocol entity. In v1, a Client capability lets Agents choose between notices and an existing presentation channel such as agent messages.

​
Status quo

How do things work today and what problems does this cause? Why would we change things?
Agents encounter user-relevant conditions that are not messages, tool calls, etc. Examples include an optional integration being unavailable, configuration falling back to defaults, or a model request being rerouted while work continues. ACP currently gives Agents no standard presentation event for these cases. They must either omit the information, use an implementation-specific update, or emit an agent message. These events also do not need Agent-managed identity or lifecycle. Whether a warning remains visible, disappears after a delay, or can be dismissed is a Client and user-interface decision.

​
What we propose to do about it

What are you proposing to improve the situation?
Add a notice variant to SessionUpdate in ACP v1 and v2:
The fields are deliberately small:
  • severity is required and non-null. Its initial values are info, warning, and error.
  • title is a required, non-null, non-empty plain-text string that can stand alone in a compact presentation.
  • description is an optional, nullable plain-text string with additional detail or guidance. Omission and null both mean that the Agent supplied no description.
  • _meta is optional and nullable. Omission and null are equivalent and mean that the Agent supplied no event metadata.
NoticeSeverity is open in both protocol versions from its introduction and follows the v2 enum-extension rules. Values beginning with _ are reserved for implementation-specific extensions, while other unknown values are reserved for future ACP severities. Clients preserve an unknown string and use a generic notice presentation without inferring salience, lifetime, or control behavior from it. Adding a severity does not require protocol negotiation. A notice has no ID, response, acknowledgement, update, or removal, and SHOULD NOT be included in session replay. Repeated notices are independent events, even when their fields are identical.

​
Client presentation

A Client that chooses to present notices makes them accessible to the user and controls their presentation. It may use a toast, banner, inline status region, notification center, or another surface. It may coalesce repeated notices and apply user preferences. Severity is a hint. For example, a Client may show info for a short period, leave warning visible until local dismissal, and present error more prominently. ACP does not prescribe those choices or a timeout. User dismissal is entirely local. The Client does not report dismissal to the Agent, and the Agent does not send a removal event. If the Agent needs to know whether the user saw, accepted, or acted on something, a notice is the wrong primitive. error severity still describes an advisory presentation event. It does not fail a JSON-RPC request, stop foreground work, change session state, or imply a prompt stop reason.

​
Delivery and history

A notice is scoped to the session identified by the surrounding session/update notification. Notices are live events, not session history. After reconnecting, an Agent may emit a new notice if the condition is still currently relevant. That is a new live event rather than replay of the earlier notice, and the Client remains free to coalesce it. Agents must not rely on notice delivery for protocol correctness, required user action, authorization, task completion, or fatal-error reporting. Those cases belong in the relevant request, permission, elicitation, message, tool, or lifecycle primitive. The Agent must behave as though the notice may not have been received, understood, displayed, or seen by the user.

​
Version-specific capability

For v1, add an optional notices object to ClientSessionCapabilities:
The object appears at clientCapabilities.session.notices in the v1 initialize request. Omitting session, setting session to null, omitting notices, or setting notices to null all mean the Client does not advertise support. Supplying {} for notices means the Client can present notices to the user with the semantics in this RFD. Agents MUST NOT send notice updates to a v1 Client unless it advertises this capability. The capability lets the Agent choose where to send advisory information. When the Client does not advertise notice support, the Agent may use an ordinary agent message instead if the information should still be surfaced to the user. That fallback is conversation content and follows normal message-history semantics. Advertising notice support does not acknowledge delivery or guarantee that the user has seen an individual notice; Clients still control presentation and user preferences. V2 does not add or require a capability. It preserves unknown notices through its unknown session-update fallback, after which the Client may ignore or generically present them. V1 keeps its closed SessionUpdate union and uses the capability rather than requiring unsupported Clients to accept a new variant.

​
Shiny future

How will things will play out once this feature exists?
Agents can surface operational information without pretending it is part of the conversation. Clients can integrate notices into their own visual language and accessibility model.

​
Implementation details and plan

Tell me more about your implementation. What is your detailed implementation plan?
  1. Add Notice and NoticeSeverity types in both versions behind the unstable_session_notices Rust feature.
  2. Add the notice variant to both SessionUpdate unions and an optional notices: NoticeCapabilities object to v1 ClientSessionCapabilities behind the same feature. Do not add a v2 capability.
  3. Document the presentation, dismissal, severity, replay semantics, and non-conversational semantics in both protocol versions, plus v1 capability gating and the agent-message fallback.
  4. Add schema tests for capability advertisement, serialization, nullable-field semantics, open severity, version-specific unsupported-update behavior, malformed known-update handling, and cross-version notice wire parity. The schema crate intentionally provides no built-in v1/v2 conversion layer.
Capability gating and the recommendation against replay are part of the protocol contract rather than something the schema crate can enforce. Runtime SDKs and example Agents and Clients can adopt notices separately after consuming the schema surface.

​
Frequently asked questions

What questions have arisen over the course of authoring this document or during subsequent discussions?

​
Why is the capability required in v1?

Without it, an Agent cannot tell whether a v1 Client can present notices or will simply drop them. As with compaction, the capability lets the Agent use the dedicated presentation event when supported and fall back to an agent message when the information should still reach users of older Clients. It advertises a presentation channel, not acknowledgement of any individual notice.

​
Why is there no notice ID?

The Agent never updates, resolves, or removes a notice. Identity would invite Clients to infer a lifecycle that the protocol does not define. Clients may use local identities for rendering, dismissal, or diagnostic retention.

​
Why does the notice not say whether it is dismissible or how long it lasts?

Those are presentation choices that vary by Client surface, accessibility needs, severity policy, and user preferences. The Agent supplies severity; the Client decides whether and when the event disappears.

​
Should the Client report dismissal to the Agent?

No. Dismissal only changes local presentation. If Agent behavior depends on a user decision, the Agent needs an explicit response-bearing primitive such as elicitation or permission, not a notice.

​
Why is this a session/update variant instead of a new session/notice method?

session/update is already ACP’s Agent-to-Client carrier for session-scoped activity. The known notice variant can define its live-only lifetime without adding another notification method. The v1 capability lets Agents choose a fallback for Clients that do not implement the variant, while the replay guidance makes clear that supporting Clients should not treat notices as durable history.

​
What alternative approaches did you consider, and why did you settle on this one?

Agent messages - Universally visible, but they pollute conversation history and can be easily missed in the rest of the text. They remain a fallback for v1 Clients that do not advertise notice support. Structured actions and acknowledgements - Useful when user interaction is required, but those cases should use response-bearing primitives rather than turning notices into a second elicitation system.

​
Revision history

  • 2026-09-17: Added a v1 Client capability so Agents can choose between notices and an agent-message fallback. V2 remains capability-free.
  • 2026-08-20: Updated the implementation plan for the schema-only architecture, which keeps v1 and v2 types separate, documents replay guidance normatively, and leaves runtime and example adoption to downstream SDKs.
  • 2026-07-22: Initial draft.