What to log when an AI agent writes to your CRM

Log the previous value. That is the single field teams leave out and the only one recovery actually depends on. Everything else in this list makes the log useful for diagnosis. The before value is what makes it useful for repair, and you will want it on the day an agent writes something wrong to four thousand records at three in the morning.

Why CRM field history is not enough

Both Salesforce and HubSpot record that a value changed and which integration changed it. Neither records why. When the question is whether the agent was working correctly, that gap is the whole question.

There is a practical problem underneath it too. If three agents share one API key, field history attributes every write to the same integration and they are indistinguishable. Give each agent its own credential. It costs nothing at setup and it is unrecoverable later.

The fields the log needs

• Agent identity and version. Which agent, running which version of its logic. When behavior changes, this is how you find out whether the agent changed or the data did.
• Run identifier. One id shared by every write in a single execution. This is what lets you reverse an entire bad run rather than hunting records one at a time.
• Target. Object, record id, and field. Specific enough to address, not so verbose that the log becomes its own storage problem.
• Before and after. Both values. Without the before, the log tells you what happened and leaves you unable to undo it.
• Reason. The rule that permitted the write, or the condition that triggered it. Not prose. A stable identifier you can filter on.
• Model and prompt version, when a model decided. Behavior that changes without a code deploy is otherwise unexplainable, and prompts change more often than code.
• Outcome. Written, skipped, blocked by policy, or failed. The skips and blocks are the interesting rows, because they tell you the guardrails are doing something.
• Timestamp, in UTC. Local timestamps across systems in different zones make incident reconstruction guesswork.

Log the writes that did not happen

A log containing only successful writes cannot answer the two questions people actually ask. Is the agent too cautious, and is it too permissive. Blocked and skipped entries are what let you tune the policy instead of guessing at it.

They are also the evidence that guardrails exist. Telling a security reviewer that the agent has restrictions is an assertion. Showing them four hundred blocked writes with the rule that blocked each one is a demonstration.

Where the log should live

Not only in the CRM. If the agent can write to the CRM, the agent can in principle write to a log stored in the CRM, and an audit trail the audited system controls is worth less than one it does not.

Somewhere append-only outside the CRM is the right shape. Chaining each entry to a hash of the previous one makes the log tamper-evident: it does not stop anyone editing history, it makes edited history detectable, which is the property that matters when someone asks whether the record can be trusted.

How much is too much

Logging every read produces volume nobody searches. Log writes, attempted writes, and decisions. Reads matter only when the data is sensitive enough that access itself is the concern, and that is a different requirement with different rules.

Set a retention period deliberately. Long enough to cover a quarter end and any review cycle you are subject to, short enough that you are not indefinitely storing the previous values of customer records for no stated reason.

The test

Pick a record the agent touched last month. Using only the log, answer four questions: what did it change, what was there before, why was the change allowed, and what else did the same run touch. If any answer requires opening the agent code or asking the person who built it, the log is incomplete.

We publish a working reference implementation of this, open source, at github.com/synauton/crm-write-guard, including the hash chaining. The broader design is in guardrails for AI agents that write to your CRM, and the work itself is AI Agents.