NVIDIANVIDIA-Certified Professional: Agentic AI2026-104.1 Deploy and orchestrate multi-agent systems at production scale.
Choose Compose or Helm by operating model
Completed by the knowledge check
Learning objective
Deploy multi-agent workflows with Docker Compose versus Helm.
Core idea
Docker Compose defines and runs a multi-container application. Helm packages a Kubernetes deployment through a chart and configurable values. Choose between them from the environment you must operate: a bounded deployment on a Docker host or workloads managed by a Kubernetes cluster.
The NVIDIA AI-Q research blueprint supplies both deployment paths. That makes it useful for comparing packaging without changing the workflow’s purpose. Neither path proves that a research answer is correct, that an interrupted job resumes, or that a deployment meets an availability target. Service separation belongs to 4.1.1; this lesson decides how you deliver and configure those services.
How it works
Compose delivers a coordinated container stack
The blueprint’s deploy/compose/docker-compose.yaml defines aiq-agent, frontend, and postgres services. Its Compose README describes the backend as using an embedded Dask scheduler and worker for background work, with PostgreSQL for async jobs and checkpoints. A deployment containing several services can still have several agents inside the backend process; the service count is not the agent count.
From deploy/compose, the documented launch is docker compose --env-file ../.env -f docker-compose.yaml up -d --build. The flags select the environment file, Compose definition, detached execution, and image build. The README also supplies prebuilt-image deployment through BACKEND_IMAGE and FRONTEND_IMAGE, omitting --build. Choose the image path that matches how your organization approves and delivers artifacts.
BACKEND_CONFIG selects the backend workflow configuration. In the Compose file, it supplies the container’s CONFIG_FILE. This is application selection, distinct from the image version and host port mapping. The documented PORT changes the host port; the backend remains on port 8000 inside the container. Changing the host port does not require rewriting a container-to-container address to use that host port.
Startup order needs a readiness condition. Compose starts dependencies before dependents, but a running database container might still be initializing. The blueprint uses depends_on.postgres.condition: service_healthy and a PostgreSQL healthcheck. Docker documents this condition as waiting for the dependency’s health check to pass. Plain depends_on ordering is insufficient when the backend needs a usable database at startup.
For a single-server production deployment, Docker recommends considering a production override file, removing application-code bind mounts, and specifying a restart policy. Combine files with repeated -f options. Such settings make the host deployment repeatable; a container restart policy does not supply a replacement host if that server fails.
Helm delivers configured Kubernetes resources
The blueprint’s Helm instructions require a Kubernetes cluster, configured kubectl, and Helm v3.x. They document the NGC chart aiq2-web version 2.0.0, and a local chart under deploy/helm/deployment-k8s.
For the packaged chart, the instructions use helm upgrade --install aiq aiq2-web-2.0.0.tgz -n ns-aiq --create-namespace, with --wait --timeout 10m. The release name is aiq; the namespace is ns-aiq. Waiting for Kubernetes resources is a deployment operation, not a ten-minute deadline on an agent’s research task.
Values select the application image and configuration. The documented keys include aiq.apps.backend.image.tag and aiq.apps.backend.env.CONFIG_FILE. Pass a values file with -f when overrides are substantial. Keep the selected configuration and endpoint settings reviewable with the image selection: installing the right container with the wrong workflow file still delivers the wrong application.
The instructions distinguish an application credentials Secret, aiq-credentials, from registry credentials in ngc-secret. The chart’s image access uses aiq.apps.backend.imagePullSecrets[0].name and the corresponding frontend key. An image-pull credential gets a container onto a node; an application API credential lets running code call its dependencies. One cannot repair the other’s failure.
Wire dependencies for the actual network
The blueprint’s Foundational RAG configuration, configs/config_web_frag.yml, requires a separately running RAG service. With Compose stacks on separate Docker networks, the AI-Q backend cannot resolve the RAG service names. The README remedies this by connecting the backend container to the RAG network. Diagnose the network attachment before treating name-resolution failure as a model or agent defect.
For Helm deployment in the same cluster, the blueprint documents aiq.apps.backend.env.RAG_SERVER_URL and RAG_INGEST_URL with internal Kubernetes Service DNS. If RAG is outside the cluster, configure reachable external addresses instead. Packaging does not discover or create an arbitrary dependency merely because a workflow configuration mentions it.
For deployment failures, the Helm troubleshooting table associates CrashLoopBackOff with missing credentials or bad configuration and directs you to Pod logs and the required Secret keys. Fix the configuration cause before increasing replicas. More copies of an invalid startup configuration reproduce the failure.
Key distinctions and trade-offs
Compare the operating requirements before choosing the packaging. The Compose row describes Docker’s single-server production case; Docker also documents running Compose applications on a Swarm cluster:
| Option | Deciding condition | Mechanism | Operational cost |
|---|---|---|---|
| Docker Compose on one server | One host is sufficient and its outage is acceptable | Compose services, environment file, dependency health checks, production override | Smaller platform footprint; the operator owns host recovery |
| Helm on Kubernetes | The organization needs cluster-managed workloads and already operates the cluster | Chart release, namespace, values file, Kubernetes workload resources | Cluster operations, scheduling, networking, and storage responsibilities |
Helm keeps a numbered release revision history. Use helm history RELEASE to inspect it and helm rollback RELEASE REVISION to restore a selected revision. Omitting REVISION, or setting it to 0, selects the previous release; --history-max limits saved revisions and defaults to 10. For the Compose host, retain the prior image tags and deployment files, then redeploy them with docker compose up -d when reverting an application change.
Compose is not confined to development: Docker documents production use. Helm is not the Kubernetes scheduler: the installed resources are operated by Kubernetes. A chart also does not establish that its database storage, backups, or agent recovery meet your requirements. Verify those separately rather than inferring them from a successful install.
Architecture / decision scenario
A manufacturing engineering team deploys an internal research assistant over maintenance documents. A five-person pilot uses one approved server, allows a four-hour maintenance outage, and has no Kubernetes operator. The team proposes Compose with the blueprint’s backend, frontend, and PostgreSQL stack, selecting its workflow through BACKEND_CONFIG. That fits the pilot’s operating constraint.
The rollout expands to three plants. The production requirement permits only ten minutes of interruption after a host failure, and the company supplies an operated Kubernetes cluster across three worker nodes. Retaining a single Compose host is tempting because the pilot already works, but its accepted four-hour recovery procedure cannot meet the ten-minute requirement. The platform owner chooses the Helm path and takes responsibility for placement, storage, and a tested recovery procedure against the tighter target.
The application team supplies a reviewed values file with CONFIG_FILE and the internal RAG_SERVER_URL and RAG_INGEST_URL. The platform team installs the approved chart version, sets image-pull Secrets, and verifies backend /health after resource readiness. It records the release revision from helm history aiq and rehearses helm rollback aiq REVISION to the approved prior revision if a rollout fails application checks. It then exercises a research request that actually reaches the RAG dependency; a healthy backend process alone would not expose a misconfigured RAG address.
The team does not claim that adopting Helm achieves the ten-minute target automatically. It accepts the rollout only after a host-loss exercise demonstrates recovery with its configured resources and stored data. Compose remains appropriate for the pilot, while the production cluster earns its additional operating cost through the required recovery behavior.
Common exam traps
- Calling Compose development-only despite Docker’s production guidance.
- Treating Helm as a runtime scheduler or agent orchestrator.
- Equating several container services with one service per specialist agent.
- Using dependency startup order without
service_healthywhen readiness matters. - Confusing registry image-pull credentials with application API credentials.
- Reading
--timeout 10mas an agent execution timeout. - Assuming separate Compose networks share service-name resolution.
What to remember
Choose Compose for an operated Docker-host stack and Helm for chart-managed Kubernetes resources. Carry the workflow configuration, endpoint addresses, health dependencies, images, and credentials through the chosen deployment path. Availability and resumability require explicit design and verification beyond successful container or chart installation.
Knowledge check
A legal team pilots a research assistant for eight users on one approved server. The pilot accepts a half-day outage if that server fails, and the organization runs no Kubernetes cluster and has no one to operate one. Which deployment meets these constraints with the least operational effort?
In a Compose deployment, the agent backend sometimes exits at startup with a database connection error, although depends_on lists postgres and Compose starts the database container first. The team wants the backend created only once the database accepts connections. What should it add?
restart: always policy on the backend servicepostgres service the backend can fail over tohealthcheck and condition: service_healthydepends_on orders container start, but a running PostgreSQL container can still be initializing. With condition: service_healthy , Compose waits for the dependency’s healthcheck to pass before creating the dependent service, which is the readiness condition the team asked for. A restart policy and a fixed delay retry or wait without knowing whether the database is usable, and a second database does not make the first one ready.After helm upgrade --install of the AI-Q chart, the backend image is pulled successfully, but the backend Pod enters CrashLoopBackOff. What should the team check first?
ngc-secret and reference it under the backend imagePullSecrets--timeout for --waitaiq-credentials for the required keysCrashLoopBackOff to missing credentials or bad configuration and points to the Pod logs and the keys of the application Secret. The image pull already worked, so the registry credential in ngc-secret is not the failing piece. More replicas reproduce the same invalid startup, and a longer --wait only waits longer on the same crashing Pod.AI-Q runs as one Compose stack and a Foundational RAG service as another on the same host. The backend uses config_web_frag.yml with RAG_SERVER_URL=http://rag-server:8081/v1, and research requests fail because rag-server cannot be resolved, although both stacks are running. What fixes the failure?
aiq-agent container to the RAG stack’s networkRAG_SERVER_URL to http://localhost:8081/v1BACKEND_CONFIG to a configuration with a larger modelrag-server to the backend’s depends_on listdocker network connect to attach the backend to the RAG network. Inside the backend container localhost is the backend itself, depends_on orders startup without joining networks, and a different model treats a name-resolution failure as an agent defect.References
- NVIDIA, AI-Q Docker Compose deployment
- NVIDIA, AI-Q Docker Compose definition
- NVIDIA, AI-Q Helm deployment
- NVIDIA, AI-Q local Helm chart deployment
- Helm, Helm Rollback
- Docker, Use Compose in production
- Docker, Control startup and shutdown order in Compose