Idempotent CRM Writes for AI Sales Agents

A model can classify a lead perfectly and still corrupt the operating system around it. The common failure is not exotic reasoning. It is an ordinary distributed-systems ambiguity: the CRM applied a write, the response disappeared, and the agent treated a timeout as permission to try again.

The fix belongs at the mutation boundary. Give each intended business effect a stable identity, elect one writer, preserve what was requested, and reconcile the retained CRM state before advancing the workflow.

The write boundary owns idempotency

Model output determinism does not make a CRM mutation safe to repeat. Temperature, seed and structured output can make a proposal easier to reproduce, but the external side effect still crosses a network and enters a system with its own concurrency, validation and field semantics.

Salesforce documents the canonical failure: an external system creates an opportunity, loses the response, retries, and creates duplicates. Its recommended simple pattern is a required unique remote identifier that lets the target reject the duplicate operation. Salesforce on idempotent operations.

For an AI sales agent, define idempotency at the business-effect level:

• One inbound source record may create or update one canonical CRM contact under one policy version.
• One qualification decision may assign one current owner or queue.
• One approved stage transition may be applied once.
• One human review item may be opened once and closed by an acknowledged decision.

The key cannot be a random request UUID minted on every retry. It must be stable for the business effect. A practical shape is:

sha256(source_system + source_record_id + policy_version + action_kind)

Changing the policy or action kind deliberately creates a new candidate mutation. Replaying the same source record under the same policy does not.

Reserve one mutation before calling the CRM

Use a database uniqueness constraint to elect the writer before the agent can call an external tool. PostgreSQL's ON CONFLICT clause can turn a unique-key collision into DO NOTHING; ON CONFLICT DO UPDATE provides an atomic insert-or-update outcome when no independent error occurs. PostgreSQL INSERT documentation.

The reservation record should retain enough intent to explain the write without asking the model to reconstruct it later:

create table crm_mutation (
  mutation_key text primary key,
  source_system text not null,
  source_record_id text not null,
  policy_version text not null,
  action_kind text not null,
  intended_state jsonb not null,
  status text not null check (
    status in ('reserved', 'submitted', 'observed', 'uncertain', 'divergent')
  ),
  provider_record_id text,
  acceptance_receipt jsonb,
  observed_state jsonb,
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

Reserve with one statement:

insert into crm_mutation (
  mutation_key,
  source_system,
  source_record_id,
  policy_version,
  action_kind,
  intended_state,
  status
) values ($1, $2, $3, $4, $5, $6, 'reserved')
on conflict (mutation_key) do nothing
returning mutation_key;

No returned row means another worker already owns or completed that effect. The losing worker reads the existing reservation and follows its status. It does not mint a new key.

This local reservation does not prove the CRM changed. It only prevents two application workers from independently deciding to perform the same mutation. The external call and read-back still need their own evidence.

Preserve three receipts

Keep intent, acceptance and authoritative state as separate records. Collapsing them into one success flag removes the evidence needed to recover safely.

Intent is the exact normalized state the workflow proposed: contact identifier, owner or queue, lifecycle field, reason, source evidence, policy version and mutation key.

Acceptance is what the CRM API returned: status, provider record ID, correlation ID, validation errors and response timestamp. A successful response proves that the provider accepted a request. It does not prove that every intended field became the durable state another operator will read.

State is a fresh read of the authoritative record and relevant associations after the write. Compare normalized business fields rather than entire provider payloads. Ignore volatile timestamps and unrelated enrichment fields, but never ignore owner, route, lifecycle, disqualification reason or the provider record identity.

This is a CRM-specific application of the broader tool receipt and outcome verification contract. The important split is not semantic. It controls whether the next operation is safe.

Read the CRM back before advancing

A write response is not the source of truth when the next workflow step depends on retained CRM state. Perform a targeted read using the provider record ID or stable external identifier, request only the authoritative fields, normalize them, and compare them with the intended state.

HubSpot's current contacts API supports create, update and batch upsert. Contacts can be retrieved by record ID or email, and reads can request current properties or property history. Upsert can use email or a custom unique identifier, with an important constraint: partial upserts are not supported when email is the identifier. HubSpot CRM contacts API.

Provider field semantics matter during reconciliation. HubSpot documents that lifecyclestage moves forward directly; moving it backward requires clearing the existing value first. A generic “set stage” tool that ignores that rule can return an error or produce a state different from the agent's proposal.

A provider adapter should expose a narrow contract:

type MutationResult =
  | { kind: "observed"; recordId: string; state: CanonicalLeadState }
  | { kind: "uncertain"; reason: string }
  | { kind: "divergent"; recordId: string; intended: CanonicalLeadState; observed: CanonicalLeadState };

async function applyAndReconcile(intent: MutationIntent): Promise<MutationResult> {
  const accepted = await crm.apply(intent);
  const recordId = accepted.recordId ?? intent.knownRecordId;

  if (!recordId) {
    return { kind: "uncertain", reason: "no canonical record identity" };
  }

  const observed = normalize(await crm.read(recordId, intent.authoritativeFields));

  if (equivalent(observed, intent.expectedState)) {
    return { kind: "observed", recordId, state: observed };
  }

  return {
    kind: "divergent",
    recordId,
    intended: intent.expectedState,
    observed
  };
}

In a real adapter, the apply call can throw or time out. Catching that exception should move the reservation to uncertain, not back to reserved and not directly into another provider call.

Stop on uncertain or divergent state

An uncertain mutation means the external effect may have happened but cannot yet be confirmed. A divergent mutation means the authoritative record exists and does not match the intended state. Both require reconciliation before replay, but they are different incidents.

For uncertain state:

1. Query by the provider record ID if one was returned.
2. Query by the stable external identifier if the provider supports it.
3. Inspect provider event or journal records when available.
4. Send the record to a named human review queue if the observation window expires.
5. Replay only after the operator or reconciler establishes that the effect is absent.

For divergent state, preserve both values and stop the next dependent action. A seller may have changed ownership while the agent was writing. A CRM workflow may have advanced the lifecycle stage. An enrichment job may have changed a field that the adapter mistakenly treated as authoritative. Blindly forcing the original proposal can overwrite legitimate work.

HubSpot's webhook journal exposes chronological event data for the past 3 days and advances through stored offsets. Its documentation recommends chronological processing, offset retention and exponential backoff for transient errors; snapshots reflect object state at request time. These are useful reconciliation aids, but a journal entry still needs to be compared with the canonical record and mutation intent. HubSpot webhooks journal.

Test ambiguity, not only the happy path

The release test should make the response unreliable while keeping the authoritative CRM observable. Five cases catch most unsafe retry designs:

1. Duplicate delivery before submit. Two workers receive the same source record. Exactly one reservation wins.
2. Timeout after apply. The CRM changes, but the adapter loses the response. The mutation becomes uncertain, read-back finds the effect, and no second create occurs.
3. Stale read. The first read does not yet expose the intended state. The reconciler waits within a bounded window, then sends unresolved work to review.
4. Conflicting human edit. A seller changes the owner between submit and read-back. The mutation becomes divergent and does not overwrite the seller.
5. Authorization failure. The CRM rejects the write. The acceptance error is retained, the canonical record stays unchanged, and the workflow does not claim an observed outcome.

Evaluate each case on four independent checks: one mutation key, one intended effect, complete evidence, and correct terminal classification. Then run the same cases against the real provider sandbox or test account because provider uniqueness, upsert and field-transition rules are part of the runtime.

The lead qualification cost and rollout worksheet uses accepted reconciled routes as its denominator for exactly this reason. An attempted call, accepted request or agent score is activity. The workflow earns an accepted route only when the business accepts the retained outcome.

The durable rule

The most important control is the read-back stop. Reservation prevents competing writers, but it cannot tell you whether a remote timeout hid a successful effect. API acceptance gives you a receipt, but it cannot tell you whether the authoritative fields match the business intent. Only observation closes the loop.

Build the sales agent so that ambiguity becomes a visible operating state with an owner. That one decision prevents a transient network failure from becoming a duplicate lead, an overwritten seller action or an invented success.