Frequently Asked Questions (FAQs) and Troubleshooting

Installation

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

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, 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 Database 23ai free, and Ollama with a pre-trained Llama3.2 LLM, via containers that operate locally within the same environment. This allows you to start using Agent Factory without previous setup. 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 Database 23ai Free User’s Oracle Database 23ai
LLM Ollama + Llama3.2 preset User-selected LLM (vLLM, OCI, etc.)
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 Database 23ai free instance runs on port 1521, and the Ollama instance runs on port 11434. 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 Database 23ai. You will need access to an instance of Oracle Database 23ai. 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 23ai Database, 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 **** 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;

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 multitenant (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';

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, or SharePoint.

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; Applied AI Studio 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. Applied AI Studio 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.

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? Are they customizable?

Annotations are generated automatically today. Customization is planned for an upcoming release.

Can I migrate workflows from other agent platforms?

Yes, provided they conform to open agent specifications.

How are agents and flows monitored?

An Agent Evaluation/Monitoring layer is under development and planned for a future release.

How can I generate the diagnostic ZIP for troubleshooting?