diff --git a/docs/rfds/session-set-title.mdx b/docs/rfds/session-set-title.mdx new file mode 100644 index 000000000..53a73026b --- /dev/null +++ b/docs/rfds/session-set-title.mdx @@ -0,0 +1,115 @@ +--- +title: "Client-Set Session Titles" +--- + +Author(s): [@lifeizhou-ap](https://github.com/lifeizhou-ap) + +## Elevator pitch + +> What are you proposing to change? + +Add an optional `session/set_title` request that lets a Client set the title of an Agent-owned session. The Agent persists the title as authoritative session metadata and publishes changes through the existing `session_info_update` notification. + +An Agent may generate session titles. After `session/set_title` succeeds, the Agent must not replace the Client-supplied title with a title it generates. + +## Status quo + +> How do things work today and what problems does this cause? Why would we change things? + +ACP allows an Agent to report a session title, but provides no operation for a Client to set one. As a result, a user-selected title cannot be stored as Agent-owned session metadata through ACP. + +[Issue #1978](https://github.com/agentclientprotocol/agent-client-protocol/issues/1978) identifies the same missing operation while also proposing semantics for Agent-generated titles and an optional initial title. This RFD addresses only the Client-to-Agent operation. + +## What we propose to do about it + +> What are you proposing to improve the situation? + +Add a capability-gated `session/set_title` request that lets a Client set the title of an Agent-owned session. The Agent persists the title and publishes the change through `session_info_update`. + +## Shiny future + +> How will things will play out once this feature exists? + + + +## Implementation details and plan + +> Tell me more about your implementation. What is your detailed implementation plan? + +### Protocol + +An Agent advertises support through `sessionCapabilities.setTitle`: + +```json +{ + "agentCapabilities": { + "sessionCapabilities": { + "setTitle": {} + } + } +} +``` + +Clients must not call `session/set_title` unless this capability is present. + +The request is: + +```json +{ + "jsonrpc": "2.0", + "id": 42, + "method": "session/set_title", + "params": { + "sessionId": "sess_123", + "title": "Investigate OAuth timeout" + } +} +``` + +`sessionId` identifies the Agent-owned session and `title` is the new session title. + +The response is empty: + +```json +{ + "jsonrpc": "2.0", + "id": 42, + "result": {} +} +``` + +- Title validation rules are defined by the Agent. If a title fails validation, the Agent returns `InvalidParams` (`-32602`) with a message explaining why it was rejected. For example: + + ```json + { + "jsonrpc": "2.0", + "id": 42, + "error": { + "code": -32602, + "message": "Title must not exceed 100 characters." + } + } + ``` + +- The Agent returns success only after persisting the title exactly as supplied. If it cannot do so, it returns an error. +- After a successful `session/set_title` request, the Agent sends a `session/update` notification containing a `session_info_update` with the persisted title. Future `session/list` calls return the same title. +- A title set through `session/set_title` must not be overwritten by a title generated by the Agent. +- If the Agent is generating a title when `session/set_title` succeeds, it must discard the generated title. +- Each subsequent successful `session/set_title` request replaces the previous title. + +## Frequently asked questions + +> What questions have arisen over the course of authoring this document or during subsequent discussions? + + + +## Revision history + +- 2026-08-19: Initial proposal.