NVIDIA AI-Q 2.0 llega a Oracle Cloud con un Blueprint listo en 25 minuto

Los agentes de IA cambiaron mucho en los últimos dos años. Los primeros solo podían responder una pregunta a la vez. Después llegó el chat multi-turno, donde el modelo conservaba algo de contexto durante una sesión. Hoy tenemos agentes de horizonte largo, sistemas que planifican muchos pasos, dividen el trabajo entre subagentes, mantienen contexto durante una tarea extensa y ejecutan herramientas en un sandbox seguro.

El NVIDIA AI-Q Blueprint es una referencia open source para este tipo de agente. Está construido sobre LangChain Deep Agents y el NVIDIA NeMo Agent Toolkit. Sirve para entregar respuestas citadas rápidas o reportes de investigación largos con fuentes verificadas.

Esta publicación muestra cómo desplegar AI-Q 2.0 sobre Oracle Cloud Infrastructure (OCI) usando Terraform para crear los recursos en OCI y Helm para instalar las cargas de trabajo en OKE. Al terminar, vas a tener un endpoint AI-Q funcionando en tu propio tenancy de OCI y un solo comando para desmontarlo cuando termines.

Para quién es: desarrolladores e ingenieros de plataforma con dominio de Kubernetes, Terraform y línea de comandos, que quieran correr AI-Q en OCI en lugar de un laptop.

Qué vas a aprender: cómo se mapea la arquitectura multi-agente de AI-Q sobre los servicios de OCI, más los comandos exactos para aprovisionar, desplegar y abrir el blueprint de principio a fin.

Más contexto sobre la arquitectura multi-agente (incluyendo intent router, shallow research agent, deep agent, planning sub-agent y researcher sub-agent) está en la página del producto AI-Q y en la documentación del NeMo Agent Toolkit.

¿Qué necesitás antes de empezar?

• Acceso a un tenancy OCI con un compartimento donde desplegar y suficientes límites de servicio para OKE (un clúster enhanced y un node pool), Block Volume (al menos 10 GB aprovisionados dinámicamente por el driver CSI de OKE para el PostgreSQL in-cluster), un Load Balancer flexible y un Vault con secretos.
• API keys: clave NGC de build.nvidia.com con formato nvapi-... (sirve como clave de inferencia NVIDIA y para autenticar contra el registro nvcr.io). Clave Tavily de tavily.com con formato tvly-...
• Herramientas locales: Terraform 1.5 o superior, kubectl 1.28 o superior, helm 3.x y la CLI oci configurada con tu llave de firma API.
• Conocimientos básicos de Kubernetes, charts de Helm, Terraform y shell. Experiencia con LangChain o NeMo Agent Toolkit es bienvenida pero no obligatoria.

¿Cómo está armada la arquitectura?

AI-Q usa un diseño multi-agente. Un intent router lee cada consulta del usuario y la envía al flujo correcto.

El blueprint fue pensado para ser extensible. Todas las capas (modelos, herramientas, backends RAG, sub-agentes, evaluadores) se intercambian mediante YAML de configuración o mediante el sistema de plugins del NeMo Agent Toolkit.

El despliegue usa Terraform para los recursos OCI y Helm para las cargas Kubernetes. Esto entrega una división limpia entre infraestructura y aplicación, y un solo terraform destroy basta para eliminar todo después.

El chart Helm instala tres cargas de trabajo en OKE:

• Backend (aiq-backend): un servidor de agentes basado en FastAPI que ejecuta el workflow AI-Q.
• Frontend (aiq-frontend): una UI web next.js expuesta vía NodePort 30080.
• PostgreSQL (aiq-postgres): una base in-cluster para el job store, los checkpoints y los resúmenes.

¿Cuáles son los pasos del despliegue?

git clone https://github.com/oracle-samples/ai-q.git
cd ai-q/oke-samples/aiq-2.0

Tiempo total: alrededor de 20 a 25 minutos. La referencia completa está en aiq-2.0/README.md.

Paso 1. Configurar las variables de Terraform

Copia el archivo de ejemplo y editalo con los detalles de tu tenancy:

cd deploy/terraform
cp terraform.tfvars.example terraform.tfvars

Como mínimo, definí estas variables en terraform.tfvars: tenancy_ocid, compartment_id, region (por ejemplo us-chicago-1), user_ocid, fingerprint, private_key_path (los mismos valores que tu ~/.oci/config), db_admin_password (para inicializar el PostgreSQL in-cluster, guardado en OCI Vault), nvidia_api_key y tavily_api_key.

Paso 2. Crear la infraestructura

Inicializá los providers, revisá el plan y aplicá:

terraform init
terraform plan
terraform apply

Esto toma alrededor de 10 a 15 minutos. Terraform crea la VCN, el clúster OKE, el Load Balancer y el Vault con las claves NGC y Tavily cifradas en reposo.

Paso 3. Instalar AI-Q desde el chart Helm de NGC

El chart y las imágenes de contenedor están publicados en NGC, así que no hay nada que construir localmente. Apuntás kubectl al nuevo clúster OKE, creás los secrets que consume el chart, hacés helm pull y helm install.

helm pull https://helm.ngc.nvidia.com/nvidia/blueprint/charts/aiq2-web-2.0.0.tgz   --username='$oauthtoken'   --password="$NGC_API_KEY"

helm upgrade --install aiq aiq2-web-2.0.0.tgz   -n ns-aiq   --wait --timeout 10m   -f values-oci-ngc.yaml

El overlay OCI (values-oci-ngc.yaml) es intencionalmente mínimo: solo fija el servicio del frontend al NodePort 30080 (el puerto que chequea el Load Balancer de OCI) y nombra el secret ngc-secret para el image-pull. Los repos de imagen, el SQL de inicialización de Postgres y la PVC dinámica de 10 GiB de Block Volume vienen de los defaults del chart.

Paso 4. Abrir AI-Q

echo "http://$LB_PUBLIC_IP"

Abrí http://<lb_public_ip> en tu navegador. Deberías ver el frontend AI-Q. Probá primero una pregunta simple, por ejemplo "¿Qué es el NeMo Agent Toolkit?", para confirmar que el ruteo funciona. Después intentá una más profunda, por ejemplo "Compará los tres principales agentes de deep research open source por benchmark y costo", para ver al deep agent en acción.

Solución de problemas comunes

• terraform apply falla en la creación de OKE con error de cuota: revisá los límites de servicio para tu compartimento en "Cluster count" y "Node count", y pedí más cuota si hace falta.
• Pods en ImagePullBackOff: revisá que el secret de image-pull se haya creado (kubectl get secret -n ns-aiq) y que tu NGC_API_KEY haya sido correcto al ejecutar el comando kubectl create secret docker-registry ngc-secret.
• El pod postgres queda Pending más de 2 minutos: la PVC de Block Volume no se aprovisionó dinámicamente. Corré kubectl describe pvc -n ns-aiq. Causas típicas: driver CSI de OKE detenido, StorageClass por defecto ausente o cuota insuficiente de Block Volume.
• La IP del Load Balancer aparece como null: OCI puede tardar uno o dos minutos después de Terraform en terminar el LB. Corré terraform refresh y después terraform output lb_public_ip de nuevo.
• El frontend carga pero las consultas devuelven 500: revisá los logs con kubectl logs -n ns-aiq deploy/aiq-backend. La causa más común es una NVIDIA_API_KEY o TAVILY_API_KEY ausente o incorrecta en el secret aiq-credentials.

¿Qué hay que tener presente después?

Ahora tenés un despliegue AI-Q 2.0 funcionando sobre OCI, y un solo comando (terraform destroy) para eliminarlo limpio cuando termines. Algunas cosas para tener en mente:

• Costo: el node pool de OKE y el Load Balancer siguen costando mientras corren. Destruí el stack entre experimentos o escalá el node pool a cero.
• Secretos: Terraform guarda las claves NGC y Tavily en OCI Vault al aprovisionar (para auditoría y disaster recovery), pero los pods en producción las leen del secret Kubernetes aiq-credentials que creaste manualmente. Para rotar, borrá y recreá ese secret con los nuevos valores y después corré kubectl rollout restart deployment -n ns-aiq aiq-backend. Editar solo terraform.tfvars no llega a los pods.
• Extensibilidad: todo lo desplegado está manejado por YAML y por el sistema de plugins del NeMo Agent Toolkit. Cambiar un LLM, agregar un sub-agente o conectar un nuevo backend RAG es un cambio de configuración, no un rewrite.