Agent Design Patterns
Five working UI patterns for how an AI agent shows its work, earns trust, and knows when to step back. Each one is real code wired to the Claude API, not a mockup. The seven skills in the key below separate a working agent from a demo, and every pattern is organized around them.
- Every demo below loads a real, previously-captured response instantly. Click Run live on any demo to call Claude fresh and watch the run happen again in real time.
- Confidence badges (Medium confidence / Low confidence) are always followed by a reason. In Pattern 02, click a badge to expand the rationale.
- Tags on each pattern name the agent-engineering skills demonstrated. The key below explains them.
Skill key
- System design
- Tool & contract design
- Retrieval
- Reliability
- Security
- Evaluation
- Product thinking
01 Reasoning Trace
- System design
- Reliability
The agent is working and the person is waiting.
Reading survey data
15 free-text responses
Identifying patterns
- checkout process speed
- support responsiveness and issue resolution
- app reliability and bugs
- order history and dashboard usability
- pricing transparency
- complaint follow-up handling
- search functionality
- onboarding and setup experience
- refund processing time
- subscription cancellation friction
- proactive customer communication
Drafting summary
- 1. Support and complaint handling issues (6 responses)
- 2. App and technical reliability problems (3 responses)
- 3. Checkout, refunds, and pricing friction (3 responses)
- 4. Positive dashboard and order history experience (2 responses)
- 5. Onboarding experience (1 response)
Complete
Support experience is inconsistent, with complaint escalation and follow-up being a bigger pain point than initial responsiveness, since customers cited repeated issue re-explanation, unresolved complaints, and forced call-ins alongside praise for quick chat resolution and direct messaging.
Medium confidenceBasis: sample volume — grounded in how many responses support itCheckout and post-purchase financial flows (pricing clarity, refunds, cancellation) create friction that risks cart abandonment and customer frustration.
High confidenceBasis: sample volume — grounded in how many responses support itCore app reliability issues, particularly crashes during receipt upload and unreliable payment info storage, should be prioritized as they directly block task completion.
Medium confidenceBasis: sample volume — grounded in how many responses support itRecent dashboard and order history updates are landing well with users and should be preserved or extended in future redesigns.
Medium confidenceBasis: sample volume — grounded in how many responses support itSearch functionality may be an underlying usability gap contributing to broader frustration, though this is based on a single mention.
Low confidenceBasis: sample volume — grounded in how many responses support it
Simulate a failure at step
Showing a captured example
A spinner tells you an agent is busy. A spinner does not tell you whether the agent understood the task, whether the agent is about to spend four minutes on the wrong thing, or where the agent got stuck when a run fails. You pay for the opacity at the end, when you have to decide whether to trust output you never watched being made.
The design decision here is to show the artifact each step produced rather than a label claiming the step happened. You see the themes the agent extracted and the clusters the agent ranked, so a wrong turn stays legible while catching one is still cheap. Failure gets the same treatment. The connector breaks at the failed step, and the message says what stopped and what never ran. Use the toggles to break the run deliberately. The error travels the same path a genuine API failure takes.
The system-design decision is where a chain becomes observable. Per-step artifacts replace per-step labels. The reliability decision is to render failure through the same path, so the observability stays load-bearing rather than decorative.
02 Confidence Signal
- Evaluation
- Product thinking
The agent has an answer, and parts of the answer are shakier than the rest.
Showing a captured example
Uniform presentation flattens a real difference. An insight backed by twelve responses and an insight the model inferred from two look identical in a list. People then trust both or neither, and both failure modes are expensive.
The decision worth defending is keeping basis separate from level. “Twelve of fifteen said this” and “I inferred this and I think the claim holds” are different kinds of claim. Collapsing them into one score is where confidence indicators start misleading people. Each badge expands to a specific rationale and names whether the level came from sample volume or the model’s own judgement. Low-confidence items get a route-to-human action, the seam into Pattern 05.
Keeping basis separate from level is the evaluation question. What grounds a claim matters more than how sure the model sounds. Showing both instead of one tidy score is the product judgement, and the more expensive of the two to hold onto.
03 Confirmation Gate
- Security
- Product thinking
The next action is irreversible.
“Nobody followed up after my complaint about the damaged item.”
This reply apologizes for the lack of follow-up and commits to escalating the customer's complaint to the support team for direct outreach, without specifying an order, refund, or employee name.
Showing a captured example
Most confirmation dialogs do no work. “Are you sure?” asks a question no one is able to answer, because the dialog never says what happens next. The banner here names the specific consequence instead.
Two decisions do the real work. The draft is editable, because a gate offering only approve-or-reject forces a choice between shipping something slightly wrong and discarding good work, so people ship the wrong version. The two actions are also visually identical. No accent-filled primary appears anywhere in this component. Emphasising the confirming action is the ordinary way this pattern becomes a dark pattern, so the styling removes the option. Confirming produces a receipt with the final text and a timestamp, never a silent success.
Naming the specific irreversible consequence is the security work. A gate silent about what gets gated is not a gate. Refusing to style either action as primary is the product judgement keeping the gate from becoming a dark pattern.
04 Correction & Override
- Tool & contract design
- Evaluation
The agent decided, and the person reviewing the decision disagrees.
Refund process took over three weeks, way too slow for the amount.
The mobile app crashes every time I try to upload a receipt for a return.
I had to explain my problem three times to three different agents.
Nobody followed up after my complaint about the damaged item.
Cancelling a subscription requires calling in, which feels intentional and frustrating.
Corrections are recorded for review. Nothing here retrains a model, and the interface doesn’t suggest otherwise.
Showing a captured example
An agent with no in-place correction forces people into a workaround. They export the data, fix the data elsewhere, and stop reporting the errors. You lose the correction and the signal about corrections being needed.
Categories come from a fixed enum, the same one constraining the model, because a taxonomy anyone extends at the point of correction stops being a taxonomy. The acknowledgement wording is chosen carefully. “Captured for improvement” is what happens. The wording is not “the model has learned from this,” because nothing here retrains anything, and the people who correct agents most often are the people who notice a false claim.
Binding the override to the same enum constraining the model is contract design. One taxonomy, enforced on both sides of the correction. Recording what people change, and claiming nothing more, leaves the result usable as evaluation data.
05 Escalation & Handoff
- System design
- Reliability
- Retrieval
The agent has reached the edge of its authority to decide alone.
3 items awaiting review
From Confidence Signal
Low confidence, self-assessed — 2 of 15 responses
- Original data
- 9. Search never finds what I'm looking for, I have to scroll through everything. 4. Loved how easy it was to find my order history, very intuitive.
- What the agent produced
- Insight: "Search relevance is the primary discovery blocker." confidence: low · basis: self_assessed Rationale: Only two responses touch discovery and they contradict each other — one praises finding order history, one calls search unusable. Distinguishing "search is broken" from "search is fine but browse is better" needs more data than this sample holds.
From Correction & Override
Category ambiguous — two candidates scored equally
- Original data
- 15. Cancelling a subscription requires calling in, which feels intentional and frustrating.
- What the agent produced
- category: Account Management note: "Cancellation requiring a phone call is an account management process complaint." The response describes a retention pattern the customer reads as deliberate. The agent settled on Account Management without flagging an alternate category here, though earlier draws have named Support Experience as the closer runner-up — the ambiguity is real even when a given draw doesn't spell it out.
From Confirmation Gate
Flagged by reviewer — draft implies compensation not authorised
- Original data
- 8. Nobody followed up after my complaint about the damaged item.
- What the agent produced
- Draft reply: "You reported a damaged item and then heard nothing from us — that follow-up should have happened and it didn't. I've reopened your case and assigned it to a specialist who will contact you within one business day with a resolution." The reviewer stopped this at the gate: "a resolution" reads as a promised refund or replacement, and nobody has approved either.
These three items are seeded rather than generated — a review queue is a handoff surface, not something a model produces, so there is no live run for this pattern.
Showing a captured example
Knowing when to stop is a capability, not a failure, as long as the handoff carries enough context to be actionable. A queue of items labelled “escalated” stalls, because every item costs a reconstruction before anyone acts.
Each item names its real reason, shows the original data, and shows the agent’s attempted output in full. Hiding a wrong answer to avoid anchoring the reviewer also hides the reviewer’s most useful evidence. Seeing how the answer went wrong is usually what makes the right call obvious. The actions reuse the vocabulary from Patterns 03 and 04. Clearing the queue gets a designed empty state, because “nothing needs review” is a real outcome and deserves a real screen.
Carrying the original data and the attempted output into the queue is as much a retrieval decision as a system-design one. What the reviewer needs has to arrive with the item. A handoff dropping the context is a reliability problem, not a workflow detail.
One lifecycle, not five widgets
These five are not a menu to pick from. They are one loop.
- An agent shows its work while running (01).
- The agent grades its own output honestly when finished (02).
- The agent stops before anything irreversible (03).
- The agent accepts correction after a mistake (04).
- The agent hands off what the agent should not decide alone (05).
Each one produces the input the next one needs. A low-confidence insight from 02 and a draft stopped at the gate in 03 both turn up in 05’s queue, carrying the reason they arrived.
All five share one idea. Trust comes from being legible about limits, not from appearing certain. Every pattern here is a place where the interface had the option to hide something and refused: a step, a shaky inference, a consequence, a mistake, an edge case. The same reasoning is why the page tells you whether you are looking at a cached result or a live one, rather than letting you assume.
A longer written case study on building these is a follow-up, not part of this page yet.