Turn session feedback into explicit branches

Learning objective

Capture in-session feedback and adapt the conversation flow.

Core idea

Feedback changes a conversation only when the workflow consumes it and makes a different decision. A rating stored for later analysis is useful, but it does not clarify a misunderstood request or redirect the active task. For in-session adaptation, define the question, the accepted response, and the branch that response selects.

NeMo Agent Toolkit provides typed human prompts and responses through UserInteractionManager. Use these to ask for a correction, preference, or choice at the point where it changes the next step. The /feedback endpoint captures a rating through observability_trace_id and reaction_type, for example "👍", when using the Weave FastAPI plugin worker. That trace-linked capture path is separate from branching the running workflow; see 3.3.1 for structured ratings and corrections, and 10.1.1 for pause, approve, edit, reject, and resume controls. Here the unit of change is the conversation that is already running.

How it works

Ask at a decision point

Acquire Context.get().user_interaction_manager inside the workflow and call its prompt_user_input method with an interactive prompt model. NVIDIA’s example uses HumanPromptText with text, required, and placeholder. Await prompt_user_input to receive a response matching the prompt’s data model. Over HTTP, interaction_required identifies the workflow as paused while waiting for that response.

For a text prompt, inspect response.content as HumanResponseText and consume its text. That text is the correction or clarification the workflow needs. Do not store the response and then continue with the original, contradicted assumption. The branch must rebuild the affected input or select a different next step before another expensive tool call or model request.

The interactive-workflows guide supports all interaction data models through nat serve; nat run supports only HumanPromptText. Its instructions for the bundled UI require WebSocket mode for these interactions. A custom HTTP client has a separate documented integration through HTTP Interactive Execution. Test the actual front end and prompt type together; success with text in the CLI does not establish that a radio control works there.

Match response structure to the decision

HTTP interaction responses discriminate their payload with response.input_type. The following choices separate feedback that changes content from feedback that selects a predefined path:

An option response carries an object such as id, label, and value. Use its offered value to select the branch. The label is presentation text, so do not make a translation or a copy edit change the workflow decision. Validate free-text feedback against the pending question before incorporating it into the next request.

Correlate the feedback with the pending prompt

With WebSocket, the server sends a system_interaction_message and the client responds with a user_interaction_message. Preserve the prompt association through the schema’s message and conversation identifiers. See 2.5.1 for event routing. Feedback for one response must not silently modify a different turn because it happened to arrive later.

With HTTP SSE, interaction_required includes execution_id, interaction_id, prompt, and response_url. Submit the typed response to POST /executions/{execution_id}/interactions/{interaction_id}/response, using the identifiers returned by that execution. A successful response returns 204 No Content; the execution returns to running, and the open stream resumes output.

A 400 means the interaction has already been resolved. A 404 means the execution or interaction was not found. Refresh execution status before offering the user another submission. Blindly retrying a response to an expired or replaced prompt does not capture valid feedback. The workflow and frontend owners share responsibility for removing stale controls and retaining the user’s correction long enough to explain a failed submission.

A submitted response either resumes the open stream or, for an interaction already resolved or not found, leads the client to refresh execution status.

Bound waiting and revision

Set the timeout in workflow code through HumanPromptBase.timeout, an int | None field defaulting to None. For example, HumanPromptText(text="Which audience?", timeout=60) sets a 60-second prompt budget. The WebSocket schema represents this as content.timeout in seconds, with null meaning no timeout; it documents countdown display, dismissal on expiration, and server-enforced TimeoutError raised to the workflow.

Distinguish the transport outcomes. For the WebSocket path, handle TimeoutError in workflow code through a defined no-response branch. The HTTP lifecycle instead documents a timed-out interaction transitioning to failed. An HTTP client can display a previously retained draft after that failure, but should not describe it as a successful workflow result. An absent response is not a user’s selection.

Bound revision in workflow state as well. For example, an application-owned revision counter can select either another prompt or a final draft branch. This counter is a design choice, not a toolkit configuration default. Each accepted correction can cause another retrieval or generation, so asking indefinitely consumes tokens and extends completion time even when the prompts themselves are inexpensive.

Key distinctions and trade-offs

Feedback collection, adaptation, and authorization have different meanings. Collection records a response; adaptation changes the next workflow step. A request for a shorter summary changes presentation, while a response permitting an external action belongs to the action’s authorization policy; see 9.4. Do not let a generic positive rating select a write operation.

HTTP interaction extensions are enabled for versioned workflow and chat routes. /v1/chat/completions requires general.front_end.enable_interactive_extensions: true to opt in. NVIDIA marks versioned endpoint paths experimental in the API reference. A client expecting only ordinary completion chunks must therefore explicitly support typed interaction events before using this path.

Architecture / decision scenario

A media company’s campaign assistant generates a draft and asks an editor which areas need revision. The production budget allows 12 seconds for an initial draft and at most two revision passes. A pilot records that a generic thumbs-down is ambiguous in 35 of 100 sessions, while a structured scope selection is ambiguous in 8 of 100. These are scenario measurements, not product benchmarks.

The workflow owner chooses a checkbox interaction for tone, audience, and length, followed by a text prompt only when a correction needs explanation. The tempting alternative is to store thumbs-down feedback and regenerate the entire campaign automatically. It wastes a complete generation and often changes content the editor wanted to keep. The selected options instead determine which draft inputs are revised.

The custom HTTP client consumes interaction_required, posts the typed response to its returned response_url, and waits for resumed output. Each prompt sets timeout=60 in its workflow model. If the HTTP interaction times out and the execution becomes failed, the client presents its retained last draft and marks the requested revision incomplete. After two successful revision passes, the application-owned counter selects the final draft branch. The product owner owns the revision budget; the workflow owner implements revision branches, and the frontend owner implements the failed-execution display. Publication remains a separate action rather than an implied consequence of positive feedback.

Common exam traps

• Calling a stored rating an adaptation of the active conversation.
• Continuing with the original assumption after accepting a correction.
• Sending feedback without associating it with the pending interaction.
• Treating notification acknowledgment as detailed preference feedback.
• Assuming all prompt types work through nat run.
• Treating timeout, positive feedback, or a generic rating as permission to perform an external action.

What to remember

Capture feedback at the point where it changes a decision. Use typed responses and execution or message identity, then select an explicit branch. Bound both prompt waiting and revision passes, and distinguish conversational preferences from permission to act.

Knowledge check

References

• NVIDIA, Interactive Workflows Guide
• NVIDIA, HTTP Interactive Execution
• NVIDIA, WebSocket Message Schema
• NVIDIA, NVIDIA NeMo Agent Toolkit API Server Endpoints
• NVIDIA, nat.data_models.interactive