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

CURRENT_STATUS: CURRENT
OBSERVATION: SPEC_ONLY
FRESHNESS: CURRENT
PAGE_TYPE: reference
CANONICAL_URL: /tools/ea-224-crm-api-agent
CLAIM_IDS: none
EVIDENCE_IDS: EA-224-CURRENT-APPROVAL, EA-224-CURRENT-BODY-READBACK
UNKNOWN_IDS: EA-224-UNKNOWN-01
OPS_IDS: none

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

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

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

## Confirmed

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

## Evidence
- EA-224-CURRENT-APPROVAL (RESEARCH): 現行本文の監査・revision対応
- EA-224-CURRENT-BODY-READBACK (IMPL): 現行本文の収録照合

## Failure / limits
重複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欠落を想定します。
## Failure / limits
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の実挙動を断定しません。
## 要点と前提
CRM APIをAI Agentから呼べることと、意図した業務更新が正しく一度だけ成立したことは別です。CRM書き込みでは、HTTP成功、部分成功、再試行、権限、管理者validation、rate limit、timeout、後続workflowやwebhookまでを分離して扱う必要があります。

## 主要claim
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します。

## 運用control
安全側の基本形は、(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と結果証拠を残します。

## failure envelope
重複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欠落を想定します。

## counterevidence / limitations
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の実挙動を断定しません。

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

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

NEXT: /agent/start.json
STOP: This is a knowledge projection, not an execution order.