Getting Access to Generative AI Agents

You can get access to Generative AI Agents resources with OCI Identity and Access Management (IAM) policies.

By default, only users in the Administrators group have access to all OCI resources including Generative AI Agents resources. If you’re a member of another group, ask your administrator to assign you the least privileges that are required to perform your responsibilities by reviewing the following sections.

Adding Policies Before You Can Use the Service

Before you use Generative AI Agents, ask your administrator to add the following policies:

User Access to All Generative AI Agents Resources

Give users access to Generative AI Agents resources such as agents, knowledge bases, data sources, data ingestion jobs, agent sessions, agent work requests, and endpoints

To get access to all Generative AI Agents resources in the entire tenancy, use the following policy:
```
allow group <genai-agent-administrators> to manage genai-agent-family in tenancy
```
To get access to all Generative AI Agents resources in your compartment, use the following policy:
```
allow group <genai-agent-administrators> to manage genai-agent-family in tenancy
```

Important

To select only specific resources that users can access, see About Generative AI Agents Resource-Types and Giving Users Granular Permission for Each Resource-Type.

User Access to Object Storage Files for Data Sources

If the data files for your agent are in OCI Object Storage buckets, you need permission to list and select those files from within the Generative AI Agents service.

To give permission to users to add Object Storage files to their knowledge bases:

allow group <your-group-name> to manage object-family in compartment <compartment-with-bucket>

Note

If the Object Storage files and agents are in different compartments, ensure that users creating the agents have permission to manage object-family in the compartment with the bucket.

Ask an administrator to review the examples in Securing Object Storage and add policies that apply to you such as policies to avoid accidental deleting of buckets that contain training data.

Data Ingestion Job Access to Object Storage Files For Long-running Jobs

To ingest large amounts of content from OCI Object Storage, follow these steps to create resource principals for data ingestion jobs that might run longer than 24 hours.

Follow the steps in Creating a Dynamic Group with the following specifics for the matching rule:
1. In the Matching Rules section, click Match any rules defined below.
2. Enter the following matching rule.
```
ALL {resource.type='genaiagentdataingestionjob'}
```
  The genaiagentdataingestionjob resource type is the resource principal for data ingestion jobs. The preceding matching rule means that this dynamic group represents the Generative AI Agents data ingestion job resource.
  To restrict the dynamic group membership to data ingestion jobs created in a specific compartment, instead of the previous matching rule, use the following one:
```
ALL {resource.type = 'genaiagentdataingestionjob', 
resource.compartment.id = '<compartment-ocid-for-ingestion-jobs>’}
```
3. Allow this dynamic group to access Object Storage objects in a specified compartment.
```
allow dynamic-group <dynamic-group-name> 
to read objects in compartment <compartment-name-for-objects>
```
  You can further restrict the policies with more conditions. For example:
```
allow dynamic-group <dynamic-group-name> 
to read objects in tenancy where all {target.compartment.id='<compartment_ocid>’, 
target.bucket.name=<bucket-name>, 
target.bucket.tag.MyTagNamespace.TagKey='<MyTagValue>'}
```
  See Securing Object Storage for more examples on writing policies.
  Note
  
  You can restrict access to Object Storage, using conditions that include bucket names, compartments, and tags. Restricting access by specifying an object name or prefix in a policy, such as target.object.name isn't supported and the data ingestion job might fail.

Service Access to Vault Secret for Oracle Database and OpenSearch

If your data is in Oracle Database vector store or OCI Search with OpenSearch, perform the following tasks:

For Oracle Database data, perform the tasks in Oracle Database Guidelines for Generative AI Agents.
For OCI Search with OpenSearch data, perform the tasks in OCI Search with OpenSearch Guidelines for Generative AI Agents.
Follow the steps in Creating a Dynamic Group with the following specifics for the matching rule:
1. In the Matching Rules section, click Match any rules defined below.
2. Enter the following matching rule.
```
ALL {resource.type='genaiagent'}
```
  The genaiagent resource type is the resource principal for agents. The preceding matching rule means that this dynamic group represents the Generative AI Agents agent resource.
3. Allow this dynamic group to access OCI Vault secrets in the compartment with your Oracle Database vector store or OCI Search with OpenSearch secret.
```
allow dynamic-group <dynamic-group-name> 
to read secret-bundle in compartment <compartment-name>
```

Service Access to Oracle Database Tools

If your data is in Oracle Database 23ai, update the dynamic group that you created in the previous section and add another rule to allow this dynamic group to access OCI Database Tools.

allow dynamic-group <dynamic-group-name> 
to read database-tools-family in compartment <compartment-name>

About Generative AI Agents Resource-Types

Generative AI Agents has the following individual resource-types to use in Identity and Access Management policies. You can assign different permissions to different user groups based on how they can use the following resource types:

genai-agent: An agent
genai-agent-knowledge-base: The knowledge base associated with an agent.
genai-agent-data-source: The data source associated with a knowledge base
genai-agent-data-ingestion-job: The job that ingests data from a data source.
genai-agent-endpoint: An endpoint to access the agent
genai-agent-work-request: The work request for Generative AI Agents operations
genai-agent-session: An agent's chat session

In addition to preceding listed individual resource types, you can use the aggregate resource type, genai-agent-family to include all seven Generative AI Agents resource types in a policy, for example:

allow group <genai-agent-administrators> to manage genai-agent-family in tenancy


Aggregate Resource-Type	Included Individual Resource-Types
`genai-agent-family`	`genai-agent` `genai-agent-knowledge-base` `genai-agent-data-source` `genai-agent-data-ingestion-job` `genai-agent-endpoint` `genai-agent-session` `genai-agent-work-request`

Giving Users Granular Permission for Each Resource-Type

This section lists the permissions for Generative AI Agents operations. The level of access is cumulative as you go from inspect to read to use to manage. For example, if you have permission to manage the genai-agent-endpoint resource-type, then you can list, get details for, create, and delete endpoints. You don't require another permission to inspect the endpoints. Expand each resource-type for its permissions.

genai-agent


Permission	API Operation	Operation Type	Verb
`GENAI_AGENT_INSPECT`	`ListAgents`	`GET`	`inspect`
`GENAI_AGENT_READ`	`GetAgent`	`GET`	`read`
`GENAI_AGENT_UPDATE`	`UpdateAgent`	`PUT`	`use`
`GENAI_AGENT_MOVE`	`ChangeAgentCompartment`	`POST`	`manage`
`GENAI_AGENT_CREATE`	`CreateAgent`	`POST`	`manage`
`GENAI_AGENT_DELETE`	`DeleteAgent`	`DELETE`	`manage`

Example:

allow group GenAI-agents-users to use genai-agent in compartment GenAI-agents-compartment

genai-agent-knowledge-base


Permission	API Operation	Operation Type	Verb
`GENAI_AGENT_KNOWLEDGE_BASE_INSPECT`	`ListKnowledgeBases`	`GET`	`inspect`
`GENAI_AGENT_KNOWLEDGE_BASE_READ`	`GetKnowledgeBase`	`GET`	`read`
`GENAI_AGENT_KNOWLEDGE_BASE_UPDATE`	`UpdateKnowledgeBase`	`PUT`	`use`
`GENAI_AGENT_KNOWLEDGE_BASE_MOVE`	`ChangeKnowledgeBaseCompartment`	`POST`	`manage`
`GENAI_AGENT_KNOWLEDGE_BASE_CREATE`	`CreateKnowledgeBase`	`POST`	`manage`
`GENAI_AGENT_KNOWLEDGE_BASE_DELETE`	`DeleteKnowledgeBase`	`DELETE`	`manage`

Example:

allow group GenAI-agents-users to manage genai-agent-knowledge-base in compartment GenAI-agents-compartment

genai-agent-data-source


Permission	API Operation	Operation Type	Verb
`GENAI_AGENT_DATASOURCE_INSPECT`	`ListDataSources`	`GET`	`inspect`
`GENAI_AGENT_DATASOURCE_READ`	`GetDataSource`	`GET`	`read`
`GENAI_AGENT_DATASOURCE_UPDATE`	`UpdateDataSource`	`PUT`	`use`
`AGENT_DATASOURCE_MOVE`	`ChangeDataSourceCompartment`	`POST`	`manage`
`GENAI_AGENT_DATASOURCE_CREATE`	`CreateDataSource`	`POST`	`manage`
`GENAI_AGENT_DATASOURCE_DELETE`	`DeleteDataSource`	`DELETE`	`manage`

Example:

allow group GenAI-agents-users to inspect genai-agent-data-source in compartment GenAI-agents-compartment

genai-agent-data-ingestion-job


Permission	API Operation	Operation Type	Verb
`GENAI_AGENT_DATA_INGESTION_JOB_INSPECT`	`ListDataIngestionJobs`	`GET`	`inspect`
`GENAI_AGENT_DATA_INGESTION_JOB_READ`	`GetDataIngestionJob`	`GET`	`read`
`GENAI_AGENT_DATA_INGESTION_JOB_UPDATE`	`UpdateDataIngestionJob`	`PUT`	`use`
`GENAI_AGENT_DATA_INGESTION_JOB_MOVE`	`ChangeDataIngestionJobCompartment`	`POST`	`use`
`GENAI_AGENT_DATA_INGESTION_JOB_CREATE`	`CreateDataIngestionJob`	`POST`	`manage`
`GENAI_AGENT_DATA_INGESTION_JOB_DELETE`	`DeleteDataIngestionJob`	`DELETE`	`manage`

Example:

allow group GenAI-agents-users to inspect genai-agent-data-ingestion-job in compartment GenAI-agents-compartment

genai-agent-endpoint


Permission	API Operation	Operation Type	Verb
`GENAI_AGENT_ENDPOINT_INSPECT`	`ListAgentEndpoints`	`GET`	`inspect`
`GENAI_AGENT_ENDPOINT_READ`	`GetAgentEndpoint`	`GET`	`read`
`GENAI_AGENT_ENDPOINT_UPDATE`	`UpdateAgentEndpoint`	`PUT`	`use`
`GENAI_AGENT_ENDPOINT_MOVE`	`ChangeAgentEndpointCompartment`	`POST`	`use`
`GENAI_AGENT_ENDPOINT_CREATE`	`CreateAgentEndpoint`	`POST`	`manage`
`GENAI_AGENT_ENDPOINT_CHAT`	`Chat`	`POST`	`use`
`GENAI_AGENT_ENDPOINT_DELETE`	`DeleteAgentEndpoint`	`DELETE`	`manage`

Example:

allow group GenAI-agents-users to manage genai-agent-endpoint in compartment GenAI-agents-compartment

genai-agent-work-request


Permission	API Operation	Operation Type	Verb
`GENAI_AGENT_WORK_REQUEST_INSPECT`	`ListWorkRequests`	`GET`	`inspect`
`GENAI_AGENT_WORK_REQUEST_READ`	`GetWorkRequest`	`GET`	`read`
`GENAI_AGENT_WORK_REQUEST_ERRORS_READ`	`GetWorkRequestErrors`	`GET`	`read`
`GENAI_AGENT_WORK_REQUEST_LOGS_READ`	`GetWorkRequestLogs`	`GET`	`read`

Example:

allow group GenAI-agents-users to read genai-agent-work-request in compartment GenAI-agents-compartment

genai-agent-session


Permission	API Operation	Operation Type	Verb
`GENAI_AGENT_SESSION_INSPECT`	`ListSessions`	`GET`	`inspect`
`GENAI_AGENT_SESSION_READ`	`GetSession`	`GET`	`read`
`GENAI_AGENT_SESSION_UPDATE`	`UpdateSession`	`PUT`	`use`
`GENAI_AGENT_SESSION_CREATE`	`CreateSession`	`POST`	`manage`
`GENAI_AGENT_SESSION_END`	`EndSession`	`POST`	`manage`
`GENAI_AGENT_SESSION_DELETE`	`DeleteSession`	`DELETE`	`manage`

Example:

allow group GenAI-agents-users to manage genai-agent-session in compartment GenAI-agents-compartment

Matching Permissions to API Operations

The following table lists the permissions required for Generative AI Agents API operations.

Expand this Permissions Table


API Operation	Permissions Required to Use the Operation
`ListAgents`	`GENAI_AGENT_INSPECT`
`GetAgent`	`GENAI_AGENT_READ`
`UpdateAgent`	`GENAI_AGENT_UPDATE`
`ChangeAgentCompartment`	`GENAI_AGENT_MOVE`
`CreateAgent`	`GENAI_AGENT_CREATE`
`DeleteAgent`	`GENAI_AGENT_DELETE`
`ListKnowledgeBases`	`GENAI_AGENT_KNOWLEDGE_BASE_INSPECT`
`GetKnowledgeBase`	`GENAI_AGENT_KNOWLEDGE_BASE_READ`
`UpdateKnowledgeBase`	`GENAI_AGENT_KNOWLEDGE_BASE_UPDATE`
`ChangeKnowledgeBaseCompartment`	`GENAI_AGENT_KNOWLEDGE_BASE_MOVE`
`CreateKnowledgeBase`	`GENAI_AGENT_KNOWLEDGE_BASE_CREATE`
`DeleteKnowledgeBase`	`GENAI_AGENT_KNOWLEDGE_BASE_DELETE`
`ListDataSources`	`GENAI_AGENT_DATASOURCE_INSPECT`
`GetDataSource`	`GENAI_AGENT_DATASOURCE_READ`
`UpdateDataSource`	`GENAI_AGENT_DATASOURCE_UPDATE`
`ChangeDataSourceCompartment`	`AGENT_DATASOURCE_MOVE`
`CreateDataSource`	`GENAI_AGENT_DATASOURCE_CREATE`
`DeleteDataSource`	`GENAI_AGENT_DATASOURCE_DELETE`
`ListDataIngestionJobs`	`GENAI_AGENT_DATA_INGESTION_JOB_INSPECT`
`GetDataIngestionJob`	`GENAI_AGENT_DATA_INGESTION_JOB_READ`
`UpdateDataIngestionJob`	`GENAI_AGENT_DATA_INGESTION_JOB_UPDATE`
`ChangeDataIngestionJobCompartment`	`GENAI_AGENT_DATA_INGESTION_JOB_MOVE`
`CreateDataIngestionJob`	`GENAI_AGENT_DATA_INGESTION_JOB_CREATE`
`DeleteDataIngestionJob`	`GENAI_AGENT_DATA_INGESTION_JOB_DELETE`
`ListAgentEndpoints`	`GENAI_AGENT_ENDPOINT_INSPECT`
`GetAgentEndpoint`	`GENAI_AGENT_ENDPOINT_READ`
`UpdateAgentEndpoint`	`GENAI_AGENT_ENDPOINT_UPDATE`
`ChangeAgentEndpointCompartment`	`GENAI_AGENT_ENDPOINT_MOVE`
`CreateAgentEndpoint`	`AGENAI_AGENT_ENDPOINT_CREATE`
`DeleteAgentEndpoint`	`GENAI_AGENT_ENDPOINT_DELETE`
`Chat`	`GENAI_AGENT_ENDPOINT_CHAT`
`ListSessions`	`GENAI_AGENT_SESSION_INSPECT`
`GetSession`	`GENAI_AGENT_SESSION_READ`
`UpdateSession`	`GENAI_AGENT_SESSION_UPDATE`
`CreateSession`	`GENAI_AGENT_SESSION_CREATE`
`EndSession`	`GENAI_AGENT_SESSION_END`
`DeleteSession`	`GENAI_AGENT_SESSION_DELETE`
`ListWorkRequests`	`GENAI_AGENT_WORK_REQUEST_INSPECT`
`GetWorkRequest`	`GENAI_AGENT_WORK_REQUEST_READ`
`GetWorkRequestErrors`	`GENAI_AGENT_WORK_REQUEST_ERRORS_READ`
`GetWorkRequestLogs`	`GENAI_AGENT_WORK_REQUEST_LOGS_READ`

Oracle Cloud Infrastructure Documentation

Getting Access to Generative AI Agents

Adding Policies Before You Can Use the Service

About Generative AI Agents Resource-Types

Giving Users Granular Permission for Each Resource-Type

Matching Permissions to API Operations