# 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 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 CONNECT, RESOURCE TO ;
GRANT CREATE SESSION TO WITH ADMIN OPTION;
GRANT CREATE TABLE, CREATE SYNONYM, CREATE SEQUENCE, CREATE TRIGGER TO ;
GRANT CREATE USER, DROP USER TO ;
GRANT READ, WRITE ON DIRECTORY DATA_PUMP_DIR TO ;
GRANT SELECT ON V_$PARAMETER TO ;
CREATE USER AAI_RO_ IDENTIFIED BY "" ACCOUNT UNLOCK;
GRANT CREATE SESSION TO AAI_RO_;
```
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 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
```
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 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 \
```
## 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. To expose the UI only on the
local host, use `-p 127.0.0.1:8080:8080` in place of `-p 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
```
## 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` |
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 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.
## 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_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`. |