{
  "format": "agent-article-v0",
  "article_id": "EA-224",
  "canonical_url": "/tools/ea-224-crm-api-agent",
  "page_type": "reference",
  "claim_ids": [],
  "evidence_ids": [
    "EA-224-CURRENT-APPROVAL",
    "EA-224-CURRENT-BODY-READBACK"
  ],
  "unknown_ids": [
    "EA-224-UNKNOWN-01"
  ],
  "operational_object_ids": [],
  "provider": [],
  "models": [],
  "plans": [],
  "surfaces": [],
  "regions": [],
  "current_status": "CURRENT",
  "observation_status": "SPEC_ONLY",
  "freshness": "CURRENT",
  "last_verified": "2026-10-04",
  "supersedes": [],
  "superseded_by": [],
  "provenance": [
    "V7-EA224-FIRST-20261019-C1",
    "BODY-SHA256:e1cf95ad8e35c73467b4fd296d9cde3d38cabd015d93448b1e929521568b824f"
  ],
  "article_sources": [
    {
      "id": "EA-224-CURRENT-APPROVAL",
      "evidence_class": "RESEARCH",
      "title": "現行本文の監査・revision対応",
      "supports": [
        "現行台帳のAUDIT_PASSと候補・revision・本文ハッシュの対応を確認しています。"
      ],
      "limit": "監査状態と来歴の記録です。外部根拠の最新性や本文の全主張を追加保証しません。",
      "origin_class": "AUDITED_CANONICAL_RESEARCH_PACKET",
      "source_or_experiment_ids": [
        "V7-EA224-FIRST-20261019-C1"
      ],
      "supporting_locators": [
        "1KqhJtiSb2S84rWmeYVwKcT_76dBwZ_B0ZZuAWQqH0rQ/EA_REVISION_LEDGER#ea_id=EA-224&revision_id=EA-224-FIRST-20261004&candidate_id=V7-EA224-FIRST-20261019-C1",
        "EA-224-FIRST-20261004"
      ],
      "provenance_status": "CURRENT_CANONICAL_APPROVAL_READBACK"
    },
    {
      "id": "EA-224-CURRENT-BODY-READBACK",
      "evidence_class": "IMPL",
      "title": "現行本文の収録照合",
      "supports": [
        "公開生成入力の本文SHA-256が、監査済み候補に結び付いたハッシュと一致しています。"
      ],
      "limit": "本文の同一性の検査です。外部システムの挙動や全主張の真偽を実証したものではありません。",
      "checked_at": "2026-10-19",
      "origin_class": "IMPLEMENTATION_READBACK",
      "source_or_experiment_ids": [
        "BODY-SHA256:e1cf95ad8e35c73467b4fd296d9cde3d38cabd015d93448b1e929521568b824f"
      ],
      "supporting_locators": [
        "content/staging/EA-224.md",
        "e1cf95ad8e35c73467b4fd296d9cde3d38cabd015d93448b1e929521568b824f",
        "EA-224-FIRST-20261004"
      ],
      "provenance_status": "CURRENT_APPROVED_BODY_HASH_MATCH"
    }
  ],
  "research_sections": [
    {
      "heading": "要点と前提",
      "text": "CRM APIをAI Agentから呼べることと、意図した業務更新が正しく一度だけ成立したことは別です。CRM書き込みでは、HTTP成功、部分成功、再試行、権限、管理者validation、rate limit、timeout、後続workflowやwebhookまでを分離して扱う必要があります。"
    },
    {
      "heading": "主要claim",
      "text": "Salesforce CompositeではトップレベルHTTP 200でも個別subrequestが失敗し得ます。したがってAgentはトップレベルstatusだけで成功を宣言せず、個別結果・依存関係・失敗項目を検査する必要があります。`allOrNone=false` を許す処理では部分mutationが成立し得るため、複数record更新には明示的なatomicity方針とpost-write readbackが必要です。\n\nUpsertも自動的に安全ではありません。Salesforceのexternal ID upsertでは一致がなければ新規作成になり得るため、作成禁止の業務では `updateOnly` 等のguardを使い、identity keyと一意性を明示します。曖昧なtimeout後に非冪等createを再試行すると重複side effectを生む可能性があります。\n\nHubSpotでは2026-09 API version以降、管理者設定のvalidationやassociation permissionがCRM API writeへ影響します。公開API仕様は特定tenantでの成功を証明しません。Agentの実行前後でtenant固有の権限・validation・schemaを扱い、重要field/associationをreadbackします。"
    },
    {
      "heading": "運用control",
      "text": "安全側の基本形は、(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を成功へ丸めない、です。\n\nrate limitとtimeoutは性能問題だけではなくcorrectness問題です。429ではprovider指示に従うbackoffを行い、retry対象が冪等かを確認します。timeout-before-responseは「失敗」ではなく「結果不明」であり、readbackまたはprovider-supported idempotencyで解消するまで再実行を安易に重ねません。\n\n権限はleast privilegeを基本とし、可能ならread/write credentialを分離します。tokenやsecretをlogへ残さず、監査logには秘密情報ではなく操作identityと結果証拠を残します。"
    },
    {
      "heading": "failure envelope",
      "text": "重複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欠落を想定します。"
    },
    {
      "heading": "counterevidence / limitations",
      "text": "Salesforce Composite Graphや `allOrNone=true` は、対応範囲内でrollback semanticsを提供できます。したがってSalesforceの全compositionが部分commitになるわけではありません。ただし、そのatomicityを外部system、webhook、別toolのside effectへ一般化してはいけません。\n\nHubSpotの管理者validationはinvalid writeを減らせますが、Agent側のauthorization、intent validation、idempotency、readbackの代替ではありません。\n\nこの項目ではlive Salesforce/HubSpot tenantへのmutationを実施していません。customer固有schema、workflow、trigger、sharing rule、field-level security、custom validation、plan entitlement、sandbox挙動、downstream integrationは未検証です。provider docsから特定tenantの実挙動を断定しません。"
    },
    {
      "heading": "OPEN_UNKNOWN",
      "text": "各tenantのcustom automation・sharing/FLS・schema、利用SDK version、実rate-limit headers、timeout時の観測、webhook delivery、外部side-effect transaction境界、独立production incident evidenceは未確定です。"
    },
    {
      "heading": "SAFE_WORDING",
      "text": "「CRM APIをAgentから操作できること」と「業務上正しく一度だけ更新できたこと」は別です。成功判定はHTTP statusだけでなく、record identity、部分失敗、権限・tenant validation、rate limit/timeout、再試行の冪等性、重要field/associationのreadbackを含めて設計します。providerがtransactional primitiveを提供しても、その原子性を外部副作用や別systemへ拡張して解釈しません。"
    }
  ],
  "human_url": "/tools/ea-224-crm-api-agent",
  "markdown_url": "/agent/article.md?path=%2Ftools%2Fea-224-crm-api-agent",
  "json_url": "/agent/article.json?path=%2Ftools%2Fea-224-crm-api-agent"
}