---
title: Agentforce connector
description: "Reference for the Agentforce connector: discover Salesforce Agentforce agents, subagents, identity bindings, and permission set assignments"
component: openicf
page_id: openicf:connector-reference:agentforce
canonical_url: https://docs.pingidentity.com/openicf/connector-reference/agentforce.html
llms_txt: https://docs.pingidentity.com/openicf/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
section_ids:
  salesforce_requirements: Salesforce requirements
  install_the_agentforce_connector: Install the Agentforce connector
  configure-agentforce-connector: Configure the Agentforce connector
  using_the_platform_admin_ui: Using the Platform admin UI
  using_the_legacy_admin_ui: Using the legacy admin UI
  connection_details: Connection details
  example_agentforce_configuration: Example Agentforce configuration
  test_the_agentforce_connector: Test the Agentforce connector
  agentforce_remote_connector: Agentforce remote connector
  config-connection-pooling-agentforce: Configure connection pooling
  implementation_specifics: Implementation specifics
  agentforce-discovery-model: Discovery model
  agentforce-search-filters: Supported search filters
  known_limitations: Known limitations
  use_the_agentforce_connector: Use the Agentforce connector
  agentforce-agents: __ACCOUNT__
  agentforce-subagents: agentSubagent
  agentforce-identity-bindings: agentIdentityBinding
  agentforce-permission-sets: agentPermissionSet
  troubleshooting: Troubleshooting
  connector_initializes_but_test_fails: Connector initializes but test fails
  agents_reconcile_but_expected_agents_are_missing: Agents reconcile but expected agents are missing
  agentsubagent_agentidentitybinding_or_agentpermissionset_is_empty_for_an_agent: agentSubagent, agentIdentityBinding, or agentPermissionSet is empty for an agent
  implemented-interfaces-org-forgerock-openicf-connectors-agentforce-AgentforceConnector-1.5.20.39: OpenICF Interfaces Implemented by the Agentforce Connector
  config-properties-org-forgerock-openicf-connectors-agentforce-AgentforceConnector-1.5.20.39: Agentforce Connector Configuration
  basic-configuration-properties-org-forgerock-openicf-connectors-agentforce-AgentforceConnector-1.5.20.39: Basic Configuration Properties
---

# Agentforce connector

[SaaS common](preface.html#saas-common)

Salesforce Agentforce is Salesforce's platform for building and running autonomous AI agents. The Agentforce connector is a read-only connector that discovers Agentforce agents, including Copilot and Bot agents, and governance-relevant objects including subagents, identity bindings, and permission set assignments.

## Salesforce requirements

Before you configure the connector, you need a Salesforce org with Agentforce enabled and an External Client App configured for the OAuth 2.0 client credentials flow:

1. In Setup, create an External Client App (or use an existing one) and enable OAuth settings for it.

2. Add the Manage user data via APIs (api) OAuth scope, plus any additional scope your org requires.

3. Enable the client credentials flow for the app, and select a run-as user. The run-as user must have API access and the View Setup and Configuration system permission, which requires View Roles and Role Hierarchy. No object-level permissions are required. For example, a user with the Salesforce Integration license and the Minimum Access - API Only Integrations profile, plus a permission set that grants only those two system permissions, can read every object the connector queries: `BotDefinition`, `BotVersion`, `GenAiPlannerDefinition`, `GenAiPlannerFunctionDef`, `GenAiPluginDefinition`, `GenAiPluginFunctionDef`, `GenAiFunctionDefinition`, and `PermissionSetAssignment`.

4. Save the app, then make a note of the following values:

   * Consumer Key (`clientId`)

   * Consumer Secret (`clientSecret`)

   * Your Salesforce instance URL (`serviceUri`), for example `https://your-org.my.salesforce.com`

   * The OAuth token endpoint (`tokenEndpoint`), which is your instance URL followed by `/services/oauth2/token`, for example `https://your-org.my.salesforce.com/services/oauth2/token`

Use these values when you [configure the connector](#configure-agentforce-connector).

## Install the Agentforce connector

|   |                                                                                                                                                                                                                                                                                                 |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | To check for an Advanced Identity Cloud application for this connector, refer to:- [Application management](https://docs.pingidentity.com/pingoneaic/latest/app-management/applications.html)

- [App catalog](https://docs.pingidentity.com/pingoneaic/latest/app-management/app-catalog.html) |

You can download most connectors from [Ping Identity Product Downloads](https://product-downloads.pingidentity.com/browse/idm/featured/connectors), but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

**Connector included in default deployment**

| Connector                     | IDM                     | RCS                     |
| ----------------------------- | ----------------------- | ----------------------- |
| [Agentforce](agentforce.html) | [icon: times, set=fa]No | [icon: times, set=fa]No |

Download the connector .jar file from [Ping Identity Product Downloads](https://product-downloads.pingidentity.com/browse/idm/featured/connectors).

* If you're running the connector locally, place it in the `/path/to/openidm/connectors` directory, for example:

  ```
  mv ~/Downloads/agentforce-connector-1.5.20.39.jar /path/to/openidm/connectors/
  ```

* If you're using a remote connector server (RCS), place it in the `/path/to/openicf/connectors` directory on the RCS.

## Configure the Agentforce connector

To create a connector configuration using a UI, use the Platform admin UI or the legacy admin UI (deprecated). Learn more about [creating connector configuration](configure-connector.html#connector-wiz-REST).

### Using the Platform admin UI

1. From the sidebar, click [icon: settings_ethernet, set=material, size=inline] Provisioners.

2. On the Provisioners page, click [icon: plus, set=fas]New Provisioner.

3. In the New Provisioner modal, enter a Name.

4. From the Connector Type list, select Agentforce Connector - 1.5.20.39.

   The UI displays a code editor field with the default provisioner configuration for the Agentforce connector.

5. Make changes to the provisioner configuration, and click Save.

   |   |                                                                                                                            |
   | - | -------------------------------------------------------------------------------------------------------------------------- |
   |   | For a list of all configuration properties, refer to [Agentforce Connector Configuration](#agentforce-config-prop-ezLink). |

When your connector is configured correctly, the connection status on the provisioner page displays as Connected.

### Using the legacy admin UI

1. From the navigation bar, click Configure > Connectors.

2. On the Connectors page, click New Connector.

3. On the New Connector page, type a Connector Name.

4. From the Connector Type list, select Agentforce Connector - 1.5.20.39.

5. Complete the Base Connector Details and any applicable Additional Options.

   |   |                                                                                                                            |
   | - | -------------------------------------------------------------------------------------------------------------------------- |
   |   | For a list of all configuration properties, refer to [Agentforce Connector Configuration](#agentforce-config-prop-ezLink). |

6. Click Save.

When your connector is configured correctly, the connector displays as Active in the legacy admin UI.

### Connection details

The Agentforce connector uses the following configuration properties, in addition to the properties it inherits from [SaaS common](preface.html#saas-common):

| Property                 | Description                                                                                                                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceUri`             | The Salesforce instance URL, for example `https://your-org.my.salesforce.com`. Required.                                                                                                                 |
| `tokenEndpoint`          | The OAuth token endpoint for the instance, for example `https://your-org.my.salesforce.com/services/oauth2/token`. Required.                                                                             |
| `clientId`               | The External Client App consumer key. Required.                                                                                                                                                          |
| `clientSecret`           | The External Client App consumer secret. Required.                                                                                                                                                       |
| `authenticationMethod`   | Must be `OAUTH`. This is the only authentication method the connector supports. Defaults to `OAUTH`.                                                                                                     |
| `grantType`              | Must be `client_credentials`. This is the only grant type the connector supports. Defaults to `client_credentials`.                                                                                      |
| `apiVersion`             | The Salesforce REST/Tooling API version to target, for example `62.0`. Defaults to `62.0`.                                                                                                               |
| `includeInternalCopilot` | When `true`, a sweep includes agents where `BotDefinition.Type=InternalCopilot`. Defaults to `true`.                                                                                                     |
| `includeExternalCopilot` | When `true`, a sweep includes agents where `BotDefinition.Type=ExternalCopilot`. Defaults to `true`.                                                                                                     |
| `includeBot`             | When `true`, a sweep includes agents where `BotDefinition.Type=Bot`. `subagentIds` is empty when no matching `GenAiPlannerDefinition` is found, which is expected for classic Bots. Defaults to `false`. |

If all three `include*` properties are `false`, sweeps of `__ACCOUNT__`, `agentIdentityBinding`, `agentPermissionSet`, and agent-scoped `agentSubagent` searches return no results. An unscoped `agentSubagent` search and `GET`-by-UID aren't affected. Refer to [Discovery model](#agentforce-discovery-model).

### Example Agentforce configuration

This excerpt shows a sample Agentforce connector configuration:

```json
{
    "connectorRef" : {
        "displayName" : "org.forgerock.openicf.connectors.agentforce.AgentforceConnector",
        "bundleVersion" : "[1.5.0.0,1.6.0.0)",
        "systemType" : "provisioner.openicf",
        "bundleName" : "org.forgerock.openicf.connectors.agentforce-connector",
        "connectorName" : "org.forgerock.openicf.connectors.agentforce.AgentforceConnector",
        "connectorHostRef" : ""
    },
    "configurationProperties" : {
        "serviceUri" : "https://your-org.my.salesforce.com",
        "tokenEndpoint" : "https://your-org.my.salesforce.com/services/oauth2/token",
        "clientId" : null,
        "clientSecret" : null,
        "authenticationMethod" : "OAUTH",
        "grantType" : "client_credentials",
        "apiVersion" : "62.0",
        "includeInternalCopilot" : true,
        "includeExternalCopilot" : true,
        "includeBot" : false
    },
    "enabled" : true
}
```

### Test the Agentforce connector

Test that the configuration is correct by running the following command:

```
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/agentforce?_action=test"
{
  "name": "agentforce",
  "enabled": true,
  "config": "config/provisioner.openicf/agentforce",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.agentforce-connector",
    "connectorName": "org.forgerock.openicf.connectors.agentforce.AgentforceConnector"
  },
  "displayName": "Agentforce Connector",
  "objectTypes": [
    "__ACCOUNT__",
    "agentSubagent",
    "agentIdentityBinding",
    "agentPermissionSet",
    "__ALL__"
  ],
  "ok": true
}
```

If the command returns `"ok": true`, your connector has been configured correctly and can authenticate to the Salesforce org.

|   |                                                                                                                                                     |
| - | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | `TestOp` issues a lightweight query (`SELECT Id FROM BotDefinition LIMIT 1`) and reports success only if Salesforce returns an HTTP `200` response. |

### Agentforce remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Agentforce connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

Refer to [Remote connectors](remote-connector.html) for configuring the Agentforce remote connector.

### Configure connection pooling

The Agentforce connector supports [HTTP pooling](pooling.html#http-pooling), which can substantially improve the performance of the connector. Learn more about the basic connection pooling configuration and different pooling mechanisms described in [Connection pooling configuration](pooling.html).

## Implementation specifics

### Discovery model

Every search except an unscoped `agentSubagent` search is resolved from a shared sweep of `BotDefinition` rows:

* The sweep is gated by `includeInternalCopilot`, `includeExternalCopilot`, and `includeBot`. If all three are `false`, the sweep returns no rows for any object class.

* For each `BotDefinition` row, the connector resolves the agent's active `BotVersion`, then its planner (`GenAiPlannerDefinition`, matched by the naming convention `<DeveloperName>_v<VersionNumber>`), then the planner's subagents (`GenAiPluginDefinition`, joined through `GenAiPlannerFunctionDef`).

* A `BotDefinition` row with no active `BotVersion`, or no matching `GenAiPlannerDefinition` (expected for classic `Bot` agents), is still emitted, with `activeVersionNumber`, `plannerId`, and `plannerType` set to null and `subagentIds` empty. This is a warn-and-continue behavior, not an error.

* `status` is derived, not a raw Salesforce field: it's `Active` when the agent has an active `BotVersion`, and `Inactive` otherwise.

An unscoped `agentSubagent` search bypasses this sweep with a direct scan of `GenAiPluginDefinition`. Because of this:

* It returns every subagent that exists, regardless of whether any agent currently references it.

* It isn't filtered by `includeInternalCopilot`, `includeExternalCopilot`, or `includeBot`, because those properties only scope the per-agent traversal, not the flat scan.

* Every returned subagent has `agentId` set to null, since a flat scan can't resolve which agent's planner it belongs to.

A search scoped to a single agent with an `agentId eq` filter resolves that one `BotDefinition` row and its child data directly, without the flat-scan behavior described above. The `include*` properties still apply: if the agent's type is disabled, the search returns no results.

A `GET`-by-UID doesn't use the sweep, and isn't filtered by `includeInternalCopilot`, `includeExternalCopilot`, or `includeBot`. Changing those properties never makes a known record report as not found. Each object class resolves a `GET`-by-UID as follows:

* `__ACCOUNT__`: Looks up the `BotDefinition` row by Id and resolves its planner and subagents, returning the same attributes as a sweep.

* `agentSubagent`: Reads the `GenAiPluginDefinition` record directly, together with its actions. `agentId` is always null, for the same reason as in an unscoped search.

* `agentIdentityBinding`: Looks up the `BotDefinition` whose `BotUserId` matches the UID, so `agentId` is populated.

* `agentPermissionSet`: Looks up the `PermissionSetAssignment` by Id and resolves `agentId` from the assignee. `agentId` is null if the assignee isn't an agent's run-as user.

### Supported search filters

The connector translates ICF filters directly to SOQL and throws an exception rather than silently returning unfiltered results for anything it can't translate.

| Object class           | Filterable attributes                                                                                                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `__ACCOUNT__`          | `agentId` (`eq` only; scopes the sweep to a single agent), `developerName`/`masterLabel` (`eq`, `co`, `sw`), `createdDate`/`lastModifiedDate` (`eq`, `gt`, `ge`, `lt`, `le`) |
| `agentSubagent`        | `developerName`/`masterLabel`/`description` (`eq`, `co`, `sw`). `agentId eq` is accepted, but can't be combined with the other attributes.                                   |
| `agentIdentityBinding` | `agentId` (`eq` only)                                                                                                                                                        |
| `agentPermissionSet`   | `permissionSetName` (`eq`, `co`, `sw`). `agentId eq` is accepted, but can't be combined with `permissionSetName`.                                                            |

`and`/`or` composition of two translatable sub-filters is supported. `not`, `containsAllValues`, and `endsWith` filters aren't supported and throw `UnsupportedOperationException`.

|   |                                                                                                                                                                                                                                                                                                                              |
| - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | `agentId eq` can be combined with another attribute (using `and`/`or`) only on `__ACCOUNT__`. `agentIdentityBinding` has no other filterable attribute. On `agentSubagent` and `agentPermissionSet`, the other filterable attributes live on a different underlying table than `agentId`, so combining them isn't supported. |

### Known limitations

* The connector discovers only `BotDefinition` rows of type `InternalCopilot`, `ExternalCopilot`, and `Bot`. Agents of any other type, such as `AgentforceOrchestrator`, aren't returned, and no `include*` property controls them.

* `subagentIds` is empty when no matching `GenAiPlannerDefinition` is found. This is expected for classic `Bot` agents.

* `InternalCopilot` agents have no run-as user (`botUserId` is null), so they never emit an `agentIdentityBinding` or `agentPermissionSet` object.

* An unscoped `agentPermissionSet` search that resolves to more than one agent returns only the first batch of `PermissionSetAssignment` rows for each agent, with no `pagedResultsCookie`, so any remaining rows aren't returned. To retrieve every assignment for an agent, scope the search with `agentId eq`, which paginates correctly.

## Use the Agentforce connector

The Agentforce connector discovers the following resource types:

| ICF Native Type        | Salesforce Resource Type               | Naming Attribute | Notes                                                                                                                                                                                                                                             |
| ---------------------- | -------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `__ACCOUNT__`          | `BotDefinition`                        | `__NAME__`       | Represents one Agentforce agent (Copilot or Bot). UID is the `BotDefinition` Id. A sweep returns only the agent types enabled by `includeInternalCopilot`/`includeExternalCopilot`/`includeBot`. `GET`-by-UID isn't filtered by these properties. |
| `agentSubagent`        | `GenAiPluginDefinition`                | `__NAME__`       | Represents a subagent attached to an agent's active planner. See [Discovery model](#agentforce-discovery-model) for unscoped-search behavior.                                                                                                     |
| `agentIdentityBinding` | Derived from `BotDefinition.BotUserId` | `__NAME__`       | Not a native Salesforce object. Represents the agent's run-as User. `InternalCopilot` agents have no run-as user and emit no binding.                                                                                                             |
| `agentPermissionSet`   | `PermissionSetAssignment`              | `__NAME__`       | Represents a PermissionSet assignment on the agent's run-as User.                                                                                                                                                                                 |

### `__ACCOUNT__`

> **Collapse: Query a single Agentforce agent**
>
> ```
> curl \
> --header "X-OpenIDM-Username: openidm-admin" \
> --header "X-OpenIDM-Password: openidm-admin" \
> --header "Content-Type: application/json" \
> --request GET \
> "http://localhost:8080/openidm/system/agentforce/__ACCOUNT__/0Xx000000000001"
> {
>   "_id": "0Xx000000000001",
>   "__NAME__": "AgentDev",
>   "agentId": "0Xx000000000001",
>   "developerName": "AgentDev",
>   "masterLabel": "Agent Dev",
>   "agentType": "ExternalCopilot",
>   "agentBuilderType": "EinsteinServiceAgent",
>   "botUserId": "0050000000000001",
>   "activeVersionNumber": "3",
>   "status": "Active",
>   "plannerId": "0jw000000000001",
>   "plannerType": "Einstein",
>   "createdById": "0050000000000099",
>   "createdDate": "2026-01-01T00:00:00.000+0000",
>   "lastModifiedDate": "2026-01-02T00:00:00.000+0000",
>   "lastModifiedById": "0050000000000098",
>   "systemModstamp": "2026-01-03T00:00:00.000+0000",
>   "subagentIds": [
>     "0hL000000000001",
>     "0hL000000000002"
>   ]
> }
> ```

> **Collapse: Query all Agentforce agents**
>
> ```
> curl \
> --header "X-OpenIDM-Username: openidm-admin" \
> --header "X-OpenIDM-Password: openidm-admin" \
> --header "Content-Type: application/json" \
> --request GET \
> "http://localhost:8080/openidm/system/agentforce/__ACCOUNT__?_queryFilter=true"
> {
>   "result": [
>     {
>       "_id": "0Xx000000000001",
>       "__NAME__": "AgentDev",
>       "agentId": "0Xx000000000001",
>       "developerName": "AgentDev",
>       "masterLabel": "Agent Dev",
>       "agentType": "ExternalCopilot",
>       "agentBuilderType": "EinsteinServiceAgent",
>       "botUserId": "0050000000000001",
>       "activeVersionNumber": "3",
>       "status": "Active",
>       "plannerId": "0jw000000000001",
>       "plannerType": "Einstein",
>       "createdById": "0050000000000099",
>       "createdDate": "2026-01-01T00:00:00.000+0000",
>       "lastModifiedDate": "2026-01-02T00:00:00.000+0000",
>       "lastModifiedById": "0050000000000098",
>       "systemModstamp": "2026-01-03T00:00:00.000+0000",
>       "subagentIds": [
>         "0hL000000000001",
>         "0hL000000000002"
>       ]
>     }
>   ],
>   "resultCount": 1,
>   "pagedResultsCookie": null,
>   "totalPagedResultsPolicy": "NONE",
>   "totalPagedResults": -1,
>   "remainingPagedResults": -1
> }
> ```

**\_\_ACCOUNT\_\_ attributes**

| Attribute             | Type   | Multivalued | Description                                                                                                  |
| --------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------ |
| `agentId`             | String | No          | The `BotDefinition` Id.                                                                                      |
| `developerName`       | String | No          | The `BotDefinition.DeveloperName`.                                                                           |
| `masterLabel`         | String | No          | The `BotDefinition.MasterLabel`.                                                                             |
| `agentType`           | String | No          | The `BotDefinition.Type` picklist value: `InternalCopilot`, `ExternalCopilot`, or `Bot`.                     |
| `agentBuilderType`    | String | No          | The `BotDefinition.AgentType` field, for example `EinsteinServiceAgent`.                                     |
| `botUserId`           | String | No          | The agent's run-as User Id. Null for `InternalCopilot` agents.                                               |
| `activeVersionNumber` | String | No          | The `VersionNumber` of the agent's active `BotVersion`, or null if none.                                     |
| `status`              | String | No          | `Active` if the agent has an active `BotVersion`, otherwise `Inactive`. Derived, not a raw Salesforce field. |
| `plannerId`           | String | No          | The resolved `GenAiPlannerDefinition` Id, or null if none.                                                   |
| `plannerType`         | String | No          | The resolved `GenAiPlannerDefinition.PlannerType`, or null if none.                                          |
| `createdById`         | String | No          | The `BotDefinition.CreatedById`.                                                                             |
| `createdDate`         | String | No          | The `BotDefinition.CreatedDate`.                                                                             |
| `lastModifiedDate`    | String | No          | The `BotDefinition.LastModifiedDate`.                                                                        |
| `lastModifiedById`    | String | No          | The `BotDefinition.LastModifiedById`.                                                                        |
| `systemModstamp`      | String | No          | The `BotDefinition.SystemModstamp`.                                                                          |
| `subagentIds`         | String | Yes         | The Ids of the agent's resolved subagents (`agentSubagent` objects).                                         |

### `agentSubagent`

> **Collapse: Query a single subagent**
>
> ```
> curl \
> --header "X-OpenIDM-Username: openidm-admin" \
> --header "X-OpenIDM-Password: openidm-admin" \
> --header "Content-Type: application/json" \
> --request GET \
> "http://localhost:8080/openidm/system/agentforce/agentSubagent/0hL000000000001"
> {
>   "_id": "0hL000000000001",
>   "__NAME__": "Sub1",
>   "subagentId": "0hL000000000001",
>   "agentId": null,
>   "developerName": "sub1",
>   "masterLabel": "Sub1",
>   "description": "d1",
>   "actions": [
>     {
>       "name": "Action1",
>       "type": "Flow",
>       "target": "flow",
>       "confirmationRequired": false
>     }
>   ]
> }
> ```
>
> |   |                                                                                                       |
> | - | ----------------------------------------------------------------------------------------------------- |
> |   | `agentId` is always null for a `GET`-by-UID. Refer to [Discovery model](#agentforce-discovery-model). |

> **Collapse: Query all subagents**
>
> ```
> curl \
> --header "X-OpenIDM-Username: openidm-admin" \
> --header "X-OpenIDM-Password: openidm-admin" \
> --header "Content-Type: application/json" \
> --request GET \
> "http://localhost:8080/openidm/system/agentforce/agentSubagent?_queryFilter=true"
> {
>   "result": [
>     {
>       "_id": "0hL000000000001",
>       "__NAME__": "Sub1",
>       "subagentId": "0hL000000000001",
>       "agentId": null,
>       "developerName": "sub1",
>       "masterLabel": "Sub1",
>       "description": "d1",
>       "actions": [
>         {
>           "name": "Action1",
>           "type": "Flow",
>           "target": "flow",
>           "confirmationRequired": false
>         }
>       ]
>     },
>     {
>       "_id": "0hL000000000002",
>       "__NAME__": "Sub2",
>       "subagentId": "0hL000000000002",
>       "agentId": null,
>       "developerName": "sub2",
>       "masterLabel": "Sub2",
>       "description": "d2",
>       "actions": [
>         {
>           "name": "Action2",
>           "type": "Flow",
>           "target": "flow",
>           "confirmationRequired": false
>         }
>       ]
>     }
>   ],
>   "resultCount": 2,
>   "pagedResultsCookie": null,
>   "totalPagedResultsPolicy": "NONE",
>   "totalPagedResults": -1,
>   "remainingPagedResults": -1
> }
> ```
>
> |   |                                                                                                                                            |
> | - | ------------------------------------------------------------------------------------------------------------------------------------------ |
> |   | An unscoped search (no `agentId` filter) returns `agentId` as null for every row. Refer to [Discovery model](#agentforce-discovery-model). |

**agentSubagent attributes**

| Attribute       | Type   | Multivalued | Description                                                                                                                  |
| --------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `subagentId`    | String | No          | The `GenAiPluginDefinition` Id.                                                                                              |
| `agentId`       | String | No          | The owning agent's `BotDefinition` Id, or null when returned by an unscoped search or a `GET`-by-UID.                        |
| `developerName` | String | No          | The `GenAiPluginDefinition.DeveloperName`.                                                                                   |
| `masterLabel`   | String | No          | The `GenAiPluginDefinition.MasterLabel`.                                                                                     |
| `description`   | String | No          | The `GenAiPluginDefinition.Description`.                                                                                     |
| `actions`       | Map    | Yes         | One entry per attached `GenAiFunctionDefinition`, each with `name`, `type`, `target`, and optionally `confirmationRequired`. |

### `agentIdentityBinding`

> **Collapse: Query a single identity binding**
>
> ```
> curl \
> --header "X-OpenIDM-Username: openidm-admin" \
> --header "X-OpenIDM-Password: openidm-admin" \
> --header "Content-Type: application/json" \
> --request GET \
> "http://localhost:8080/openidm/system/agentforce/agentIdentityBinding/0050000000000001"
> {
>   "_id": "0050000000000001",
>   "__NAME__": "0050000000000001",
>   "agentId": "0Xx000000000001",
>   "userId": "0050000000000001"
> }
> ```

> **Collapse: Query all identity bindings**
>
> ```
> curl \
> --header "X-OpenIDM-Username: openidm-admin" \
> --header "X-OpenIDM-Password: openidm-admin" \
> --header "Content-Type: application/json" \
> --request GET \
> "http://localhost:8080/openidm/system/agentforce/agentIdentityBinding?_queryFilter=true"
> {
>   "result": [
>     {
>       "_id": "0050000000000001",
>       "__NAME__": "0050000000000001",
>       "agentId": "0Xx000000000001",
>       "userId": "0050000000000001"
>     }
>   ],
>   "resultCount": 1,
>   "pagedResultsCookie": null,
>   "totalPagedResultsPolicy": "NONE",
>   "totalPagedResults": -1,
>   "remainingPagedResults": -1
> }
> ```

**agentIdentityBinding attributes**

| Attribute | Type   | Multivalued | Description                                             |
| --------- | ------ | ----------- | ------------------------------------------------------- |
| `agentId` | String | No          | The owning agent's `BotDefinition` Id.                  |
| `userId`  | String | No          | The agent's run-as User Id (`BotDefinition.BotUserId`). |

### `agentPermissionSet`

> **Collapse: Query a single permission set assignment**
>
> ```
> curl \
> --header "X-OpenIDM-Username: openidm-admin" \
> --header "X-OpenIDM-Password: openidm-admin" \
> --header "Content-Type: application/json" \
> --request GET \
> "http://localhost:8080/openidm/system/agentforce/agentPermissionSet/0Pa000000000001"
> {
>   "_id": "0Pa000000000001",
>   "__NAME__": "Agentforce Access",
>   "agentId": "0Xx000000000001",
>   "permissionSetId": "0PS000000000009",
>   "permissionSetName": "Agentforce Access"
> }
> ```

> **Collapse: Query all permission set assignments**
>
> ```
> curl \
> --header "X-OpenIDM-Username: openidm-admin" \
> --header "X-OpenIDM-Password: openidm-admin" \
> --header "Content-Type: application/json" \
> --request GET \
> "http://localhost:8080/openidm/system/agentforce/agentPermissionSet?_queryFilter=true"
> {
>   "result": [
>     {
>       "_id": "0Pa000000000001",
>       "__NAME__": "Agentforce Access",
>       "agentId": "0Xx000000000001",
>       "permissionSetId": "0PS000000000009",
>       "permissionSetName": "Agentforce Access"
>     }
>   ],
>   "resultCount": 1,
>   "pagedResultsCookie": null,
>   "totalPagedResultsPolicy": "NONE",
>   "totalPagedResults": -1,
>   "remainingPagedResults": -1
> }
> ```

**agentPermissionSet attributes**

| Attribute           | Type   | Multivalued | Description                                    |
| ------------------- | ------ | ----------- | ---------------------------------------------- |
| `agentId`           | String | No          | The owning agent's `BotDefinition` Id.         |
| `permissionSetId`   | String | No          | The `PermissionSetAssignment.PermissionSetId`. |
| `permissionSetName` | String | No          | The assigned PermissionSet's `Name`.           |

## Troubleshooting

### Connector initializes but test fails

Check:

1. `serviceUri` points to the correct Salesforce instance and doesn't include a trailing path.

2. `tokenEndpoint` is set to the token URL for the same instance, for example `https://your-org.my.salesforce.com/services/oauth2/token`.

3. `clientId` and `clientSecret` are valid, and the External Client App's client credentials flow is enabled.

4. `authenticationMethod` is `OAUTH` and `grantType` is `client_credentials`. The connector rejects any other combination during configuration validation.

5. The client credentials flow's run-as user has API access enabled.

6. The run-as user has the View Setup and Configuration system permission. Without it, Salesforce returns `INVALID_TYPE: sObject type 'BotDefinition' is not supported`.

### Agents reconcile but expected agents are missing

Check:

1. `includeInternalCopilot`, `includeExternalCopilot`, and `includeBot` are set correctly for the agent types you expect.

2. The run-as user can see the relevant `BotDefinition` rows.

### `agentSubagent`, `agentIdentityBinding`, or `agentPermissionSet` is empty for an agent

Check:

1. The agent has an active `BotVersion` and a matching `GenAiPlannerDefinition`. Without a planner, the agent has no `agentSubagent` entries, which is expected for classic `Bot` agents.

2. For `agentIdentityBinding`/`agentPermissionSet`: the agent has a non-null `BotUserId`. `InternalCopilot` agents don't.

3. The run-as user can see the related `GenAiPlannerDefinition`, `GenAiPlannerFunctionDef`, `GenAiPluginDefinition`, `GenAiPluginFunctionDef`, `GenAiFunctionDefinition`, and `PermissionSetAssignment` records. A missing permission fails with an `INVALID_TYPE` error rather than returning an empty result.

## OpenICF Interfaces Implemented by the Agentforce Connector

The Agentforce Connector implements the following OpenICF interfaces. For additional details, see [ICF interfaces](interfaces.html):

* Schema

  Describes the object types, operations, and options that the connector supports.

* Script on Connector

  Enables an application to run a script in the context of the connector.

  Any script that runs on the connector has the following characteristics:

  * The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.

  * The script has access to a `connector` variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.

  * The script has access to any script arguments passed in by the application.

* Search

  Searches the target resource for all objects that match the specified object class and filter.

* Test

  Tests the connector configuration.

  Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

  This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

  You can invoke the test operation before a connector configuration has been validated.

[]()

## Agentforce Connector Configuration

The Agentforce Connector has the following configurable properties:

### Basic Configuration Properties

| Property                                                                                                                                                                                          | Type            | Default                 | Encrypted(1)             | Required(2)               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------------------- | ------------------------ | ------------------------- |
| `serviceUri`                                                                                                                                                                                      | `String`        | `null`                  |                          | [icon: check, set=fas]Yes |
| The Salesforce instance URL, e.g. [https://\<org>.my.salesforce.com](https://<org>.my.salesforce.com)                                                                                             |                 |                         |                          |                           |
| `apiVersion`                                                                                                                                                                                      | `String`        | `62.0`                  |                          | [icon: times, set=fas]No  |
| Salesforce REST/Tooling API version, e.g. 62.0                                                                                                                                                    |                 |                         |                          |                           |
| `includeInternalCopilot`                                                                                                                                                                          | `boolean`       | `true`                  |                          | [icon: times, set=fas]No  |
| When true, sweeps agents of Type=InternalCopilot (default true)                                                                                                                                   |                 |                         |                          |                           |
| `login`                                                                                                                                                                                           | `String`        | `null`                  |                          | [icon: times, set=fas]No  |
| The service login name.                                                                                                                                                                           |                 |                         |                          |                           |
| `password`                                                                                                                                                                                        | `GuardedString` | `null`                  | [icon: lock, set=fas]Yes | [icon: times, set=fas]No  |
| The service user password.                                                                                                                                                                        |                 |                         |                          |                           |
| `includeExternalCopilot`                                                                                                                                                                          | `boolean`       | `true`                  |                          | [icon: times, set=fas]No  |
| When true, sweeps agents of Type=ExternalCopilot (default true)                                                                                                                                   |                 |                         |                          |                           |
| `includeBot`                                                                                                                                                                                      | `boolean`       | `false`                 |                          | [icon: times, set=fas]No  |
| When true, sweeps agents of Type=Bot. subagentIds is empty when no matching GenAiPlannerDefinition is found, which is expected for classic Bots (default false)                                   |                 |                         |                          |                           |
| `authenticationMethod`                                                                                                                                                                            | `String`        | `OAUTH`                 |                          | [icon: check, set=fas]Yes |
| Defines which method is to be used to authenticate on the remote server. Options are `BASIC` (username/password), `OAUTH` (Client id/secret), `JWT_TOKEN` (jwt token), or `TOKEN` (static token). |                 |                         |                          |                           |
| `tokenEndpoint`                                                                                                                                                                                   | `String`        | `null`                  |                          | [icon: times, set=fas]No  |
| When using OAUTH as authentication method, this property defines the endpoint where a new access token should be queried for (<https://myserver.com/oauth2/token>).                               |                 |                         |                          |                           |
| `clientId`                                                                                                                                                                                        | `String`        | `null`                  |                          | [icon: times, set=fas]No  |
| External Client App consumer key (client_credentials grant)                                                                                                                                       |                 |                         |                          |                           |
| `clientSecret`                                                                                                                                                                                    | `GuardedString` | `null`                  | [icon: lock, set=fas]Yes | [icon: times, set=fas]No  |
| External Client App consumer secret (client_credentials grant)                                                                                                                                    |                 |                         |                          |                           |
| `acceptSelfSignedCertificates`                                                                                                                                                                    | `boolean`       | `false`                 |                          | [icon: times, set=fas]No  |
| To be used for debug/test purposes. To be avoided in production.                                                                                                                                  |                 |                         |                          |                           |
| `disableHostNameVerifier`                                                                                                                                                                         | `boolean`       | `false`                 |                          | [icon: times, set=fas]No  |
| To be used for debug/test purposes. To be avoided in production.                                                                                                                                  |                 |                         |                          |                           |
| `disableHttpCompression`                                                                                                                                                                          | `boolean`       | `false`                 |                          | [icon: times, set=fas]No  |
| Set this property to `true` to disable content compression.                                                                                                                                       |                 |                         |                          |                           |
| `clientCertAlias`                                                                                                                                                                                 | `String`        | `null`                  |                          | [icon: times, set=fas]No  |
| If TLS Mutual Auth is needed, set this to the certificate alias from the keystore.                                                                                                                |                 |                         |                          |                           |
| `clientCertPassword`                                                                                                                                                                              | `GuardedString` | `null`                  | [icon: lock, set=fas]Yes | [icon: times, set=fas]No  |
| If TLS Mutual Auth is needed and the client certificate (private key) password is different from the keystore password, set this to the client private key password.                              |                 |                         |                          |                           |
| `maximumConnections`                                                                                                                                                                              | `Integer`       | `10`                    |                          | [icon: times, set=fas]No  |
| Defines the max size of the HTTP connection pool used.                                                                                                                                            |                 |                         |                          |                           |
| `httpProxyHost`                                                                                                                                                                                   | `String`        | `null`                  |                          | [icon: times, set=fas]No  |
| Defines the Hostname if an HTTP proxy is used between the connector and the service.                                                                                                              |                 |                         |                          |                           |
| `httpProxyPort`                                                                                                                                                                                   | `Integer`       | `null`                  |                          | [icon: times, set=fas]No  |
| Defines the Port if an HTTP proxy is used between the connector and the service.                                                                                                                  |                 |                         |                          |                           |
| `httpProxyUsername`                                                                                                                                                                               | `String`        | `null`                  |                          | [icon: times, set=fas]No  |
| Defines Proxy Username if an HTTP proxy is used between the connector and the service.                                                                                                            |                 |                         |                          |                           |
| `httpProxyPassword`                                                                                                                                                                               | `GuardedString` | `null`                  | [icon: lock, set=fas]Yes | [icon: times, set=fas]No  |
| Defines Proxy Password if an HTTP proxy is used between the connector and the service.                                                                                                            |                 |                         |                          |                           |
| `connectionTimeout`                                                                                                                                                                               | `int`           | `30`                    |                          | [icon: times, set=fas]No  |
| Defines a timeout for the underlying HTTP connection in seconds.                                                                                                                                  |                 |                         |                          |                           |
| `refreshToken`                                                                                                                                                                                    | `GuardedString` | `null`                  |                          | [icon: times, set=fas]No  |
| Used by the refresh_token grant type.                                                                                                                                                             |                 |                         |                          |                           |
| `grantType`                                                                                                                                                                                       | `String`        | `client_credentials`    |                          | [icon: times, set=fas]No  |
| The OAuth2 grant type to use (`client_credentials`, `refresh_token`, or `jwt_bearer`).                                                                                                            |                 |                         |                          |                           |
| `scope`                                                                                                                                                                                           | `String`        | `null`                  |                          | [icon: times, set=fas]No  |
| The OAuth2 scope to use.                                                                                                                                                                          |                 |                         |                          |                           |
| `authorizationTokenPrefix`                                                                                                                                                                        | `String`        | `Bearer`                |                          | [icon: times, set=fas]No  |
| The prefix to be used in the Authorization HTTP header for Token authentication.                                                                                                                  |                 |                         |                          |                           |
| `useBasicAuthForOauthTokenNeg`                                                                                                                                                                    | `boolean`       | `true`                  |                          | [icon: times, set=fas]No  |
| The Authentication method for refresh token (Basic Authentication or Sending the ClientId and Client Secret in the Header).                                                                       |                 |                         |                          |                           |
| `jwtKey`                                                                                                                                                                                          | `GuardedString` | `null`                  | [icon: lock, set=fas]Yes | [icon: times, set=fas]No  |
| The JWT data structure that represents a cryptographic key.                                                                                                                                       |                 |                         |                          |                           |
| `jwtExpiration`                                                                                                                                                                                   | `Integer`       | `null`                  |                          | [icon: times, set=fas]No  |
| Defines the JWT expiration time in minutes.                                                                                                                                                       |                 |                         |                          |                           |
| `jwtAlgorithm`                                                                                                                                                                                    | `String`        | `null`                  |                          | [icon: times, set=fas]No  |
| The Algorithm type to sign payload.                                                                                                                                                               |                 |                         |                          |                           |
| `jwtClaims`                                                                                                                                                                                       | `Map`           | `null`                  |                          | [icon: times, set=fas]No  |
| JWT Claims to be included in the payload                                                                                                                                                          |                 |                         |                          |                           |
| `jwtPem`                                                                                                                                                                                          | `GuardedString` | `null`                  | [icon: lock, set=fas]Yes | [icon: times, set=fas]No  |
| The contents of the private key of the PEM file                                                                                                                                                   |                 |                         |                          |                           |
| `jwtCert`                                                                                                                                                                                         | `GuardedString` | `null`                  | [icon: lock, set=fas]Yes | [icon: times, set=fas]No  |
| The contents of the certificate of the PEM file                                                                                                                                                   |                 |                         |                          |                           |
| `keyAlgorithm`                                                                                                                                                                                    | `String`        | `null`                  |                          | [icon: times, set=fas]No  |
| Indicates the type of key (such as RSA, DSA or EC) used to sign from the PEM.                                                                                                                     |                 |                         |                          |                           |
| `userAgent`                                                                                                                                                                                       | `String`        | `PingIdentityConnector` |                          | [icon: times, set=fas]No  |
| The User Agent HTTP Header used by the connector. Defaults to `PingIdentityConnector`.                                                                                                            |                 |                         |                          |                           |

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.
