How to Document Agent Behavior

Your Evidence is Your Credibility

Your credibility comes from how clearly you can show what the agent actually did — not how smart your analysis sounds.Good documentation is defensible, repeatable, and useful for fixing real problems.

Document Behavior, Not Interpretation

The golden rule: Describe before you judge.

Every observation follows this order:What happened (facts only)When it happened (context)Why it matters (UX impact)

What the agent said or did, not what the model "meant"

When it happened, not what it "should" do

Under what conditions, not what users "might feel"

How it affected the experience, not whether it's "good" or "bad"

Good

Agent replaced text without warning before user confirmed
Agent answered confidently but information was incorrect

Bad

Agent violated user control principles
Agent has trust issues

Structure of a Behavior Note

Context

What to capture: Task, step, modality

Example: "Task 1 — Summarize text (Canva Magic Write)"

Observation

What to capture: Exactly what happened (neutral)

Example: "Agent replaced content without explaining this would happen"

Impact

What to capture: What this causes for user

Example: "User loses content unexpectedly, unsure how to recover"

Evidence

What to capture: Proof (timestamp, screenshot)

Example: "Video 01 — 02:14–02:28"

Keep Notes Short and Specific

If a note includes "and then… and also…" → split it.

1–3 sentences per behavior
One behavior per note
No mixing multiple issues

Notes by Modality

Voice - Transcribe responses, misrecognitions, confirmation phrasing, pauses
Text/Chat - Exact phrasing, formatting changes, overwrites, context drift
Multimodal - Entry points, side effects, invisible actions, differences between UI paths

Document Good AND Bad Behavior

Professional audits are balanced. Note what worked smoothly, what was helpful, what felt clear. This builds credibility and shows teams what NOT to break while fixing issues.

Example finding: "Toolbar invocation preserved content; floating bubble invocation overwrote it." - Gold for teams.

How to Document Agent Behavior

You must be logged in to access this course

Foundation

Agent Experience Assessment

Task Scenario Library

Failure Patterns

Real Audit Example

Downloads & Templates