All posts
Product design

Agent Activity Logs: Designing a Timeline Users Can Audit

How to design an agent activity log UI: what each entry shows, how to group runs, link changes, explain why and make undo work from the timeline itself.

By Mehdi Hassan9 min read

The short answer

An agent activity log UI is a timeline of everything an AI agent did during a run: each action, the tool it used, why it chose that step, what changed and whether it can be undone. Design it for three readers: the user checking a result, the admin auditing later and the engineer debugging a failure.

Key takeaways

  • Write every log entry as an action in plain language, with the object it touched and a link to that object.
  • Group entries by run, then by step. A flat stream of tool calls is a debug console, not an activity log.
  • Show the reason for a step on demand, and keep raw inputs and outputs one level deeper.
  • Put undo on the entry that caused the change, and say honestly when a step can't be reversed.
  • Treat the log as a product surface with filters and export, not a leftover of the loading state.

Part of AI Product UX: How to Design AI Features Users Trust

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.

Frequently asked questions

Is an agent activity log the same as an audit trail?
Not quite. An audit trail is a compliance record that proves who did what and when, usually kept for a set period and rarely read by end users. An agent activity log is a user-facing view built on top of that record, written in plain language, linked to the changed objects and paired with undo. Most products need both, fed from the same data.
Should users see the agent's raw reasoning in the log?
Usually no, at least not by default. Raw reasoning is long, hard to scan and can read as more certain than it is. Show a one-sentence reason per step with links to the evidence it used, and put a summarized explanation behind an expand control. Keep the raw traces in internal tools where engineers can read them when debugging.
How much detail should a log entry show by default?
Show one line by default: the action, the object it touched, its status and the time. Put the before and after view, the reason, the tool calls and any approval record behind an expand control. Users scanning a run need to spot the unusual entry fast, and a wall of expanded detail hides it. Let power users choose an expanded view if they want it.
Where should the activity log live in the product?
Put it in two places. Attach each run's timeline to the task or conversation that started it, so users find it in context. Then offer an account-level history view where admins can filter every run by status, person, system and date. Linking from a changed record back to the run that changed it closes the loop in both directions.
What should the log show when an agent fails partway through?
Show exactly where it stopped, what it completed before that point and what it didn't attempt. Mark the failed step with a plain reason and the next options: retry, skip or hand the task back to the user. Keep the completed steps undoable, so the user can either finish the job or cleanly reverse the partial work rather than guessing what state things are in.

· CEO & Design Director

Copywriter, designer and developer, and founder of Designify Studio. Over five years, 60+ projects across 14+ industries, for startups that have raised $300M+.

Want this done for you? Monthly retainer, $6,000.

Your ongoing design and development team, for products that keep shipping. $6,000, per month, flat fee. Book a free 30-minute call to see if it fits.

Schedule Call