Salesforce Agent Inventory: Agents, Users, Permissions

Most Salesforce orgs with Agentforce turned on cannot answer three questions quickly: how many agents exist, which user each one runs as, and what that user is allowed to read and change. Agents are spread across templates, Agent Builder, metadata deployments and packaged apps, and their effective access is the sum of a running user, its permission sets and whoever has been granted access to the agent. This runbook builds one inventory from the BotDefinition object, agent metadata, the agent users and their permission set assignments, the Agent Access grants in permission sets and the audit data. It covers read-only discovery first, then ownership, access reduction and deactivation with a rollback. It is for Salesforce administrators, platform security teams and architects. For how to harden each agent once you have found it, see the Securing Salesforce Agentforce Guide, which this page does not repeat.

Sources: Salesforce developer and Trailhead documentation as cited below, checked November 2026. Confirm against the official text before relying on it.

This is an independent guide from NHI Mgmt Group, based on Salesforce's public documentation as of November 2026. It is not sponsored or reviewed by Salesforce. Agentforce changes with each release, so confirm object fields, menu names and licensing against Salesforce's current documentation.

Key takeaways

BotDefinition is the agent list. Salesforce documents BotDefinition as the top-level object for Einstein Bots and Agentforce agents, it supports query(), and its BotUser relationship points to the running user.
The running user is the blast radius. Service agents act as their agent user, so its profile, permission sets and sharing define what any conversation can reach.
Employee agents are gated by permission sets. Access to an employee agent is granted in a permission set's Agent Access section, and the agent then acts with the logged-in user's own permissions.
Topics and actions live in metadata. From Winter '26 the GenAiPlannerBundle type holds each agent's topics and actions, which is where you find the flows, Apex and prompt templates an agent can call.
Deactivate before you delete. Deactivating an agent and removing permission set assignments are reversible; deleting an agent user's history or the agent itself removes evidence.

When you need this

Before go-live or a new template: templates such as the Engagement (SDR) agent create or select their own agent user record during setup, so each one adds an identity to review.
After a release or package install: new agents and agent users can arrive through metadata deployments and managed packages rather than through Setup.
For an audit or AI register request: NIST SP 800-53 CM-8 and NIST CSF 2.0 ID.AM-02 expect a maintained inventory of software and services, and AC-6 expects least privilege for the accounts they run as. The AI Register and AI Inventory Template gives the record this inventory feeds.
When a permission set has grown: a permission set added to make one action work and never removed is the usual way an agent user drifts. See Agent Permission Drift.

Where agents and their access show up

Source	What it shows	How to read it	Limit to know
BotDefinition object	Every Einstein Bot and Agentforce agent, its configuration type, agent type, template and running user	SOQL through the API or Salesforce CLI	Requires Agents to be enabled; confirm field names with describe
Bot and GenAiPlannerBundle metadata	Versions, the active version, topics, actions and attribute mappings	Metadata API retrieve	Bot retrieval is not supported for Lead Nurturing or Sales Coach agents
Agent users (Einstein Agent User profile)	The service identities agents run as	SOQL on User and PermissionSetAssignment	Only administrators can see or edit agent users in Setup
Permission sets: Apps > Agent Access	Which employee agents each permission set enables	Setup, per permission set	Effective reach is the assigned users' own permissions
Agentforce Agents setup page	Agents with status and the org-wide Agentforce toggle	Setup	A view, not an export; use the object query for the record
Einstein audit and usage data (Data 360)	Agent sessions and usage, joined on session ID	Data 360 objects such as `ssot__AiAgentSession__dlm`	Needs Data 360 and Audit and Feedback enabled

Agent types and the identity each uses

Configuration type	Typical agent	Identity used	Inventory question
`ExternalCopilot`	Agentforce Service Agent on web chat or messaging	The agent user; on authenticated Experience Cloud sites the logged-in user only when Credential-Based User Verification is on	What can the agent user read and change, and through which channels?
`InternalCopilot`	Agentforce Employee Agent	The logged-in employee	Which permission sets grant Agent Access, and to whom?
`Bot`	Classic Einstein Bot	Its bot user	Is it still in use, or a candidate for retirement?
Template agents (for example Engagement)	Sales and service templates	The agent user chosen during setup	Was a new user created, or an existing one reused?
Agents called through the Agent API	Any agent exposed to an external client app	The agent user or the token's user, depending on configuration	Which external client app holds the credentials, and who owns it?

Before you start

Access: run discovery with a user that has View Setup and Configuration and API access, and use Salesforce CLI for queries and retrieves. Keep Customize Application, Manage Users and Assign Permission Sets for the change steps in an approved group.
Sandbox first: run the queries in a full sandbox to check field names and volume, then in production.
Describe the object: Salesforce's object reference adds BotDefinition fields by API version (for example, the agent type field arrived in API version 62.0). Run sf sobject describe --sobject BotDefinition --target-org prod and use the field names your org returns.
Record format: agree fields first: agent name and developer name, configuration type, agent type, template, active version, running user, agent user status, permission sets and groups, high-risk permissions, objects with edit or delete, topics and actions, channels, external client apps, Agent Access grants, owner, sponsor, last session and decision.

Step-by-step

Steps 1 to 6 are read-only. Steps 7 and 8 change access but are reversible. Step 9 is destructive.

List every agent. Query BotDefinition with the running user joined. Adjust field names to your describe output:
```
sf data query --target-org prod --query "SELECT Id, DeveloperName, MasterLabel, Type, BotUserId, BotUser.Username, BotUser.IsActive FROM BotDefinition"
```
Add the agent type and template fields where your API version returns them. Group the results by configuration type: ExternalCopilot, InternalCopilot and Bot. Compare the count with the Agentforce Agents setup page.
List agent users and their history. Agent users created by the CLI use the Einstein Agent User profile and have no password. Find them and check that each maps to exactly one agent:
```
SELECT Id, Username, IsActive, CreatedDate, CreatedBy.Username, LastLoginDate FROM User WHERE Profile.Name = 'Einstein Agent User'
```
Any agent user that is not the BotUser of an agent is an orphan. Any agent whose running user has a different profile (for example a template agent that reused an existing user, or a classic bot) needs its own review, because that user may also be a person or an integration account. The connected apps and integration users runbook covers integration accounts.
Expand each running user's permissions. Pull permission set assignments, including those that come through permission set groups:
```
SELECT Assignee.Username, PermissionSet.Name, PermissionSet.IsOwnedByProfile, PermissionSetGroup.DeveloperName,
       PermissionSet.PermissionsModifyAllData, PermissionSet.PermissionsViewAllData, PermissionSet.PermissionsApiEnabled
FROM PermissionSetAssignment WHERE Assignee.Profile.Name = 'Einstein Agent User'
```
Repeat with AssigneeId filters for running users that have a different profile. Expect the three documented base sets, AgentforceServiceAgentBase, AgentforceServiceAgentUser and EinsteinGPTPromptTemplateUser, plus one agent-specific set. Then query ObjectPermissions for those permission set IDs and record every object with PermissionsEdit, PermissionsDelete, PermissionsViewAllRecords or PermissionsModifyAllRecords. Flag Modify All Data and View All Data as findings to remove. Note the running user's role, because a high role in the hierarchy widens record visibility without any permission set change.
Map who can use employee agents. For InternalCopilot agents, open each permission set that grants Apps > Agent Access and record the Enabled Agents list, then export its assignments with Manage Assignments. Salesforce notes that even administrators cannot use an agent without this access, so this list is the true user population of each employee agent. Because the agent acts as each of those users, the risk question is which assigned users hold broad permissions themselves.
Retrieve topics and actions. Pull agent metadata into a working folder:
```
sf project retrieve start --target-org prod --metadata Bot GenAiPlannerBundle GenAiPlugin GenAiFunction
```
For each agent record the active Bot version and, from its GenAiPlannerBundle, the topics (genAiPlugins) and standalone actions (genAiFunctions). Resolve each action to the flow, Apex class or prompt template it calls, and note any action that creates, updates or deletes records or sends email. Global and Asset Library topics and actions sit in GenAiPlugin and GenAiFunction, so check those too. For orgs still on Summer '25 metadata, topics and actions are in GenAiPlugin and GenAiFunction only.
Add channels, API access and usage. For service agents, record the deployment channels (Messaging for In-App and Web, Experience Cloud sites) and whether Credential-Based User Verification is on. For agents exposed through the Agent API, record the external client app, its OAuth scopes and its owner; the Salesforce External Client Apps guide covers those settings. Where Data 360 is licensed, turn on Audit and Feedback under Einstein Audit, Analytics, and Monitoring Setup and use the agent session data to record the last session per agent. Setup Audit Trail shows who created or changed agents, permission sets and agent users.
Reconcile and assign owners (reversible). Join the sources on BotDefinition ID, developer name and agent user ID. Classify each agent as approved, needs owner, needs review or retire. Record a business owner and a technical owner for each agent and its agent user, and see Agent Identity Recertification for the review cycle.
Reduce access (reversible). Remove permission set assignments that no action needs, split shared agent users so that each agent has its own, and remove high-risk system permissions. For employee agents, move agents out of Enabled Agents in permission sets that are too broadly assigned. For an agent you cannot justify, deactivate it in Agent Builder so that no channel serves it. Record the before state of every change so you can restore it, and hold for a full business cycle.
Retire (destructive). After the hold and owner sign-off, deactivate the agent user (do not delete it, so audit history keeps its name), remove its permission sets, revoke the external client app credentials and remove the agent's channel deployments. Delete the agent only when the retained configuration is no longer needed, and keep a metadata retrieve of it as the record.

Verify it worked

One user per agent: no agent user is the BotUser of more than one agent, and no active agent user is orphaned.
No high-risk permissions: the step 3 query returns no Modify All Data or View All Data for any running user.
Access matches purpose: every object with edit or delete for a running user maps to an action that needs it.
Retired agents are quiet: session data shows no new sessions for deactivated agents, and Setup Audit Trail shows the change with a ticket reference.

Rollback and common errors

Situation	Fix
An action fails after a permission set was removed	Reassign the recorded permission set, then replace it with a narrower set that grants only that object or field
A deactivated agent is needed	Reactivate it in Agent Builder; check that its agent user is still active
Users lost an employee agent	Restore the agent to Enabled Agents in the permission set, or assign a narrower permission set that grants it
Query returns an invalid field error	The field arrived in a later API version or has a different name; use the describe output
Agent missing from the Bot retrieve	Expected for Lead Nurturing and Sales Coach agents; record them from BotDefinition and Setup
Agent user cannot be found in Setup by a non-administrator	By design: only administrators see agent users

Common failure patterns

Counting agents, not identities: two agents sharing one agent user share every permission set; record the user, not just the agent.
Ignoring employee agent populations: a broadly assigned permission set with Agent Access puts an agent in front of every administrator and integration account it reaches.
Reading permission sets without sharing: role hierarchy and View All on an object widen access without any new permission set.
Missing packaged and deployed agents: agents arriving through metadata or packages bypass the setup flow; query BotDefinition after every release.
Deleting agent users: deactivate instead, so audit records and session data still resolve to a named identity.

Hardening afterwards

Schedule the queries: run steps 1 to 3 weekly and alert on any new BotDefinition, new agent user or new permission set assignment to an agent user.
Gate releases: require an inventory record and owner for any Bot or GenAiPlannerBundle change in your deployment pipeline.
Monitor activity: feed Setup Audit Trail and agent session data into detection. The Salesforce Event Monitoring Guide covers what to collect.
Treat agent users as non-human identities: owner, purpose, minimal permission sets and periodic review. See the AI Agent Authorisation Guide.

Small org or large enterprise

A small org with a handful of agents can run the queries and the Agent Access review quarterly and keep the inventory in a spreadsheet. A large enterprise with many orgs should script steps 1 to 5 with Salesforce CLI per org, load the results into its CMDB or AI register, and make the inventory record part of the release checklist for every agent change.

Metrics

Metric	Direction
Agents without a named owner	Zero
Agent users shared by more than one agent	Zero
Running users with Modify All Data or View All Data	Zero
Orphaned active agent users	Zero
Days from agent creation to inventory record	Under 7

Framework mapping

Framework	Reference	Relevance
NIST SP 800-53 Rev 5	CM-8 System Component Inventory; AC-2 Account Management; AC-6 Least Privilege	Agents as components; agent users as managed accounts with minimal permissions
NIST CSF 2.0	ID.AM-02; PR.AA-05; DE.CM-03	Software and service inventory; permission review; monitoring technology usage
CIS Controls v8.1	Control 5 Account Management; Control 6 Access Control Management	Service account inventory and least-privilege access for agent users
MITRE ATT&CK	T1078.004 Cloud Accounts	Over-privileged or orphaned agent users as valid accounts for abuse

Practitioner checklist

Describe BotDefinition and query every agent with its running user.
List Einstein Agent User accounts and match each to exactly one agent.
Expand permission sets, groups and object permissions for every running user.
Record which permission sets grant Agent Access to employee agents, and to whom.
Retrieve Bot and GenAiPlannerBundle metadata and resolve every action.
Record channels, verification settings and external client apps per agent.
Assign a business and technical owner to every agent and agent user.
Remove unused permission sets, deactivate before retiring, and keep a metadata record.
Schedule the queries and alert on new agents, agent users and assignments.

Salesforce Agent Inventory: Find every agent, running user and permission