Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

multiple.md

238 lines7.3 KB

1---
2title: Multiple Interrupts
3id: interrupts-multiple
4order: 3
5description: "Render a queue of pending decisions and resolve them item by item or all at once as one atomic batch."
6keywords:
7 - tanstack ai
8 - ag-ui interrupts
9 - resolveInterrupts
10 - batch approval
11 - cancelInterrupts
12---
13​
14# Multiple Interrupts
15​
16One run can pause on several decisions at once. The model lines up three
17transfers, or an approval and a question land together. You want to show the
18whole queue and send the answers back together, not one round trip each.
19​
20## Two ways to resolve
21​
22You have already seen the first one on the [Tool Approval](./tool-approval) page:
23call a method on the item itself.
24​
25```ts ignore
26// Per item: resolve each one where you render it.
27interrupt.resolveInterrupt(true)
28```
29​
30When several are pending, it is often easier to answer them all from one place.
31The `useChat` hook gives you root helpers that act on the whole queue:
32​
33```ts ignore
34// All at once: one callback decides every pending item.
35resolveInterrupts((interrupt) => {
36 if (interrupt.kind === 'tool-approval') {
37 interrupt.resolveInterrupt(true)
38 return
39 }
40 interrupt.cancel()
41})
42```
43​
44Both stage local drafts. Nothing goes to the server until every pending item has
45an answer, then the whole set submits at once. The server accepts all of them or
46none, so you never end up with half a batch applied.
47​
48## Render the queue
49​
50Map over `interrupts` and switch on `kind`. Each item carries its own
51`canResolve` and `errors`:
52​
53```tsx
54// app/decision-queue.tsx
55import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
56import { transferTool } from '../tools/transfer'
57​
58export function DecisionQueue() {
59 const { interrupts, resolveInterrupts, cancelInterrupts, resuming } = useChat({
60 threadId: 'account-42',
61 connection: fetchServerSentEvents('/api/chat'),
62 tools: [transferTool] as const,
63 })
64​
65 if (interrupts.length === 0) return null
66​
67 return (
68 <section>
69 <p>{interrupts.length} decision(s) needed</p>
70​
71 {interrupts.map((interrupt) => {
72 if (
73 interrupt.kind === 'tool-approval' &&
74 interrupt.toolName === 'transfer'
75 ) {
76 return (
77 <article key={interrupt.id}>
78 <p>
79 {interrupt.originalArgs.amount} to{' '}
80 {interrupt.originalArgs.recipient}
81 </p>
82 <button
83 disabled={!interrupt.canResolve || resuming}
84 onClick={() => interrupt.resolveInterrupt(true)}
85 >
86 Approve
87 </button>
88 <button
89 disabled={!interrupt.canResolve || resuming}
90 onClick={() => interrupt.resolveInterrupt(false)}
91 >
92 Reject
93 </button>
94 </article>
95 )
96 }
97 return <article key={interrupt.id}>Unsupported: {interrupt.kind}</article>
98 })}
99​
100 <button onClick={() => resolveInterrupts(true)} disabled={resuming}>
101 Approve all
102 </button>
103 <button onClick={() => cancelInterrupts()} disabled={resuming}>
104 Cancel all
105 </button>
106 </section>
107 )
109```
110​
111## Resolve every item from one callback
112​
113`resolveInterrupts(callback)` runs your callback once per item inside a single
114synchronous transaction. It must resolve or cancel every item. If it throws or
115leaves one item unanswered, nothing submits:
116​
117```ts ignore
118resolveInterrupts((interrupt) => {
119 if (interrupt.kind === 'tool-approval') {
120 interrupt.resolveInterrupt(true, { payload: { note: 'Batch review' } })
121 return
122 }
123 interrupt.cancel()
124})
125```
126​
127Two shortcuts cover the common cases:
128​
129- `resolveInterrupts(true)` / `resolveInterrupts(false)` approves or rejects the
130 whole queue. It works only when every item is a tool approval that needs no
131 payload or edits. Generic items, mixed queues, or required payloads are
132 rejected.
133- `cancelInterrupts()` cancels every item with no payload.
134​
135## When an answer is wrong
136​
137A bad answer does not tear down the queue. The item keeps your last valid draft,
138shows what went wrong, and lets you fix it and resubmit. Errors come in two
139places, and you render both.
140​
141Each item carries its own `errors`: a bad payload, invalid edited args, or an
142expired item. The root `interruptErrors` carries failures for the whole batch:
143transport problems, server rejections, and errors for the internal client-tool
144steps that never show up as their own item.
145​
146This component renders both, gates its buttons correctly, and offers the two
147recovery paths:
148​
149```tsx
150// app/robust-queue.tsx
151import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
152import { toolDefinition } from '@tanstack/ai'
153import { z } from 'zod'
154​
155const transferTool = toolDefinition({
156 name: 'transfer',
157 description: 'Move money between accounts',
158 needsApproval: true,
159 inputSchema: z.object({
160 recipient: z.string(),
161 amount: z.number(),
162 }),
163 outputSchema: z.object({ receiptId: z.string() }),
164}).client()
165​
166export function RobustQueue() {
167 const { interrupts, interruptErrors, retryInterrupts, resuming } = useChat({
168 threadId: 'account-42',
169 connection: fetchServerSentEvents('/api/chat'),
170 tools: [transferTool] as const,
171 })
172​
173 // Retry only helps a transport failure. Expired or stale batches can't be
174 // retried, so don't offer it for those.
175 const canRetry = interruptErrors.some((error) => error.code === 'transport')
176​
177 return (
178 <section>
179 {interrupts.map((interrupt) => {
180 if (
181 interrupt.kind !== 'tool-approval' ||
182 interrupt.toolName !== 'transfer'
183 ) {
184 return null
185 }
186​
187 // canResolve reflects the schema and binding, not the live phase, so
188 // also gate on the item's status and the run being busy.
189 const busy = interrupt.status === 'submitting' || resuming
190​
191 return (
192 <article key={interrupt.id}>
193 <p>
194 {interrupt.originalArgs.amount} to{' '}
195 {interrupt.originalArgs.recipient}
196 </p>
197 <button
198 disabled={!interrupt.canResolve || busy}
199 onClick={() => interrupt.resolveInterrupt(true)}
200 >
201 Approve
202 </button>
203 <button disabled={busy} onClick={() => interrupt.clearResolution()}>
204 Start over
205 </button>
206​
207 {/* Item errors: bad payload, bad edited args, expired. */}
208 {interrupt.errors.map((error) => (
209 <p key={`${error.code}:${error.path?.join('.') ?? ''}`}>
210 {error.message}
211 </p>
212 ))}
213 </article>
214 )
215 })}
216​
217 {/* Batch errors: transport, server, and hidden client-tool steps. */}
218 {interruptErrors.map((error) => (
219 <p key={error.code}>{error.message}</p>
220 ))}
221 {canRetry ? (
222 <button onClick={() => retryInterrupts()} disabled={resuming}>
223 Retry
224 </button>
225 ) : null}
226 </section>
227 )
229```
230​
231The two recovery paths, side by side:
232​
233- `interrupt.clearResolution()` drops one item's draft so the user can answer it
234 again from scratch. Fixing a form and calling `resolveInterrupt` again works
235 too, the draft is replaced, not stacked.
236- `retryInterrupts()` re-sends the whole staged batch after a transport failure.
237 It does nothing for expired or stale batches, start a fresh run to get a new
238 set of interrupts for those.