> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesforce integration architecture

> How the Salesforce integration maps agent-facing tools to different Salesforce org models.

The Salesforce integration uses a hybrid model: stable agent-facing tools for common CRM and support work, plus generic Salesforce primitives for discovery and custom orgs.

Salesforce orgs model customers differently. A B2B org often uses `Account` and `Contact`. A B2C org can use Person Accounts. Enterprise orgs can add entitlements, assets, subscriptions, account hierarchies, record types, and custom objects.

The integration keeps those differences behind a Salesforce profile layer instead of exposing every org model directly to agents.

## Why Veryfront sits between agents and Salesforce

There are three useful ways to connect agents to Salesforce:

| Pattern                    | Best fit                                                                                                   | Limitation                                                                                                                          |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Direct Salesforce API      | Backend services, migrations, admin jobs, and custom applications that already know the Salesforce schema. | The caller must own OAuth, schema discovery, SOQL generation, permission errors, audit semantics, retries, and object-level policy. |
| Direct Salesforce MCP      | User-authorized assistant sessions that need dynamic Salesforce discovery and generic sObject access.      | Generic tools such as `query_soql` and `update_record` expose storage concepts instead of business capabilities.                    |
| Veryfront Salesforce tools | Production agents that need stable support and CRM capabilities across many Salesforce orgs.               | Requires an integration profile that maps business concepts to the customer's Salesforce objects and fields.                        |

Veryfront keeps Salesforce API access underneath the integration, then exposes a governed tool contract above it. Agents see customer, case, account, contact, lead, opportunity, and knowledge capabilities. The project config decides which tools are visible, which Salesforce objects are allowed, whether expert SOQL is available, and how the connected org maps to Veryfront concepts.

This gives teams the flexibility of Salesforce APIs without making raw Salesforce schema access the default agent interface.

## Agent-facing tools

Agents call tools named after work, not Salesforce storage details:

| Tool pattern                | Purpose                                                                          |
| --------------------------- | -------------------------------------------------------------------------------- |
| `find_customer`             | Resolve a customer identity from Salesforce records.                             |
| `list_cases`                | Find Service Cloud cases by customer, account, contact, owner, queue, or status. |
| `get_case`                  | Read the full case record for support triage.                                    |
| `list_case_activity`        | Read comments and timeline context for a case.                                   |
| `search_knowledge_articles` | Find published Knowledge content for support answers.                            |
| `add_case_comment`          | Add a controlled support note or customer-visible comment.                       |

These tools give agents a consistent vocabulary across projects. The agent asks for customer context, cases, or support notes. Veryfront translates that intent into the Salesforce objects and fields configured for the connected org.

## Generic Salesforce tools

The integration also exposes generic tools for expert and fallback paths:

| Tool              | Purpose                                                                     |
| ----------------- | --------------------------------------------------------------------------- |
| `describe_object` | Read Salesforce object metadata, fields, relationships, and permissions.    |
| `run_soql_query`  | Run a bounded read-only SOQL query for custom objects and advanced reports. |

Generic tools are necessary because no fixed product catalog can cover every Salesforce implementation. They let consultants and admins inspect the org, validate mappings, and handle custom objects without adding a new Veryfront tool for every Salesforce object.

The generic tools are intentionally not the primary production interface. Use them for discovery, validation, and consultant/admin workflows. Ordinary support agents should use curated tools such as `find_customer`, `list_cases`, and `add_case_comment`.

## Customer model

`customer` is a Veryfront semantic concept, not a native Salesforce object.

The default Service Cloud profile maps customer context to:

| Concept          | Default Salesforce source |
| ---------------- | ------------------------- |
| Customer account | `Account`                 |
| Customer person  | `Contact`                 |
| Support issue    | `Case`                    |
| Case timeline    | `CaseComment`             |
| Help content     | `KnowledgeArticleVersion` |

That default works for a common B2B Service Cloud demo and for many account-based support orgs. Production deployments need a validated profile when the org uses Person Accounts, custom customer objects, account hierarchies, entitlements, assets, subscriptions, or custom support objects.

## Project configuration

Salesforce project configuration is an optional governance layer.

When the project has no Salesforce `config`, or when `config` is `{}`, the integration keeps the default compatibility behavior. Existing projects keep working after connecting Salesforce.

When the project saves Salesforce `config`, Veryfront applies the saved governance fields. New Studio saves use the object-first shape; older `allowedSObjects`, `allowExpertSoql`, and `maxQueryRows` configs are still accepted during migration.

| Field                                                                          | Purpose                                                                                                                                 |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `dataAccess.objects`                                                           | Restricts Salesforce tools to selected object API names, such as `Account`, `Contact`, `Case`, `Customer__c`, or `ns__Subscription__c`. |
| `capabilities.allowExpertSoql`                                                 | Controls whether the raw SOQL expert path can be used after `run_soql_query` is also explicitly enabled.                                |
| `capabilities.maxQueryRows`                                                    | Sets the maximum allowed top-level SOQL `LIMIT` value.                                                                                  |
| `mappings.customer`, `mappings.contact`, `mappings.case`, `mappings.knowledge` | Records how this org maps Veryfront concepts to Salesforce objects, identity fields, display fields, and relationships.                 |

For the Service Cloud support demo, allow `Account`, `Contact`, `Case`, `CaseComment`, and `KnowledgeArticleVersion`, keep expert SOQL disabled, and set `capabilities.maxQueryRows` to `100`.

## Salesforce profile

A Salesforce profile defines how Veryfront maps semantic tools to one Salesforce org:

| Profile setting      | Meaning                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| `customer_model`     | `account_contact`, `person_account`, or `custom_object`.                                              |
| `customer_object`    | Object that represents the customer, such as `Account`, `PersonAccount`, or `Customer__c`.            |
| `contact_object`     | Object that represents people, usually `Contact`.                                                     |
| `case_object`        | Object that represents support work, usually `Case`.                                                  |
| `identity_fields`    | Fields used for lookup, such as `Contact.Email`, `Account.Name`, `Account.Website`, or external IDs.  |
| `case_relationships` | Relationships that connect cases to customers, such as `Case.AccountId` or `Case.ContactId`.          |
| `read_filters`       | Default filters, such as excluding closed cases or limiting Knowledge articles to published versions. |
| `write_policy`       | Allowed write actions, such as internal case comments only.                                           |

The current product stores these mappings and enforces object and tool policy. Metadata validation with Salesforce `describe_object` should be added before using advanced custom mappings in high-assurance production deployments, so invalid objects, missing fields, and inaccessible relationships become configuration errors instead of agent runtime surprises.

## Why this scales

The agent contract stays stable while the Salesforce mapping changes per org.

For example, `find_customer` can resolve different backend models:

| Org model                | Backend mapping                                                        |
| ------------------------ | ---------------------------------------------------------------------- |
| B2B Service Cloud        | `Account` plus related `Contact` and `Case` records.                   |
| B2C Service Cloud        | Person Account records plus related cases.                             |
| Enterprise Service Cloud | `Account`, `Contact`, `Entitlement`, `Asset`, and `Case`.              |
| Custom implementation    | `Customer__c`, custom relationship fields, and custom support objects. |

This separates agent behavior from Salesforce schema variance. Agents learn one stable set of tools. Admins and consultants adapt the Salesforce profile to the customer's org.

## Salesforce references

This architecture follows established Salesforce patterns rather than a single product-specific blueprint.

| Reference                                                                                                                            | How it applies                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| [Salesforce Customer 360 Data Model](https://developer.salesforce.com/docs/data/data-cloud-dmo-mapping/guide/c360dm-model-data.html) | Treats customer context as a harmonized model across objects, fields, metadata, and relationships.                        |
| [Salesforce REST `sObject Describe`](https://developer.salesforce.com/docs/platform/mobile-sdk/guide/ref-rest-apis-describe.html)    | Supports metadata-driven object and field discovery before a profile is accepted.                                         |
| [Salesforce Well-Architected Secure](https://architect.salesforce.com/docs/architect/well-architected/guide/secure.html)             | Supports least-privilege integration access and separate integration identities where service users are used.             |
| [Salesforce Integration Patterns](https://architect.salesforce.com/docs/architect/fundamentals/guide/integration-patterns.html)      | Supports authenticated API access over HTTPS and explicit integration design.                                             |
| [Salesforce Data Model Gallery](https://developer.salesforce.com/docs/platform/data-models/guide/get-started.html)                   | Keeps object and relationship design explicit when a Salesforce cloud or industry model uses specialized data structures. |

Veryfront uses these practices to keep the Salesforce integration portable. The profile records how a specific org models customer context, while Salesforce permissions and metadata decide what the connected user can actually read or write.

## Safety model

Read tools can use broad Salesforce metadata and query capability, but write tools stay narrow.

Veryfront treats Salesforce writes as explicit capability grants. A project can allow `add_case_comment` without allowing generic record creation, updates, or deletes. SOQL execution is read-only, bounded, and validated before execution.

This keeps support automation useful while preventing agents from receiving unrestricted Salesforce mutation access.

## Competitive gaps to close

The current architecture is strong for governed Service Cloud and CRM agents because the agent contract is stable, project-scoped, and configurable. To be stronger than a direct Salesforce MCP or API-only integration, the product should continue closing these gaps:

| Gap                        | Why it matters                                                                                                      | Target capability                                                                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Credential mode clarity    | Some deployments need per-user OAuth; others need a dedicated integration user or customer-managed app credentials. | Make the connection mode explicit in Studio and docs: per-user, project service account, or customer-managed dedicated deployment.                         |
| Field-level discovery      | Object allowlists are useful, but advanced mappings still need field validation.                                    | Let admins pick fields from Salesforce `describe_object` metadata, validate access before save, and show readable permission errors.                       |
| Profile validation         | A wrong object, relationship, or display field should fail during setup, not during an agent run.                   | Add a profile validation action that checks selected objects, fields, relationships, queryability, writeability, and row limits against the connected org. |
| Native MCP backend option  | Direct provider MCP can be useful for advanced admin sessions and broader object discovery.                         | Add provider MCP as an optional backend for expert/admin contexts while keeping Veryfront tools as the governed default.                                   |
| Audit and replay evidence  | Consultants and enterprise buyers need to see what an agent accessed and changed.                                   | Record tool, object, record ID, user, project, prompt/run context, and write intent for every Salesforce tool call.                                        |
| Approval policy for writes | Writes need different treatment from reads.                                                                         | Require explicit tool grants and optional human approval for `create_case`, `update_case`, `add_case_comment`, and future mutation tools.                  |
| Config portability         | Customer cloud deployments should not require hand-built Salesforce profiles.                                       | Export/import integration profiles and keep REST, GraphQL, MCP, and Studio config surfaces aligned.                                                        |

## Current status

The current Salesforce integration exposes Service Cloud and Sales Cloud tools plus metadata and SOQL fallback tools. Studio now lets admins configure object access, expert SOQL, row limits, and concept mappings without relying on a fixed preset list.

The remaining scalable production hardening path is to validate custom mappings with `describe_object`, generate agent instructions from the validated profile, and make connection mode, audit, and write approval behavior visible in the product.

## Related

* [Salesforce](/cloud/integrations/salesforce): Auth, scopes, credentials, and available tools.
* [Connect an integration](/cloud/integrations): Connect projects to external services.
* [Integrations and OAuth](/cloud/integrations-and-oauth): How integration auth models fit together.