NVIDIA AI-Q Blueprint Deployment on Oracle Cloud Infrastructure

NVIDIA published a deployment guide for AI-Q 2.0 on Oracle Cloud Infrastructure (OCI), using Terraform to create the OCI resources and Helm to install workloads on OKE. The setup produces a working AI-Q endpoint in about 20 to 25 minutes, with a single command to tear everything down.

AI-Q is an open source reference for long-horizon AI agents that plan multiple steps, split work between sub-agents, keep context across a long task, and run tools in a safe sandbox. It is built on LangChain Deep Agents and the NVIDIA NeMo Agent Toolkit. The multi-agent architecture includes an intent router that reads each user query and sends it to the right workflow: a shallow research agent for fast, bounded tool-augmented search, or a deep agent with planning and researcher sub-agents that share a Filesystem layer and run skills in sandboxes.

Infrastructure and Application Split

The deployment separates infrastructure from application. Terraform modules create a VCN with subnets, gateways, and network security groups, an enhanced OKE cluster with a node pool using VCN-native CNI, a flexible Load Balancer for public HTTP ingress on port 80 forwarding to NodePort 30080, and an OCI Vault with AES-256 encrypted storage for API keys and credentials.

The Helm chart installs three workloads on OKE: a FastAPI-based agent server that runs the AI-Q workflow, a Next.js web UI exposed over NodePort 30080, and an in-cluster PostgreSQL for the job store, checkpoints, and summaries. The chart and container images are published on NGC, so there is nothing to build locally.

Prerequisites include OCI tenancy access with a compartment, service limits for one enhanced OKE cluster and node pool, at least 10 GB of Block Volume dynamically provisioned by the OKE CSI driver, one flexible Load Balancer, one Vault plus secrets, an NGC API key from build.nvidia.com in the format nvapi- used both as the inference key and to authenticate to the nvcr.io container registry, a Tavily API key from tavily.com in the format tvly-, and local tools: Terraform 1.5 or later, kubectl 1.28 or later, Helm 3.x or later, and the OCI CLI set up with an API signing key.

Deployment Steps

The guide walks through cloning the repository from oracle-samples on GitHub, then configuring Terraform variables in a terraform.tfvars file with tenancy details, compartment ID, region, user OCID, fingerprint, private key path, database admin password, NVIDIA API key, and Tavily API key.

Running terraform init, terraform plan, and terraform apply takes about 10 to 15 minutes. The output should show values for oke_cluster_id and lb_public_ip. After capturing those values, the next step configures kubectl for the OKE cluster using the OCI CLI, exports the API keys, creates a namespace, and creates two secrets: one for application credentials including the NVIDIA and Tavily inference keys and the Postgres user, and one docker-registry secret for nvcr.io.

The Helm chart is pulled from helm.ngc.nvidia.com and installed with an OCI overlay that pins the frontend service to NodePort 30080 and names the image-pull secret. Pods should show Running state after 3 to 5 minutes. The final step opens the frontend at the Load Balancer IP.

Troubleshooting and Cleanup

Common issues include quota errors on OKE creation, pods stuck in ImagePullBackOff due to a wrong NGC key, the Postgres pod staying in Pending because the Block Volume PVC was not dynamically provisioned, a null Load Balancer IP that needs a terraform refresh, and frontend queries returning 500 errors from a wrong or missing API key in the credentials secret.

The guide notes that the OKE node pool and Load Balancer keep costing while running, so destroying the stack between experiments or scaling the node pool to zero is recommended. Terraform stores the NGC and Tavily keys in OCI Vault at provision time for audit and disaster recovery, but running pods read them from the Kubernetes secret. To rotate keys, delete and re-create that secret with new values, then restart the backend deployment.