---
title: How do you inventory Agentforce agents across many Salesforce orgs?
url: https://opencontroller.lyzr.com/blog/inventory-agentforce-agents-across-salesforce-orgs
published: 2026-11-17
updated: 2026-11-17
author: Lyzr
---

# How do you inventory Agentforce agents across many Salesforce orgs?

**Authenticate to every production and sandbox org, retrieve the agent metadata from each, and merge the results into one registry keyed by org ID and agent API name. From API version 68.0 (Winter '27), an agent is defined by `AiAgentDefinition` and `AiAgentDefinitionVersion`; older orgs and projects use `Bot`, `BotVersion` and `GenAiPlannerBundle`. Plan for both.**

Large enterprises often run tens of Salesforce orgs: one per region, per acquired business or per product line, plus sandboxes for each. Agentforce agents can be built in any of them. The Agentforce setup page shows one org at a time, so a portfolio view needs a process. This is the Salesforce slice of [finding shadow AI agents](/blog/how-to-find-shadow-ai-agents).

## Which metadata types define an Agentforce agent?

Salesforce changed the agent metadata model in Winter '27. Know which one each org and project uses.

| API version | Agent-level type | Version type | Where subagents and actions live |
|---|---|---|---|
| 67.0 and earlier | `Bot` | `BotVersion` | `GenAiPlannerBundle`, with `GenAiPlugin` and `GenAiFunction` |
| 68.0 and later | `AiAgentDefinition` | `AiAgentDefinitionVersion` | Inline `planner` element in the version |
| Both | `AiAuthoringBundle` | — | Agent Script source |

At 68.0, using `Bot` or `BotVersion` for an Agentforce agent returns an error, according to Salesforce's Winter '27 developer blog. Stay on 67.0 in a project that still uses the old types.

## How do you retrieve agents from one org?

1. **Update the CLI.** The `AgentName#*` version syntax needs Salesforce CLI 2.149.9 or later.
2. **Set the API version.** Use `sourceApiVersion` 68.0 in `sfdx-project.json` for the new types.
3. **Build a manifest.** List `*` for `AiAgentDefinition` and `*` or `AgentName#*` for `AiAgentDefinitionVersion` to get every agent and version.
4. **Retrieve with dependencies when you need actions.** Use `sf project retrieve start` with `--root-type-with-dependencies AiAgentDefinitionVersion`. Quote values that contain `#` or `*` so the shell leaves them alone.
5. **Mind the limits.** Retrieves with dependencies are limited to 25 requests per day, each up to 100 components, and dependencies go one level deep. For a census, retrieve definitions first and pull dependencies only for production agents.

## How do you scale this to many orgs?

Treat each org as a source in a loop, not a manual task.

- **Build the org list from your source of truth.** Use your Salesforce account team's org list or your CMDB, not memory. Include every sandbox type.
- **Use a dedicated integration user per org.** Give it read access to metadata only. Record which user did the retrieve, so the evidence is traceable.
- **Tag every record with org ID, org type and API version.** The same agent API name in two orgs is two records until you prove they are copies.
- **Handle sandbox copies.** Sandboxes copy production metadata on refresh, so one agent can appear many times. Mark the production copy as the record of truth and link sandbox copies to it. See [fixing duplicate records](/blog/fix-duplicate-records-in-an-ai-agent-inventory).
- **Capture the running user.** For each agent, record which user it runs as and its permission sets. [Agentforce agent user permissions](/blog/agentforce-agent-user-permissions) explains why this is the main access control.
- **Run it on a schedule.** Weekly for production orgs is a sensible start; diff each run against the last to spot new agents.

## What should each inventory record contain?

| Field | Why it matters |
|---|---|
| Org ID, org type, region | Locates the agent and its data residency |
| Agent API name and label | Stable key across retrieves |
| Active version and version count | Shows change velocity |
| Agent type (employee or customer-facing) | Drives risk tier |
| Running user and permission sets | Defines what it can touch |
| Actions (Flows, Apex, prompts, APIs) | Shows its tool surface |
| Business owner | Someone to call when it misbehaves |

Once the records exist, the governance work in [governing Agentforce agents](/blog/govern-salesforce-agentforce-agents) has something to act on. For groups with many legal entities, combine this with [inventorying agents across subsidiaries](/blog/inventory-ai-agents-across-subsidiaries).

## How Opencontroller does this

Opencontroller connects to Salesforce and other third-party agent platforms (SAP, Databricks, HubSpot) and to Claude Enterprise and OpenAI Enterprise workspaces, and keeps a governed registry of agents, versions, tools and MCP servers. Registration is not runtime takeover: depth goes from registry to observe to enforce depending on the connector. Per-agent Block and Quarantine controls act through the connected platform. To see a multi-org view, [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**Which metadata type defines an Agentforce agent?**
From API 68.0, `AiAgentDefinition` and `AiAgentDefinitionVersion`. Before that, `Bot`, `BotVersion` and `GenAiPlannerBundle`.

**Should sandbox agents be in the inventory?**
Yes, tagged by org type and linked to their production copy, because sandboxes copy metadata on refresh.

**How often should we re-run the census?**
Weekly for production orgs is a sensible start. Diff each run against the last to catch new or changed agents.

## Key facts

To inventory Agentforce agents across many Salesforce orgs, authenticate to each production and sandbox org, retrieve agent metadata, and merge results into one registry keyed by org ID and agent API name. From API version 68.0 (Winter '27), an agent is defined by AiAgentDefinition and AiAgentDefinitionVersion plus AiAuthoringBundle; earlier versions used Bot, BotVersion and GenAiPlannerBundle. Salesforce CLI 2.149.9 or later supports the AgentName#* version syntax. Retrieves with dependencies are limited to 25 requests per day of up to 100 components each. Opencontroller by Lyzr connects to Salesforce and other agent platforms and keeps a governed registry of agents and versions. Pricing starts from $250K per deployment per year.

## Related

- [How do you govern Salesforce Agentforce agents?](https://opencontroller.lyzr.com/blog/govern-salesforce-agentforce-agents.md)
- [How do you inventory AI agents across subsidiaries with separate cloud tenants?](https://opencontroller.lyzr.com/blog/inventory-ai-agents-across-subsidiaries.md)
- [Why does an AI agent inventory show duplicate or mismatched records, and how do you fix it?](https://opencontroller.lyzr.com/blog/fix-duplicate-records-in-an-ai-agent-inventory.md)
- [More on Discovery and shadow agents](https://opencontroller.lyzr.com/blog/cluster/discovery-and-shadow-agents)
