This page explains how to share agents with users in your organization and how
administrators can transfer ownership of shared agents. As an administrator, you
can share the available agents (Google-made, employee-made, and custom-made) with
individual users, groups, Workforce Identity Pool groups, or all users in your
organization, and transfer ownership of shared employee-made agents to yourself
or another user. For more information about the different types of agents
available in Gemini Enterprise, see
[Agents overview](https://docs.cloud.google.com/gemini/enterprise/docs/agents-overview.md.txt#types-of-agents).

> [!NOTE]
> **Note:** To share employee-made agents, you must have one or more agents created using Workflow Builder in your Gemini Enterprise web app. For information about creating agents using Workflow Builder, see [Create an agent using Workflow Builder](https://docs.cloud.google.com/gemini/enterprise/docs/workflow-builder/create-chat-agent.md.txt).

## Before you begin

Before you can share an agent, you must meet the following requirements:

1. You must have an existing Gemini Enterprise web app. To create a new app, see
   [Create an app](https://docs.cloud.google.com/gemini/enterprise/docs/create-app.md.txt).

2. To share custom agents, you must have registered or added the custom agents to Gemini Enterprise using
   any of the following options:

   - [Register and manage A2A agents](https://docs.cloud.google.com/gemini/enterprise/docs/register-and-manage-an-a2a-agent.md.txt)
   - [Register and manage ADK agents hosted on Agent Runtime on Gemini Enterprise Agent Platform](https://docs.cloud.google.com/gemini/enterprise/docs/register-and-manage-an-adk-agent.md.txt)
   - [Add and manage A2A agents from Google Cloud Marketplace](https://docs.cloud.google.com/gemini/enterprise/docs/register-and-manage-marketplace-agents.md.txt)
   - [Register and manage Dialogflow agents](https://docs.cloud.google.com/gemini/enterprise/docs/register-and-manage-a-dialogflow-agent.md.txt)

## Share an agent

To share an agent, follow these steps:

### Console

1. In the Google Cloud console, go to the **Gemini Enterprise** page.

[Go to **Gemini Enterprise**](https://console.cloud.google.com/gemini-enterprise/products)

1. Select your project.

2. Click your app from the **Name** column. The navigation menu updates.

3. Click **Agents** from the navigation menu.

4. Click the **Display name** of the agent that you want to share.

5. Click the **User permissions** tab, and the **Permissioned users** page
   displays.

6. Click **Add user** . The **Add user permissions roles to agent** dialog
   displays.

7. Configure the permission details:

   1. Select one of the following options in the **Member type**
      section:

      - **User** : An individual end user. For this member type to function, you
        must include the correct IAM role. For more
        information, see [IAM roles and
        permissions](https://docs.cloud.google.com/gemini/enterprise/docs/access-control).

      - **Group** : A collection of end users. For this member type to function,
        you must include the correct IAM role. For more
        information, see [IAM roles and
        permissions](https://docs.cloud.google.com/gemini/enterprise/docs/access-control).

      - **Principal** : A single identity in a Workforce Identity Pool
        (`principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ID`).

      - **Workforce Identity Pool** : A workforce pool group, custom
        attribute, or all users in a Workforce Identity Pool
        (`principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/...`).

      - **All users**: All users in the organization.

      The member types that are displayed depend on the identity provider
      that your app uses. For apps that use Google identities, the **User**
      and **Group** member types are shown. For apps that use
      Workforce Identity Federation, the **Principal** and **Workforce Identity
      Pool** member types are shown instead.

      > [!TIP]
      > **Tip:** If you use Workforce Identity Federation with a third-party identity provider such as Microsoft Entra ID or Okta, configure System for Cross-domain Identity Management (SCIM) provisioning for your workforce identity pool. With SCIM configured, the **Add user** and **Transfer ownership** dialogs autocomplete users and groups and fill in the exact, case-sensitive <var translate="no">SUBJECT_ID</var> and <var translate="no">GROUP_ID</var> for you. SCIM-based autocomplete requires a dedicated workforce identity pool for each Google Cloud project, and the SCIM attribute mapping must produce the same subject as the pool's `google.subject` mapping. Users and groups appear in autocomplete only after your identity provider has provisioned them through SCIM. For more information, see [Configure Workforce Identity Federation](https://docs.cloud.google.com/gemini/enterprise/docs/configure-identity-provider.md.txt#configure_workforce_id_federation) and [Example mappings for subject consistency](https://docs.cloud.google.com/iam/docs/workforce-identity-federation-scim.md.txt#example-claim-mappings).

   2. Enter the unique member identification, and select a role:

      | **Member type** | **Description** |
      |---|---|
      | **User** | Enter email addresses in the **Member** field. Select a role in the **Assign role** field. |
      | **Group** | Enter email addresses in the **Member** field. Select a role in the **Assign role** field. |
      | **Principal** | Enter the single-subject principal identifier (`//iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ID` or `principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ID`) in the **Member** field. Select a role in the **Assign role** field. |
      | **Workforce Identity Pool** | Enter the principal set identifier (`//iam.googleapis.com/locations/global/workforcePools/POOL_ID/...` or `principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/...`) in the **Member** field. Select a role in the **Assign role** field. For examples of principal sets, see [Principal sets](https://docs.cloud.google.com/gemini/enterprise/docs/share-custom-agents.md.txt#principal_sets). |
      | **All users** | Select a role in the **Assign role** field. |

8. Click **Save**.

#### Principal sets

The following are examples of principal identifiers and principal sets that you
can specify when sharing with Workforce Identity Federation users and groups. If
SCIM provisioning is configured for your workforce identity pool, the
**Add user** dialog suggests users and groups as you type and fills in these
identifiers for you; otherwise, enter them exactly as shown, including the
letter case of <var translate="no">SUBJECT_ID</var>:

| **Principal or principal set** | **Description** |
|---|---|
| `//iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ID` | A single identity in a workforce identity pool (select the **Principal** member type). |
| `//iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID` | All workforce identities in a group (select the **Workforce Identity Pool** member type). |
| `//iam.googleapis.com/locations/global/workforcePools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE` | All workforce identities with a specific attribute value (select the **Workforce Identity Pool** member type). |
| `//iam.googleapis.com/locations/global/workforcePools/POOL_ID/*` | All identities in a workforce identity pool (select the **Workforce Identity Pool** member type). |

Replace the following placeholders with values in the code sample:

- **`GROUP_ID`**: a specific group identifier from an external Identity Provider (IdP), letting you grant access to all members of that group.
- **`POOL_ID`**: the unique ID for the workforce identity pool that you create in Google Cloud.
- **`SUBJECT_ID`** : the unique subject identifier (`google.subject`) for a single identity within a workforce identity pool. `SUBJECT_ID` is case-sensitive and must match the exact capitalization asserted by your identity provider (for example, in the SAML assertion or OIDC token).
- **`ATTRIBUTE_NAME`**: a user-defined name of a custom attribute that you have mapped from an external Identity Provider (IdP).
- **`ATTRIBUTE_VALUE`** : the specific value of the `ATTRIBUTE_NAME` used to restrict access.

> [!NOTE]
> **Note:** To grant access to a single Workforce Identity Federation user rather than a group or pool, select **Principal** as the member type and use the single-subject format `principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ID` (or omit the `principal:` prefix in the Google Cloud console). Ensure that `SUBJECT_ID` (`google.subject`) matches the exact capitalization asserted by your identity provider.

## Transfer agent ownership

As an administrator, you can transfer ownership of a shared agent to another
user in your organization or to yourself. This capability is useful in scenarios
such as:

- **Departing employees:** Transferring agents created by employees who leave the organization to active team members to ensure uninterrupted maintenance.
- **Contractor handoffs:** Handing over agents created by temporary or contract workers to full-time staff.
- **Team restructuring:** Reassigning agent responsibilities as roles or projects evolve.

### Considerations and limitations

Before transferring agent ownership, note the following considerations and
limitations:

- **Administrator permission:** Only administrators with the [Gemini Enterprise Admin](https://docs.cloud.google.com/gemini/enterprise/docs/access-control.md.txt#discoveryengine.agentspaceAdmin) role (`roles/discoveryengine.agentspaceAdmin`) or the [Discovery Engine Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/discoveryengine.md.txt#discoveryengine.admin) role (`roles/discoveryengine.admin`) can transfer agent ownership. The current agent owner cannot transfer ownership unless they are also an administrator.
- **Shared agents only:** You can only transfer ownership of agents that are already shared. On the **Agents** page in the Google Cloud console, the agent's **Sharing** column must display **Enabled**. Private (unshared) agents cannot be transferred.
- **Single owner:** Each agent has exactly one owner. When ownership is transferred, the selected recipient becomes the sole owner of the agent.
- **Previous owner access:** When ownership is transferred, the previous owner is demoted to a user on the agent with the `agentUser` role. They retain permission to query and run the agent, but can no longer edit the agent's configuration or settings.
- **Supported agent types:** Ownership transfer is supported for employee-made agents (low-code and workflow agents created in the web app).
- **Agents with schedules or triggers:** If the transferred agent has a schedule trigger or event trigger, the transfer operation marks them as disabled schedules or events. The new owner must enable the schedule or event trigger before being able to use the agent.

### Transfer ownership of an agent

To transfer ownership of an agent, follow these steps:

### Console

1. In the Google Cloud console, go to the **Gemini Enterprise** page.

   [Go to **Gemini Enterprise**](https://console.cloud.google.com/gemini-enterprise/products)
2. Select your project.

3. Click your app from the **Name** column. The navigation menu updates.

4. Click **Agents** from the navigation menu.

5. Click the **Display name** of the shared agent.

6. Click the **User permissions** tab. The **Permissioned users** list
   displays.

7. Click **Transfer ownership** . The **Transfer ownership** dialog opens.

8. Under **Transfer ownership to**, choose one of the following options:

   - **Myself**: Transfer ownership of the agent to your current administrator account. This option is disabled if you already own the agent.
   - **Another user**: Transfer ownership to another user in your organization.
9. If you selected **Another user**, specify the new owner:

   - **Google Identity and Cloud Identity:** Enter the user's email address in the **New owner email** field (for example, `user@example.com`).
   - **Workforce Identity Federation (WIF) accounts:** Enter the single identity principal identifier in the **New owner principal** field:

   ```
   //iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ID
   ```

   Alternatively, you can include the `principal:` prefix:

   ```
   principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ID
   ```

   Replace the following:
   - <var translate="no">POOL_ID</var>: The unique ID of your workforce identity pool.
   - <var translate="no">SUBJECT_ID</var>: The user's subject identifier in the workforce identity pool.

   > [!NOTE]
   > **Note:** Workforce Identity Federation principal identifiers are case-sensitive. Ensure that the identifier matches the exact casing configured in your identity provider's `google.subject` mapping. If SCIM provisioning is configured for your workforce identity pool, the **New owner principal** field suggests users as you type and fills in the identifier for you. For more information, see [Configure
   > Workforce Identity Federation](https://docs.cloud.google.com/gemini/enterprise/docs/configure-identity-provider#configure_workforce_id_federation).

10. Click **Transfer ownership**.

    The agent's owner is updated. The previous owner is retained as a
    permissioned user with the `agentUser` role.

    > [!NOTE]
    > **Note:** If the transferred agent has a schedule trigger or event trigger, the transfer operation marks them as disabled schedules or events. The new owner must enable the trigger before being able to use the agent.