> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/SaaS/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/SaaS/agentic-data-access/manage-agents.md). # Manage Agents Manage your agents and view agent activity {% 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](/SaaS/configuration/people/section-contents.md#how-to-guides) to register an existing agent in Immuta. If your identity provider uses the [SAML](/SaaS/configuration/people/section-contents/reference-guides/saml-protocol.md#configuration-options) or [OpenID Connect](/SaaS/configuration/people/section-contents/reference-guides/openid-connect-protocol.md#configuration-options) protocol and SCIM is enabled, you can map a custom SCIM attribute to Immuta to automatically identify and register user accounts as agents. Otherwise, you must [convert the user account to an agent](#convert-an-existing-user-to-an-agent) after it is registered 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. [Connect the agent to your data platform](/SaaS/agentic-data-access/manage-agents/connecting-the-agent-to-the-data-platform.md) so the agent can run queries and act on behalf of users.
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. [Connect the agent to your data platform](/SaaS/agentic-data-access/manage-agents/connecting-the-agent-to-the-data-platform.md) so the agent can run queries and act on behalf of users.
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. [Connect the agent to your data platform](/SaaS/agentic-data-access/manage-agents/connecting-the-agent-to-the-data-platform.md) so the agent can run queries and act on behalf of users.
### Generate credentials for your agent The credentials agents use for authentication depend on the version of the agentic access API you're using to request and manage [ephemeral roles](/SaaS/agentic-data-access/agentic-data-access-reference-guide.md#requesting-the-ephemeral-role) for the agent: * [**Agentic access V1 API**](/SaaS/agentic-data-access/agentic-data-access-reference-guide.md#agentic-access-v1-api): Agents use a personal access token to authenticate. * [**Deprecated legacy agentic access API**](/SaaS/agentic-data-access/agentic-data-access-reference-guide.md#legacy-agentic-access-api): Agents use an API key to authenticate. Click one of the tabs below for instructions on generating a personal access token or API key for your agent. {% tabs %} {% tab title="Personal access token" %} **Requirement**: `USER_ADMIN` Immuta permission or own the agent The agent will use this token 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 **Personal Access Tokens** tab and click **Generate Token**. 4. Enter a token **Description** and opt to set an **expiration date**. 5. Click **Generate token.** 6. **Copy the token** and store it somewhere secure. It will not be visible in Immuta after closing the dialog. This token can now be added to your agent service so that it can use it when [requesting the ephemeral role](/SaaS/agentic-data-access/agentic-data-access-reference-guide.md#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 personal access token. {% code overflow="wrap" %} ```bash curl -X 'POST' \ 'https://www.organization.immuta.com/bim/iam/{iamId}/agent/{agentId}/tokens' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "description": "Marketing department agent token", "expirationDate": "2027-03-23" }' ``` {% endcode %} 1. Replace the **Immuta URL** and [**bearer token**](/SaaS/developer-guides/api-intro/authentication.md#bearer-token-method) 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](/SaaS/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#search-all-iams). If you created the agent in Immuta, this value is `bim`. 3. Replace the **{agentId}** request parameter with the unique identifier of the agent. You can get this ID [through the Immuta API](/SaaS/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#search-all-users) and using the agent's name as a search filter, or you can get it from the **Agents** page in the Immuta UI. 4. Change the payload values to your own, where * **description** is a brief description of the agent's personal access token. * **expirationDate** is the date the token expires. This token can now be added to your agent service so that it can use it when [requesting the ephemeral role](/SaaS/agentic-data-access/agentic-data-access-reference-guide.md#requesting-the-ephemeral-role). For information about additional endpoints used to manage agents' personal access tokens, see the [Manage IAMs API reference guide](/SaaS/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#manage-api-keys-and-personal-access-tokens). {% endtab %} {% tab title="API key (legacy method)" %} {% hint style="warning" %} **Deprecation notice**: Support for this method has been deprecated. {% endhint %} **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](/SaaS/agentic-data-access/agentic-data-access-reference-guide.md#api-key-request-example-legacy-method). #### 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 [**bearer token**](/SaaS/developer-guides/api-intro/authentication.md#bearer-token-method) 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](/SaaS/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#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](/SaaS/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#search-all-users) and using the agent's name as a search filter, or you can get it from the **Agents** page in the Immuta UI. 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](/SaaS/agentic-data-access/agentic-data-access-reference-guide.md#api-key-request-example-legacy-method). {% endtab %} {% endtabs %} ### 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](/SaaS/configuration/people/users-index/how-to-guides/managing-attribute-and-group.md#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 when [connecting to the data platform](/SaaS/agentic-data-access/manage-agents/connecting-the-agent-to-the-data-platform.md). 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](/SaaS/configuration/people/users-index/how-to-guides/external-user-mapping.md#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](/SaaS/configuration/people/users-index/how-to-guides/external-user-mapping.md#manually-configure-external-user-id-mapping-on-a-users-page). ### Request an ephemeral role and connect the agent to the data platform The agent harness will use the new agentic access V1 API or the legacy agentic access API to request an ephemeral role for your agent. You will then use that ephemeral role to [connect to the agent to the data platform](/SaaS/agentic-data-access/manage-agents/connecting-the-agent-to-the-data-platform.md). Expand the blocks below for guidance.
New agentic access V1 API 1. The agent harness requests an ephemeral role. ```bash curl \ --request POST 'https://{globalSegment}.api.immutacloud.com/agents/roles' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "username": "taylor@immuta.com", "platforms": [ {"technology": "Snowflake"}, {"technology": "Databricks", "connectionKeys": ["finance_dbx_conn"]} ], "ttl": "30m" }' ``` * **globalSegment** should match the region your Immuta tenant is in: * **Asia Pacific**: `ap` * **European Union**: `eu` * **North America**: `na` * **AGENT\_PAT** is the agent's personal access token. * **username** is the Immuta user ID of the human user the agent will act on behalf of. This value can be found on the user's profile page in the Immuta UI. For example, `taylor.smith@immuta.com`. * **technology** is the data platform the agent will be querying. * **ttl** (time to live) is the amount of time the role will be active before it automatically expires. The agent harness can also specify a connection key along with the platform to target specific connections. For information about this request and the payload, see the [Agentic access V1 API](/SaaS/developer-guides/api-intro/agentic-access-api/agentic-access-v1.md) guide. 2. The call to vend roles is asynchronous, so roles are not guaranteed to exist after it returns a response. Therefore, the agent harness should poll the endpoint below until the `status` is `READY`. The **requestId** is returned in the response of the previous call and is the unique identifier assigned to that request. ```bash curl \ --request GET 'https://{globalSegment}.api.immutacloud.com/agents/roles/{requestId}' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ ``` 3. Use the vended role(s) returned under the `metadata` field to [connect to your agentic platform](/SaaS/agentic-data-access/manage-agents/connecting-the-agent-to-the-data-platform.md). The response below returns vended roles for two different connections: `IMMUTA_VENDED_3f2504e0-4f89-11d3-9a0c-0305e82c3301` and [`1234567890123456`](#user-content-fn-1)[^1]. ```json { "requestId": "019fcd26-e9f8-746f-a174-fdebc0e643cf", "createdAt": "2026-04-02T11:15:00.000Z", "expiresAt": "2026-04-02T11:45:00.000Z", "roles": [ { "id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301", "name": "IMMUTA_VENDED_3f2504e0-4f89-11d3-9a0c-0305e82c3301", "technology": "Snowflake", "connectionKey": "finance_snowflake_conn", "status": "READY", "metadata": { "roleName": "IMMUTA_VENDED_3f2504e0-4f89-11d3-9a0c-0305e82c3301" } }, { "id": "9b2504e0-4f89-11d3-9a0c-0305e82c3302", "technology": "Databricks", "name": "IMMUTA_VENDED_9b2504e0-4f89-11d3-9a0c-0305e82c3302", "connectionKey": "finance_dbx_conn", "status": "READY", "metadata": { "groupName": "IMMUTA_VENDED_9b2504e0-4f89-11d3-9a0c-0305e82c3302", "groupId": "1234567890123456" } } ] } ```
Legacy agentic access API {% hint style="warning" %} **Deprecation notice**: Support for this API has been deprecated. {% endhint %} 1. The agent harness requests an ephemeral role. 
curl -X POST "https://{your-immuta-url}/agent/obo/roles" \
        -H "Authorization: Bearer <AGENT_ACCESS_TOKEN>" \
        -H 'Content-Type: application/json' \
        -d '{
            "userid": "<the authenticated human>",
            "technology": ["Snowflake", "Databricks"],
            "ttl": "30m"
        }'
* **your-immuta-url** is the URL of your Immuta tenant. * **AGENT\_ACCESS\_TOKEN** is the agent's [**bearer token**](/SaaS/developer-guides/api-intro/authentication.md#bearer-token-method). * **userid** is the Immuta user ID of the human user the agent will act on behalf of. The `userid` is displayed as `Username` in the Immuta UI. For example, `taylor.smith@immuta.com`. * **technology** is the data platform the agent will be querying. * **ttl** (time to live) is the amount of time the role will be active before it automatically expires. For information about this request and the payload, see the [Agentic access - legacy API reference guide](/SaaS/developer-guides/api-intro/agentic-access-api/agentic-access-legacy.md). 2. Use the vended role(s) returned in the `roleName` field to [connect to your agentic platform](/SaaS/agentic-data-access/manage-agents/connecting-the-agent-to-the-data-platform.md). The response below returns vended roles for a Snowflake connection: `IMMUTA_VENDED_3f2504e0-4f89-11d3-9a0c-0305e82c3301`. 
{
     "id": "019fcd26-e9f8-746f-a174-fdebc0e643cf",
     "roles": {
       "Snowflake": {
         "roleName": "IMMUTA_VENDED_3f2504e0-4f89-11d3-9a0c-0305e82c3301",
         "status": "READY"
       }
     },
     "expiresAt": "2026-04-02T11:45:00.000Z"
   }
## 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. [^1]: For Databricks, you will use the `groupId` to connect the agent to the data platform. See the [Connecting the agent to the data platform page](/SaaS/agentic-data-access/manage-agents/connecting-the-agent-to-the-data-platform.md#connecting-to-databricks-as-the-agent) for details. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.immuta.com/SaaS/agentic-data-access/manage-agents.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.