mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-07-30 03:09:50 +08:00
73 lines
2.9 KiB
Markdown
73 lines
2.9 KiB
Markdown
# Agent Access Permissions & Visibility Troubleshooting
|
|
|
|
How to make a published agent visible to end users in the Lightning Experience Copilot panel.
|
|
|
|
---
|
|
|
|
## Agent Access Permissions
|
|
|
|
Employee Agents require explicit access via the `<agentAccesses>` element in Permission Sets. Without this, users won't see the agent in the Lightning Experience Copilot panel.
|
|
|
|
### Permission Set XML Structure
|
|
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
|
|
<agentAccesses>
|
|
<agentName>Case_Assist</agentName>
|
|
<enabled>true</enabled>
|
|
</agentAccesses>
|
|
<hasActivationRequired>false</hasActivationRequired>
|
|
<label>Case Assist Agent Access</label>
|
|
</PermissionSet>
|
|
```
|
|
|
|
### Key Points
|
|
|
|
- `<agentName>` must exactly match the `developer_name` in the agent's config block
|
|
- Multiple `<agentAccesses>` elements can be included for multiple agents
|
|
- `<enabled>true</enabled>` grants access; `false` or omission denies access
|
|
|
|
### Deploy and Assign
|
|
|
|
Deploy the permission set with `sf project deploy start --json --metadata "PermissionSet:<PermissionSetName>"`. Assign it to a specific user with `sf org assign permset --json --name <PermissionSetName> --on-behalf-of user@example.com`.
|
|
|
|
---
|
|
|
|
## Visibility Troubleshooting
|
|
|
|
When an Agentforce Employee Agent is deployed but not visible to users, work through these steps:
|
|
|
|
### Step 1: Verify Agent Status
|
|
|
|
Confirm the agent is active. Query `BotVersion` to check: `sf data query --json -q "SELECT Status, VersionNumber FROM BotVersion WHERE BotDefinition.DeveloperName = '<developer_name>'"`. At least one version should have `Status = 'Active'`. If none do, activate with `sf agent activate --json --api-name <developer_name>` before continuing.
|
|
|
|
### Step 2: Check for Agent Access Permission
|
|
|
|
Retrieve permission sets with `sf project retrieve start --json --metadata "PermissionSet:*"`. Search retrieved files for `<agentAccesses>` containing agent's `developer_name`. If none, create a new permission set.
|
|
|
|
### Step 3: Create Permission Set (if needed)
|
|
|
|
Create a file at `force-app/main/default/permissionsets/MyAgent_Access.permissionset-meta.xml`:
|
|
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
|
|
<agentAccesses>
|
|
<agentName>MyAgent</agentName>
|
|
<enabled>true</enabled>
|
|
</agentAccesses>
|
|
<hasActivationRequired>false</hasActivationRequired>
|
|
<label>MyAgent Access</label>
|
|
</PermissionSet>
|
|
```
|
|
|
|
### Common Issues
|
|
|
|
| Symptom | Cause | Solution |
|
|
|---------|-------|----------|
|
|
| No Agentforce icon | CopilotSalesforceUser PS not assigned | Assign CopilotSalesforceUser permission set |
|
|
| Icon visible, agent not in list | Missing agentAccesses | Add `<agentAccesses>` to permission set |
|
|
| Agent visible, errors on open | Agent not fully published | See Step 1: Verify Agent Status |
|
|
| "Agent not found" error | Name mismatch | Ensure `<agentName>` matches `developer_name` exactly |
|