Agentic CRM
Use when: an autonomous agent reads or writes contacts, companies, deals, or activities in a CRM. This skill is a design pattern, not an implementation.
The one rule
The agent never invents a contact fact. Every write resolves to a real record first, and every resolved write stays traceable to its source.
Six invariants (do not ship without all six)
- Resolve before write. Match to an existing record by a stable key (record id, verified email, or exact phone) before updating. No match ⇒ create through one explicit create path, never by silent upsert.
- Provenance on every field. Each written value carries where it came from (user-stated, provider-verified, imported, inferred). Inferred values are marked as such and never sync outward.
- Consent gates outreach. Email/phone/mail fields are writable any time but usable for outreach only with a recorded opt-in, its timestamp, and its source. No opt-in ⇒ the channel stays closed.
- Dedup is a merge, not a delete. A suspected duplicate opens a merge review (surviving id, field-level winners, loser tombstoned). Merges are reversible for a fixed window.
- Least-privilege sync. The agent sees and writes only the objects its task needs. Credentials come from the operator-selected connection, never a shared key. Bulk export needs a separate approval.
- Append-only activity ledger. Every agent read of sensitive fields and every write appends who/what/when/source. The ledger is un-purgeable and queryable per record.
Minimal shape
interface CrmWrite { recordId?: string; fields: Record<string, unknown>; source: Source; actor: AgentId }
type Resolution = { kind: 'matched', id: string } | { kind: 'create' } | { kind: 'ambiguous', candidates: string[] }
Resolve → check consent (for outreach fields) → write with provenance → ledger append. ambiguous never auto-merges; it asks.
Anti-patterns
- ❌ Fuzzy auto-merge on name alone (two same-name contacts become one).
- ❌ Backfilling empty fields with model guesses that later sync as facts.
- ❌ One global API key for every agent and every task.
- ❌ Deleting duplicates instead of tombstoning them.