Frequently Asked Questions (FAQs) and Troubleshooting

Installation and Upgrade

How do I configure Agent Factory with a 26ai Database?

Follow the steps in the setup guide to connect Agent Factory to Oracle AI Database 26ai. See Configure Database Connection.

How do I start the application after the application host has been rebooted?

Run the make start command from the staging directory.

cd <staging directory>
make start

Where should helper commands be run after an upgrade?

After completing an upgrade, all helper commands such as make start, make diagnose, and make uninstall must be executed from the new staging directory. Using the old staging directory may lead to inconsistencies or unexpected behavior.

How do I reinstall the application after uninstalling a previous installation?

A fresh installation must always be done in a new location by following these steps:

  1. Untar the provided .tar.gz kit into a fresh directory.

  2. Run bash interactive_install.sh --reset

  3. Run bash interactive_install.sh

This ensures a clean setup without conflicts from previous installations.

What should I do if an upgrade repeatedly fails on macOS?

If an upgrade fails multiple times on macOS, it may be due to leftover containers or images from a previous attempt. You can resolve this by cleaning them up and retrying the upgrade:

  1. Remove the existing container: 
    podman rm -f oracle-applied-ai-label-old
  2. Remove the related image: 
    podman rmi -f localhost/applied-ai-label_snapshot
  3. Retry the upgrade process.

This cleanup helps eliminate conflicts caused by stale resources and allows the upgrade to proceed successfully.

During OCI deployment, are there any additional considerations I have to take into account?

Yes. If you are using a load balancer, make sure to increase the timeout to at least 10 minutes. Otherwise, you may face issues during installation.

Seems I’m no longer able to log in with my credentials

Make sure not to copy and paste passwords into the sign-up page, as they may contain hidden Unicode characters. It is recommended to manually type your email and password to avoid access issues.

My company has an existing OCI account but I am not an administrator.

When signing up for a Free Tier account, by default your account is in the Administrators group. However, if your company has an existing OCI account and you are not in the Administrators group, ask your administrator to assign you with the following policy:

allow group <your-group-name> to manage generative-ai-family in compartment <your-compartment>

For more information see Getting access to generative AI.

What if I receive a message like ‘no space available on device’ during installation?

This error can occur due to low space in the /tmp directory.

What are the space and RAM requirements?

Environment Recommended Disk Space Recommended RAM
Quickstart 30 GB 10 GB
Production 10 GB 8 GB

What is the difference between Production and Quickstart installations?

Production mode allows you to manually set up the database and LLM endpoint details. This setup empowers you to use your own credentials and connect with the supported LLM providers such as vLLM, OpenAI, Ollama, Google, and the full catalogue of pre-trained foundational models that OCI GenAI offers. Resource usage: about 10 GB of device storage and 8 GB of RAM.

Quickstart mode sets up instances of an Oracle AI Database 26ai free, via containers that operate locally within the same environment. This allows you to start using Agent Factory without setting up the database. Resource usage: about 30 GB of device storage and 10 GB of RAM.

Summary

Feature Quickstart Production
Setup Automated, local containers Manual, user-provided endpoints
Database Oracle AI Database 26ai Free User’s Oracle AI Database 26ai
LLM User selected LLM (Ollama/OpenAI/vLLM/Google/OCI Gen AI) User selected LLM (Ollama/OpenAI/vLLM/Google/OCI Gen AI)
Storage Usage 30 GB 10 GB
RAM Usage 10 GB 8 GB
Ports Used 1521, 11434 (+8080 always) 8080

What platforms does the application support?

The currently supported operating systems are:

What ports does the application use?

By default, the container running Oracle AI Database Private Agent Factory uses port 8080.

If you install on Quickstart mode, the Oracle AI Database 26ai free instance runs on port 1521. Ensure that these ports are available on your system to avoid installation issues.

What are the prerequisites to install the application?

Regardless of platform, the following prerequisites are required:

Oracle AI Database 26ai. You will need access to an instance of Oracle AI Database 26ai. It is recommended to create a dedicated user for this purpose. This user should be used exclusively for managing these tables and not for storing production data.

LLM endpoint. The Oracle AI Database Private Agent Factory relies on integration with a Large Language Model to function properly. You will require appropriate authentication credentials or an access key to connect the application with an available LLM instance of your choice.

What database versions are supported?

Oracle AI Database Private Agent Factory requires an Oracle AI Database 26ai, both Self-managed and Autonomous instances.

The max_string_size database parameter must be set to EXTENDED before running the application.

What privileges must the database user have to use the application?

The database user required for the application set up requires the following privileges. Replace <DB_USER> and <DB_PASSWORD> 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 CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE TRIGGER, CREATE TYPE, CREATE PROCEDURE, CREATE VIEW, CREATE SYNONYM TO <DB_USER>;
GRANT READ, WRITE ON DIRECTORY DATA_PUMP_DIR TO <DB_USER>;
GRANT SELECT ON V$PARAMETER TO <DB_USER>;
CREATE USER AAI_RO_<DB_USER> IDENTIFIED BY <SAME_DB_PASSWORD_AS_DB_USER> ACCOUNT UNLOCK;
GRANT CREATE SESSION TO AAI_RO_<DB_USER>;
exit;

For Autonomous Database, use V_$PARAMETER instead of V$PARAMETER in the above code block.

How to extend the max_string_size database parameter?

  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 multi-tenant (CDB/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';

Why do I see an insecure connection warning “Your connection is not private” when accessing the Agent Factory application?

By default, the Agent Factory web page uses self-signed SSL certificates. Some web browsers show a warning for self-signed certificates because they are not trusted by default, but this does not impact the application’s functionality. See Adding your own SSL certificates to remove the warning by installing your own certificates issued by a trusted certificate authority (CA).

How do I troubleshoot the installation failure of the Oracle AI Database Private Agent Factory Knowledge Assistant?

The Oracle AI Database Private Agent Factory Knowledge Assistant is optional. It answers questions about Agent Factory documentation, and skipping it does not affect the Agent Factory application or the Knowledge Agent component.

To install the assistant when using database wallets, the database environment must not be air-gapped and must be able to access OCI Object Storage using Pre-Authenticated Request (PAR) files.

See Create SSL Wallet with Certificates for more details.

MCP Server

I see “Authentication required” error

Set authType to Bearer or Basic and supply valid credentials. For OAuth, ensure server URL points to the /mcp endpoint and the token is not expired.

I see 404 error

The serverUrl’s path is likely wrong. Use the correct MCP endpoint path such as /mcp, /mcp/jsonrpc, or your server’s documented route.

Can we attach more than one MCP server to a single agent? How does the agent determine which MCP server to call and which tool to execute?

Yes, you can attach multiple MCP Servers to a single Agent. The LLM will select the appropriate server and tool based on each tool’s description and how well it matches the user’s query. Even when multiple tools are available, the model chooses the most relevant tool for the request.

Does MCP server support streamable HTTP?

Yes. StreamableHTTPTransport with auth is supported and recommended for OAuth/Bearer-secured servers.

Custom Agents

Is the custom agent conversational or stateless?

LLMs in Agent builder support conversational memory. Knowledge Agents are currently stateless, meaning they respond to one question at a time.

Can we connect sub-agents to an Agent?

Yes, you can attach multiple sub-agents to a single agent. The main agent orchestrates and coordinates with the sub-agents, selects the correct sub-agent based on the user’s query, and aggregates the final response.

Can I provide a custom knowledge base when building a custom agent?

Yes, you can provide custom knowledge bases when building a Knowledge Agent. Knowledge bases can be created using web sources, file systems, Google Drive, SharePoint, or Amazon S3.

Is schema-level data exploration supported in the Data Analysis Agent?

Not yet. Today, data exploration is supported at the table and view levels. Schema-level exploration is on the roadmap.

Does Agent Factory support agent-to-agent protocols across external platforms and within OCI?

Not at this time. This capability is on the roadmap.

Will the LLM container be based on Ollama?

Agent Factory supports multiple serving options, including Ollama, vLLM, OCI Generative AI, and OpenAI.

Is there an additional license cost for on‑premises use, or is it included with the database?

It is included. Agent Factory is a no‑cost add‑on to the Oracle AI Database 26ai.

Can the container run in Exadata environments (ExaCC, ExaCS, Exadata on‑prem)?

Supported on Exadata VM-based deployments where a supported container runtime (e.g., Podman) is available. It is not supported on bare Exadata database nodes. Consult the latest platform support matrix for details.

How can customers control who can set up or connect data sources? Is there role-based authorization?

Yes. Agent Factory includes user management with three roles: Chat-only Users, Editors, and Administrators, enabling separation of duties across the AI agent lifecycle.

After prototyping in Agent Factory, where does the agent run?

The agent runs in its own container. It connects to the Oracle AI Database and to an LLM service (e.g., via vLLM/Ollama or directly to services like OCI Generative AI or OpenAI).

Can applications call Agent Factory APIs so users can interact with agents from web pages?

Yes. Published agents expose a REST API that applications can call to invoke agent flows/workflows. See Integration Options (API Endpoint URL).

Can multiple agents collaborate to answer prompts?

Yes. Multi‑agent patterns are supported.

Can I use an SLM instead of an LLM?

Yes. You can use a variety of model sizes and providers supported via vLLM, Ollama, OCI Generative AI, and OpenAI.

Is the Agent Factory container available for multicloud deployments?

Yes. Agent Factory runs wherever the Oracle AI Database runs.

Can annotations with metadata be generated automatically?

Annotations can currently only be configured manually. Automatic annotation generation will be available in future releases. See AI Enrichment.

Can I migrate workflows from other agent platforms?

Yes, provided they conform to open agent specifications. See Import Flows from External Frameworks.

How are agents and flows monitored?

Administrators can configure observability to export flow and agent execution traces to Arize Phoenix, Langfuse, or Comet Opik. These traces include spans for flow steps, LLM calls, tool executions, latency, status, and token usage. See Configure Observability.

How can I generate the diagnostic zip for troubleshooting?

Use the Collect Diagnostics option in the About dialog to download application logs as a ZIP file. See Collect Diagnostics for more details.

For host-level diagnostics, navigate to the staging directory where the application was installed and run make diagnose. This command generates a diagnostic ZIP file that contains logs and system information.

Data Sources

What are the ingestion stages for a data source?

When Agent Factory ingests a data source, it runs the following stages: CRAWLING, PARSING, STORING_CONTENT, CHUNKING, EMBEDDING, INDEX_REBUILD, and INGESTED. These stages mean that Agent Factory is crawling the source, parsing the content, and storing document metadata and content in the database. It then chunks the content, generates embeddings, creates or rebuilds the vector index, and marks ingestion as complete. Re-ingestion is possible only after the configured frequency has elapsed since the last ingested date.

What does the STATIC_SNAPSHOT data source status mean?

The STATIC_SNAPSHOT status means that data source re-ingestion is disabled, but the data source can still be queried through knowledge bases that contain it using the last ingested snapshot.

What does the DISABLED data source status mean?

The DISABLED status means that data source ingestion is suspended, and the data source cannot be added to knowledge bases. A data source cannot be added to any knowledge base (new or existing) while it is in DISABLED status.

What does the ERROR data source status mean?

The ERROR status means that data source ingestion failed partway. Currently, ingestion is not re-attempted for data sources in ERROR status.

Errors appear when Agent Factory cannot validate, crawl, parse, embed, or ingest a configured data source. Use the error number and message to identify the cause and the corrective action.

AAIKA-nnnnn: message text

In this format, AAIKA identifies Knowledge Agent processing, and nnnnn identifies the error number. See Knowledge Agent Errors.

Knowledge Agent Errors

AAIKA-00001

Internal error {err}

Parameters:

Cause:

Oracle AI Database Private Agent Factory has encountered the specified internal error.

Action:

This is an internal error, contact Oracle Support.

AAIKA-00002

Data source {data_source_name} ingestion encountered the following internal error during ingestion stage {ingest_stage}
{err}

Parameters:

Cause:

Oracle AI Database Private Agent Factory has encountered the following internal error during data source ingestion.

Action:

This is an internal error, contact Oracle Support.

AAIKA-00003

Data source {data_source_name} ingestion encountered the following database error during ingestion stage {ingest_stage}
{err}

Parameters:

Cause:

Oracle AI Database Private Agent Factory has encountered the following database error during data source ingestion.

Action:

Review the accompanying database error to determine the underlying issue. Solve the issue and retry the command. If the problem persists, contact Oracle Support.

AAIKA-00004

Data source {data_source_name} ingestion encountered the following error during embedding operation
{err}

Parameters:

Cause:

Oracle AI Database Private Agent Factory has encountered the following error during data source embedding.

Action:

Ensure that the provided embedding model is accessible and retry ingestion. If the problem persists, contact Oracle Support.

AAIKA-00005

No files can be crawled for data source {data_source_name}

Parameters:

Cause:

The crawler could not find any data with the crawling parameters provided.

Action:

AI Studio failed to crawl any content for the specified data source. The possible causes are:

If the problem persists, delete then re-create the data source with updated parameters.

AAIKA-00006

Storage space exceeded on disk for data source {data_source_name} during ingestion stage {ingest_stage} for file {file_path}

Parameters:

Cause:

There is not enough available disk space to ingest the specified data source.

Action:

Free up space in the indicated file system and retry the operation. If the problem persists, contact Oracle Support.

AAIKA-00007

Invalid credentials for key {credentials_key} while ingesting data source {data_source_name} during ingestion stage {ingest_stage}

Parameters:

Cause:

The credentials supplied are invalid.

Action:

Verify credentials and retry the operation.

AAIKA-00008

No extractable text content found in data source {data_source_name}

Parameters:

Cause:

The files in the specified data source cannot be processed because none of the files currently match a supported modality or format for content extraction. This can occur if the files are empty, contain only non-extractable content, or use an unsupported encoding or format.

Action:

Verify that the data source contains supported documents with extractable text. If the problem persists, contact Oracle Support.

AAIKA-00009

Data source {data_source_name} ingestion encountered the following error during vector index creation
{err}

Parameters:

Cause:

Oracle AI Database Private Agent Factory has encountered the specified error during data source vector index building.

Action:

Ensure that the database is functioning correctly and retry ingestion. If the problem persists, contact Oracle Support.

AAIKA-00010

The LLM Provider {llm_provider} returned the error: {err}

Parameters:

Cause:

The specified LLM provider above returned an error while generating the response.

Action:

Review the accompanying LLM provider error to determine the underlying issue. Solve the issue and retry the request. If the problem persists, contact Oracle Support.

AAIKA-00011

The embedding model provider {embedding_model_provider} returned the error: {err}

Parameters:

Cause:

The specified embedding model provider above returned an error while generating the embedding.

Action:

Review the accompanying embedding model provider error to determine the underlying issue. Solve the issue and retry the request. If the problem persists, contact Oracle Support.