ORACLE CONFIDENTIAL. For authorized use only. Do not distribute to third parties.

Pre-General Availability: 2025-12-16

Installation on macOS

Follow the steps below to get your Agent Factory environment provisioned, configured, and running on macOS.

Caution: Run the installation as a non-root user. Podman must be set up and used in rootless mode for Agent Factory installations. Do not perform the installation or run deployment steps as the root user.

Step 1: Download the Kit and Prepare the Environment

Download the installation kit from artifactory

Connect to the Oracle VPN.
Unset proxies (Oracle internal).
```
unset https_proxy
```

Download the latest version of the installation kit from the Artifactory location.

For Apple Silicon (M-series) chips:

wget http://phoenix120624.dev3sub3phx.databasede3phx.oraclevcn.com:8083/applied_ai_arm64.tar.gz

For Intel chips:

wget http://phoenix120624.dev3sub3phx.databasede3phx.oraclevcn.com:8083/applied_ai.tar.gz

Untar the Zip at the Staging Location

The staging location is a designated directory that:

Stores build artifacts like executables and configuration files used to create Podman images for the application
Contains a Makefile that allows the user to manage the full deployment lifecycle

Note: While choosing the staging location, make sure it is not on an NFS mount.

Steps:

Run the following command to create the staging location.
```
mkdir <staging_location>
```

Copy and extract the downloaded kit to the staging location.

cp <path to applied_ai.tar.gz> <staging_location>
tar xzf applied_ai_arm64.tar.gz

Automated Installation (Recommended)

The interactive_install.sh script, included in the installation kit, automates nearly all setup tasks, including environment configuration, dependency installation, and application deployment.

This file will be present in the staging location once you extract the kit. Disconnect from the VPN and follow the steps below to run the script:

Run the Interactive Installer

Now that the kit is unpacked, execute the interactive_install.sh script from within the same directory.
```
cd <staging_location>
bash interactive_install.sh
```
Follow the On-Screen Prompts

The script will now guide you through the rest of the process:

Environment Detection: It will detect your operating system (Oracle Linux or macOS) and ask you to confirm your environment type.

Automated Setup: It will automatically configure Podman, set up subuids/subgids, install dependencies like podman-compose, and enable user linger mode.

Guided Steps: It will prompt you for necessary inputs, such as your username, passwords, and confirmation for key steps.

Database Preparation: If you opt for a production setup, the script will display the exact SQL commands you need to run on your database.

Application Build & Launch: Finally, the script will run the make build and make up commands to build the container images and launch the application.
Proceed to UI Setup

Once the script completes the make up step, the application will be running at https://<hostname>:8080/studio/installation. You can now proceed to the installation steps to be done from UI to finalize the configuration through your web browser.

Manual Installation

Follow the steps below for manual installation.

Note: Oracle recommends running the interactive installer included in the installation kit to automate the setup tasks instead of performing a manual installation.

Install Prerequisites
1. Disconnect from the VPN
2. If brew is not installed on your mac, install it by running the command below:
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
3. Install bash
```
brew install bash
```
4. Set your PATH to use the newly installed version of bash.
  - Add the new bash path to your shell configuration file:
  For Apple Silicon (M-series) chips, use the following command:
```
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
```
  For Intel chips, use the following command:
```
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
```
  - Reload your configuration
```
source ~/.zshrc
```
  - Verify the bash version
```
bash --version
```
  This should output a bash version >= 4.4.20.
5. Set up Podman
  
  Note: This will create a podman machine with the recommended 4 CPUs, 8GB RAM and 100GB disk size. You can adjust these values based on your system capabilities.
```
brew install podman
brew install podman-compose
podman machine init --cpus "4" --memory "8192" --disk-size "100"
podman machine start
```
6. Install wget
```
brew install wget
```
Create a database user

Note: This step is only required for a production installation and can be skipped for quickstart mode.

You will need an Oracle AI Database 26ai instance available for the Agent Factory.

Create the database user. Replace and with your desired username and password, then run the commands below.

CREATE USER <DB_USER> IDENTIFIED BY <DB_PASSWORD> DEFAULT TABLESPACE USERS QUOTA unlimited ON USERS;
GRANT CONNECT, RESOURCE, CREATE TABLE, CREATE SYNONYM, CREATE DATABASE LINK, CREATE ANY INDEX, INSERT ANY TABLE, CREATE SEQUENCE, CREATE TRIGGER, CREATE USER, DROP USER TO <DB_USER>;
GRANT CREATE SESSION TO <DB_USER> WITH ADMIN OPTION;
GRANT READ, WRITE ON DIRECTORY DATA_PUMP_DIR TO <DB_USER>;
GRANT SELECT ON V_$PARAMETER TO <DB_USER>;
exit;

Extend VARCHAR2 for self-managed Oracle AI Database

The max_string_size database parameter must be set to EXTENDED before running the application. The max_string_size parameter for the DB should be extended to 32K before running the application.
1. Log in as the SYSDBA user to your PDB (Pluggable Database) using SQL*Plus or your preferred tool.
2. Check the current value of the parameter:
```
SELECT value FROM v$parameter WHERE name = 'max_string_size';
```
3. If the output is already EXTENDED, no further action is needed. Otherwise, run the following script as the SYSDBA user. This sequence will restart the database.
```
ALTER SYSTEM SET max_string_size=extended SCOPE=SPFILE;

SHUTDOWN NORMAL;
STARTUP UPGRADE;

@$ORACLE_HOME/rdbms/admin/utl32k.sql

SHUTDOWN IMMEDIATE;
STARTUP;

@$ORACLE_HOME/rdbms/admin/utlrp.sql
```
4. If you are using a multitenant CDB or PDB architecture, repeat the following for the PDB where the application schema will be installed:
  1. From the CDB root, open the PDB in UPGRADE mode.
    ALTER PLUGGABLE DATABASE <PDB_NAME> OPEN UPGRADE;
  2. Switch your session to the PDB.
    ALTER SESSION SET CONTAINER=<PDB_NAME>;
  3. Run the migration script in the PDB.
    @$ORACLE_HOME/rdbms/admin/utl32k.sql
  4. Switch back to CDB root.
    ALTER SESSION SET CONTAINER=CDB$ROOT;
  5. Close and then open the PDB.
    ALTER PLUGGABLE DATABASE <PDB_NAME> CLOSE IMMEDIATE; ALTER PLUGGABLE DATABASE <PDB_NAME> OPEN;
5. Switch to the PDB, and verify that the change was successful. The output of this query must be EXTENDED.
```
SELECT value FROM v$parameter WHERE name = 'max_string_size';
```

Step 2: Install and Launch Agent Factory

Installation from Source

Installation from source can be performed in two modes: prod and quickstart. For installation using the prod mode, you need your own 26ai database user, while the quickstart mode brings up the containerised form of Oracle AI database 26ai.

Note: Refer to the Installation Modes if you are unsure which installation mode to choose.

Follow the steps below to perform the installation in prod mode.

Disconnect from the Oracle VPN.
Unset proxies (Oracle internal).
Go to the staging location where you have copied the kit in Step 1.
```
cd <staging_location>
```
Untar kit.
```
tar xzf applied_ai.tar.gz
```
Create the images required to run the application.

Note: This step can be skipped by checking if you have the latest Private AI image already present using the command podman images
```
make build
```

For deployment in prod mode, type 1 when prompted to choose the install mode.

Select installation mode:
1) prod
2) quickstart
Enter choice (1 or 2): 1

Building the images necessary in Production mode

You selected Production mode. Confirm? (yes/no) [yes]: yes

Building Applied AI Image...

Bring the containers up.

make up

The following is the output for a prod installation. We can see the ollama-server-label was not built.

Oracle Agent Factory
Starting deployment mode determination...
[checkmark] Image 'localhost/applied-ai-label:latest' found.
[checkmark] Image 'localhost/applied-ai-label:latest' found.
Only Production mode deployment is possible.
Deploying Agent Factory in Production mode...
Initiating startup for oracle-applied-ai-label container...
[checkmark] oracle-applied-ai-label container is UP and RUNNING.
-Please wait while the application is being set up within oracle-applied-ai-label container...
Application setup successfully within the container 'oracle-applied-ai-label'.
-Configuring application container: oracle-applied-ai-label...
[checkmark] Application container oracle-applied-ai-label configured successfully.
[checkmark] Production deployment complete.

Note: The user can monitor Agent Factory installation logs by running: make logsaai

Once installation is complete, you can access the application at:
```
https://<hostname>:8080/studio/installation
```

Installation Steps from the User Interface

Accessing the application URL for the first time in prod mode would bring up the UI based installation flow.

Database Configuration Options

Provide your database connection details in either of the three formats and click Test Connection to verify that the information entered is correct. Upon a successful connection, you will see a Database connection successful notification.

Format 1: Enter all the connection details manually

Manual Database Configuration

Description of the illustration install-step-2-db-config-1.png

Format 2: Enter the database connection String

Database Configuration Using Connection String

Description of the illustration install-step-2-db-config-2.png

Format 3: Upload a database wallet file

Database Configuration Using Wallet File

Description of the illustration install-step-2-db-config-3.png

LLM Configuration Options

Choose an LLM - Ollama, vLLM, OpenAI, or OCI GenAI to configure a generative model. See Configure LLM for more details on the LLM configurations.

LLM Configuration

Description of the illustration install-step-llm-config.png

Enter the required details in the selected LLM configuration and select Test Connection. Once you see the Connection successful message, select Save Configuration.

Optionally, configure an embedding model to use for data ingestion and retrieval. By default, cohere-embed-multilingual-light-v3.0 model is used to generate embeddings and is also the local embedding model included with the service.

Pre-built Knowledge Assistants currently support only Large Language Models (LLMs) from the OCI Generative AI Service. To ensure proper functionality of the pre-built knowledge agents, select from the following embedding models.

cohere.embed-multilingual-light-v3.0
cohere.embed-english-v3.0
cohere.embed-multilingual-v3.0

Finally, select Finish Installation to complete the setup and be redirected to the login page.

Import Certificates into the Container (Optional)

Follow the steps below to import certificates into the oracle-applied-ai-label container.

Copy certificate and key files into the container.

podman cp <cert_file> oracle-applied-ai-label:/tmp
podman cp <key_file> oracle-applied-ai-label:/tmp

Enter the container.

podman exec -it oracle-applied-ai-label bash

Run the import command.

cd /home/aaiuser/install
./aai importcert -cert /tmp/<cert_file> -key /tmp/<key_file>