Once an AI agent can change records, send messages or edit files, users stop asking "what did it say?" and start asking "what did it do?" The activity log is where that question gets answered, and it's often the screen teams design last. This guide focuses on that one component: the timeline of agent actions. For the wider set of patterns around plans, approvals and autonomy, start with our guide to AI product UX.
What is an agent activity log?
An agent activity log is a time-ordered record of the actions an AI agent took, written so a person can check, explain and reverse them. It sits between the live progress view a user watches while the agent works and the raw traces engineers read in an observability tool.
The distinction matters because each of those three surfaces has a different reader. The live view answers "is it still working?" The raw trace answers "which prompt and tool payload caused this bug?" The activity log answers "what changed in my account, and was it right?" Our guide to agentic UX introduces the task log as one pattern among several. Here we go deeper on how to design it so it survives real use.
Surface | Main reader | Question it answers | Lifetime |
|---|---|---|---|
Live progress view | The user who started the task | Is it working, and what's it doing now? | While the run is active |
Activity log | Users, team leads, admins | What did it do, why, and can I undo it? | Kept with the account history |
Raw trace | Engineers | Which input or tool call caused this? | Kept in internal tooling |
What should each agent log entry show?
Each agent log entry should show the action as a verb phrase, the object it touched, the outcome and the time. "Updated the billing email on Acme Corp's account" is an entry. "tool_call: crm.update (200)" is a trace line that leaked into the interface.
A reliable entry has a fixed anatomy, so users learn where to look. Keep the summary to one line and hide the rest behind an expand control.
- Action summary: a plain-language verb phrase, written for the user, not the model.
- Object and link: the record, file, message or page that changed, linked so users can open it in place.
- Status: done, failed, skipped, waiting for approval or reverted, each with its own icon and label, never color alone.
- Source of authority: whether the step ran automatically, after a user's approval or because of a standing rule.
- Change detail: a before and after view for edits, and the full content for anything sent.
- Reversibility: an undo control, or a clear note that the step can't be undone.
How do you design an agent activity log UI people can audit?
You design an auditable agent activity log UI by grouping entries into runs, making every entry traceable to who or what authorized it, and keeping the record complete even when steps fail or get undone. Auditing means someone who wasn't there can reconstruct what happened later.
Start with the run as the top-level unit. A run card holds the original request in the user's words, who started it, when, the overall result and a count of changes. Inside, list steps in order. When a step involves several tool calls, show the step and nest the calls underneath, collapsed by default.
Never delete entries. When a user undoes a step, add a new entry for the reversal and mark the original as reverted, so the history stays honest. The same goes for failures: a failed step and its retry are two entries, not one silently replaced line.
Hypothetical example: a sales-ops agent's run, step by step
For example, suppose a user asks an agent to "clean up duplicate contacts for accounts I own." The run card shows that request, the start time and a summary: 6 merges, 2 skipped, 1 waiting for approval.
Inside, step one reads "Found 9 possible duplicate pairs across 4 accounts," with a link to the list. Each merge entry names both contacts, shows which fields were kept, and has an undo button. The two skipped pairs explain why: conflicting phone numbers the agent wouldn't guess between. The waiting entry asks the user to choose which email to keep. An admin reading this a month later can see exactly what changed and on whose request, without opening a single trace.
How should a log explain why the agent did something?
A log should explain why with a short, factual reason attached to each step, such as the rule, instruction or data that triggered it. One sentence is usually enough: "Merged because both contacts share the same email and company." Longer explanations belong behind an expand control.
The reason should point at evidence the user can check. If a step relied on a document, a record or a web page, link it, the same way citations in AI answers point at the passage behind a claim. If the agent followed a standing rule the user set, name the rule and link to where it can be edited. This turns a frustrating "why did it do that?" into a fix the user can make themselves.
Be careful with confidence language. Words like "definitely" or a decorative confidence score invite trust the system hasn't earned. Plain reasons plus visible evidence do more than any meter.
How do undo and rollback work from an activity log?
Undo works best when it lives on the entry that caused the change, with a run-level rollback for undoing everything at once. Users shouldn't have to leave the log and hunt for the changed record to reverse it.
Design three levels of reversibility and label them honestly. Some steps are fully reversible, like a field edit. Some are partly reversible, like a message that can be followed up but not unsent. Some can't be undone at all, like a payment or a deleted file outside your system. Mark the last two clearly, both in the log and in the plan before the run. When an undo would clash with later changes, say so and show what would be affected before the user confirms.
Reversibility | Example step | What the log offers |
|---|---|---|
Fully reversible | Changed a field value | One-click undo with a before and after preview |
Partly reversible | Sent an email | Show the sent content and offer a follow-up action |
Not reversible | Issued a refund | A clear label, the approval record and who approved it |
How do you design agent run history across many runs?
Agent run history needs list-level design: filters, search and summaries, because once an agent runs daily, nobody reads individual timelines unless something looks wrong. The history view's job is to surface the run worth opening.
Useful filters are status (failed, waiting, reverted), who started the run, which tools or systems were touched, and date. Search should cover object names, so a user can type a customer's name and see every run that touched that account. Each row in the history shows the request, the result and a change count, with failures and pending approvals visually distinct.
Admins will also ask for export. Even if you don't build it on day one, design the data model so each entry already carries the actor, the authorizing user, the timestamp and the changed object. Retrofitting that later is far harder than designing the screen.
How should the activity log relate to loading states and approvals?
The activity log should be the same timeline as the live progress view, just finished. While a run is active, new entries appear as steps complete. When it ends, that same list becomes the permanent record. Building two separate components usually means the two drift apart.
Our guide to AI loading states covers the in-progress side: tool-use indicators, streaming and how much detail to show while users wait. Approvals slot into the same timeline as entries with a waiting status and an inline decision, so users never wonder whether a pending action is still alive. For agents that run while the user is away, the log matters even more, because it becomes the main thing a user returns to.
How do you build the log as reusable components?
Build the log from a small set of components: a run card, a step row, a nested tool-call row, a change preview and a status badge. With those five pieces you can assemble the live view, the finished log and the history list without redesigning each one.
Define the status set once, with icons and labels that work without color, and reuse it everywhere agents appear. When you review the result, our AI product UX audit checklist includes checks for logs, approvals and undo alongside the rest of the AI experience. If you're building on an existing component library, shadcn/ui vs a custom design system helps you decide where the log components should live.
We design and build these surfaces as one team, from the words in each entry to the React components that render them. See our product design service and our work for AI agent companies.
