docs(ai-transport): document interruption and steering#3471
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
83f68ff to
aac02af
Compare
| { | ||
| name: 'Token streaming', | ||
| link: '/docs/ai-transport/features/token-streaming', | ||
| name: 'Agent presence', |
There was a problem hiding this comment.
bringing in @m-hulbert comment from #3468 regarding alphabetical ordering here:
I agree that the feature list is rapidly expanding, and it would help to make that easier to navigate; however I'm not convinced that alphabetising the list is the right way to do this. In terms of releative 'importance' - is 'Agent presence' the first thing we believe should be read to understand the value proposition and how AI Transport works?
IMO, the core value proposition should be immediately stated and clear in the "About AI Transport". "How AI Transport works" is covered by "Concepts".
And "Features" then shows you what you can build with it. If you're just skimming through the docs to see the overall feature set, I don't think there's a material difference whether "Features" is sorted alphabetically or based on our assumptions of what we deem important - people will still be able to find what they want. But when you're returning to the documentation, having the list sorted makes it way easier to navigate.
There was a problem hiding this comment.
Ok, well @m-hulbert if you have a concrete proposal for an order then please share that here. In the mean time, this re-ordering makes the features findable when you want to return to a page you already know exists.
(I'm highly allergic to comments along the lines of "not this thing", without "this instead")
Replace the Interruption feature page with a combined Interruption and steering page, and add a "Steer a Run" section to the Runs concept. Repoint the nav entry and all cross-links from the old page, with a redirect_from to preserve the old URL. The page documents three ways a client changes direction mid-response: steer the active Run with a follow-up prompt, cancel and re-prompt, or send alongside as a concurrent Run.
The server-side abort-signal example fed run.messages straight to the model. run.messages is only the current Run's own turn (its triggering input plus its output), not the multi-turn conversation, so a model called with it loses all prior context. Drain run.view with loadOlder() before run.start() and feed run.view.getMessages() through convertToModelMessages, matching the agent hydration pattern used across the getting-started and interruption-and-steering pages.
Order the Features section entries by name so the nav is predictable and new pages have an obvious insertion point.
Bring the interruption and steering feature page in line with the steering API and the Vercel codec used elsewhere on the page, and capture the vocabulary rule that drove the copy edits in the write-docs skill so future drafts inherit it. - Rewrite the agent loop to use streamText + toUIMessageStream() and run.abortSignal, matching the Vercel examples used across the page - Add a "Cancel the in-flight model call" section documenting onSteer, the stepAbort/AbortSignal.any pattern, and how to tell a steer interruption apart from a genuine cancel before ending the Run - Add FAQ entries for cross-device cancel, steer persistence, batched steers, and an unreachable agent endpoint - Replace off-vocabulary terms (noun "pass", "inference pass", "projection", "RunNode") with documented product vocabulary - Rename the section to cancel-and-reprompt and fix the stale /interruption roadmap link to /interruption-and-steering - Add a "Stay inside the product vocabulary" rule, grep, and reviewer checklist item to the write-docs skill
aac02af to
4b72de9
Compare
Resolve the remaining review comments on the interruption and steering page. The steer outcome docs contradicted themselves on suspend, and two smaller items were still open. - Clarify when steer outcome resolves: a consumed steering message resolves even if the Run later suspends (runTerminalReason absent), while a not-yet-consumed message stays pending until the Run resumes and consumes it or ends. Aligns the property list with the suspended-Run edge case, which previously said outcome stays pending until the Run ends - Drop the "How does steering differ from concurrent turns?" FAQ, which only compared two of the three patterns the How it works table already covers - Rename the section heading to "Implement cancel and re-prompt" and its anchor so it matches the table row wording
VeskeR
left a comment
VeskeR
left a comment
There was a problem hiding this comment.
LGTM, one note about the skill change
| **Writing standards** | ||
|
|
||
| 9. Page complies with the rules in [`writing-style-guide.md`](../../../writing-style-guide.md). Use the verification greps above to spot the common violations (em dashes, bold-prefix bullets, Latin abbreviations, subjective phrases, vague modals, "we" as the subject, AI-fingerprint patterns). | ||
| 10. Author ran `/deslop` (or equivalent AI-pattern check). |
There was a problem hiding this comment.
I think we should keep this as item 11
3 participants
Documents the AI Transport interruption and steering feature, and verifies the affected agent-side docs against the SDK source (the
ait-1017-steering-stepsbranch, the release target).features/interruption.mdxwithfeatures/interruption-and-steering.mdx, covering the three change-direction patterns: steer the active Run with a follow-up prompt, cancel and re-prompt, or send alongside as a concurrent Run.concepts/runs.mdxdocumenting the client-sidesteer()API ({ published, outcome },consumed/runTerminalReason).cancellation.mdx,concurrent-turns.mdx,double-texting.mdx, andwhy/index.mdx.createRunis synchronous (noawait), drainrun.viewwithloadOlder()beforerun.start(), feedrun.view.getMessages()to the model (notrun.messages, which is turn-only), and tear down withsession.end(). Corrects a strayActiveRunreference toClientRun.run.messages(this Run's own turn) straight to the model, losing all prior conversation context. It now drainsrun.viewand feeds the full conversation.