Salesforce Agentforce

Salesforce Agentforce + Data Cloud + Messaging-for-Web Playbook

A practical, product-agnostic playbook for building and operating an Agentforce solution on any org, in any industry (commerce, financial services, healthcare, B2B, etc.). The guidance and gotchas are general; concrete examples are drawn from real builds but the patterns apply to any domain — substitute your own objects (an Order example maps equally to a Claim, Application, Policy, or Work Order). Follow the DX-first ordering below; only fall to the browser/UI when there is genuinely no API/metadata/CLI path.

The #0 rule: Official-first — research the supported Salesforce way; never Frankenstein a custom workaround

Before building ANYTHING, find the official, supported Salesforce mechanism for the requirement and use it. Research it actively — official Salesforce docs (help.salesforce.com, developer.salesforce.com), the context7 MCP for product docs, and web search — based on the actual requirement, not from memory or assumption. Standard objects and native product features almost always already cover the need.

Do NOT hand-roll a custom object + Apex to mimic a capability the platform already provides — not to satisfy a design quickly, not to stay "headless," not to dodge a setup/UI step, not because it's faster to write. That is a Frankenstein solution: it demos fine but duplicates a platform feature, bloats storage, drifts from the product's roadmap, reimplements (badly) something Salesforce already does correctly, and becomes permanent tech debt the next person must untangle.

Real anti-example from this playbook's own history: a custom Web_Event__c object + Apex IdentityStitchService was built to do device→person identity stitching and store browsing — when the official answer is the Data Cloud Web SDK + native Identity Resolution (deviceId/anonymousId match rules). The custom version "worked," but it mirrored high-volume web events into a 5 MB CRM org (repeated storage outages) and re-implemented identity resolution by hand. The right move was to research and use the native Data Cloud capability from the start.

Decision rule for every requirement:

1. Ask "What is the official Salesforce product / feature / standard object / declarative tool for this?" — then research to confirm; do not guess.
2. Use it in this order: standard object/native feature → declarative (Flow) → thin Apex glue invoked by Flow → custom object/Apex (last, only with a stated reason no official path exists).
3. If the official path needs a UI/Setup step (Identity Resolution match rules, a Data Cloud connector, an Einstein Studio model), do the UI step. Correct-and-supported beats convenient-and-custom. Never substitute a custom Apex hack just to avoid the official setup.
4. Show the research: when choosing custom, name the official options ruled out and why; when choosing official, name the feature.

"Do it right" = the supported way, even when it's more work or needs a tool you don't currently have — not the fastest custom thing that satisfies the demo. See crm-vs-datacloud-architecture.md and standard-objects-and-declarative-first.md.

The #1 rule: DX/CLI/API first, UI last

Preference order for every task:

1. Salesforce DX / sf CLI — sf project deploy/retrieve, sf data, sf apex run, sf agent.
2. Connect/REST API via CLI — sf api request rest "/services/data/vXX.0/..." (uses the stored session; works even when the raw access token is hidden).
3. Metadata XML deploy — author the component, deploy it.
4. Apex / REST for anything procedural.
5. Browser/UI automation — last resort, and say so first. A handful of things are genuinely UI-only (listed in troubleshooting.md): creating CRM data streams, attaching a User-Verification keyset to a MIAW deployment, setting the Person-Account default record type on a profile.

> In a sandboxed agent environment, sf org display REDACTS the access token. Do NOT try to scrape it. Instead use sf api request rest / sf data / sf apex run, which all reuse the CLI's stored session under the hood.

What's in this skill

• discovery-intake.md — ⭐ STEP 1, before designing anything. The discovery interview: what to ask the user (industry, process, start points, data sources, identity, outputs) + research the industry yourself + confirm the concrete inputs (API names, URLs, screenshots, source of truth). You can't design an agent for a business you haven't interviewed. Produces the discovery brief that feeds the design step.
• standard-objects-and-declarative-first.md — ⭐ Cross-cutting rule for STEPS 1–3. Research Salesforce STANDARD objects before inventing custom ones, prefer FLOWS/declarative over Apex, and DX/CLI over UI. Includes a standard-object map by domain (Account/Contact/Lead, Order/OrderItem/OrderSummary, FulfillmentOrder, ReturnOrder, Shipment, CreditMemo, Case/Entitlement, Individual/ContactPoint, MessagingSession/ConversationEntry…) and the Flow-vs-Apex cheat-sheet.
• solution-design-process-outcomes.md — ⭐ STEP 2 (after discovery), before authoring. The design discipline: capability map → process/outcome matrix → per-process decision tree → coverage rule. This is how you stop an agent from hallucinating success (claiming a refund/case happened when no action ran). An agent without these four artifacts WILL BS.
• deploy-cicd.md — DX project layout, deploy/retrieve commands, the profile+recordType deploy trick, sf apex run/sf data query/sf api request rest, and post-deploy smoke scripts.
• agentforce-agents.md — Agent Script authoring bundles, the sf agent lifecycle, employee vs Service Agent rules, custom Apex actions, and headless invocation via AgentInvoker (generateAiAgentResponse).
• crm-vs-datacloud-architecture.md — ⭐ STEP 0 architecture decision: what lives in CRM vs Data Cloud, and what the agent reads vs writes. CRM = transactional system of record (records you act on); Data Cloud = analytical/unification layer beside it (360, high-volume events, identity resolution, insights, activation) — not transactional. The anti-pattern (mirroring a whole external system into CRM → storage exhaustion + brittle Apex single-key matching + stale 360), the Data-Cloud-forward target shape (streaming ingest → identity resolution → unified profile → Data-Cloud-Triggered-Flow writeback to a thin CRM record → agent reads 360 / writes transactional actions to the system of record or external API), the zero-copy-vs-ingest-vs-copy ladder, and the Agentforce rules (profile quality first, Data Graphs for known retrievals, read-from-Data-Cloud/write-to-SoR). Researched + sourced.
• data-cloud.md — DLO/DMO metadata types, ObjectSourceTargetMap field maps, Calculated Insight SQL rules (currency!), the Connect REST endpoints for Identity Resolution / CI / query, and the empty-identity-key gotcha that silently produces 0 unified profiles.
• data-cloud-ingestion-actions-grounding.md — ⭐ the rest of Data Cloud: ingestion (CRM / Ingestion API streaming-vs-bulk / cloud-storage / MuleSoft + refresh modes), segmentation (batch vs real-time), Data Actions (event-driven Data Cloud → Platform Event / Webhook / Marketing Cloud via the change-data feed), Data Graphs (materialized denormalized 360 views for fast retrieval + structured grounding), agent grounding (Data-Graph structured grounding + RAG: unstructured → chunk → vector index → Data Library retriever, and when to use it vs typed actions), and the predictive-tool map (Prediction Builder vs Einstein Studio / BYOM) + Data Spaces. Official mechanisms (research-sourced), complementing the battle-tested data-cloud.md.
• predictive-and-engagement.md — ⭐ Einstein Studio Model Builder (the 7-step UI flow), predict jobs (streaming vs batch, the Run action, output-DMO schema, write-back PK join + the ConnectApi-JOIN-returns-0 gotcha), web-engagement capture (Web SDK connector vs custom Apex REST route, self-healing identity stitch, the JS identify hook (appIdentify)), the 5 MB Developer-Edition storage trap (transient rows, emptyRecycleBin 200-cap, recalc lag, silent STORAGE_LIMIT_EXCEEDED on a 200 response), MktCalcInsightObjectDef silent-deploy-fail (build CIs in the UI), and the DLO→DMO mapping modal's 60–120 s load (not hung).
• messaging-web.md — MIAW WebV2 deployment, EmbeddedServiceConfig + MessagingChannel + Omni-Channel routing flow, JWT user verification (RS256/JWKS/kid), pre-chat hidden fields, and a live SCRT-API conversation test.
• email-and-notifications.md — ⭐ how an agent/Apex actually gets a message to a person: transactional vs marketing routing, the setTargetObjectId daily-cap exemption (the real fix for "Email limit exceeded" — sending to a Lead/Contact/User record doesn't count against the cap, only setToAddresses does), OWEA/DMARC deliverability, consent-gating in one shared send service, async-callout (Queueable) when DML precedes the send, and the anti-pattern of bolting a non-Salesforce relay onto the org.
• consent-and-marketing-activation.md — ⭐ enterprise consent + send architecture. The separation of concerns (Agentforce decides · Data Cloud unifies+enforces consent+segments · Marketing Cloud sends); ingesting consent from many source apps into Data Cloud's standard Consent data model (Engagement Channel / Communication Subscription / Authorization Form consent) keyed to the unified Individual; reconciling to ONE effective consent (latest-wins/opt-out-sticky via a CI); enforcing consent at the activation, not in app code; the Agentforce→Data-Cloud-segment→Marketing-Cloud bridge (the agent nominates, never sends); Marketing Cloud Connect / Activation / Journey connectors; MCE vs Growth vs Pardot; and how a no-Marketing-Cloud build maps onto it.
• agent-orchestration-and-memory.md — ⭐ multi-subagent + multi-agent design: orchestrator→subagent routing as a 3-layer topology, identity/eligibility gating as a no-tool structural subagent (the guardrail that actually holds), the shared context envelope (displayable summary + hidden JSON, one mandatory first action), three identity tiers + OTP opaque-proof step-up, linked vs mutable anti-spoofing invariant, the anti-hallucination instruction grammar, confirm-before-mutate + bounded-autonomy-in-code, named-entity substitution guard, deterministic-engine-narrates, cross-agent durable memory (journey object + append-only log + idempotent "done sets" + race-safe upsert), passing the transcript into actions, off-topic/injection fixtures, and the compiled-planner topology.
• flex-credit-efficient-design.md — ⭐ design agents for fewer Flex Credits. The meter is driven by exposed actions (Apex/Flow/Knowledge/retrieval/record-update/summary ≈20 credits, voice ≈30), NOT topics or routing. The one rule: consolidated action chains, never action-over-action — each use case = ONE exposed action that chains the logic in Apex/Flow. One unified context action fetched once per session and cached in a VARIABLE (never re-query a custom object per turn). Data Cloud prepares (pre-materialized onto CRM) → Apex packages → Agentforce explains. Topics over A2A unless real reuse. Always validate actual metering in Digital Wallet. Also covers the MANDATORY conversation abuse/loop protection every agent must ship with (no native repeat-detector/turn-cap/cooldown exists): an always-on instruction guard that never re-runs an action to repeat an answer and exits the loop after ~3 repeats, why it must be an instruction not a per-turn guard action, why a server-side trigger end-on-flood is NOT viable on native MIAW (ConversationEntry not triggerable; MessagingSession count only final at end), and the limited edge options on MIAW (CAPTCHA/pre-chat + inactivity timeout; full per-message rate-limiting needs a custom front-end).
• integration-and-fulfillment.md — ⭐ the integration/ops layer: HMAC-verified inbound webhook ingestion via your own @RestResource (MAC over raw body, case-insensitive headers, ping handling), Named Credential + External Credential outbound (and the principal-grant runtime gotcha), secrets via protected __mdt, idempotent two-way sync without loops (upsert-by-external-id, reconcile-don't-skip, per-field ownership, consent monotonicity), the single-writer status source-of-truth ladder (rank/promote/terminal/evidence-gated/feature-tolerant SOQL), capture-now/sweep-later event synthesis, transactional/destructive action conventions (callouts-before-DML, 3-part guard, traceability trail, fail-closed external dep), and least-privilege security config (guest profile = Apex-only, service-agent permset, CORS/CSP/Site hardening).
• page-layouts-fields-related-lists.md — ⭐ making fields/related lists actually visible (DX): the 4 gates (exists → FLS permset → placed → rendered), the Dynamic Forms trap (page layout is ignored for fields — check flexipage:fieldSection before editing layouts; add fields to the FlexiPage with the exact RecordField identifier + uiBehavior or you get the misleading "field isn't allowed in the region" error), related-list names (ChildObject.LookupField from childRelationships) + the column-token rules (custom = API names + NAME; standard children reject NAME, use legacy CASES.STATUS tokens or their __c fields), section organization, and standard-object tabs via permission-set tabSettings (no CustomTab). Always --dry-run first.
• multi-turn-agent-testing.md — ⭐ MANDATORY certification method for EVERY agent. No agent is "tested" until all use cases pass as multi-turn conversations, run ≥10× to 100%. Single-turn sf agent test run passes while production breaks (proven: single-turn 100% green, multi-turn ~1-in-3 FAIL on the same flow). Covers: documenting every use case as a matrix (turns × verification state × expected topic/action/PASS-rubric), turning each into a dripped multi-turn conversation, and the exact sf agent test run-eval JSON harness (create_session + a send_message per turn + evaluator.* steps), with all the gotchas (agentid/versionid required, valid evaluator tags, non-determinism → repeat runs). Also: delete rubrics that endorse insecure behavior.
• scorers-intent-and-observability.md — ⭐ how to SCORE, OBSERVE, and prove an agent's real behavior. The two things both called "scorer" (offline AiEvaluationDefinition you fully control vs live AiAgentScorerDefinition/Quality-Score that's mostly standard + often a DE create-dead-end); the 3 eval expectation types → result metric labels (topic_sequence_match→topicassertion, action_sequence_match→actionsassertion, bot_response_rating→output_validation = the rubric IS the LLM-judge prompt, read metricExplainability for its reasoning); mandatory calibration (first run looks low — fix the EXPECTED values to the agent's correct behavior, not the agent); a catalog of what a custom scorer looks like per use case (identity-gate, action-OUTCOME-happened/anti-"please hold", unanswerable→escalate, brand-scope, reco-quality, confirm-before-mutate, jailbreak-no-mutation, eligibility/pricing); running scorers on historical sessions via triggerAgentBulkScoring (Flow/REST/Apex); intent tags (Optimization → Sessions & Intents — auto-mined weekly, READ-ONLY, NOT_SET = untagged) and the full observability stack; and the AI-eval storage hog with the confirmed reality that there's no programmatic purge (Testing Center UI / Support only) so prevention (don't over-run evals; use the AgentInvoker harness that writes zero eval records) is the answer.
• deterministic-grounding-and-hardening.md — ⭐ **how to make an agent behave deterministically (anti-halluci

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: alexkwitko
• Source: alexkwitko/Salesforce-Agentforce
• License: MIT

Install and usage instructions live in the source repository linked above.