# Introducing Oracle AI Database Private Agent Factory
Oracle AI Database Private Agent Factory is an out-of-box no-code AI Agent building, testing and deployment framework Using oracle AI Database vector search to discover/uncover the knowledge from structured and unstructured enterprise data
Some of the key features of this product will be
1. Ability to create, train and Deploy agents with access to customer business data
2. Using Oracle AI Agent Memory for a persistent, context-aware capability for AI agents that retain relevant information across interactions to personalize responses, improve continuity, and make better decisions over time.
3. Integrated with customers security procedures using federated identify providers for authentication and authorization
4. Agent Factory A2A enables trusted agents to work together across organizational boundaries and with any agentic solution that supports the A2A protocol. Users can share selected agents built in Agent Factory with authorized external agents or connect external A2A agents to their workflows.
5. Revolutionize the document analysis using RAG(retrieve and generate)
6. Structured Data exploration to uncover business critical insights and trends from structured database stored in customers data warehouse.
7. Prompt lab to experiment and innovate with various prompt technologies, store perfected prompts, and deploy prompts to use the power of LLM for building workflows
# Using the image
This image runs a self-contained Private Agent Factory deployment. On its first
start it bootstraps the application using a persistent application volume, a
runtime configuration file, and mounted secret files.
## Prerequisites
Before starting the container, prepare the following:
* Podman and an image reference from Oracle Container Registry.
* A persistent Podman volume mounted at `/mount`.
* A `runtime.env` file with the non-secret runtime configuration.
* Podman secrets for the initial administrator password and database password.
* A target PDB with both a runtime database user and its read-only user.
The target database must have `MAX_STRING_SIZE` set to `EXTENDED` (32K) before
the application is installed. Sign in to the target PDB as `SYSDBA` and check
the current setting:
```sql
SELECT value FROM SYS.V_$PARAMETER WHERE name = 'max_string_size';
```
If the result is already `EXTENDED`, continue to the user-creation steps. If
not, run the following sequence as `SYSDBA`. It restarts the database:
```sql
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
```
The read-only user must be named `AAI_RO_
` and use the same password
as the runtime user. Connect to the target PDB as an administrative user, then
adapt and run the following SQL:
```sql
CREATE USER IDENTIFIED BY ""
DEFAULT TABLESPACE USERS QUOTA UNLIMITED ON USERS;
GRANT CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE TRIGGER,
CREATE TYPE, CREATE PROCEDURE, CREATE VIEW, CREATE SYNONYM,
CREATE JOB TO ;
GRANT READ, WRITE ON DIRECTORY DATA_PUMP_DIR TO ;
GRANT SELECT ON SYS.V_$PARAMETER TO ;
GRANT CTXAPP TO ;
GRANT EXECUTE ON CTXSYS.CTX_DDL TO ;
GRANT SELECT ON SYS.V_$SQL_PLAN TO ;
GRANT EXECUTE ON SYS.DBMS_AQ TO ;
GRANT EXECUTE ON SYS.DBMS_AQADM TO ;
CREATE USER AAI_RO_ IDENTIFIED BY "" ACCOUNT UNLOCK;
GRANT CREATE SESSION TO AAI_RO_;
```
For Autonomous Database, use the database's applicable default tablespace
(for example, `DATA`) and grant unlimited quota on that tablespace instead of
`USERS`. Use the schema-qualified `SYS.V_$PARAMETER` grant shown above for
both Autonomous and non-Autonomous databases; do not substitute `V$PARAMETER`.
The initial administrator password must contain at least eight characters,
including an uppercase ASCII letter, a decimal digit, and a character from
`-+_!@#$%^&*.,?`.
## Quick start
Create a volume and the required Podman secrets. Replace the placeholder values
with the values for your environment.
```bash
podman volume create agentfactory_selfcontained_mount
printf '%s' '' | podman secret create agent_factory_admin_password -
printf '%s' '' | podman secret create agent_factory_db_password -
mkdir -p config
```
### Details mode
Use Details mode when the image connects through the database host, port, and
service name. Create `config/runtime.env`:
```ini
AGENT_FACTORY_MODE=prod
AGENT_FACTORY_SILENT_INSTALL=true
AGENT_FACTORY_ADMIN_USERNAME=admin@example.com
AGENT_FACTORY_DB_CONNECTION_TYPE=Details
AGENT_FACTORY_DB_USERNAME=
AGENT_FACTORY_DB_IS_AIR_GAPPED=no
AGENT_FACTORY_DB_USES_WALLET=no
AGENT_FACTORY_DB_WALLET_HAS_OCI_CERTIFICATES=no
AGENT_FACTORY_DB_PROTOCOL=TCP
AGENT_FACTORY_DB_HOST=
AGENT_FACTORY_DB_PORT=1521
AGENT_FACTORY_DB_SERVICE_NAME=
AGENT_FACTORY_BIND_HOST=0.0.0.0
```
Start the container:
```bash
podman run -d \
--name oracle-applied-ai-selfcontained \
-p 0.0.0.0:8080:8080 \
-v agentfactory_selfcontained_mount:/mount:Z \
-v "$PWD/config/runtime.env:/etc/agent-factory/runtime.env:ro,Z" \
--secret agent_factory_admin_password \
--secret agent_factory_db_password \
```
### Wallet mode
Use Wallet mode when the image connects through a database wallet. Create the
wallet secret first:
```bash
podman secret create db_wallet.zip
```
If the wallet contains an encrypted `ewallet.pem`, also provide its wallet
password. Store the exact password in an owner-only file with **no trailing
newline**, then create the secret from that file:
```bash
podman secret create agent_factory_db_wallet_password /secure/path/wallet_password
```
Create `config/runtime.env` with the selected TNS alias:
```ini
AGENT_FACTORY_MODE=prod
AGENT_FACTORY_SILENT_INSTALL=true
AGENT_FACTORY_ADMIN_USERNAME=admin@example.com
AGENT_FACTORY_DB_CONNECTION_TYPE=Wallet
AGENT_FACTORY_DB_USERNAME=
AGENT_FACTORY_DB_IS_AIR_GAPPED=no
AGENT_FACTORY_DB_USES_WALLET=yes
AGENT_FACTORY_DB_WALLET_HAS_OCI_CERTIFICATES=yes
AGENT_FACTORY_DB_SELECTED_TNS_ALIAS=
AGENT_FACTORY_BIND_HOST=0.0.0.0
```
Start the container with the wallet secret:
```bash
podman run -d \
--name oracle-applied-ai-selfcontained \
-p 0.0.0.0:8080:8080 \
-v agentfactory_selfcontained_mount:/mount:Z \
-v "$PWD/config/runtime.env:/etc/agent-factory/runtime.env:ro,Z" \
--secret agent_factory_admin_password \
--secret agent_factory_db_password \
--secret db_wallet.zip \
--secret agent_factory_db_wallet_password \
```
Omit `--secret agent_factory_db_wallet_password` if the wallet does not require
a password.
## Access and verify
Monitor bootstrap until it completes:
```bash
podman logs -f oracle-applied-ai-selfcontained
```
> **Important:** Do not access the web UI until bootstrap has finished.
After bootstrap completes, open `https://:8080` and sign in
with the administrator username from `runtime.env` and the password supplied
through the `agent_factory_admin_password` secret. The examples publish the
application on all IPv4 host interfaces (`0.0.0.0:8080:8080`).
## Persistence and repeat runs
The `/mount` volume persists application data and installation state. Restart a
previously installed deployment by starting a container with the same volume.
For a clean deployment, use a new volume, or remove the old container and its
volume before creating the volume again. A clean deployment also requires new
runtime and read-only database users, or recreating the existing users by
dropping and creating them again before starting the image.
```bash
podman rm -f oracle-applied-ai-selfcontained
podman volume rm agentfactory_selfcontained_mount
podman volume create agentfactory_selfcontained_mount
```
### Upgrade an existing image deployment
Ensure the database user has the grants listed in **Prerequisites**. Pull the
new image and stop all Agent Factory containers connected to the same database.
Keep the database running.
```bash
podman pull
podman stop [ ...]
```
Start a new container with the existing application volume and the `upgrade`
command. Replace the volume name below with your existing volume name;
preserve its contents and the existing database users.
```bash
podman run -d \
--name oracle-applied-ai-upgraded \
--network bridge \
-p 0.0.0.0:8080:8080 \
-v agentfactory_selfcontained_mount:/mount:Z \
upgrade
podman logs -f oracle-applied-ai-upgraded
```
If an encrypted database wallet needs a password that has not already been
saved, add `--secret agent_factory_db_wallet_password` as described in
**Wallet mode**. Retain any proxy or network settings needed by your deployment.
Wait for the upgrade to complete, then open the application and sign in with
your existing credentials.
## Runtime configuration and secrets
The default in-container input locations are:
| Input | Default location |
| --- | --- |
| Runtime configuration | `/etc/agent-factory/runtime.env` |
| Secret directory | `/run/secrets` |
| Administrator password | `/run/secrets/agent_factory_admin_password` |
| Database password | `/run/secrets/agent_factory_db_password` |
| Database wallet | `/run/secrets/db_wallet.zip` |
| Database wallet password (encrypted wallet) | `/run/secrets/agent_factory_db_wallet_password` |
| Custom server certificate/chain (optional) | `/run/secrets/agent_factory_server_certificate.pem` |
| Custom server private key (optional) | `/run/secrets/agent_factory_server_private_key.pem` |
For a custom runtime-file location, pass the location to the container and
mount the file at that path:
```bash
podman run -d \
--name oracle-applied-ai-selfcontained \
-p 0.0.0.0:8080:8080 \
-e AGENT_FACTORY_RUNTIME_ENV_PATH=/agent-factory-input/runtime.env \
-v agentfactory_selfcontained_mount:/mount:Z \
-v "$PWD/config/runtime.env:/agent-factory-input/runtime.env:ro,Z" \
--secret agent_factory_admin_password \
--secret agent_factory_db_password \
```
If you mount a secrets directory instead of using Podman secrets, set
`AGENT_FACTORY_RUNTIME_SECRETS_DIR` to its absolute in-container path.
For a fresh installation with a custom inbound HTTPS certificate, supply both
secrets together:
```bash
podman secret create agent_factory_server_certificate.pem /secure/path/fullchain.pem
podman secret create agent_factory_server_private_key.pem /secure/path/private-key.pem
```
Add `--secret agent_factory_server_certificate.pem` and
`--secret agent_factory_server_private_key.pem` to the fresh-install command.
The certificate must be PEM (leaf certificate first when supplying a chain),
and its matching private key must be unencrypted PEM. The default filenames
above are recognized automatically. For different secret filenames, set
`AGENT_FACTORY_SERVER_CERTIFICATE_FILE` and
`AGENT_FACTORY_SERVER_PRIVATE_KEY_FILE` in `runtime.env`; these values must be
filenames under the runtime secrets directory, without directory separators.
When no custom pair is supplied, the application generates its default pair.
## Optional LLM bootstrap
LLM bootstrap is optional. Leave `AGENT_FACTORY_LLM_PROVIDER` unset to install
the base application without configuring an LLM. You can also configure an LLM
later from the web UI after the application is deployed.
When configured during bootstrap, select one provider with
`AGENT_FACTORY_LLM_PROVIDER`. Supported values are `oci`, `vllm`, `openai`,
`openai_compatible`, `private_ai_services`, `ollama`, and `google`. Add the
provider's non-secret settings to `runtime.env` and add any required credential
files as Podman secrets to the `podman run` command.
| Provider | Typical required settings | Optional or required secret file |
| --- | --- | --- |
| OCI GenAI | model ID, service endpoint, compartment ID | API-key mode also uses fingerprint and private-key files |
| vLLM | model ID, host, port | `agent_factory_llm_vllm_api_key` when required |
| OpenAI | model ID | `agent_factory_llm_openai_api_key` |
| OpenAI-compatible | model ID, base URL | `agent_factory_llm_openai_compatible_api_key` when required |
| Oracle Private AI Services | model ID, base URL | API key and CA files when required |
| Ollama | model ID, host, port | None |
| Google Gemini | model ID and credentials type | API key or service-account JSON |
For example, to configure OpenAI at bootstrap, add the following to
`runtime.env` and create the matching secret:
```ini
AGENT_FACTORY_LLM_PROVIDER=openai
AGENT_FACTORY_LLM_NAME=llm_model_entry
AGENT_FACTORY_LLM_OPENAI_MODEL_ID=
AGENT_FACTORY_LLM_OPENAI_API_KEY_FILE=agent_factory_llm_openai_api_key
```
```bash
printf '%s' '' | podman secret create agent_factory_llm_openai_api_key -
```
Then add `--secret agent_factory_llm_openai_api_key` to the `podman run`
command.
## Configuration reference
### Core keys
| Key | Required | Description |
| --- | --- | --- |
| `AGENT_FACTORY_MODE` | Yes | Set to `prod`. |
| `AGENT_FACTORY_SILENT_INSTALL` | Yes | Set to `true` for bootstrap installation. |
| `AGENT_FACTORY_ADMIN_USERNAME` | Yes | Initial administrator username or email. |
### Database keys
| Key | Required | Description |
| --- | --- | --- |
| `AGENT_FACTORY_DB_CONNECTION_TYPE` | Yes | `Details` or `Wallet`. |
| `AGENT_FACTORY_DB_USERNAME` | Yes | Runtime database user. |
| `AGENT_FACTORY_DB_IS_AIR_GAPPED` | Yes | `yes` or `no`. |
| `AGENT_FACTORY_DB_USES_WALLET` | Yes when not air-gapped | `yes` for Wallet mode; `no` for Details mode. |
| `AGENT_FACTORY_DB_WALLET_HAS_OCI_CERTIFICATES` | When using a wallet | `yes` or `no`. |
| `AGENT_FACTORY_DB_PROTOCOL` | Details mode | `TCP` or `TCPS`. |
| `AGENT_FACTORY_DB_HOST` | Details mode | Database host. |
| `AGENT_FACTORY_DB_PORT` | Details mode | Database listener port. |
| `AGENT_FACTORY_DB_SERVICE_NAME` | Details mode | Database service name. |
| `AGENT_FACTORY_DB_SELECTED_TNS_ALIAS` | Wallet mode | TNS alias in the supplied wallet. |
### Web and operational keys
| Key | Default | Description |
| --- | --- | --- |
| `AGENT_FACTORY_BIND_HOST` | `0.0.0.0` | Application bind host inside the container. |
| `AGENT_FACTORY_CERT_FQDN` | Unset | Certificate FQDN override. |
| `AGENT_FACTORY_CERT_IP_ADDRESS` | Unset | Certificate IP address override. |
| `AGENT_FACTORY_SERVER_CERTIFICATE_FILE` | `agent_factory_server_certificate.pem` | Optional custom inbound PEM certificate/chain secret filename; supply with the private key. |
| `AGENT_FACTORY_SERVER_PRIVATE_KEY_FILE` | `agent_factory_server_private_key.pem` | Optional matching unencrypted PEM private-key secret filename; supply with the certificate. |
| `AGENT_FACTORY_ENABLE_SWAGGER` | Unset | Swagger enablement setting. |
| `AGENT_FACTORY_STATE_POLL_INTERVAL_SECONDS` | `5` | Bootstrap state polling interval. |
| `AGENT_FACTORY_API_READY_TIMEOUT_SECONDS` | `600` | Local API availability timeout. |
| `AGENT_FACTORY_INSTALL_TIMEOUT_SECONDS` | `1800` | Installation completion timeout. |
| `AGENT_FACTORY_READY_TIMEOUT_SECONDS` | `600` | Final readiness timeout. |
| `AGENT_FACTORY_HTTP_PROXY` | Unset | HTTP proxy. |
| `AGENT_FACTORY_HTTPS_PROXY` | Unset | HTTPS proxy. |
| `AGENT_FACTORY_NO_PROXY` | Unset | No-proxy host list. |
### LLM keys
Configure at most one LLM provider for bootstrap. The secret-file values below
may be absolute paths or filenames in the runtime secrets directory.
| Key | Required | Description |
| --- | --- | --- |
| `AGENT_FACTORY_LLM_PROVIDER` | No | Selects `oci`, `vllm`, `openai`, `openai_compatible`, `private_ai_services`, `ollama`, or `google`. |
| `AGENT_FACTORY_LLM_NAME` | No | LLM configuration name. Defaults to `llm_model_entry`. |
#### OCI GenAI
| Key | Required | Description |
| --- | --- | --- |
| `AGENT_FACTORY_LLM_OCI_MODEL_ID` | Yes | OCI model ID. |
| `AGENT_FACTORY_LLM_OCI_SERVICE_ENDPOINT` | Yes | OCI GenAI service endpoint. |
| `AGENT_FACTORY_LLM_OCI_COMPARTMENT_ID` | Yes | OCI compartment OCID. |
| `AGENT_FACTORY_LLM_OCI_USER_OCID` | API-key mode | OCI user OCID. |
| `AGENT_FACTORY_LLM_OCI_FINGERPRINT_FILE` | API-key mode | Fingerprint secret file; default name `agent_factory_llm_oci_fingerprint`. |
| `AGENT_FACTORY_LLM_OCI_TENANCY_OCID` | API-key mode | OCI tenancy OCID. |
| `AGENT_FACTORY_LLM_OCI_REGION` | API-key mode | OCI region. |
| `AGENT_FACTORY_LLM_OCI_PRIVATE_KEY_FILE` | API-key mode | Private-key secret file; default name `agent_factory_llm_oci_private_key.pem`. |
#### vLLM
| Key | Required | Description |
| --- | --- | --- |
| `AGENT_FACTORY_LLM_VLLM_MODEL_ID` | Yes | Model ID. |
| `AGENT_FACTORY_LLM_VLLM_HOST` | Yes | vLLM host or base host. |
| `AGENT_FACTORY_LLM_VLLM_PORT` | Yes | vLLM port. |
| `AGENT_FACTORY_LLM_VLLM_API_KEY_FILE` | No | API-key secret file when required; default name `agent_factory_llm_vllm_api_key`. |
#### OpenAI
| Key | Required | Description |
| --- | --- | --- |
| `AGENT_FACTORY_LLM_OPENAI_MODEL_ID` | Yes | OpenAI model ID. |
| `AGENT_FACTORY_LLM_OPENAI_API_KEY_FILE` | Yes | API-key secret file; default name `agent_factory_llm_openai_api_key`. |
#### OpenAI-compatible
| Key | Required | Description |
| --- | --- | --- |
| `AGENT_FACTORY_LLM_OPENAI_COMPATIBLE_MODEL_ID` | Yes | Model ID. |
| `AGENT_FACTORY_LLM_OPENAI_COMPATIBLE_BASE_URL` | Yes | OpenAI-compatible base URL. |
| `AGENT_FACTORY_LLM_OPENAI_COMPATIBLE_API_KEY_FILE` | No | API-key secret file when required; default name `agent_factory_llm_openai_compatible_api_key`. |
#### Oracle Private AI Services
| Key | Required | Description |
| --- | --- | --- |
| `AGENT_FACTORY_LLM_PRIVATE_AI_SERVICES_MODEL_ID` | Yes | Model ID. |
| `AGENT_FACTORY_LLM_PRIVATE_AI_SERVICES_BASE_URL` | Yes | Service base URL. |
| `AGENT_FACTORY_LLM_PRIVATE_AI_SERVICES_API_KEY_FILE` | No | API-key secret file when required; default name `agent_factory_llm_private_ai_services_api_key`. |
| `AGENT_FACTORY_LLM_PRIVATE_AI_SERVICES_CA_FILE` | No | Custom CA secret file when required; default name `agent_factory_llm_private_ai_services_ca.pem`. |
#### Ollama
| Key | Required | Description |
| --- | --- | --- |
| `AGENT_FACTORY_LLM_OLLAMA_MODEL_ID` | Yes | Ollama model ID. |
| `AGENT_FACTORY_LLM_OLLAMA_HOST` | Yes | Ollama host. |
| `AGENT_FACTORY_LLM_OLLAMA_PORT` | Yes | Ollama port. |
#### Google Gemini
| Key | Required | Description |
| --- | --- | --- |
| `AGENT_FACTORY_LLM_GOOGLE_MODEL_ID` | Yes | Google model ID. |
| `AGENT_FACTORY_LLM_GOOGLE_CREDENTIALS_TYPE` | Yes | `API_KEY` or `GOOGLE_SERVICE_ACCOUNT`. |
| `AGENT_FACTORY_LLM_GOOGLE_API_KEY_FILE` | API-key mode | API-key secret file; default name `agent_factory_llm_google_api_key`. |
| `AGENT_FACTORY_LLM_GOOGLE_REGION` | Service-account mode | Google region. |
| `AGENT_FACTORY_LLM_GOOGLE_SERVICE_ACCOUNT_FILE` | Service-account mode | Service-account JSON secret file; default name `agent_factory_llm_google_service_account.json`. |