Skip to main content

How to Show an Approval Card for an AG-UI Interrupt in React

· 10 min read
Jagdish Kumawat
Founder @ Dewiride

An AG-UI agent that needs a person's approval doesn't wait in the middle of a run: the run ends with an interrupt, a question for the person, and the next run carries the answer. In React, that's a card with Approve and Reject, a list the AG-UI client keeps for you, and one parameter of runAgent.

Syntax​

Syntax
// After a run: the questions the agent is waiting for.
const <interrupts> = <agent>.pendingInterrupts;

// The answer: a new run, with one resume entry per open question.
await <agent>.runAgent({
resume: [
{ interruptId: <interrupt>.id, status: "resolved", payload: { approved: <true or false> } },
],
});
PartWhat it is
<agent>Your AG-UI agent in the browser: an HttpAgent for an agent on a server, or any other AbstractAgent
pendingInterruptsThe interrupts the agent's most recent run ended with. The client's own description: Populated when RUN_FINISHED arrives with outcome.type === "interrupt" and Cleared when a subsequent run completes successfully
<interrupt>.idThe interrupt's ID. The answer names it, so the agent knows what is being answered
<interrupt>.messageA question written for a person, to show on the card
status: "resolved"The person answered. cancelled means they moved on without answering
payloadThe answer itself. For an approval, { approved: true } or { approved: false }: AG-UI's documentation says Denials are expressed inside the payload

The Example​

A small agent offers to empty the trash. Its first run doesn't do it: it ends with an interrupt that asks Empty the trash? Its 3 files will be deleted for good. The page shows that question as a card. Approve empties the trash in the next run, and Reject keeps the files.

So that the example runs on its own, the agent runs in the browser. It is an AbstractAgent, the class every AG-UI agent in TypeScript extends, including HttpAgent. With an agent on a server, the page stays the same, and only the agent changes.

Prerequisites​

  • Node.js 20.9 or later, which Next.js 16 needs. node --version shows yours.

Step 1: Create a Next.js App​

Terminal
npx create-next-app@16.4.6 approval-card-demo --ts --biome --app --no-tailwind --no-src-dir --no-react-compiler --import-alias "@/*" --use-npm --no-agents-md --no-agent-feedback --disable-git
cd approval-card-demo

create-next-app creates a Next.js app with TypeScript, the App Router and its own sample page, without asking any questions: every answer is in the command.

Step 2: Install the AG-UI Client​

Terminal
npm install @ag-ui/client@1.0.5 rxjs@7.8.1 --save-exact

@ag-ui/client is AG-UI's TypeScript client: it runs agents, collects their messages and keeps their interrupts. rxjs is the library its agents use to send events. Version 7.8.1 is the one @ag-ui/client 1.0.5 itself depends on, so the app ends up with a single copy.

Step 3: Add an Agent That Asks First​

Create app/trash-agent.ts:

app/trash-agent.ts
import {
AbstractAgent,
type AGUIEvent,
EventType,
type RunAgentInput,
randomUUID,
} from "@ag-ui/client";
import { Observable } from "rxjs";

// A small AG-UI agent that runs in the browser. Before it empties the
// trash, it stops and asks: its first run ends with an interrupt.
export class TrashAgent extends AbstractAgent {
run(input: RunAgentInput) {
const { threadId, runId } = input;
const answer = input.resume?.[0];

return new Observable<AGUIEvent>((subscriber) => {
subscriber.next({ type: EventType.RUN_STARTED, threadId, runId });

if (!answer) {
// No answer yet: end the run with a question for the person.
subscriber.next({
type: EventType.RUN_FINISHED,
threadId,
runId,
outcome: {
type: "interrupt",
interrupts: [
{
id: "empty-trash",
reason: "confirmation",
message: "Empty the trash? Its 3 files will be deleted for good.",
responseSchema: {
type: "object",
properties: { approved: { type: "boolean" } },
required: ["approved"],
},
},
],
},
});
} else {
// The next run carries the answer: act on it, and say what happened.
const approved =
answer.status === "resolved" && answer.payload?.approved === true;
const messageId = randomUUID();
subscriber.next({
type: EventType.TEXT_MESSAGE_START,
messageId,
role: "assistant",
});
subscriber.next({
type: EventType.TEXT_MESSAGE_CONTENT,
messageId,
delta: approved ? "Done. The trash is empty." : "OK. I kept the 3 files.",
});
subscriber.next({ type: EventType.TEXT_MESSAGE_END, messageId });
subscriber.next({ type: EventType.RUN_FINISHED, threadId, runId });
}

subscriber.complete();
});
}
}
  • run is what every AG-UI agent implements: it gets the run's input and returns the run's events, one by one.
  • The first run has no resume, so it ends with RUN_FINISHED and an outcome of type interrupt. reason: "confirmation" is AG-UI's reason for a yes-or-no question that isn't tied to a tool. responseSchema describes the answer it expects: approved, a boolean.
  • The next run carries the answer in input.resume. The agent reads approved and says what it did.

Step 4: Show the Card​

Replace everything in app/page.tsx:

app/page.tsx
"use client";

import type { Interrupt, Message, ResumeEntry } from "@ag-ui/client";
import { useRef, useState } from "react";
import { TrashAgent } from "./trash-agent";

export default function Home() {
const agentRef = useRef<TrashAgent | null>(null);
const [messages, setMessages] = useState<Message[]>([]);
const [interrupts, setInterrupts] = useState<Interrupt[]>([]);
const [isRunning, setIsRunning] = useState(false);

// One run of the agent: a new request, or the answers to its questions.
async function run(resume?: ResumeEntry[]) {
agentRef.current ??= new TrashAgent();
const agent = agentRef.current;
setIsRunning(true);
try {
await agent.runAgent(
{ resume },
{ onMessagesChanged: ({ messages }) => setMessages([...messages]) },
);
} finally {
// The questions the agent is still waiting for: after a run that
// stopped to ask, its interrupts; after any other run, none.
setInterrupts([...agent.pendingInterrupts]);
setIsRunning(false);
}
}

// The person's answer goes back in the next run, as a resume entry.
function answer(interrupt: Interrupt, approved: boolean) {
void run([
{ interruptId: interrupt.id, status: "resolved", payload: { approved } },
]);
}

return (
<main className="demo">
<button
type="button"
onClick={() => run()}
disabled={isRunning || interrupts.length > 0}
>
Empty the trash
</button>

{interrupts.map((interrupt) => (
<fieldset key={interrupt.id} className="card" disabled={isRunning}>
<legend>Approval needed</legend>
<p>{interrupt.message}</p>
<div className="buttons">
<button type="button" onClick={() => answer(interrupt, true)}>
Approve
</button>
<button type="button" onClick={() => answer(interrupt, false)}>
Reject
</button>
</div>
</fieldset>
))}

{messages.map(
(message) =>
message.role === "assistant" && (
<p key={message.id} className="reply">
{message.content}
</p>
),
)}
</main>
);
}

macOS-style code window titled app/page.tsx showing the run function, which calls agent.runAgent with resume and then copies agent.pendingInterrupts into the state, and the answer function, which runs again with a resume entry holding the interrupt ID, the status resolved and the payload approved

  • run starts a run, with answers or without. Afterwards, it copies agent.pendingInterrupts into the state, so the page shows a card for every question the agent is waiting for, and none after a run that finished.
  • answer is a new run with one resume entry: the interrupt's id, status: "resolved", and approved in the payload.
  • The card is a <fieldset>: its <legend> names it, and disabled={isRunning} turns off both buttons while a run is going. interrupt.message is the agent's own question.
  • Empty the trash stays off while a card waits, because the next run has to be the answer.

The page's styles, for app/globals.css:

app/globals.css
body {
margin: 0;
font-family: system-ui, sans-serif;
color: #1b1f24;
background: #ffffff;
}

.demo {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 16px;
max-width: 520px;
margin: 48px auto;
padding: 0 20px;
}

.demo button {
padding: 8px 16px;
border: 1px solid #2f6fd6;
border-radius: 8px;
background: #2f6fd6;
color: #ffffff;
font: inherit;
cursor: pointer;
}

.demo button:disabled {
opacity: 0.45;
cursor: default;
}

.card {
display: flex;
flex-direction: column;
gap: 10px;
min-width: 0;
padding: 10px 16px 14px;
border: 1px solid #2f6fd6;
border-radius: 12px;
}

.card legend {
padding: 0 6px;
font-weight: 600;
}

.buttons {
display: flex;
gap: 8px;
}

.reply {
margin: 0;
padding: 10px 14px;
border-radius: 12px;
background: #f1f4f7;
}

The sample page's app/page.module.css isn't used any more, so delete it.

Step 5: Run It​

Terminal
npm run dev

Open http://localhost:3000 and select Empty the trash. The run ends with the interrupt, and the card appears, with the agent's question:

The page with a dimmed Empty the trash button and a card titled Approval needed with the question Empty the trash? Its 3 files will be deleted for good. and the buttons Approve and Reject

Select Approve. The next run carries { approved: true }, the agent empties the trash, and the card is gone, because that run finished:

The page after approving: the Empty the trash button enabled again and the agent's reply Done. The trash is empty.

Reload the page, select Empty the trash again, and select Reject this time:

The page after rejecting: the Empty the trash button and the agent's reply OK. I kept the 3 files.

Common Mistakes​

MistakeWhat happensDo this instead
Starting a new run without a resume while a card waitsThe client throws Thread has 1 pending interrupt(s) not addressed by resume and sends nothingAnswer every open interrupt in the next run
Expressing a rejection with status: "cancelled"cancelled means the person didn't answerSend resolved with { approved: false }
Keeping the interrupts only in your own stateThe client checks every run against its own list, pendingInterrupts, not yoursRead agent.pendingInterrupts after every run
Showing interrupt.reason to the personconfirmation or tool_call means nothing to themShow interrupt.message

FAQ​

What if the agent asks two questions at once?​

Then pendingInterrupts holds two interrupts, and the page shows two cards. The next run must answer both: AG-UI's documentation says A single resume array must address every open interrupt from the interrupted run. This example's answer sends one entry, which is enough for its one question. With several, collect the person's answers first, and send one run with an entry for each.

What if the person writes something else instead of answering?​

Send their message together with a cancelled entry for every open interrupt. Without it, the client refuses the run: Fixed: "Thread has 1 pending interrupt(s) not addressed by resume" in the AG-UI Client.

Does this work with an agent on a server?​

Yes. Use an HttpAgent for your server instead of TrashAgent: it has the same runAgent and pendingInterrupts. The answer then travels to the server in the resume field of the run's input. In the IT Service Desk series, the same card approves a password reset that a Microsoft Agent Framework agent waits for.

Conclusion​

An AG-UI agent asks for approval by ending its run with an interrupt. After each run, read agent.pendingInterrupts and show each interrupt's message on a card. Approve and Reject start the next run with runAgent({ resume }): one entry per open interrupt, with status: "resolved" and approved in the payload.

Additional Resources​