Skip to content

Commit 846403a

Browse files
committed
docs(rfd): Update elicitation.mdx to reflect separate method pattern
Updated RFD to document the refactored architecture where elicitation uses a separate session/elicitation request/response method (matching permissions pattern) instead of being embedded in session/prompt flow. KEY CHANGES: - Clarified that elicitation is triggered by stopReason: "elicitation_requested" - Updated flow to show separate session/elicitation method call - Aligned with permission request/response pattern for consistency - Added complete JSON-RPC examples with method names and full message structure This addresses @benbrandt's feedback about consistency between permission and elicitation request/response mechanisms.
1 parent 7d2ccf1 commit 846403a

1 file changed

Lines changed: 28 additions & 22 deletions

File tree

docs/rfds/elicitation.mdx

Lines changed: 28 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ The mechanism would:
4141
- **Selections**: select (single), multiselect (multiple) with enum-based options
4242
- **Sensitive inputs**: password, URL-mode for out-of-band OAuth flows (addressing PR #330 authentication pain points)
4343

44-
3. **Work in turn context**: Elicitation requests appear as part of turn responses, allowing agents to ask questions naturally within the conversation flow. Unlike Session Config Options (which are persistent), elicitation requests are transient and turn-specific.
44+
3. **Work in turn context**: Elicitation requests are triggered when a turn ends with `stopReason: "elicitation_requested"`, allowing agents to ask questions naturally within the conversation flow. Agents send elicitation requests via a separate `session/elicitation` method (following the same request/response pattern as `session/request_permission`). Unlike Session Config Options (which are persistent), elicitation requests are transient and turn-specific.
4545

4646
4. **Support client capability negotiation**: Clients declare what elicitation types they support (similar to the client capabilities pattern emerging in the protocol). Agents handle gracefully when clients don't support elicitation.
4747

@@ -79,7 +79,7 @@ Key differences from MCP:
7979

8080
### Elicitation Request Structure
8181

82-
An elicitation request would be included in a turn response. Example 1 (User Selection - from PR #340):
82+
When a turn ends with `stopReason: "elicitation_requested"`, the agent sends a separate elicitation request (following the same pattern as permission requests). Example 1 (User Selection - from PR #340):
8383

8484
```json
8585
{
@@ -188,9 +188,9 @@ Aligning with MCP and building on [Session Config Options discussions](https://g
188188

189189
This constraint list can expand in future versions based on community feedback.
190190

191-
### Complete Turn Response with Elicitation
191+
### Turn Response with Elicitation Stop Reason
192192

193-
An agent can include both content and an elicitation request in the same turn response:
193+
When an agent reaches a decision point and needs structured user input, it ends the turn with `stopReason: "elicitation_requested"`:
194194

195195
```json
196196
{
@@ -203,6 +203,22 @@ An agent can include both content and an elicitation request in the same turn re
203203
"text": "I can refactor this code in several ways. Each approach has different tradeoffs. Which strategy would you prefer?"
204204
}
205205
],
206+
"stopReason": "elicitation_requested"
207+
}
208+
}
209+
```
210+
211+
### Elicitation Request
212+
213+
After the turn completes with `stopReason: "elicitation_requested"`, the agent immediately sends a separate `session/elicitation` request (following the same pattern as `session/request_permission`):
214+
215+
```json
216+
{
217+
"jsonrpc": "2.0",
218+
"id": 43,
219+
"method": "session/elicitation",
220+
"params": {
221+
"sessionId": "...",
206222
"elicitation": {
207223
"id": "refactor-strategy-001",
208224
"type": "select",
@@ -230,34 +246,22 @@ An agent can include both content and an elicitation request in the same turn re
230246
"description": "Maximum optimization, requires review"
231247
}
232248
]
233-
},
234-
"stopReason": "elicitation_requested"
249+
}
235250
}
236251
}
237252
```
238253

239-
The agent displays content to the user, then presents the elicitation UI. The `stopReason` indicates why the turn has stopped (awaiting user input).
254+
The client presents the elicitation UI to the user based on the input type and constraints.
240255

241256
### User Response
242257

243-
When a user responds to an elicitation request, the response is included in the next turn request:
258+
When the user responds to an elicitation request, the client sends a separate `session/elicitation` response:
244259

245260
```json
246261
{
247-
"method": "session/turn",
248-
"params": {
249-
"sessionId": "...",
250-
"messages": [
251-
{
252-
"role": "user",
253-
"content": [
254-
{
255-
"type": "text",
256-
"text": "I'll go with balanced"
257-
}
258-
]
259-
}
260-
],
262+
"jsonrpc": "2.0",
263+
"id": 43,
264+
"result": {
261265
"elicitationResponse": {
262266
"id": "refactor-strategy-001",
263267
"value": "balanced"
@@ -266,6 +270,8 @@ When a user responds to an elicitation request, the response is included in the
266270
}
267271
```
268272

273+
The agent then continues processing with the user's input in the next turn or takes immediate action based on the response.
274+
269275
### Client Capabilities
270276

271277
Clients declare whether they support elicitation during the `initialize` phase via `ClientCapabilities`, following the same pattern as `fs` and `terminal` capabilities:

0 commit comments

Comments
 (0)