Architecture and Security

Use this page before installing Agent Factory in a production, private subnet, regulated, or partner-operated environment. It summarizes the components that must be reachable, the data that moves between them, and the controls administrators can use to restrict access.

Deployment Components

An Agent Factory deployment contains these major components.

Component Purpose Operational notes
Agent Factory application container Hosts the web application, APIs, Agent Builder execution, configuration screens, and administration utilities. The default application URL is https://<host>:8080/agentFactory/. Put a load balancer or reverse proxy in front of the container for production access.
Oracle Database repository Stores Agent Factory metadata, flow definitions, user and role records, data source metadata, and runtime state. Use a dedicated application user. Do not use the Agent Factory repository schema for unrelated production application data.
Read-only database user Used for database access paths that should not run with the owner user’s privileges. The expected user name is AAI_RO_<DB_USER>. See Database Preparation and Grants.
Volume and staging directories Store persistent application configuration, logs, certificates, snapshots, and local data source files. Back up these paths before upgrades or host migration.
External LLM and embedding providers Generate text, invoke tool-using models, and create embeddings for retrieval. Supported connection types include OCI Generative AI, OpenAI-compatible endpoints, Ollama, vLLM, and Gemini. Model availability is provider-specific.
Data sources Provide content and structured data for Knowledge Agents, Data Analysis Agents, and workflows. Supported source types include files, websites, databases, REST APIs, SharePoint, Google Drive, Amazon S3, and MCP servers.
Observability provider Receives OpenTelemetry-style traces for flow runs, LLM calls, and tool calls. Release 26.4 supports Arize Phoenix and Comet Opik in the inspected code path.

Runtime Data Flow

Typical runtime execution follows this path:

  1. A user signs in with local credentials or SSO and opens a pre-built agent or Agent Builder workflow.
  2. Agent Factory loads the agent, workflow, model configuration, data source metadata, and any required secrets.
  3. The workflow invokes nodes such as prompt templates, LLMs, REST tools, MCP tools, Select AI, database queries, or retrieval over indexed content.
  4. If the workflow calls an external service, Agent Factory applies outbound URL and proxy validation before sending the server-side request.
  5. The result is returned to the user and, when observability is configured, trace spans are exported to the active tracing provider.

The following text diagram shows the main boundaries:

User browser
  |
  | HTTPS /agentFactory
  v
Load balancer or reverse proxy
  |
  v
Agent Factory application container
  |-- Oracle Database repository
  |-- App wallet and persisted volume
  |-- LLM and embedding providers
  |-- Data sources and tool endpoints
  |-- Observability provider

Network Requirements

Plan these network paths before installation.

Direction Required for Notes
Browser to Agent Factory UI, setup wizard, chat, admin settings Use HTTPS. The browser-visible host name must match configured SSO and MCP callback URLs.
Agent Factory to repository database Application metadata, flows, users, data source metadata, migrations Production mode requires a reachable Oracle Database. Quickstart creates a local database container.
Agent Factory to LLM and embedding providers Model tests, flow execution, retrieval ingestion Validate DNS, firewall, proxy, and provider allow lists.
Agent Factory to data sources Crawling, ingestion, connector tests, runtime tools Web, cloud storage, SharePoint, Google Drive, REST, and MCP endpoints are reached from the Agent Factory container, not from the browser.
Agent Factory to observability provider Trace export If the provider is on a private address, review proxy and outbound URL security settings.

Do not assume localhost inside a browser is the same as localhost inside the Agent Factory container. Use a host name or IP address that the container can resolve and reach.

Credential and Secret Storage

Agent Factory separates secret values from non-secret configuration where supported.

Secret type Stored as Notes
LLM API keys, OCI key material, Gemini credentials, and vLLM API keys Application wallet Metadata such as provider name and model ID is stored separately from sensitive values.
MCP bearer tokens, OAuth tokens, and Auth Request tokens Application wallet MCP source metadata references the saved secret.
Google Drive service account JSON Application wallet or protected backend storage path, depending on the flow Treat service account JSON files as credentials.
Database wallet ZIP uploads Private filesystem path with validation and safe extraction Wallet uploads must contain required files such as sqlnet.ora and tnsnames.ora.
TLS certificate and private key files Application configuration/volume paths Imported keys are hardened with private file permissions.

Limit administrator access to the host, staging directory, persistent volume, diagnostics bundles, and database repository. These locations can contain operational data, connection metadata, logs, or secrets.

Outbound URL Security

Agent Factory includes server-side outbound controls for user-supplied URLs and proxy settings. Administrators can configure whether the deployment:

Keep private outbound URL blocking enabled unless there is a documented need to connect to private data sources. If private access is required, prefer explicit network architecture such as a private subnet, load balancer, service gateway, NAT gateway, or enterprise proxy rather than disabling controls broadly. See Configure Proxy and Access Agent Factory Deployed in a Private Subnet.

Authentication and Authorization

Agent Factory supports local users and SSO users. The externally visible application URL matters for SSO because identity providers validate the redirect URL exactly.

Use role-based access to limit who can:

For API usage, local credential authentication through loginValidation is different from browser-based SSO. SSO users authenticate through the browser redirect flow and may not be able to bootstrap an API session with Basic Auth. See Agent Builder and Configure Single Sign-On.

Production Readiness Checklist

Before production use, verify the following: