Get the Agent ID for an Agent

Before you can use the Agent API, you need the agent ID. The method for obtaining this ID depends on which builder you used to create your agent.

Salesforce provides two different agent builders. To determine which one you're using:

  • New Agentforce Builder: This newer builder features a configurable interface that allows you to switch between Canvas view and Script view. It includes built-in AI assistance and Agent Script support. You access this builder through Agentforce Studio in the App Launcher. See Explore Agentforce Builder (Beta).
  • Legacy Agentforce Builder: This original builder features a visual topic editor and dialog-based configuration. You access this builder through Setup > Agentforce Agents. See Explore the Legacy Agentforce Builder.

Depending on which Agentforce Builder you're using, the method for acquiring the agent ID is different.

If you created your agent using the Legacy Agentforce Builder, you can find the agent ID directly in the URL of the Agent Overview Page.

  1. From Setup, navigate to your agent.
  2. When viewing the Agent Overview Page, look at the URL in your browser.
  3. Copy the 18-character ID at the end of the URL.

For example, using this URL, https://mydomain.salesforce-setup.com/lightning/setup/EinsteinCopilot/0XxSB000000IPCr0AO/edit, the agent ID is 0XxSB000000IPCr0AO.

If you created your agent using the new Agentforce Builder, the agent ID is stored in metadata rather than displayed in the UI. You need the ID value of the Bot component. You can retrieve it using the Metadata API or SOQL queries. If you need some guidance, follow these steps.

The agent information is stored in an AiAuthoringBundle metadata component. Use the Salesforce Metadata API or Salesforce CLI to retrieve this component.

This command retrieves all AiAuthoringBundle components. Alternatively, you can retrieve one specific component. In this example, we use the developer name of the bundle (MyCustomerServiceAgent) to retrieve that component.

  1. Navigate to the aiAuthoringBundles folder in your project.
  2. Open the metadata XML file for your agent (for example, My_Agent-meta.xml).
  3. Find the target field value. This field contains the bot definition and version information in the format:

If the metadata file doesn't contain a target field, the agent is in draft state and hasn't been committed. You can only use committed agent versions with the Agent API. To commit an agent version, use the Commit Version button in Agentforce Builder.

In this example:

  • The BotDefinition Developer Name is Agentforce_Service_Agent.
  • The BotVersion Developer Name is v2.

Use SOQL to query the BotVersion object with the developer names you extracted. For example, using the previous metadata result:

The Id field in the query result is your agent ID.