CRM API × Agent — 書き込み成功を業務上の成功と誤認しない

CRM APIをAI Agentから呼べることと、意図した業務更新が正しく一度だけ成立したことは別です。CRM書き込みでは、HTTP成功、部分成功、再試行、権限、管理者validation、rate limit、timeout、後続workflowやwebhookまでを分離して扱う必要があります。

Salesforce CompositeではトップレベルHTTP 200でも個別subrequestが失敗し得ます。したがってAgentはトップレベルstatusだけで成功を宣言せず、個別結果・依存関係・失敗項目を検査する必要があります。allOrNone=false を許す処理では部分mutationが成立し得るため、複数record更新には明示的なatomicity方針とpost-write readbackが必要です。

Upsertも自動的に安全ではありません。Salesforceのexternal ID upsertでは一致がなければ新規作成になり得るため、作成禁止の業務では updateOnly 等のguardを使い、identity keyと一意性を明示します。曖昧なtimeout後に非冪等createを再試行すると重複side effectを生む可能性があります。

HubSpotでは2026-09 API version以降、管理者設定のvalidationやassociation permissionがCRM API writeへ影響します。公開API仕様は特定tenantでの成功を証明しません。Agentの実行前後でtenant固有の権限・validation・schemaを扱い、重要field/associationをreadbackします。

安全側の基本形は、(1) 対象identityを確定、(2) 現在stateとpreconditionを読む、(3) bounded mutationを構築、(4) providerのupsert/idempotent primitiveを意味が一致する場合だけ使う、(5) item-level結果を検査、(6) 重要field/associationをreadback、(7) correlation ID・actor/agent・requested intent・target key・precondition・response class・個別失敗・readbackを監査証拠として保存、(8) partial/unknownを成功へ丸めない、です。

rate limitとtimeoutは性能問題だけではなくcorrectness問題です。429ではprovider指示に従うbackoffを行い、retry対象が冪等かを確認します。timeout-before-responseは「失敗」ではなく「結果不明」であり、readbackまたはprovider-supported idempotencyで解消するまで再実行を安易に重ねません。

権限はleast privilegeを基本とし、可能ならread/write credentialを分離します。tokenやsecretをlogへ残さず、監査logには秘密情報ではなく操作identityと結果証拠を残します。

重複create、部分batch成功、トップレベル成功＋subrequest失敗、stale read-before-write、non-unique external ID、permission/validation rejection、rate limit、timeout、trigger/workflow side effect、association constraint、webhook lag/failure、schema/version drift、token refresh race、audit evidence欠落を想定します。

Salesforce Composite Graphや allOrNone=true は、対応範囲内でrollback semanticsを提供できます。したがってSalesforceの全compositionが部分commitになるわけではありません。ただし、そのatomicityを外部system、webhook、別toolのside effectへ一般化してはいけません。

HubSpotの管理者validationはinvalid writeを減らせますが、Agent側のauthorization、intent validation、idempotency、readbackの代替ではありません。

この項目ではlive Salesforce/HubSpot tenantへのmutationを実施していません。customer固有schema、workflow、trigger、sharing rule、field-level security、custom validation、plan entitlement、sandbox挙動、downstream integrationは未検証です。provider docsから特定tenantの実挙動を断定しません。

各tenantのcustom automation・sharing/FLS・schema、利用SDK version、実rate-limit headers、timeout時の観測、webhook delivery、外部side-effect transaction境界、独立production incident evidenceは未確定です。

「CRM APIをAgentから操作できること」と「業務上正しく一度だけ更新できたこと」は別です。成功判定はHTTP statusだけでなく、record identity、部分失敗、権限・tenant validation、rate limit/timeout、再試行の冪等性、重要field/associationのreadbackを含めて設計します。providerがtransactional primitiveを提供しても、その原子性を外部副作用や別systemへ拡張して解釈しません。