Traces of Successful Workflows Are the Most Valuable Context for AI Agents

Most people feed their AI agent documentation. API specs, README files, style guides. This is useful but it misses something critical - documentation describes what should happen, not what actually happens.

A trace of a successful workflow captures the real sequence. The exact clicks, the specific order of operations, the fields that were filled in, the pauses between steps. When an agent learns from traces, it learns patterns that documentation never captures - like the fact that you always check Slack before updating the CRM, or that a particular form requires saving before navigating away.

Documentation vs. Traces

Documentation tells the agent "update the customer record in HubSpot." A trace shows: open HubSpot, search by email, click the contact, scroll to the deals section, update the stage dropdown, add a note with the call summary, click save, then copy the deal link into Slack.

The trace includes implicit knowledge. The agent learns that search-by-email is more reliable than search-by-name. It learns that the note goes before the save. These are details no one would think to document.

Capturing Traces Naturally

The best trace collection is passive. Run your agent in observation mode while you work. Let it record what you do, which apps you switch between, what you type. After a week you have a library of real workflows that cover your actual daily patterns.

Then when you ask the agent to "do the Monday reporting thing," it has a concrete reference instead of guessing from vague instructions.

Start Small

Pick your three most repetitive workflows. Record yourself doing each one twice. Feed those traces to your agent. The improvement in execution accuracy is immediately noticeable compared to text-based instructions alone.

The best context is not what you write down - it is what you actually do.

Fazm is an open source macOS AI agent. Open source on GitHub.