mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-11 18:38:22 +08:00
552 lines
24 KiB
Markdown
552 lines
24 KiB
Markdown
|
|
# Org Setup for ADL
|
|||
|
|
|
|||
|
|
Configure a fresh Salesforce org so it's ready for Agentforce Data Library (ADL) usage — all three source types (SFDRIVE, KNOWLEDGE, RETRIEVER).
|
|||
|
|
|
|||
|
|
## Overview
|
|||
|
|
|
|||
|
|
The ADLC `/agentforce-generate` skill assumes the org is already configured for ADL. A fresh org (even with correct licenses provisioned) still needs several setup steps before ADL can work. This skill automates those steps via SF CLI.
|
|||
|
|
|
|||
|
|
**What this skill sets up:**
|
|||
|
|
- Lightning Knowledge (required for KNOWLEDGE source type)
|
|||
|
|
- Data Cloud verification (required for all ADL source types)
|
|||
|
|
- CRM Connector validation (required for Knowledge article ingestion)
|
|||
|
|
- Sample Knowledge articles (optional, for testing)
|
|||
|
|
- Einstein Agent User permissions (Data Cloud permset + Knowledge FLS)
|
|||
|
|
- Language alignment verification (prevents silent empty results)
|
|||
|
|
|
|||
|
|
**After this skill completes**, you can run `/agentforce-generate` to create knowledge-grounded agents with any source type.
|
|||
|
|
|
|||
|
|
## Platform Notes
|
|||
|
|
|
|||
|
|
- Shell examples below use bash syntax. On Windows, use PowerShell equivalents or Git Bash.
|
|||
|
|
- Replace `python3` with `python` on Windows.
|
|||
|
|
- Replace `/tmp/` with `$env:TEMP\` (PowerShell) or `%TEMP%\` (cmd).
|
|||
|
|
|
|||
|
|
## Rules That Always Apply
|
|||
|
|
|
|||
|
|
1. **Always `--json`.** ALWAYS include `--json` on EVERY `sf` CLI command. Read the full JSON response directly.
|
|||
|
|
|
|||
|
|
2. **Verify target org.** Before any org interaction, run `sf config get target-org --json` to confirm a target org is set. If none configured, ask the user to set one with `sf config set target-org <alias> --global` (the `--global` flag is required when not inside an SFDX project directory).
|
|||
|
|
|
|||
|
|
3. **Stop on auth failure.** If org authentication fails, do NOT proceed. Ask the user to re-authenticate.
|
|||
|
|
|
|||
|
|
4. **Confirm destructive actions.** Before deploying metadata that changes org-wide settings (like enabling Lightning Knowledge), confirm with the user.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Prerequisites
|
|||
|
|
|
|||
|
|
Before starting, verify:
|
|||
|
|
|
|||
|
|
### 1. SF CLI is available
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf --version --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Minimum version: `@salesforce/cli 2.139.6`. If missing, offer install options but do NOT auto-install.
|
|||
|
|
|
|||
|
|
### 2. Org is authenticated
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf org display --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Set the target-org alias as a shell variable for all subsequent steps:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
TARGET_ORG="<org-alias>"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. Required licenses exist
|
|||
|
|
|
|||
|
|
Query for the add-on licenses needed:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT Name, Status, TotalLicenses FROM UserLicense WHERE Name LIKE '%Einstein%' OR Name LIKE '%Knowledge%' OR Name LIKE '%Agent%'"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Expected licenses/add-ons:
|
|||
|
|
|
|||
|
|
| License/AddOn | Purpose | Required For |
|
|||
|
|
|---|---|---|
|
|||
|
|
| `EinsteinGPTCopilotAddOn` | Agentforce / Agent platform | All ADL types |
|
|||
|
|
| `EinsteinGPTServiceAddOn` | BOTS VSaaS framework | All ADL types |
|
|||
|
|
| `GenieDataPlatformStarter` (AddOn) | Data Cloud — triggers DC provisioning | All ADL types |
|
|||
|
|
| `CDP Base User` (PSL) | Per-user Data Cloud access | Agent user runtime |
|
|||
|
|
| `EinsteinGPTPromptBuilderAddOn` | Einstein Prompt Templates — for Prompt Builder UI (optional for ADL) | Optional — only needed if using Prompt Builder directly |
|
|||
|
|
| `KnowledgeAddOn` | Knowledge feature | KNOWLEDGE source type only |
|
|||
|
|
|
|||
|
|
To verify Data Cloud is provisioned (not just licensed):
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT COUNT() FROM DataKnowledgeSpace"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
If this returns `INVALID_TYPE`, Data Cloud is not provisioned. Check Setup → Data Cloud Setup — if it says "get a Data Cloud license," the `GenieDataPlatformStarter` add-on is missing.
|
|||
|
|
|
|||
|
|
If licenses are missing, STOP and inform the user. These must be provisioned at the org level (SKU assignment, contract update, or trial enablement). No CLI command can add licenses.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Step 0 -- Enable Platform Features and Assign Admin Permissions
|
|||
|
|
|
|||
|
|
The org needs Einstein and Agentforce platform features turned on, and the admin user needs permission sets assigned BEFORE they can access Data Cloud or Agentforce.
|
|||
|
|
|
|||
|
|
**Temp directory for deploys:** Commands below use `/tmp/adl-setup/` as a temp workspace. On Windows, substitute with `%TEMP%\adl-setup\` (cmd) or `$env:TEMP/adl-setup` (PowerShell). The key requirement is that `sfdx-project.json` must exist in the same directory tree, and `sf project deploy start` must run from within that directory.
|
|||
|
|
|
|||
|
|
### 0a. Enable Einstein GPT Platform
|
|||
|
|
|
|||
|
|
Deploy the EinsteinGpt settings to turn on Einstein:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
mkdir -p /tmp/adl-setup/main/default/settings
|
|||
|
|
cat > /tmp/adl-setup/main/default/settings/EinsteinGpt.settings-meta.xml << 'EOF'
|
|||
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|||
|
|
<EinsteinGptSettings xmlns="http://soap.sforce.com/2006/04/metadata">
|
|||
|
|
<enableEinsteinGptPlatform>true</enableEinsteinGptPlatform>
|
|||
|
|
<enableEinsteinGptGlobalLangSupport>true</enableEinsteinGptGlobalLangSupport>
|
|||
|
|
</EinsteinGptSettings>
|
|||
|
|
EOF
|
|||
|
|
cat > /tmp/adl-setup/sfdx-project.json << 'EOF'
|
|||
|
|
{"packageDirectories":[{"path":"main/default","default":true}],"namespace":"","sourceApiVersion":"67.0"}
|
|||
|
|
EOF
|
|||
|
|
cd /tmp/adl-setup && sf project deploy start --source-dir main/default/settings/EinsteinGpt.settings-meta.xml --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**IMPORTANT:** `sf project deploy start` must run from within a directory that has `sfdx-project.json`. Always `cd` into the temp directory before deploying.
|
|||
|
|
|
|||
|
|
If this fails with "object does not exist," the org may not have the `EinsteinGPTCopilotAddOn` license. STOP and inform the user.
|
|||
|
|
|
|||
|
|
### 0b. Enable Agentforce (Einstein Copilot)
|
|||
|
|
|
|||
|
|
Deploy the EinsteinCopilot settings to turn on Agentforce:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cat > /tmp/adl-setup/main/default/settings/EinsteinCopilot.settings-meta.xml << 'EOF'
|
|||
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|||
|
|
<EinsteinCopilotSettings xmlns="http://soap.sforce.com/2006/04/metadata">
|
|||
|
|
<enableEinsteinGptCopilot>true</enableEinsteinGptCopilot>
|
|||
|
|
</EinsteinCopilotSettings>
|
|||
|
|
EOF
|
|||
|
|
cd /tmp/adl-setup && sf project deploy start --source-dir main/default/settings/EinsteinCopilot.settings-meta.xml --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
If this fails, the org may not have the Agentforce license (`EinsteinGPTCopilotAddOn`). STOP and inform the user.
|
|||
|
|
|
|||
|
|
### 0b2. Enable Agent Platform
|
|||
|
|
|
|||
|
|
ADL SFDRIVE creation requires the `AgentPlatformEnabled` org preference in addition to `EinsteinGPTPlatformEnabled`. Deploy the AgentPlatform settings:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cat > /tmp/adl-setup/main/default/settings/AgentPlatform.settings-meta.xml << 'EOF'
|
|||
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|||
|
|
<AgentPlatformSettings xmlns="http://soap.sforce.com/2006/04/metadata">
|
|||
|
|
<enableAgentPlatform>true</enableAgentPlatform>
|
|||
|
|
</AgentPlatformSettings>
|
|||
|
|
EOF
|
|||
|
|
cd /tmp/adl-setup && sf project deploy start --source-dir main/default/settings/AgentPlatform.settings-meta.xml --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Without this, `sf agent adl create --source-type sfdrive` returns: `"To create a File data library, enable Agentforce in your org. Required org preferences: EinsteinGPTPlatformEnabled, AgentPlatformEnabled."`
|
|||
|
|
|
|||
|
|
### 0c. Find required permission sets
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT Id, Name, Label FROM PermissionSet WHERE Name IN ('GenieAdmin', 'CopilotSalesforceAdmin') ORDER BY Name"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Note:
|
|||
|
|
- `GenieAdmin` has Label "Data Cloud Architect" in the UI (do NOT query by `Name = 'DataCloudArchitect'` — that doesn't exist)
|
|||
|
|
- `CopilotSalesforceAdmin` has Label "Agentforce Default Admin" in the UI
|
|||
|
|
|
|||
|
|
**Optional:** `PromptTemplateManager` / `PromptTemplatePermSet` is only needed for Prompt Builder UI access. It is NOT required for ADL knowledge grounding — preview, publish, and runtime all work without it.
|
|||
|
|
|
|||
|
|
### 0d. Get the current user ID
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf org display --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Extract `userId` from the response.
|
|||
|
|
|
|||
|
|
### 0e. Assign Data Cloud Architect
|
|||
|
|
|
|||
|
|
Required to view Data Cloud Setup pages, manage data streams, search indexes, and retrievers.
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data create record --sobject PermissionSetAssignment --target-org $TARGET_ORG --json \
|
|||
|
|
--values "AssigneeId='<adminUserId>' PermissionSetId='<DataCloudArchitectId>'"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 0f. (Optional) Assign Prompt Template Manager
|
|||
|
|
|
|||
|
|
Only needed if the admin wants to use Prompt Builder UI. NOT required for ADL knowledge grounding.
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Skip this step unless the user needs Prompt Builder access.
|
|||
|
|
# Requires EinsteinGPTPromptBuilderAddOn license on the org.
|
|||
|
|
sf data create record --sobject PermissionSetAssignment --target-org $TARGET_ORG --json \
|
|||
|
|
--values "AssigneeId='<adminUserId>' PermissionSetId='<PromptTemplateManagerId>'"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 0g. Assign CopilotSalesforceAdmin (Agentforce Default Admin)
|
|||
|
|
|
|||
|
|
Required to access Agentforce Studio, agent APIs, and author/publish agents. Without this, `sf agent preview` and `sf agent publish` return 503.
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data create record --sobject PermissionSetAssignment --target-org $TARGET_ORG --json \
|
|||
|
|
--values "AssigneeId='<adminUserId>' PermissionSetId='<CopilotSalesforceAdminId>'"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 0h. Verify assignments
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE AssigneeId = '<adminUserId>' AND PermissionSet.Name IN ('GenieAdmin', 'CopilotSalesforceAdmin')"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Both should appear in the results (plus `PromptTemplateManager` if 0f was run). If the org shows a "Data Cloud standard permission sets have changed" banner in Setup, acknowledge it — Salesforce periodically updates DC permset structures.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Step 1 -- Enable Knowledge User on Running User
|
|||
|
|
|
|||
|
|
The current authenticated user needs the Knowledge User permission before any Knowledge operations.
|
|||
|
|
|
|||
|
|
First, get the current user ID:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf org display --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Extract `userId` from the response. Then enable the Knowledge User permission:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data update record --sobject User --record-id <userId> --values "UserPermissionsKnowledgeUser=true" --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Verification:**
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT Id, Username, UserPermissionsKnowledgeUser FROM User WHERE Id = '<userId>'"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Confirm `UserPermissionsKnowledgeUser` is `true`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Step 2 -- Enable Lightning Knowledge via Metadata Deploy
|
|||
|
|
|
|||
|
|
Lightning Knowledge must be enabled org-wide. Deploy via KnowledgeSettings metadata.
|
|||
|
|
|
|||
|
|
### 2a. Create a temporary deployment directory
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
mkdir -p /tmp/knowledge-settings/main/default/settings
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2b. Write the KnowledgeSettings metadata file
|
|||
|
|
|
|||
|
|
Create `/tmp/knowledge-settings/main/default/settings/Knowledge.settings-meta.xml`:
|
|||
|
|
|
|||
|
|
```xml
|
|||
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|||
|
|
<KnowledgeSettings xmlns="http://soap.sforce.com/2006/04/metadata">
|
|||
|
|
<enableKnowledge>true</enableKnowledge>
|
|||
|
|
<enableLightningKnowledge>true</enableLightningKnowledge>
|
|||
|
|
</KnowledgeSettings>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2c. Write a minimal sfdx-project.json
|
|||
|
|
|
|||
|
|
Create `/tmp/knowledge-settings/sfdx-project.json`:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"packageDirectories": [
|
|||
|
|
{ "path": "main/default", "default": true }
|
|||
|
|
],
|
|||
|
|
"sourceApiVersion": "62.0"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2d. Deploy
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf project deploy start --source-dir /tmp/knowledge-settings/main/default/settings --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Important:** This is an org-wide settings change. If it fails with a permissions error, the user may need to enable Knowledge via Setup UI first (Setup > Knowledge Settings > Enable Knowledge).
|
|||
|
|
|
|||
|
|
### 2e. Verify
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf org open --target-org $TARGET_ORG --path "/lightning/setup/KnowledgeSettings/home" --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Or query for the Knowledge article object:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT QualifiedApiName FROM EntityDefinition WHERE QualifiedApiName = 'Knowledge__kav'"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
If the query returns a result, Lightning Knowledge is enabled.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Step 3 -- Verify CRM Connector is Active
|
|||
|
|
|
|||
|
|
The CRM Connector (Home org connection) is required for Knowledge article indexing. It auto-activates when Data Cloud provisioning completes — no manual step needed on fresh orgs.
|
|||
|
|
|
|||
|
|
Verify it's active:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf org open --target-org $TARGET_ORG --path "/lightning/setup/CdpSalesforceCrm/home" --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Check that the "Home" connection shows Status = `Active`.
|
|||
|
|
|
|||
|
|
**If not active (rare):** Navigate to Setup > Data Cloud > Salesforce CRM and click "Activate." This should only happen on sandbox orgs or orgs with non-standard DC provisioning.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Step 4 -- Create Sample Knowledge Articles (Optional)
|
|||
|
|
|
|||
|
|
Creating sample articles is recommended for testing ADL grounding. Skip this step if the user already has articles or passes `--skip-sample-articles`.
|
|||
|
|
|
|||
|
|
### 4a. Create articles
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data create record --sobject Knowledge__kav --values "Title='Getting Started with Our Product' UrlName='getting-started' Summary='This article covers the basics of setting up and using our product for the first time.'" --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data create record --sobject Knowledge__kav --values "Title='Troubleshooting Common Issues' UrlName='troubleshooting-common' Summary='Solutions for the most frequently reported problems including login failures, sync errors, and performance issues.'" --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data create record --sobject Knowledge__kav --values "Title='Account Management FAQ' UrlName='account-management-faq' Summary='Answers to common questions about creating accounts, managing users, resetting passwords, and billing.'" --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4b. Publish articles
|
|||
|
|
|
|||
|
|
Articles must be published to be indexed. Use the KnowledgeManagement API:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf apex run --target-org $TARGET_ORG --json -f /dev/stdin <<'EOF'
|
|||
|
|
List<Knowledge__kav> drafts = [SELECT Id, KnowledgeArticleId FROM Knowledge__kav WHERE PublishStatus = 'Draft'];
|
|||
|
|
for (Knowledge__kav article : drafts) {
|
|||
|
|
KbManagement.PublishingService.publishArticle(article.KnowledgeArticleId, true);
|
|||
|
|
}
|
|||
|
|
System.debug('Published ' + drafts.size() + ' articles.');
|
|||
|
|
EOF
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4c. Verify published articles
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT Id, Title, PublishStatus, Language FROM Knowledge__kav WHERE PublishStatus = 'Online'"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Step 5 -- Verify Data Cloud Provisioning
|
|||
|
|
|
|||
|
|
ADL requires Data Cloud. Verify it is provisioned and can see Knowledge data:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT COUNT() FROM DataKnowledgeSpace"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
If this returns a count > 0, Data Cloud recognizes the Knowledge data space.
|
|||
|
|
|
|||
|
|
If it fails or returns 0, Data Cloud may not be fully provisioned. Direct the user to:
|
|||
|
|
1. Setup > Data Cloud Setup
|
|||
|
|
2. Ensure provisioning is complete
|
|||
|
|
3. Wait for the CRM Connector sync to complete (can take 5-15 minutes after activation)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Step 6 -- Set Up Agent User Permissions (Runtime)
|
|||
|
|
|
|||
|
|
For the agent to retrieve Knowledge at runtime, the Einstein Agent User needs proper permissions.
|
|||
|
|
|
|||
|
|
### 6a. Find or Create the Einstein Agent User
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT Id, Username, Name FROM User WHERE Profile.Name = 'Einstein Agent User' LIMIT 1"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
If no agent user exists, **create one now** — it's needed for preview/testing, not just activation:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT Id FROM Profile WHERE Name = 'Einstein Agent User'"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data create record --sobject User --target-org $TARGET_ORG --json \
|
|||
|
|
--values "FirstName='Digital' LastName='Agent' Username='digitalagent.<orgId>@salesforce.com' Email='noreply@salesforce.com' Alias='dagent' ProfileId='<profileId>' TimeZoneSidKey='America/Los_Angeles' LocaleSidKey='en_US' LanguageLocaleKey='en_US' EmailEncodingKey='UTF-8'"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Replace `<orgId>` with the org's 18-character ID (from `sf org display`). The username must be globally unique.
|
|||
|
|
|
|||
|
|
**IMPORTANT:** `default_agent_user` is required in the `.agent` file even for "employee" agents when using `AnswerQuestionsWithKnowledge` with `--use-live-actions`. The platform treats any agent using the knowledge action as requiring an Einstein Agent User context at runtime.
|
|||
|
|
|
|||
|
|
### 6b. Assign required permission sets to agent user
|
|||
|
|
|
|||
|
|
The agent user needs THREE permsets for knowledge grounding to work at preview/runtime:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT Id, Name, Label FROM PermissionSet WHERE Name IN ('GenieUserEnhancedSecurity', 'AgentforceServiceAgentUser') ORDER BY Name"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Assign both:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Data Cloud access (retriever queries)
|
|||
|
|
sf data create record --sobject PermissionSetAssignment --values "AssigneeId='<agentUserId>' PermissionSetId='<GenieUserEnhancedSecurityId>'" --target-org $TARGET_ORG --json
|
|||
|
|
|
|||
|
|
# Agent runtime access (required for preview sessions)
|
|||
|
|
sf data create record --sobject PermissionSetAssignment --values "AssigneeId='<agentUserId>' PermissionSetId='<AgentforceServiceAgentUserId>'" --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Without `AgentforceServiceAgentUser`, preview returns "Unable to access the Salesforce Agent APIs" even when all other permissions are correct.
|
|||
|
|
|
|||
|
|
### 6c. Assign Knowledge FLS permission set
|
|||
|
|
|
|||
|
|
The agent user needs:
|
|||
|
|
- **`AllowViewKnowledge` user permission** — critical, without this Knowledge fields are inaccessible regardless of FLS grants
|
|||
|
|
- **Object-level Read** on `Knowledge__kav`
|
|||
|
|
- **Field-level Read** on ALL `contentFields` configured in the ADL (note: field permissions on Knowledge__kav may be silently stripped by the platform for Einstein Agent User license — the `AllowViewKnowledge` permission is what actually grants access)
|
|||
|
|
|
|||
|
|
Deploy a permission set that includes all of these:
|
|||
|
|
|
|||
|
|
Deploy the Knowledge access permission set:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
mkdir -p /tmp/adl-setup/main/default/permissionsets
|
|||
|
|
cat > /tmp/adl-setup/main/default/permissionsets/KnowledgeAgentAccess.permissionset-meta.xml << 'EOF'
|
|||
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|||
|
|
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
|
|||
|
|
<label>Knowledge Agent Access</label>
|
|||
|
|
<userPermissions>
|
|||
|
|
<enabled>true</enabled>
|
|||
|
|
<name>AllowViewKnowledge</name>
|
|||
|
|
</userPermissions>
|
|||
|
|
<objectPermissions>
|
|||
|
|
<allowRead>true</allowRead>
|
|||
|
|
<object>Knowledge__kav</object>
|
|||
|
|
<viewAllRecords>true</viewAllRecords>
|
|||
|
|
</objectPermissions>
|
|||
|
|
</PermissionSet>
|
|||
|
|
EOF
|
|||
|
|
cd /tmp/adl-setup && sf project deploy start --source-dir main/default/permissionsets --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Then assign to the agent user:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT Id FROM PermissionSet WHERE Name = 'KnowledgeAgentAccess'"
|
|||
|
|
sf data create record --sobject PermissionSetAssignment --target-org $TARGET_ORG --json \
|
|||
|
|
--values "AssigneeId='<agentUserId>' PermissionSetId='<KnowledgeAgentAccessId>'"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**CRITICAL:** The `AllowViewKnowledge` user permission is what actually grants Knowledge field access for the Einstein Agent User license. Raw field-level permissions get silently stripped by the platform for this license type. The `AllowViewKnowledge` + `viewAllRecords` combination grants access through a different mechanism that works.
|
|||
|
|
|
|||
|
|
### 6d. Verify language alignment
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT Id, LanguageLocaleKey FROM User WHERE Name = 'Einstein Agent User'"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data query --target-org $TARGET_ORG --json -q "SELECT Language, COUNT(Id) cnt FROM Knowledge__kav WHERE PublishStatus = 'Online' GROUP BY Language"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**CRITICAL -- Language Filter:** The retriever filters indexed chunks by language. The article `Language` field MUST match the agent user's language context. Even `en_US` vs `en_GB` causes a mismatch and returns zero results. Reference: W-21956266.
|
|||
|
|
|
|||
|
|
If there is a mismatch:
|
|||
|
|
- Update article language to match the agent user locale, OR
|
|||
|
|
- Update the agent user locale to match the articles
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sf data update record --sobject User --record-id <agentUserId> --values "LanguageLocaleKey='en_US'" --target-org $TARGET_ORG --json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Verification Checklist
|
|||
|
|
|
|||
|
|
After completing all steps, verify the full setup:
|
|||
|
|
|
|||
|
|
| Check | Command | Expected |
|
|||
|
|
|-------|---------|----------|
|
|||
|
|
| Knowledge User enabled | Query User.UserPermissionsKnowledgeUser | `true` |
|
|||
|
|
| Lightning Knowledge active | Query EntityDefinition for Knowledge__kav | Row returned |
|
|||
|
|
| CRM Connector active | Query DataSourceInstance WHERE Type='CRM' | Status = Active |
|
|||
|
|
| Published articles exist | Query Knowledge__kav WHERE PublishStatus='Online' | Count > 0 |
|
|||
|
|
| Data Cloud sees Knowledge | Query DataKnowledgeSpace | Count > 0 |
|
|||
|
|
| Agent user has permissions | Query PermissionSetAssignment for agent user | DC + Knowledge permsets assigned |
|
|||
|
|
| Language alignment | Compare User.LanguageLocaleKey vs article Language | Match |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Troubleshooting
|
|||
|
|
|
|||
|
|
### "Knowledge is not enabled in this org"
|
|||
|
|
|
|||
|
|
- Ensure Step 2 metadata deploy succeeded
|
|||
|
|
- Try enabling manually: Setup > Knowledge Settings > Enable Knowledge
|
|||
|
|
- Some org editions require a specific license SKU
|
|||
|
|
|
|||
|
|
### "INVALID_FIELD: UserPermissionsKnowledgeUser"
|
|||
|
|
|
|||
|
|
- The org may not have the Knowledge feature license provisioned
|
|||
|
|
- Check: `sf data query --target-org $TARGET_ORG --json -q "SELECT Id FROM UserLicense WHERE Name = 'Knowledge Only'"`
|
|||
|
|
|
|||
|
|
### Articles not appearing in ADL after indexing
|
|||
|
|
|
|||
|
|
- Verify articles are Published (not Draft)
|
|||
|
|
- Check language alignment (most common cause -- see Step 6d)
|
|||
|
|
- Verify CRM Connector sync completed
|
|||
|
|
- Wait 5-15 minutes after publishing for Data Cloud sync
|
|||
|
|
|
|||
|
|
### "Insufficient access" when agent retrieves Knowledge
|
|||
|
|
|
|||
|
|
- Verify object-level Read on Knowledge__kav (not just field-level)
|
|||
|
|
- Verify field-level Read on ALL configured contentFields
|
|||
|
|
- Check the GenieUserEnhancedSecurity permset is assigned to the agent user
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Known Issues and Notes
|
|||
|
|
|
|||
|
|
- **Language filter (W-21956266)**: Retriever filters chunks by language. Even minor locale variants (en_US vs en_GB) cause zero results. Always verify alignment.
|
|||
|
|
- **Knowledge FLS for Einstein Agent User**: Raw field-level permissions are silently stripped by the platform for the Einstein Agent license. The correct fix is `AllowViewKnowledge` user permission + `viewAllRecords: true` on Knowledge__kav. Do NOT attempt individual field grants.
|
|||
|
|
- **CRM Connector**: Auto-activates when Data Cloud provisioning completes. No manual step needed on fresh orgs. Only check manually if DC provisioning completed but Knowledge indexing fails.
|
|||
|
|
- **Intermittent DNS failures for api.salesforce.com**: The SF CLI's Node.js process (with @mswjs/interceptors) can intermittently fail DNS for `api.salesforce.com`. If `sf agent preview start` alternates between ENOTFOUND and 404 "Unable to access Agent APIs" — retry. The underlying DNS works (verifiable with `nslookup`), it's an MSW interception issue. Set `SF_DISABLE_MSW=1` if using a linked plugin.
|
|||
|
|
- **Data Cloud provisioning time**: First-time DC provisioning can take 30 min – 2 hours. The skill cannot speed this up.
|
|||
|
|
- **SFDRIVE doesn't need Knowledge**: Steps 1-4 (Knowledge enablement) are only required for KNOWLEDGE source type. SFDRIVE and RETRIEVER only need Data Cloud (Step 5) and agent user setup (Step 6).
|
|||
|
|
- **default_agent_user required for knowledge agents**: Even "employee" type agents require `default_agent_user` in the `.agent` file when using `AnswerQuestionsWithKnowledge` with live actions. The platform treats it as needing an Einstein Agent User context at runtime.
|
|||
|
|
- **Always specify contentFields explicitly**: When creating a KNOWLEDGE ADL, always pass `--content-fields "Summary,Answer__c"` (or your fields). If `contentFields` is empty, the retriever checks FLS on ALL Knowledge fields at query time — if even one non-required field is inaccessible, you get `INSUFFICIENT_ACCESS`.
|
|||
|
|
- **Agentforce Studio URL**: The correct path is `/lightning/setup/EinsteinCopilot/home` (not `/lightning/setup/CopilotStudio/home`).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Next Steps
|
|||
|
|
|
|||
|
|
Once setup is complete, use `/agentforce-generate` to create a knowledge-grounded agent:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
You: Create a knowledge-grounded agent from ~/docs/manual.pdf on org myOrg
|
|||
|
|
→ Skill routes to SFDRIVE, provisions ADL, wires into agent
|
|||
|
|
|
|||
|
|
You: Ground my agent on Knowledge articles on org myOrg
|
|||
|
|
→ Skill routes to KNOWLEDGE, creates library, indexes articles
|
|||
|
|
|
|||
|
|
You: Use custom retriever 1CxXXX on org myOrg
|
|||
|
|
→ Skill routes to RETRIEVER, wraps retriever, immediately ready
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
For all source types, the `/agentforce-generate` skill handles ADL creation, wiring, preview, and publish automatically — this setup skill just ensures the org is ready for it.
|