# Manage Agents
{% hint style="info" %}
**Private preview**: This feature is available to select accounts. Contact your Immuta representative for details.
{% endhint %}
## Register and manage agents
### Create an agent
**Required Immuta permission**: `USER_ADMIN`
Register an agent in Immuta from your identity provider, by creating a new agent in Immuta, or by converting an existing user to an agent. Expand the blocks below for instructions on these methods.
Add an agent from your identity provider
1. See the [how-to guide for your identity management protocol](https://documentation.immuta.com/saas/configuration/people/section-contents#how-to-guides) to register an existing agent in Immuta.
2. Click :users: **Identities** and select **Users**.
3. Click the **overflow menu** in the **Actions** column of the agent you just registered and click **Configure dependencies**.
4. Copy the **script** provided in the modal that appears and run that script in your data platform.
Create a new agent using the Immuta UI
1. Click :users: **Identities** and select **Agents**.
2. Click **New agent**.
3. Enter a **Name** for your agent, select an **Owner**, and provide an optional **description**.
4. Click **Create agent**.
5. Copy the **script** provided in the modal that appears and run that script in your data platform.
Convert an existing user to an agent
{% hint style="warning" %}
**User will lose all Immuta permissions**\
If converting a user to an agent, all Immuta permissions will be removed. Agents can only act through APIs and cannot log in to Immuta.
{% endhint %}
1. Click :users: **Identities** and select **Users**.
2. Click the **overflow menu** in the **Actions** column of the user you want to convert to an agent and select **Convert to agent**.
3. Click **Convert to agent** again to confirm your changes.
4. Copy the **script** provided in the modal that appears and run that script in your data platform.
### Generate an API key for your agent
**Requirement**: `USER_ADMIN` Immuta permission or own the agent
The agent will use this API key to make requests to the Immuta API to vend and delete ephemeral roles.
#### With the UI
1. Click :users: **Identities** and select **Agents**.
2. Click the **name** of the agent you want to generate the API for.
3. Navigate to the **API Keys** tab and click **Generate API Key**.
4. Enter an **API key name** and click **Generate key**.
This API key can now be added to your agent service so that it can use it when [requesting the ephemeral role](https://documentation.immuta.com/saas/agentic-data-access-reference-guide#requesting-the-ephemeral-role).
#### With the API
Copy the request example below and replace the values with your own as directed to generate the agent's API key.
{% code overflow="wrap" %}
```bash
curl -X 'POST' \
'https://www.organization.immuta.com/bim/iam/{iamid}/user/{userid}/apikeys' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"name": "Marketing department agent API key",
"expiration": "2027-03-23"
}'
```
{% endcode %}
1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/saas/developer-guides/api-intro/integrations-api/getting-started#authenticate-with-the-api) with your own.
2. Replace the **{iamid}** request parameter with the unique identifier of your identity provider. You can find this ID in the identity provider's configuration section on the app settings page or [through the Immuta API](https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim#search-all-iams). If you created the agent in Immuta, this value is `bim`.
3. Replace the **{userid}** request parameter with the unique identifier of the agent. You can get this ID [through the Immuta API](https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim#search-all-users) and using the agent's name as a search filter. Or it is presented in the Agent table.
4. Change the payload values to your own, where
* **name** is the name of the agent's API key.
* **expiration** is the date the API key expires.
This API key can now be added to your agent service so that it can use it when [requesting the ephemeral role](https://documentation.immuta.com/saas/agentic-data-access-reference-guide#requesting-the-ephemeral-role).
### Assign groups or attributes to your agent
**Requirement**: `USER_ADMIN` Immuta permission or own the agent
Opt to assign groups and attributes to the agent, just like you would for a human user. Once these entitlements are added, they can be used in global policies to target agents and grant or limit their access to data.
1. Click :users: **Identities** and select **Agents**.
2. Click the **name** of the agent you want to add groups or attributes to.
3. Navigate to the **Attributes** or **Groups** tab to add these entitlements to the agent:
* **Attributes**: Click **Add Attributes**.
1. Begin typing the attribute name in the **Attribute** text box. If the attribute already exists, select it from the dropdown list. If the attribute does not exist yet, enter the full name of the attribute, and then select it from the dropdown.
2. In the **Attribute Value** text box, enter a value. If the value already exists, select it from the dropdown list. If the value does not exist, enter the full name, and then select it from the dropdown.
3. Click **Close**.
* **Groups**: Click **Add Groups**.
1. Begin typing in the **Search by Group Name** text box. If you need to create a new group, follow the instructions on the [Manage attributes and groups page](https://documentation.immuta.com/saas/configuration/people/users-index/how-to-guides/managing-attribute-and-group#create-group), and then add the agent to the group.
2. Click the **name** in the dropdown list to add the agent to the group.
3. Click **close**.
### Map the agent to external data platforms
**Requirement**: `USER_ADMIN` Immuta permission or own the agent
Map external usernames to the agent account in Immuta to ensure Immuta properly enforces policies.
The instructions below illustrate how to do this for individual agents, but you can also configure external mapping in your [Identity provider connection on the app settings page](https://documentation.immuta.com/saas/configuration/people/users-index/how-to-guides/external-user-mapping#configure-external-user-id-mapping-on-app-settings-page).
1. Click :users: **Identities** and select **Agents**.
2. Click the **name** of the agent you want to map to external data platforms.
3. Navigate to the **External Mapping** tab.
4. Click **Edit** for the data platform username you want to map to and complete the fields in the modal that appears. For guidance on what to enter in these fields, see the [External user ID mapping page](https://documentation.immuta.com/saas/configuration/people/users-index/how-to-guides/external-user-mapping#manually-configure-external-user-id-mapping-on-a-users-page).
## View agent activity
1. Click :users: **Identities** and select **Agents**.
2. Click the **name** of the agent you want to view.
3. Click the **Activity** tab.
This view displays a list of vended roles, the vended role expiration dates, and the users the agent was acting on behalf of.
## Disable or delete agents
{% hint style="info" %}
**Deleting agents**
Only agents created in the Immuta UI can be deleted from the agents page.
{% endhint %}
**Requirement**: `USER_ADMIN` Immuta permission or own the agent
1. Click :users: **Identities** and select **Agents**.
2. Click the **overflow menu** in the **Action** column of the agent you want to disable or delete and select **Disable** or **Delete.**
3. Click **Disable** or **Delete** again to confirm your changes.