Playbooks / Agent UX & Human Interaction
Agent UX & Human Interaction
How agents present themselves, ask for input, and earn trust — UX patterns for human-in-the-loop systems.
- Designing for Trust & CalibrationTrust is calibrated by three disclosures — what you checked, what you did not, and what the check skips — and the third has no UI pattern. Seventy per cent of the miscalibration in a worked sample sits in the twenty per cent of items the system called certain, the one band every sensible-looking UI stops confirming: reviewing it costs 3.8 reads per defect against 100 in the band below. The best implementations of all three disclosures shipped in secret scanners, not chat.
- Approval & Confirmation UXA dialog cleared in under a second is not oversight and you cannot prove it was, which is the same defect twice — so design the gate to emit a binding artefact rather than a boolean: payload digest, a digest of what was actually rendered, who decided, and dwell time. Consequence tiers, the arithmetic that turns eleven reflexive gates into two real ones, why every shipping harness as of October 2026 pins the pause and not the arguments, and the three cases where a gate is the wrong instrument.
- Progressive-disclosure UX for agentsShow the user only the next decision they need to make — when to surface the chain of thought, the tool call, the diff; and when to keep it folded.
- Transparency & ExplainabilityThe design argument about showing the chain of thought was settled by the vendors: as of October 2026 every major reasoning API returns its hidden reasoning encrypted — Anthropic in a signature field on each thinking block, Google as a thought signature, OpenAI as reasoning.encrypted_content — with the readable part an optional summary from a separate pass, and summarized as the documented default on Claude Opus 4.6 and Sonnet 4.6. So three unverified hops now sit between your UI and the computation, not one, and the only tier you control is the one your own harness emits: the exact tool call, the query, the diff, the quoted passage with its document id. Treat the signature as a credential — round-trip it byte-exact, never echo it, since an August 2026 paper reports encrypted reasoning can be replayed out of a compatible model — and never label a vendor summary as the agent's reasoning.
- Interruption, Steering & HandoffAn interrupt is a request MCP lets the receiver ignore, and a resume is a re-execution — LangGraph's docs say the node restarts from the top, not from the interrupt() line — so the engineering surface is the span between the last durable write and the stop point, where every side effect runs twice. Worked through on a six-step support agent that posts the reply again after the human stopped it, plus the pause ceiling nobody sets, the handback that reverts a human's fix, and why for a four-second call the honest control is undo.
- Progressive AutonomyThe ladder you design is per scope and every shipping harness's dial is per session: Claude Code has six session-global permission modes as of October 2026 and Codex CLI crosses three sandbox modes with a separate approval policy, and none of them can say Observer for labelling tickets and Operator for refunds at once. So the rung lives in the credential scope and the per-call allow/deny policy, and the mode selector only decides who gets asked. Promotion needs a visible track record inside one scope, demotion must cost less than promotion, and a classifier rung — Notion's reviewer model, Claude Code's auto — makes that classifier's false-negative rate your autonomy policy.
- Designing for Failure & RecoveryGraceful failure that stops before compounding, undo as the safety net that makes lower friction affordable, actionable error messages, failing closed on consequence and open on capability, and the explicit work of trust repair.
- Async & Away: UX for Unwatched RunsPast ninety seconds nobody is watching, so the expensive problem is re-entry rather than the wait: an inbox over runs, a notification budget spent only on decisions, status pushed into the artifact, a diff instead of a transcript, and pre-authorisation because a gate with nobody behind it is a deadlock.
- Shared & Multi-User AgentsA second pair of eyes breaks three assumptions at once — one intent, one permission set, one accountable person — and the one that ends pilots is attribution collapse, not leakage: bind every run to one human principal, take permissions as the intersection, and print the name in the room.
- Undo & ReversibilityEvery confirmation dialog is a bill for the undo you did not build: sort actions by cost of reversal rather than by scariness, buy time with a hold window, and make each tool return a revert handle — because confirmation asks a person to predict a bad outcome while undo only asks them to recognise one.
- First Run & OnboardingThe first session sets a durable prior about what the agent can do, and the capability tour calibrates it to the ceiling: demonstrate a refusal early, pick a first task you can guarantee on the user's real data, and stop bundling permissions the user has no basis to evaluate.
- Memory & Personalization UXMemory is the only agent feature whose worst outcome is a privacy incident rather than a wrong answer, and it gets there through one default: writing silently — a user cannot correct, consent to or forget a fact they never saw being stored.
- Waiting & Latency UXAbandonment tracks legibility rather than duration, so shaving seconds off an agent run buys almost nothing — publish the plan before the work starts, reorder it so something checkable happens first, and hand off to async at a threshold you decided rather than one your users discover.
- Citations & Source-Attribution UXAn audit of four generative search engines found only 51.5% of sentences fully supported by their citations, so a footnote nobody opens raises confidence without raising correctness — attach spans during generation, drive the cost of checking one claim to three seconds, and measure detection of planted errors rather than click-through.
- Cost & Quota UXNobody budgets in tokens and a live dollar counter with no control attached is anxiety with a number on it — denominate the meter in the unit the user asked for, ship the receipt before the live meter, give a band rather than a point on a heavy-tailed distribution, and measure calibration rather than spend, because a cost surface optimised to reduce spend throttles the workflow returning 55× alongside the one that loses money.
- Generative UI & Agent-Rendered SurfacesThe moment an agent renders a screen instead of describing one your test matrix stops being finite — so exhaust selection before composition, make every component total over its prop space, never let a generated surface decide anything, snapshot the payload rather than the pixels, and keep a flag that drops the whole thing back to prose.
- Embedding an Agent in an Existing AppThe chat panel is the cheapest surface and the one users abandon, because it knows nothing about the screen in front of them — anchor the agent to the object instead, pass the view as structured context rather than a screenshot, write through the code path the UI already uses, and put state on the server on day one, because that is the only decision here you cannot retrofit.
- Notifications & DigestsDeciding to interrupt someone is a second policy with its own asymmetric, ratcheting cost — a useless notification permanently lowers the attention the next fifty get, and mute is an absorbing state — so route by decision deadline rather than importance, budget per recipient in the notification service where the agent gets no vote, and measure actioned-within-window rather than delivery, because this component fails in a way that looks exactly like success in your logs.
- Accessible Agent InterfacesEvery failure here is timing rather than markup, so the automated audit comes back green on an interface nobody can drive — assistive technology assumes a page that settles and an agent produces one that never does, the token stream wired to aria-live talks over its own user for forty seconds, and the auto-approval countdown discriminates precisely against whoever reads most slowly.
- Review Queues for Agent OutputDecisions per reviewer-hour is a hard multiplier on how much the agent is allowed to ship, so the queue is the autonomy ceiling — order by expected value of review rather than arrival time, build a surface for deciding rather than for reading the trajectory, and read a 98% approval rate as a broken control instead of a good model.
- Permission Grants & RevocationThe consent screen you inherited from OAuth assumes an actor whose behaviour is fixed at build time, and an agent breaks that assumption every run — but the screen that actually decides how much access you get is the revocation screen, because people over-grant when taking access back is invisible and under-grant when it looks permanent. Resolve scopes into object counts, make duration a first-class choice with a default that is not "always", and design what a running agent does the moment its access disappears.
- Agents in Shared ChannelsA team channel pulls apart two things a one-to-one thread kept together — who the agent works for and who wrote the text it is reading — and every framework still has one user field for both. Default to silence and treat only the addressed message as an instruction; resolve authority from the requester at the moment of the request, intersected with what the room may see; and label pasted, forwarded and bot-authored content as the untrusted tier it is.
- User-Authored SkillsSaved instructions ship a prompt supply chain into your product — named, stackable, shared by copy-paste, executing with the invoker’s permissions: keep invocation explicit because users name skills for themselves and not for a retriever, state precedence before stacking does it for you, and render user-authored text at user authority.
- Plan Review & EditingA plan screen trades twelve informed decisions for one uninformed one, because every argument in a plan is a guess made before any tool has run — so use the plan to let the user steer and keep authorisation on the irreversible step where the payload is real. Covers the four edits users actually want and why a deletion must become a standing constraint that survives replanning, the two promises a plan makes silently, a mechanical re-ask rule for plan drift, the four cases where the screen is the wrong decision, and the edit rate that tells you to delete it.
- Rewind, Branching & Side EffectsClaude Code's checkpoints capture edits made through its own file tools, so the shell command, the push and the sent email survive the rewind the user watched happen — the checkpoint boundary is your tool surface and they will read it as the world. Tag every tool rewindable / compensatable / irreversible, move branch points to just before the first irreversible action, split restore into code and conversation because all four combinations are weekly requests, and make the rewind dialog lead with what it will NOT undo.
- Proactive & Unprompted AgentsA proactive agent is a specificity problem wearing a judgement problem's clothes: at a 2.2% base rate — 180 inbound items a day, four that need you — a 97%-specific trigger yields 5.3 false alarms against 3.6 real ones, and 80% precision needs 99.6% specificity, which no prompt rewrite reaches. Cut the candidate set with deterministic rules instead, note that deleting the prompt also deleted the scope and the authorisation, give every trigger class its own tool scope and token budget, dedupe on item-plus-reason, and watch precision, sampled misses, candidate volume and quiet-day spend.
- Defaults, Settings & Who Can Change ThemYour defaults are your policy — at a 5% change rate, 95% of your install base runs the value someone picked in a planning meeting — and a setting the agent can write is a preference no matter what the screen calls it. Separates preference from requirement from capability grant (Codex CLI's allow_managed_hooks_only works only in requirements.toml and is a no-op in config.toml, which is the whole mechanism), shows why “turn that off” said in conversation has three meanings and your product implements the weakest, relabels settings with the worst unpredicted consequence rather than the mechanism, gives every grant an explicit scope and lifetime, and names the fail-open validator you inherited without choosing it.