afv-library/skills/agentforce-development/references/agent-access-guide.md

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 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 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