<AgentChat> is the drop-in UI: a transcript where every answer keeps its own
activity, a composer with everything around the input, and optional side
panels for saved chats and the agent's workspace. Every part can be switched
off, relabelled, rendered by you, or swapped for your own component — and
everything it does is also available as hooks and pure helpers for a fully
custom UI.
import {
AgentChat,
ChatHistoryStore,
VirtualFileSystem,
createFileTools,
useAgent,
} from '@dudko.dev/agent-web-react'
import '@dudko.dev/agent-web-react/styles.css'
const files = new VirtualFileSystem({ namespace: 'my-app' }) // IndexedDB
const history = new ChatHistoryStore() // IndexedDB
function Assistant() {
const agent = useAgent({
model,
tools: { ...myTools, ...createFileTools(files) }, // the agent can use the workspace too
memory: new IndexedDBStore(), // a reopened chat keeps its context
toolApproval: { mode: 'ask-writes' },
})
return (
<AgentChat
controller={agent}
title="Assistant"
history={history}
files={files}
composer={{
model: { label: 'Gemini 3.5 Flash', options: models, value, onSelect },
thinking: { value: level, onChange: setLevel },
convertFile: pdfToMarkdown, // PDFs the model can't read become Markdown
dropZone: 'window',
}}
style={{ height: 640 }}
/>
)
}- Transcript
- Composer
- Talking to the agent while it works
- The agent's notebook, and what it fetched
- Attachments: images, PDFs, files, URLs
- Saved chats (IndexedDB)
- Workspace (virtual file system)
- Tool consent
- Customising: show/hide, labels, render props, slots, components, theme
- Hooks and helpers for your own UI
- Label reference
Each assistant message keeps its own activity after the next run starts — the reducer mirrors the run onto the message:
- a collapsible summary ("2 steps · 3 tool calls · skills: …"), open while the answer is being produced;
- every step with its streamed text and thoughts;
- every tool call — name, arguments, status, ≈tokens of its arguments and
of the result fed back to the model, its duration, and any images it
returned (data URLs or
{ type: 'image' }parts are shown as thumbnails); - consent decisions and subagent delegations under the step that made them;
- the answer's thoughts (when the model thinks);
- a usage line with tokens by kind:
in 12k · out 456 · think 120 · cached 9k · 4.2 s.
User messages show their text and attachments: image thumbnails (click to open full size) and file chips. The header shows the conversation's total.
| Prop | Default | |
|---|---|---|
showActivity |
true |
the per-answer activity block |
showToolCalls |
true |
each tool call inside it |
showUsage |
true |
per-answer and per-tool-call tokens |
showTotalUsage |
true |
the conversation total in the header |
showThoughts |
true |
step and answer thoughts |
showStatus |
true |
the status dot in the header |
showContext |
false |
context meter above the composer (number = budget bar) |
activityOpen |
false |
keep finished answers' activity expanded |
emptyState |
labels.emptyState |
what the transcript shows before the first message (any node) |
defaultHistoryOpen |
wide panel: yes · narrow: no | whether the saved-chats sidebar starts open |
defaultFilesOpen |
false |
whether the Files panel starts open |
narrowWidth |
760 |
below this width (px) the side panels overlay the chat |
<AgentComposer> (the footer of <AgentChat>, usable on its own):
- notices above the input: a limit that stopped the run, a compaction, a start failure, an attachment the model can't take, a microphone error — dismissible;
- "+", Ctrl+V and drag & drop for files and images;
- "/" commands:
/compact,/new,/stop,/autopilot,/ask,/ask-all,/read-only,/think <level>, and every skill as/skill-name <goal>; add your own withcommands; - run timer, running subagents ("2 agents"), the model + thinking chip (with a switcher), the consent-mode chip ("⚡ Auto"), a mic (speech to text with the browser's Web Speech API) and send / stop.
| Prop | |
|---|---|
model |
{ label, options?, value?, onSelect? } — chip and switcher |
thinking |
{ value, options?, onChange } — shown next to the model; default levels off (the provider's default), none (thinking off), low, medium, high |
commands / builtinCommands / skillCommands |
slash commands |
attachments |
false, or { accept, maxBytes, imageMaxDimension, imageMaxPixels } |
convertFile / convert |
file → text (e.g. PDF → Markdown), 'when-needed' or 'always' |
files |
save attachments into a VirtualFileSystem under /attachments/ |
dropZone |
'self' (default), 'window', or a ref (<AgentChat> passes its panel) |
speech |
false, or { lang } |
steering / showQueued |
typing to the agent while it works; the queue strips (below) |
showTimer / showAgents / showApprovalMode / showNotices |
toolbar parts |
toolbarExtra / toolbarEnd |
your own toolbar content |
compactWidth |
below this width (px) the toolbar chips show icons and numbers only (default 460) |
renderAttachment |
render a pending attachment chip yourself |
labels, placeholder, disabled, className |
Speech to text uses SpeechRecognition / webkitSpeechRecognition (Chrome,
Edge, Safari). In Chrome the audio is recognised by Google's service; the mic
button only appears where the API exists.
The input stays live during a run. Text typed then is said to the running agent (the
send button, or Enter): it is shown to the model at the next boundary — between tool
calls, or when the step ends, where the replanner re-checks the plan against it. It never
cuts a tool call short. Needs @dudko.dev/agent-web with createRunControl (see the
core's steering docs).
What the user sees:
- a message waiting for a boundary shows above the input as queued ("waiting for the agent's next step");
- once the agent has it, the queue entry becomes a note under the step it reached — "you said, between tool calls" / "after this step" / "before the answer". It is a note on that run, not a new turn, and it is saved with the chat;
- a message that arrives too late for the run (while the answer is being written) is
sent as the next message when the run ends (
followUp, default on); - Stop does not send behind the user's back: whatever the run never showed the agent is offered above the input — "Not delivered (1 message)" with Send now / Discard;
- every running subagent gets a stop button (and shows its profile, when the parent chose one). Stopping one fails only that delegation — the parent model is told and routes around it; the run and its siblings go on. It then shows as "stopped".
- files cannot join a run that is going (they are sent with the next message) — the composer says so instead of dropping them.
const agent = useAgent(config)
agent.send('use the staging database') // false: no run in flight (or empty) — use run()
agent.stopSubagent(agent.subagents.find((s) => s.status === 'running')!.id)
agent.queued // [{ id, text }] — sent, not yet shown to the model
agent.notes // [{ id, text, at: 'round' | 'step' | 'final', stepId? }] — shown, and where
agent.undelivered // string[] — a stopped run's leftovers; sendUndelivered() / discardUndelivered()| Prop / option | |
|---|---|
steering (composer, default true) |
off: the input does nothing during a run, as before |
showQueued (composer, default true) |
the queue and "not delivered" strips |
showNotes (chat / message list / step list, default true) |
the notes under the steps |
stoppableSubagents (chat, default true) |
the stop button on running subagents |
followUp (useAgent option, default true) |
send what a run never showed the agent as the next message |
onStopSubagent (message list / step list) |
wire your own stop button (useAgent().stopSubagent) |
Labels: placeholderBusy, steer, noAttachmentsWhileBusy, queuedWaiting, noteAt,
undelivered, sendUndelivered, discardUndelivered, stopSubagent, subagentStopped.
A replan caused by a message has replan.byUser === true.
With learning in the agent's config (core: learning: true, or { store: new VfsSkillStore(files) }
to keep lessons as SKILL.md in the workspace) the agent writes down what it figured out. The UI
follows it:
- The turn says what the agent learned in that answer ("learned: image-format-jpg") and, with
egress, what it fetched - each request with its status, a refused one with the reason ("refused: not on the allow list"). Hide it withshowLearned={false}(chat / message list). <LearnedSkills />is the notebook itself: each lesson with when it applies, its revision and where it came from (the sources it named, the pages it read), and a button to forget it. Place it anywhere - a settings panel, a sidebar (slots.sidebar). Props:controller(default: the provider's),lessons(to show your own list),onForget(defaultcontroller.forgetSkill;false= read-only),showSources,hideTitle,empty,labels.- State:
learned(the notebook,LessonView[]) belongs to the agent, not to a conversation - it survivesresetand a chat switch, and the hook re-reads it whenever the agent is rebuilt (so a store that persists brings its lessons back).learnedNow/fetchesare the current run's; each assistant message keeps its ownlearned/fetches.useAgent().forgetSkill(name)deletes one.
Labels: learnedNow, fetches, fetchRefused, notebookTitle, notebookEmpty, notebookForget,
notebookRevision, notebookFrom.
What the composer does with each file:
| Kind | Goes to the model as | When the model can't take it |
|---|---|---|
text (.md, .json, .ts, …) |
inlined into the goal, fenced | — (every model reads text) |
| image | a file part (downscaled to ≤ 1568 px / 1.15 MP first) | refused with a sentence the user can act on |
| a file part | converted with convertFile if given, else refused |
|
| other | a file part | convertFile, else refused |
"Can't take it" comes from the core's agent.capabilities (images, pdf,
files: true / false / unknown). Unknown means try: if the provider refuses,
the run fails with an AttachmentsNotSupportedError naming the model and what
to do instead — never a raw provider error.
Images are downscaled because providers bill images by their pixel size and resize anything larger themselves; a 12 MP phone photo costs the same tokens as its 1.15 MP version but uploads ten times slower.
The core also takes URLs: agent.run(goal, { files: [{ data: new URL('https://…/report.pdf') }] }) — providers that accept links fetch them
themselves; for the rest the AI SDK downloads them (from a browser: subject to
CORS).
history on <AgentChat>: true (a default ChatHistoryStore), your own
ChatHistoryStore, or the result of your own useChatHistory() (to render the
list elsewhere). Each chat stores the transcript with its tool calls, usage
and image attachments, and its id becomes the agent's memory session — use a
persistent memory (IndexedDBStore) and a reopened chat continues with the
model's context intact.
The sidebar sits beside a wide panel and overlays a narrow one (under
narrowWidth, default 760 px), where it starts closed.
const store = new ChatHistoryStore({ dbName: 'my-app-chats' }) // or { memory: true }
const chats = useChatHistory(agent, { store, resumeLatest: true })
chats.chats // [{ id, title, createdAt, updatedAt, messageCount, totalUsage }]
chats.select(id) // open one
chats.newChat() // start fresh
chats.remove(id)Chats are saved when a run settles, not on every streamed token.
<ChatHistoryList> (the sidebar, usable on its own) also takes renderChat(chat, active, fallback)
to draw a row yourself and formatTime(ms) for the timestamps.
files takes the core's VirtualFileSystem (IndexedDB, browser only — in Node
use the real file system). The composer saves attachments into it under
/attachments/, the Files panel shows it live (preview text and images,
download, delete, upload), and createFileTools(files) gives the agent
fs_list, fs_read (read-only), fs_write and fs_delete over the same
files — so "summarise the PDF I attached and save the summary next to it"
works.
<FilesPanel> (usable on its own) props: allowUpload / allowDelete (both default true),
uploadDir (where uploads go, default /uploads), onOpen(file) (a row was clicked, in addition to
the preview) and renderFile(file, fallback) to draw a row yourself.
With a toolApproval mode other than autopilot, consent requests appear as
cards in the transcript ("Allow once", "Always allow", "Deny"); the consent
chip in the composer and the /autopilot, /ask, /ask-all, /read-only
commands switch the mode live, even mid-run.
<ToolApprovalPrompt> (usable on its own) takes approvals (e.g. useAgent().pendingApprovals), onApprove(id, { remember }) and
onDeny(id, reason) (wire them to useAgent().approve / .deny), and allowRemember (default
true; false hides "Always allow"). <ContextMeter> shows tokens against budgetTokens and, with
onCompact (e.g. agent.compact), a "Compact" button — compacting disables it while it runs.
Show / hide — the show* props above, composer={false}, history,
files.
Labels (i18n) — every string is a label, counted phrases are functions so plurals work in any language:
<AgentChat labels={{ send: 'Отправить', steps: (n) => `${n} шаг(ов)` }} />
// or for a whole tree:
<AgentLabelsProvider labels={ruLabels}>…</AgentLabelsProvider>See defaultLabels for the full list (the demo ships a complete Russian set in
demo/src/i18n.ts).
Render props — take over a part and keep the rest; each gets the built-in
rendering as fallback:
<AgentChat
renderContent={(m) => <Markdown>{m.content}</Markdown>}
renderToolCall={(call, fallback) =>
call.name === 'make_move' ? <li><ChessMove move={call.input} /></li> : fallback}
renderAttachment={(a) => <MyThumb attachment={a} />}
renderMessage={(m, fallback) => <Animated key={m.id}>{fallback}</Animated>}
renderApproval={(req, fallback) => fallback}
/>Slots — slots={{ header, headerStart, headerEnd, beforeMessages, afterMessages, footerStart, sidebar }} (header: false hides it).
Components — swap whole parts with your own (same props):
components={{ Composer, MessageList, HistoryList, FilesPanel, ApprovalPrompt }}.
Theme — theme="auto" | "light" | "dark", the --awr-* custom properties
(colours, radius, fonts, --awr-sidebar-width, --awr-files-width),
classNames={{ root, main, header, body, footer, sidebar, files }} and
className / style. Components used outside <AgentChat> get the theme
tokens inside an element with class awr-theme.
useAgent |
the agent, its UI state, run(goal, { images, files, attachments, label }), send / stopSubagent (steer a running agent), forgetSkill (the notebook), consent, compact, sessionId, loadChat |
useChatHistory |
saved chats over a ChatHistoryStore |
lessonsOf |
the agent's own skills (agent.listLearnedSkills()) as LessonView[] - what the hook seeds the notebook with |
useVirtualFiles |
a live listing of a VirtualFileSystem + upload / remove / read |
useSpeechToText |
Web Speech API: { supported, listening, interim, start, stop, toggle } |
useMcpServers |
several MCP servers, merged tools — import from @dudko.dev/agent-web-react/mcp |
agentStateReducer |
the pure event → UI reducer |
useAgentContext / useOptionalAgentContext |
the controller of the enclosing <AgentProvider> (the first throws outside one, the second returns undefined) |
useLabels / mergeLabels / defaultLabels |
the labels in effect, merged over a base, and the English defaults (below) |
parseSlash, filterCommands, attachmentKindOf, withAttachments, attachmentRefusal, noticesOf, formatElapsed, usageLine |
the composer's and transcript's pure logic |
downscaleImage |
the image downscaler |
Every string the components show is a key of AgentLabels. Pass a partial object as labels (to a
component or <AgentLabelsProvider>); whatever you leave out falls back to defaultLabels. Keys marked
(fn) are functions, so plurals work in any language; (map) keys are objects keyed by something.
- Frame and transcript:
emptyState,status(map by status),history,newChat,files,totalUsage,showHistory,showFiles,close,steps(fn: n),toolCalls(fn: n),subagents(fn: n),skillsUsed(fn: names),answerThoughts,stepThoughts,usageTitle,attachments,planned,replanned(fn: mode, reason),failed,toolCostTitle. - Notebook and fetches:
learnedNow(fn: names),fetches(fn: n),fetchRefused(fn: reason),notebookTitle,notebookEmpty,notebookForget,notebookRevision(fn: n),notebookFrom. - Composer:
placeholder,listening,message,dropHint,attach,attachTitle,commands,commandsTitle,send,stop,dismiss,remove(fn: name),dictate,dictateTitle,stopDictation,microphone,model,thinking,toolConsent,modes(map by approval mode:{ label, hint }),timerRunning,timerLast,agents(fn: n),agentsTitle,notices(map of notice texts),attachmentsOnly,seeAttachments,tooLarge(fn: name, mb),binaryText(fn: name),commandGroups(map),commandDescriptions(map),thinkingLevels(map). - Steering:
placeholderBusy,steer,noAttachmentsWhileBusy,queuedWaiting,noteAt(map byround/step/final),undelivered(fn: n),sendUndelivered,discardUndelivered,stopSubagent,subagentStopped. - Files and saved chats:
filesEmpty,upload,download,delete,preview,bytes(fn: n),historyEmpty,deleteChat,messagesCount(fn: n). - Consent:
approvalLead,approve,alwaysAllow,deny,declinedReason,readOnlyTool,consentWaiting,consentAllowed,consentDenied(fn: reason?).
tests/chat.test.ts fails if a key is added to AgentLabels and not listed here.